Work with agents / Local workspaces
Run hooks in workspaces
A new workspace sometimes needs more than its dependencies, for example a database with test data. Hooks run your commands when a workspace is made, when src ws accept tests its changes, and when the workspace closes.
3 min read
1. Add the hooks
In .source/workspace.yaml:
hooks:
setup: pnpm db:seed
validate: pnpm test
teardown: pnpm db:drop
| Hook | When it runs |
|---|---|
setup | In each new workspace, after its layers are ready, its env files are copied and its ports are set. |
validate | In the candidate folder of src ws accept, before your checkout changes. If it exits with a code other than 0, accept stops, shows the output, and your checkout does not change. |
teardown | In close, after src stops the processes that the workspace owns. Then close gives the folder to the pool of ready workspaces. When the pool is off, it deletes the folder. |
2. Trust the hooks
src ws trust
The hooks are commands of the config, so they run only after src ws trust.
3. Create a workspace
src ws create api
create runs setup in the new workspace.
Done
Each new workspace runs setup, each accept runs validate before your checkout changes, and each close runs teardown.
What the hooks get
setup and teardown get the environment of src ws exec: the ports, the caches, and the vault values after src ws trust. restore and sync do not run setup again.
To skip the hooks once, add --no-hooks to create, close, accept or repair.
When a hook fails
- When
setupfails, the workspace stays. Its state issetup-failed, andcreateshows the end of the output and exits 1. Fix the cause, then repair the workspace. - When
teardownfails,closeshows the output and still closes the workspace.
Repair a workspace
A setup hook failed, or a layer folder of a workspace is gone. Fix the cause, then run:
src ws repair api
repair runs the steps that did not finish:
- If the create of the workspace failed, it makes the folder again from its baseline.
- It makes each layer again that failed, or whose folder is gone. The other layers stay.
- It copies missing env files again, and sets the read-only flags again.
- If
setupfailed before, or the folder is new, it runssetupagain.
When every step works, the state is live again. A workspace that needs nothing stays as it is, so you can run repair again with no harm. A workspace with conflicts from a sync needs src ws sync <name> --continue first.