@sassywares/skills 0.11.1 → 0.11.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CONCEPTS.md +11 -4
- package/README.md +18 -8
- package/package.json +1 -1
- package/skills/sassy-dogfood/SKILL.md +36 -11
- package/skills/sassy-plan/references/plan-format.md +1 -1
- package/skills/sassy-setup/SKILL.md +4 -4
- package/skills/sassy-setup/assets/dogfood-recipe.md +1 -1
- package/skills/sassy-setup/assets/worktree/_lib.sh +71 -5
- package/skills/sassy-setup/assets/worktree/create +21 -7
- package/skills/sassy-setup/assets/worktree/list +31 -8
- package/skills/sassy-setup/assets/worktree/prune +14 -6
- package/skills/sassy-setup/assets/worktree/remove +9 -6
- package/skills/sassy-setup/assets/worktree/stop +6 -3
- package/skills/sassy-setup/references/config.md +9 -5
- package/skills/sassy-setup/references/dogfood.md +63 -12
- package/skills/sassy-setup/references/harness.md +6 -0
- package/skills/sassy-setup/references/worktree.md +39 -12
- package/skills/sassy-setup/scripts/detect.sh +44 -8
- package/skills/sassy-worktree/SKILL.md +11 -8
package/CONCEPTS.md
CHANGED
|
@@ -59,12 +59,19 @@ owns the lifecycle; the scripts in `.sassywares/worktree/` own the git.
|
|
|
59
59
|
- **Namespace** — the slug prefixed with the repo (`shop-feat-catalog`), and the
|
|
60
60
|
only name a hook should use for a database, a compose project, or a simulator.
|
|
61
61
|
Derived once by `create`; never rebuilt by hand.
|
|
62
|
-
- **Port claim** — the private port a checkout owns
|
|
63
|
-
|
|
64
|
-
collision. Liveness is *probed*, never read
|
|
62
|
+
- **Port claim** — the private port a checkout owns, *when the project configured
|
|
63
|
+
`worktrees.ports`*: hashed from the slug into the range, claimed with an atomic
|
|
64
|
+
`mkdir`, and probed forward on a collision. Liveness is *probed*, never read
|
|
65
|
+
from a pid file. Without a range there is no port and nothing to claim — a port
|
|
66
|
+
is one resource, not the definition of a preview.
|
|
65
67
|
- **Preview** — bringing that checkout up so a human can look at it. It runs the
|
|
66
68
|
dogfood recipe's steps up to the section's `Prove it:` and never judges the
|
|
67
|
-
work; proving is dogfood's job.
|
|
69
|
+
work; proving is dogfood's job. **How to see it** is the recipe's `**Preview:**`
|
|
70
|
+
line with `WT_*` substituted — a URL, a simulator, a window, never the command
|
|
71
|
+
that started it — so the suite never assumes a browser.
|
|
72
|
+
- **Managed checkout** — one under `worktrees.dir` that also carries
|
|
73
|
+
`.sassywares/config.yaml`. The tooling lists, prunes, stops, and removes only
|
|
74
|
+
those; anything else belongs to another tool or predates the wiring.
|
|
68
75
|
|
|
69
76
|
`create` and `remove` need an agent because their hooks are project skills, and a
|
|
70
77
|
script cannot dispatch one. That is why the lifecycle is a skill and the git is a
|
package/README.md
CHANGED
|
@@ -179,7 +179,7 @@ hooks:
|
|
|
179
179
|
worktrees: # parallel checkouts of this repo
|
|
180
180
|
enabled: false # true = a run may work in its own checkout
|
|
181
181
|
dir: ~/.sassywares/worktrees # parent of the per-repo folder
|
|
182
|
-
ports: 3000-3099 #
|
|
182
|
+
ports: 3000-3099 # optional; delete for a non-port preview
|
|
183
183
|
dogfood: # agent QA: a stored procedure that proves a change runs
|
|
184
184
|
enabled: false # true lets a plan write Mode: Auto QA rows
|
|
185
185
|
recipe: .sassywares/dogfood/recipe.md # the procedure; never commands here
|
|
@@ -199,12 +199,22 @@ directory, a port, a database. `worktrees:` turns that on:
|
|
|
199
199
|
└── feat-catalog-search/
|
|
200
200
|
```
|
|
201
201
|
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
202
|
+
Only checkouts this tooling manages are listed or pruned: one under `worktrees.dir`
|
|
203
|
+
that also carries `.sassywares/config.yaml`. Anything else — another tool's
|
|
204
|
+
worktree, or one cut from a ref that predates the wiring — is counted in a footer
|
|
205
|
+
and left alone.
|
|
206
|
+
|
|
207
|
+
`create` derives the identity from the branch and prints it — `WT_PATH`,
|
|
208
|
+
`WT_SLUG`, `WT_NAMESPACE` — so a project's hook derives `.env`, a database name,
|
|
209
|
+
or a simulator from one source instead of inventing its own.
|
|
210
|
+
|
|
211
|
+
A **port is a resource, not the model**. With `ports:` configured, a checkout
|
|
212
|
+
also gets `WT_PORT` and `WT_BASE_URL`, hashed into the range and claimed
|
|
213
|
+
atomically so a restarted app returns to the same port. Delete `ports:` and there
|
|
214
|
+
is no port at all: the checkout is addressed by the recipe's `**Preview:**` line
|
|
215
|
+
instead — a simulator named `$WT_NAMESPACE`, a desktop window, or nothing at all
|
|
216
|
+
for a CLI. The `list` table's column is `HOW TO SEE`, not "address", for exactly
|
|
217
|
+
that reason.
|
|
208
218
|
|
|
209
219
|
It needs `commit.branch: new`: under `current` a run commits where it stands and
|
|
210
220
|
never cuts a branch, so nothing would create a checkout. `--check` says so rather
|
|
@@ -212,7 +222,7 @@ than leaving a switch that cannot fire.
|
|
|
212
222
|
|
|
213
223
|
**Previewing.** `sassy-worktree mode:preview` runs the dogfood recipe's bring-up
|
|
214
224
|
steps — everything up to the section's `Prove it:` — leaves the app running, and
|
|
215
|
-
prints the
|
|
225
|
+
prints the preview line — the result, not the command that booted it. A worktree gets a fresh, empty `.sassywares/session/`, and
|
|
216
226
|
most providers register one callback URL, so the usual answer is to copy or link
|
|
217
227
|
the main checkout's session in the `after_create` hook: a cookie is host-scoped
|
|
218
228
|
and crosses ports freely, while a `localStorage` session is origin-scoped and has
|
package/package.json
CHANGED
|
@@ -36,22 +36,41 @@ recipe, and the next `run` is what proves it.
|
|
|
36
36
|
|
|
37
37
|
## Steps — `mode:run`
|
|
38
38
|
|
|
39
|
-
1. **Resolve the target.** Read the `dogfood:` block. If `enabled` is not `true`, stop with one line: reporting is not enabled, and enabling it is `sassy-setup mode:init`. Load the recipe; a section the caller names (`section:<name>`) is the target, otherwise every section. A missing recipe, or one whose section has no `Prove it:` step, stops the run and names `mode:discover` —
|
|
40
|
-
2. **
|
|
41
|
-
3. **
|
|
42
|
-
|
|
39
|
+
1. **Resolve the target.** Read the `dogfood:` block. If `enabled` is not `true`, stop with one line: reporting is not enabled, and enabling it is `sassy-setup mode:init`. Load the recipe; a section the caller names (`section:<name>`) is the target, otherwise every section. A missing recipe, or one whose section has no `Prove it:` step, stops the run and names `mode:discover`. A section whose `**Prove it:**` says `none` is refused with one line — it has no machine verdict by design, so its QA rows are `Manual`, and running it would only manufacture an opinion. Never guess a verdict from a procedure that has none.
|
|
40
|
+
2. **Open the report.** Create `<reports>/<YYYYMMDD-HHMMSS>/` with `steps/` and `artifacts/`, and write `summary.md` with `status: running`, the class blank, the recipe path with the current commit, and the start time. Prune older run directories down to ten.
|
|
41
|
+
3. **Preflight, then the bring-up.** Preflight checks presence only: each env var the recipe **names** (never print a value), a session it refers to actually sitting in `.sassywares/session/`, and the commands' entry points existing. A missing entry point, a tool not on `PATH`, or an absent env var is `class: env` — write the report, report it, and stop.
|
|
42
|
+
|
|
43
|
+
Then **run the recipe's *Set up once*.** It is the bring-up, not a checklist: install frozen where the project has a lockfile, and continue. That is the only installing a run does — never install something the recipe does not name, never `docker pull`, never mutate the environment to make a step pass.
|
|
44
|
+
|
|
45
|
+
4. **Execute in order, stopping at the first broken expectation.** Per step: write `steps/<section>-<NN>.log`, capped head-and-tail, with the command and its output, values of every env var the recipe names masked, and the exit code. `Do` is a command *or* an instruction — satisfy it with whatever is available, and judge it only against its `Expect`. The step's own shell mechanics are part of the step: backgrounding a server, redirecting its output, creating the directory a log path lives in. Improvisation is what the recipe does **not** name. A step whose expectation fails ends that section: record it, keep everything already written, and skip to the report. Resume at the failed step on the next run, never from the top: the summary's `Next:` line says which.
|
|
43
46
|
5. **Take the verdict from the prove step.** The section's `Prove it:` step decides: exit 0 is `pass`, non-zero is `failed`. A failure earlier in the section is `failed` regardless. This skill holds no opinion about the work — a check it judged by reading instead of running is not a verdict.
|
|
44
|
-
|
|
45
|
-
|
|
47
|
+
**The deadline is yours to hold.** Track wall-clock from the start and stop at `dogfood.timeout`, filing the run as `failed` with `class: env` and the step it stopped in. A step that can hang states its own bound in its `Expect`; the recipe-wide deadline is the backstop, not a substitute.
|
|
48
|
+
|
|
49
|
+
6. **Classify.** `env` when the environment cannot produce a verdict: exit 75 or 127, a missing dependency, or **a service nobody in this run controls** being down (a third-party API, a shared backend). That last one is neither `code` nor `recipe` — report it, name the dependency, and stop. The line between the two is whose text is wrong: the named toolchain is right but absent → `env`; the recipe names the wrong version, script, or URL → `recipe`, because the procedure itself is what failed; `recipe` when a step cannot be followed at all (a script renamed, a URL that no longer exists, a UI that no longer matches) — that is the procedure being stale, not the code being wrong; `code` otherwise. When in doubt between `recipe` and `code`, ask: could a person follow this step as written and still be testing the app? If not, it is `recipe`.
|
|
50
|
+
7. **Finalize and report.** A preflight or bring-up failure has no step id, so it logs to `steps/00-setup.log` and the summary's table row reads `setup`. Write the final `summary.md` (`status`, `class`, the per-step table, artifacts, `Next:`), then return compactly: verdict, class, section, failing step id, the last ~600 characters of that step's log, the report path, and — for `recipe` — the one-line diff you propose. Never paste a whole log to the caller.
|
|
46
51
|
8. **On `recipe`, propose and stop.** Show the diff that would make the procedure followable and ask before writing it. Never edit the recipe to turn a red run green: the cheapest way to pass a check must not be to weaken it.
|
|
47
52
|
|
|
48
53
|
## Steps — `mode:discover`
|
|
49
54
|
|
|
50
|
-
1. **Read what the project already says.** The existing recipe, the config, and the manifest's scripts (`package.json`, `Makefile`, `pyproject.toml`, `deno.json`, a CI workflow)
|
|
51
|
-
2. **Find the surfaces.** What is this product? A web app, an API, a CLI, a library, a desktop app, a mobile app in a simulator, several of them. Each surface that a change can break gets a
|
|
52
|
-
3. **
|
|
53
|
-
|
|
54
|
-
|
|
55
|
+
1. **Read what the project already says.** The existing recipe, the config, and the manifest's scripts (`package.json`, `Makefile`, `pyproject.toml`, `deno.json`, a CI workflow). **Reading is not deciding** — what exists is the starting point, never the target.
|
|
56
|
+
2. **Find the surfaces.** What is this product? A web app, an API, a CLI, a library, a desktop app, a mobile app in a simulator, several of them. Each surface that a change can break gets its own answer — in a monorepo especially, one app having a suite says nothing about its siblings. **A surface is something this repository serves**; a backend it calls is not a surface — record it as `**Upstream:**` and let its outages be `env`.
|
|
57
|
+
3. **Classify each surface, honestly.** Three classes and no fourth:
|
|
58
|
+
|
|
59
|
+
| Class | Means | Becomes |
|
|
60
|
+
|---|---|---|
|
|
61
|
+
| `runtime` | something already drives the running product — e2e, integration, a smoke script | a section that wraps it |
|
|
62
|
+
| `unit-only` | tests exist, but they never start the product | an **uncovered** section |
|
|
63
|
+
| `none` | nothing | an **uncovered** section |
|
|
64
|
+
|
|
65
|
+
**A unit test is not a dogfood path**, and neither is `lint`, `tsc`, or `build`: they never start the product. Recording one as coverage is the failure this step exists to prevent — it makes an untested app look tested, and nobody can tell afterwards that the gap was never closed.
|
|
66
|
+
4. **Ask, one surface at a time — and stop until answered.** With what you found: *"`web`, `api`, and `admin` have no runtime path — `web` has Playwright, the other two only unit tests. Set up a runtime check for `api` and `admin`?"* The options are wrap an existing suite, add a small runtime check, or leave it uncovered and say so. **This step blocks steps 5–8**: the answer decides what gets written, so with no user to ask, stop and report the question verbatim — never write a recipe on a guessed answer. Never leave a surface uncovered silently, and never fill the gap with what happens to exist.
|
|
67
|
+
|
|
68
|
+
A **small runtime check is in scope**: a boot plus one assertion, a `curl`, a screenshot diff — written into the recipe as steps. That is not a test framework, and it is the only check this skill authors. Installing a driver or a runner to make one possible is out of bounds; without one already present, the surface is uncovered.
|
|
69
|
+
5. **Write the draft, gaps included.** An uncovered section ends with `**Prove it:** none` — explicitly, so a plan keeps its rows `Manual`. Name the uncovered surfaces in the header too (`**Uncovered:** api (unit tests only), admin (nothing)`), so the gap is visible without reading every section.
|
|
70
|
+
6. **Run it, and log every deviation.** Bring the product up and run the draft. Anything you do that is **not a step in the recipe** — an install, an export, a patch, a workaround, a second terminal — is a *deviation*, written down as you go. This is the only step where improvising is allowed, and it is never silent.
|
|
71
|
+
7. **Reconcile.** Every deviation becomes exactly one of two things: a step in the recipe, or the reason this surface is unprovable (`**Prove it:** none`). A recipe whose check passed only with help the recipe does not contain is wrong. If you cannot capture a deviation as a step, the surface is uncovered — say so rather than shipping a procedure nobody else can follow.
|
|
72
|
+
8. **Prove the procedure, not the day — with a fresh agent.** Hand the recipe to a run that has **nothing but the recipe and the config**: a new session, or a dispatched agent, but never this one. It is run once from a clean checkout, allowing no deviation. If you cannot get one, say the recipe is **unverified** rather than claiming it. That second run is the artifact. If it needs improvising, the recipe is wrong: fix it and repeat once; still failing means uncovered and visible.
|
|
73
|
+
9. **Report.** Per surface: its class, its proof, whether it was asked about, the deviations you reconciled, and what is still unknown. Mark a check you wrote as **unproven** if you never watched it fail — breaking the thing once is the way to earn that. Say plainly that `sassy-setup` flips `dogfood.enabled` and that the switch alone changes nothing.
|
|
55
74
|
|
|
56
75
|
## Steps — `mode:check`
|
|
57
76
|
|
|
@@ -70,6 +89,12 @@ Run the `sassy-setup` skill's `scripts/detect.sh --root <path> --check` and repo
|
|
|
70
89
|
| Env is not code | Exit 75/127, a missing dependency, or an unreachable service is `env`: report and park. Looping on a broken toolchain burns a run for nothing. |
|
|
71
90
|
| Resume, don't restart | Re-run from the failed step; the summary says where. Starting over hides the state that made the failure happen. |
|
|
72
91
|
| Reports are disposable | Pruned to ten. The durable record is the QA row's note, which names the verdict and the run id, never a path that will vanish. |
|
|
92
|
+
| Never promote what exists | A unit test, `lint`, or `build` is not a dogfood path. Discovery records what the product needs, and says so when that is nothing yet. |
|
|
93
|
+
| Improvise out loud, or not at all | Discovery may improvise, never silently: every action that is not a step is a deviation, and every deviation is promoted into a step or kills the surface. A run never improvises — it classifies and stops. |
|
|
94
|
+
| The second run is the artifact | A recipe is proven by a clean checkout that has nothing but the recipe. If it only works with the discoverer's context, it does not work. |
|
|
95
|
+
| Ask about every gap | Each uncovered surface gets one question: wrap a suite, add a runtime check, or leave it uncovered and visible. Silence is how a gap becomes a false green. |
|
|
96
|
+
| No third-party mutation | A run never registers a user, sends mail, charges a card, or writes to a shared service it does not own. A public demo API is somebody else's database. |
|
|
97
|
+
| No dependency churn | A bring-up never changes a lockfile. Install frozen where the project has one; a broken lockfile is `env`, not something to repair mid-run. |
|
|
73
98
|
| Not a test framework | If the project has a suite, the recipe wraps it. This skill never grows assertions of its own beyond a step's `Expect`. |
|
|
74
99
|
|
|
75
100
|
## What dogfood is not
|
|
@@ -19,7 +19,7 @@ The plan has no open-questions section. Every branch the interview found is a de
|
|
|
19
19
|
Every phase gets a QA table. Each row's `Mode` is `Auto` or `Manual`, and the choice is not a preference:
|
|
20
20
|
|
|
21
21
|
- **`Manual` is the default.** Write each row so a person can run it without reading code — what to set up, what to do, and what passing looks like.
|
|
22
|
-
- **`Auto` needs two things**: the project's `dogfood.enabled` is `true` (per the `sassy-setup` skill's `references/dogfood.md`) **and** the row names a recipe section
|
|
22
|
+
- **`Auto` needs two things**: the project's `dogfood.enabled` is `true` (per the `sassy-setup` skill's `references/dogfood.md`) **and** the row names a recipe section whose `**Prove it:**` names a step. One without the other stays `Manual`. A section whose `**Prove it:**` says `none` has no machine verdict by design — its rows are `Manual`, and writing `Auto` against it is a gate that proves nothing.
|
|
23
23
|
- An `Auto` row names the recipe **section**, never a command. Commands belong in the recipe; copied into a row they rot one row at a time.
|
|
24
24
|
|
|
25
25
|
A row stays `Manual` when the answer is genuinely a human's:
|
|
@@ -44,8 +44,8 @@ A check run never edits the config and never rewrites the tree: it prints what `
|
|
|
44
44
|
- **`commit.branch`** — default `new`: the run cuts a branch before the first change and never commits on a base branch. Offer `current` for a repo that genuinely wants work committed where it stands, and say plainly that `current` lets a run commit onto its base branch and push it, with no PR (`pr.*` and `hooks.pr` are ignored; `hooks.push` runs). Under `mode:auto` with `current` on a base branch, ship pushes to that base with no gate.
|
|
45
45
|
- **`pr.*`** — default `babysit: true`, `merge: false`, `delete_branch: false`. Say plainly that `merge: true` authorizes merging every babysat PR in this project without asking.
|
|
46
46
|
- **Hooks** — offer, do not impose. Ask whether the project wants steps injected at `before_create`, `after_create`, `before_merge`, or `after_merge` (or `hooks.push` `after_push`, for `commit.branch: current` only), and under which head branch (`"*"` for all). Entries may carry args (`<skill> <args…>`); a hook skill's args are its own vocabulary. Leave them `[]` when there is nothing to add. **Never write a hook skill yourself** — hooks are project skills, and copying one of ours into that role is the fork this mechanism exists to prevent.
|
|
47
|
-
- **Worktrees** — ask whether the project wants parallel work in this repo: a checkout per branch, each with its own derived namespace and port, so two runs never fight over one working tree. Say plainly what it costs and what it needs. `false` — the run works here, which is today's behaviour. `true` — a run may create a checkout, and `sassy-worktree` gains `create`, `list`, `preview`, `remove`, and `prune`. It needs `commit.branch: new`: under `current` nothing ever cuts a branch, so the switch would do nothing — say so and leave it `false` rather than writing a setting that cannot fire. In `workspace` or `none` topology, say it is not available and write `false`. Read `references/worktree.md`; **never write
|
|
48
|
-
- **Dogfood** — ask whether the project wants agent QA: a stored procedure that proves a change works in the running product, which then lets `sassy-plan` write `Mode: Auto` QA rows instead of manual ones. Say plainly what each answer means. `false` — every QA row stays a human's, which is today's behavior. `true` — a plan may write Auto rows, but only for a recipe section that carries a `Prove it:` step, so the switch alone never makes a gate prove something. Write the answer explicitly either way; never leave it to inference. On yes, scaffold per step 4. Read `references/dogfood.md` and **never** write a command into the block or author the procedure: the recipe is the project's, and its first real content comes from a `sassy-dogfood mode:discover` run.
|
|
47
|
+
- **Worktrees** — ask whether the project wants parallel work in this repo: a checkout per branch, each with its own derived namespace and port, so two runs never fight over one working tree. Say plainly what it costs and what it needs. `false` — the run works here, which is today's behaviour. `true` — a run may create a checkout, and `sassy-worktree` gains `create`, `list`, `preview`, `remove`, and `prune`. It needs `commit.branch: new`: under `current` nothing ever cuts a branch, so the switch would do nothing — say so and leave it `false` rather than writing a setting that cannot fire. In `workspace` or `none` topology, say it is not available and write `false`. Read `references/worktree.md`. **Say what a checkout will need for this project** — install, `.env` derivation, a per-namespace database, a simulator, the session — and offer to create the hook with `sassy-skill`; **never write its body yourself**. With no hook, say plainly that every new checkout starts empty and the first preview will show it.
|
|
48
|
+
- **Dogfood** — ask whether the project wants agent QA: a stored procedure that proves a change works in the running product, which then lets `sassy-plan` write `Mode: Auto` QA rows instead of manual ones. Say plainly what each answer means. `false` — every QA row stays a human's, which is today's behavior. `true` — a plan may write Auto rows, but only for a recipe section that carries a `Prove it:` step, so the switch alone never makes a gate prove something. Write the answer explicitly either way; never leave it to inference. On yes, scaffold per step 4 and offer to run the first `sassy-dogfood mode:discover` before this run ends: yes means do it now (it is the only step that knows how to bring this app up), no means hand over the command and say the recipe stays a skeleton until it runs. Read `references/dogfood.md` and **never** write a command into the block or author the procedure: the recipe is the project's, and its first real content comes from a `sassy-dogfood mode:discover` run.
|
|
49
49
|
4. **Write the config.** Build the file from the proposal plus the answers. It is written **fully commented**: every key keeps a description and its allowed values, exactly as the detector emits them. Never strip those comments to save lines — for a teammate opening the file, the comments are the documentation. If a config already exists, show what changes and ask before writing — never silently overwrite. Keep every key; an unset key falls back to its documented default, so a short file is legal when nothing deviates.
|
|
50
50
|
|
|
51
51
|
**The dogfood scaffold, only when the answer was yes.** Create `.sassywares/dogfood/` holding `recipe.md` copied verbatim from `assets/dogfood-recipe.md`, and `.sassywares/.gitignore` with two lines — `/session/` and `/dogfood/reports/` — adding them to a `.gitignore` that already exists rather than replacing it. Never overwrite an existing recipe — show it and ask. The skeleton is deliberately incomplete: it carries the shape and the rules and fills in nothing, because `sassy-dogfood mode:discover` writes the procedure from what actually worked. Say so in the report — `enabled: true` is a permission, not a promise that a check exists.
|
|
@@ -81,7 +81,7 @@ A check run never edits the config and never rewrites the tree: it prints what `
|
|
|
81
81
|
|
|
82
82
|
6. **Install the git tooling.** Two independent sets, each only when its answer was yes.
|
|
83
83
|
|
|
84
|
-
- **Worktrees, `repo` topology and `worktrees.enabled: true`.** Copy every file in `assets/worktree/` flat into `.sassywares/worktree/` and make the five scripts executable, then add one `worktree:<script>` alias per script to the project's manifest, append-only, exactly as the workspace aliases are. Report the `worktree-version` you installed. **Ask before overwriting any of them when they already exist** — from the first install they are the project's files. Read `references/worktree.md`. Do not create a worktree, and do not run a script: installing is the whole job, and the first `create` belongs to a run or to the user.
|
|
84
|
+
- **Worktrees, `repo` topology and `worktrees.enabled: true`.** Copy every file in `assets/worktree/` flat into `.sassywares/worktree/` and make the five scripts executable, then add one `worktree:<script>` alias per script to the project's manifest, append-only, exactly as the workspace aliases are. **Prove the merge**: the file must still parse (`node -p "require('./package.json')"`, or the manifest's own syntax check) and `git diff` must show only added lines plus at most one trailing comma — anything else is a rewrite, so restore the file from `HEAD` and insert again. Report the `worktree-version` you installed. **Ask before overwriting any of them when they already exist** — from the first install they are the project's files. Read `references/worktree.md`. Do not create a worktree, and do not run a script: installing is the whole job, and the first `create` belongs to a run or to the user.
|
|
85
85
|
- **Workspace, `workspace` topology only.** The snapshot plus the `branches` / `pull` / `checkout-bases` git helpers, and one `workspace:<script>` alias per script in the project's own manifest. Read `references/workspace.md` and follow it.
|
|
86
86
|
7. **Verify.** Run `scripts/detect.sh --root <path> --check`. It validates the config against the tree — topology and remotes, `base_map` shape and cycles, `repos` against each nested repo, hooks, artifacts paths, `knowledge`, `pr.*` booleans, `commit.branch`, the `worktrees` block, the `dogfood` block, any unknown key, and in `workspace` mode the installed snapshot's version — plus, for a project-scope install, the pin: every suite-skill folder in `.agents/skills` (a name in the suite's roster, `assets/roster` in sassy-setup, not any `sassy-` prefix) hashed against `skills-lock.json`, the lock's coverage both ways, and whether git carries the lock. A user-scope install has no pin here; the check notes the scope it found. Report every `drift:` line verbatim, or that the config matches the tree. Drift blocks step 8.
|
|
87
87
|
|
|
@@ -92,7 +92,7 @@ A check run never edits the config and never rewrites the tree: it prints what `
|
|
|
92
92
|
Then check the skills and the agents exactly as step 5's **Installed** rules say, and report the scope each was found in or what is missing. A check run never installs them; a missing suite or roster is reported with the fix (`mode:init`), and it does not block step 8.
|
|
93
93
|
8. **Commit what setup owns.** `repo` topology only, and only when step 7 is clean. The file list is exactly what setup wrote or found unwritten:
|
|
94
94
|
|
|
95
|
-
`.sassywares/config.yaml`, `.sassywares/README.md`, `.sassywares/dogfood/recipe.md` and `.sassywares/.gitignore` when step 4 created them, `.sassywares/worktree/*` when step 6 installed
|
|
95
|
+
`.sassywares/config.yaml`, `.sassywares/README.md`, `.sassywares/dogfood/recipe.md` and `.sassywares/.gitignore` when step 4 created them, `.sassywares/worktree/*` and `package.json` when step 6 installed the tooling and added its aliases, `.agents/skills/sassy-*` and `skills-lock.json` when the suite is in project scope, the project-scope agent files when step 5 copied them, and `.gitignore` when step 5 created it. Named files only — never `git add -A`, never `git add .`. The reports directory is never in this list: it is gitignored, and nothing setup writes lives there.
|
|
96
96
|
|
|
97
97
|
Dispatch `sassy-commit` with that list and `branch:current`. The token is explicit, not this skill's default: wiring is a one-time bootstrap commit, and cutting a branch would leave the project configured but uncommitted until someone ships it. Name the branch it landed on, base branch included.
|
|
98
98
|
|
|
@@ -7,7 +7,7 @@ never values>
|
|
|
7
7
|
|
|
8
8
|
**Reset:** <back to a known state>
|
|
9
9
|
|
|
10
|
-
**Preview:** <
|
|
10
|
+
**Preview:** <what you look at once it is up — `http://localhost:$WT_PORT`, a simulator name, a window. Not the command; that is a step below.>
|
|
11
11
|
|
|
12
12
|
<!--
|
|
13
13
|
Incomplete on purpose. sassy-setup writes this skeleton so the shape is visible;
|
|
@@ -100,7 +100,7 @@ wt_namespace() {
|
|
|
100
100
|
# under a home that survives a reboot. A second clone of the same project gets a
|
|
101
101
|
# suffixed folder instead of sharing this one.
|
|
102
102
|
wt_home() {
|
|
103
|
-
local dir base cand parent
|
|
103
|
+
local dir base cand parent owner
|
|
104
104
|
dir="$(wt_cfg dir "$HOME/.sassywares/worktrees")"
|
|
105
105
|
case "$dir" in
|
|
106
106
|
"~") dir="$HOME" ;;
|
|
@@ -114,18 +114,29 @@ wt_home() {
|
|
|
114
114
|
[ -d "$parent" ] && dir="$(cd "$parent" && pwd -P)/$(basename "$dir")"
|
|
115
115
|
base="$(basename "$MAIN")"
|
|
116
116
|
cand="$dir/$base"
|
|
117
|
-
if [ -f "$cand/.repo" ]
|
|
118
|
-
|
|
117
|
+
if [ -f "$cand/.repo" ]; then
|
|
118
|
+
owner="$(cat "$cand/.repo" 2>/dev/null || true)"
|
|
119
|
+
# Only a live checkout squats the plain name; a deleted one is reclaimed, so a
|
|
120
|
+
# finished project does not leave a hash-suffixed home behind forever.
|
|
121
|
+
if [ "$owner" != "$MAIN" ] && [ -n "$owner" ] && [ -d "$owner" ]; then
|
|
122
|
+
cand="$dir/$base-$(printf '%s' "$MAIN" | shasum -a 256 | cut -c1-6)"
|
|
123
|
+
fi
|
|
119
124
|
fi
|
|
120
125
|
printf '%s' "$cand"
|
|
121
126
|
}
|
|
122
127
|
|
|
123
128
|
wt_path() { printf '%s/%s' "$(wt_home)" "$1"; }
|
|
124
129
|
|
|
125
|
-
# ---
|
|
130
|
+
# --- resources ------------------------------------------------------------
|
|
131
|
+
# A port is one resource a checkout may need, not the definition of a preview. A
|
|
132
|
+
# mobile app claims a simulator, a desktop app nothing, and both are legitimate:
|
|
133
|
+
# when `worktrees.ports` is absent nothing is derived and nothing is claimed.
|
|
134
|
+
wt_has_ports() { [ -n "$(wt_cfg ports '')" ]; }
|
|
135
|
+
|
|
126
136
|
wt_range() {
|
|
127
137
|
local r lo hi
|
|
128
|
-
r="$(wt_cfg ports
|
|
138
|
+
r="$(wt_cfg ports '')"
|
|
139
|
+
[ -n "$r" ] || return 0
|
|
129
140
|
case "$r" in
|
|
130
141
|
*-*) lo="${r%%-*}"; hi="${r##*-}" ;;
|
|
131
142
|
*) lo="$r"; hi="$r" ;;
|
|
@@ -159,6 +170,7 @@ wt_owner() {
|
|
|
159
170
|
# one probed forward past claims held by others. Read-only, so `list` may call it.
|
|
160
171
|
wt_port_for() {
|
|
161
172
|
local slug="$1" lo hi span i port owner hex d
|
|
173
|
+
wt_has_ports || return 0
|
|
162
174
|
read -r lo hi <<<"$(wt_range)"
|
|
163
175
|
for d in "$(wt_home)/ports"/*; do
|
|
164
176
|
[ -d "$d" ] || continue
|
|
@@ -221,6 +233,24 @@ wt_find() { # $1 slug or branch -> path<TAB>branch, or nothing
|
|
|
221
233
|
done < <(wt_all)
|
|
222
234
|
}
|
|
223
235
|
|
|
236
|
+
# A checkout is ours when it lives under this repo's worktree home AND carries
|
|
237
|
+
# the wiring. Anything else — another tool's worktree, or one cut before setup
|
|
238
|
+
# was committed — is not managed here: we do not list it, prune it, or delete it.
|
|
239
|
+
wt_managed() { # $1 path
|
|
240
|
+
case "$1" in
|
|
241
|
+
"$(wt_home)"/*) [ -f "$1/.sassywares/config.yaml" ] ;;
|
|
242
|
+
*) return 1 ;;
|
|
243
|
+
esac
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
wt_require_managed() { # $1 slug or branch -> path<TAB>branch, or die
|
|
247
|
+
local rec
|
|
248
|
+
rec="$(wt_require "$1")"
|
|
249
|
+
wt_managed "${rec%%$'\t'*}" \
|
|
250
|
+
|| die "'$1' is not managed here — it is outside the worktree home, or it was cut before the wiring"
|
|
251
|
+
printf '%s' "$rec"
|
|
252
|
+
}
|
|
253
|
+
|
|
224
254
|
wt_require() { # $1 slug or branch -> path<TAB>branch, or die
|
|
225
255
|
local rec
|
|
226
256
|
rec="$(wt_find "$1")"
|
|
@@ -257,6 +287,42 @@ wt_upstream_state() { # merged | gone | unmerged
|
|
|
257
287
|
fi
|
|
258
288
|
}
|
|
259
289
|
|
|
290
|
+
# wt_subst LINE NAME VALUE — expand `$NAME`, `${NAME}` and `${NAME:-default}` for
|
|
291
|
+
# one variable. No name here is a prefix of another, so a plain replace is exact.
|
|
292
|
+
wt_subst() {
|
|
293
|
+
local line="$1" name="$2" val="$3"
|
|
294
|
+
if [ -n "$val" ]; then
|
|
295
|
+
printf '%s' "$line" \
|
|
296
|
+
| sed -e "s|\${$name:-[^}]*}|$val|g" -e "s|\${$name}|$val|g" -e "s|\$$name|$val|g"
|
|
297
|
+
else
|
|
298
|
+
printf '%s' "$line" \
|
|
299
|
+
| sed -e "s|\${$name:-\([^}]*\)}|\1|g" -e "s|\${$name}||g" -e "s|\$$name||g"
|
|
300
|
+
fi
|
|
301
|
+
}
|
|
302
|
+
|
|
303
|
+
# wt_preview SLUG — the recipe's `**Preview:**` line with WT_* substituted.
|
|
304
|
+
# Empty when the project has no recipe or no preview line.
|
|
305
|
+
wt_preview() {
|
|
306
|
+
local slug="$1" recipe line port base
|
|
307
|
+
recipe="$(wt_flat | awk -F'\t' -v p="dogfood${WLIB_US}recipe" '$1 == p { print $2; exit }')"
|
|
308
|
+
recipe="${recipe:-.sassywares/dogfood/recipe.md}"
|
|
309
|
+
case "$recipe" in /*) ;; *) recipe="$MAIN/$recipe" ;; esac
|
|
310
|
+
[ -f "$recipe" ] || return 0
|
|
311
|
+
line="$(sed -n 's/^\*\*Preview:\*\*[[:space:]]*//p' "$recipe" 2>/dev/null | head -n 1)"
|
|
312
|
+
[ -n "$line" ] || return 0
|
|
313
|
+
port=""
|
|
314
|
+
if wt_has_ports; then
|
|
315
|
+
port="$(wt_port_for "$slug")"
|
|
316
|
+
base="http://localhost:$port"
|
|
317
|
+
fi
|
|
318
|
+
line="$(wt_subst "$line" WT_SLUG "$slug")"
|
|
319
|
+
line="$(wt_subst "$line" WT_NAMESPACE "$(wt_namespace "$slug")")"
|
|
320
|
+
line="$(wt_subst "$line" WT_PATH "$(wt_path "$slug")")"
|
|
321
|
+
line="$(wt_subst "$line" WT_PORT "$port")"
|
|
322
|
+
line="$(wt_subst "$line" WT_BASE_URL "$base")"
|
|
323
|
+
printf '%s' "$line"
|
|
324
|
+
}
|
|
325
|
+
|
|
260
326
|
# Newest dogfood verdict for a checkout, as `status class` — or empty.
|
|
261
327
|
wt_verdict() {
|
|
262
328
|
local dir="$1/.sassywares/dogfood/reports" newest s c
|
|
@@ -50,20 +50,34 @@ slug="$(wt_slug "$branch")"
|
|
|
50
50
|
path="$(wt_path "$slug")"
|
|
51
51
|
|
|
52
52
|
report() { # $1 path, $2 branch
|
|
53
|
-
local port addr ns
|
|
53
|
+
local port="" addr="" ns
|
|
54
54
|
ns="$(wt_namespace "$slug")"
|
|
55
|
-
port
|
|
56
|
-
|
|
55
|
+
# A port is a resource this project asked for, not a property of a checkout.
|
|
56
|
+
if wt_has_ports; then
|
|
57
|
+
port="$(wt_claim "$slug")"
|
|
58
|
+
addr="http://localhost:$port"
|
|
59
|
+
fi
|
|
57
60
|
if [ "$env_only" -eq 1 ]; then
|
|
58
|
-
printf 'WT_PATH=%s\nWT_BRANCH=%s\nWT_SLUG=%s\nWT_NAMESPACE=%s\
|
|
59
|
-
|
|
61
|
+
printf 'WT_PATH=%s\nWT_BRANCH=%s\nWT_SLUG=%s\nWT_NAMESPACE=%s\n' "$1" "$2" "$slug" "$ns"
|
|
62
|
+
[ -n "$port" ] && printf 'WT_PORT=%s\nWT_BASE_URL=%s\n' "$port" "$addr"
|
|
60
63
|
return 0
|
|
61
64
|
fi
|
|
62
65
|
ok worktree "$1"
|
|
63
66
|
ok branch "$2"
|
|
64
67
|
ok namespace "$ns"
|
|
65
|
-
|
|
66
|
-
|
|
68
|
+
if [ -n "$port" ]; then
|
|
69
|
+
ok port "$port"
|
|
70
|
+
ok address "$addr"
|
|
71
|
+
else
|
|
72
|
+
ok port "none — worktrees.ports is unset, so this checkout holds no port"
|
|
73
|
+
fi
|
|
74
|
+
local preview
|
|
75
|
+
preview="$(wt_preview "$slug")"
|
|
76
|
+
[ -n "$preview" ] && ok preview "$preview"
|
|
77
|
+
# A branch cut from a ref that predates setup has no config and no tooling, so
|
|
78
|
+
# this checkout is not managed here: `list` skips it, `prune` leaves it alone.
|
|
79
|
+
[ -f "$1/.sassywares/config.yaml" ] \
|
|
80
|
+
|| ok unmanaged "this branch has no .sassywares/config.yaml — cut from a ref that predates setup; list and prune will skip it"
|
|
67
81
|
local hooks n
|
|
68
82
|
hooks="$(wt_hook after_create "$2")"
|
|
69
83
|
if [ -z "$hooks" ]; then
|
|
@@ -28,7 +28,7 @@ while [ $# -gt 0 ]; do
|
|
|
28
28
|
case "$1" in
|
|
29
29
|
-h|--help) usage; exit 0 ;;
|
|
30
30
|
--version) printf '%s\n' "$WT_VERSION"; exit 0 ;;
|
|
31
|
-
--address|--path) kind="${1#--}"; shift; want="${1:-}"; [ -n "$want" ] || die "$kind needs a slug" ;;
|
|
31
|
+
--address|--path|--preview) kind="${1#--}"; shift; want="${1:-}"; [ -n "$want" ] || die "$kind needs a slug" ;;
|
|
32
32
|
-*) die "unknown flag: $1 (try --help)" ;;
|
|
33
33
|
*) die "unexpected argument: $1 (try --help)" ;;
|
|
34
34
|
esac
|
|
@@ -38,7 +38,7 @@ done
|
|
|
38
38
|
need_git
|
|
39
39
|
|
|
40
40
|
one() { # $1 path, $2 branch
|
|
41
|
-
local p="$1" b="$2" slug port
|
|
41
|
+
local p="$1" b="$2" slug port line
|
|
42
42
|
slug="$(wt_slug "$b")"
|
|
43
43
|
if wt_is_main "$p"; then
|
|
44
44
|
die "the main checkout has no derived port — it uses whatever the app defaults to"
|
|
@@ -46,33 +46,56 @@ one() { # $1 path, $2 branch
|
|
|
46
46
|
case "$kind" in
|
|
47
47
|
path) printf '%s\n' "$p" ;;
|
|
48
48
|
address)
|
|
49
|
+
wt_has_ports || die "no port resource here — worktrees.ports is unset; try --preview"
|
|
49
50
|
port="$(wt_port_for "$slug")"
|
|
50
51
|
printf 'http://localhost:%s\n' "$port"
|
|
51
52
|
;;
|
|
53
|
+
preview)
|
|
54
|
+
line="$(wt_preview "$slug")"
|
|
55
|
+
[ -n "$line" ] || die "no preview line for '$slug' — add one to dogfood.recipe"
|
|
56
|
+
printf '%s\n' "$line"
|
|
57
|
+
;;
|
|
52
58
|
esac
|
|
53
59
|
}
|
|
54
60
|
|
|
55
61
|
if [ -n "$kind" ]; then
|
|
56
|
-
rec="$(
|
|
62
|
+
rec="$(wt_require_managed "$want")"
|
|
57
63
|
one "${rec%%$'\t'*}" "${rec##*$'\t'}"
|
|
58
64
|
exit 0
|
|
59
65
|
fi
|
|
60
66
|
|
|
61
|
-
printf ' %-34s %-50s %-
|
|
67
|
+
printf ' %-34s %-50s %-40s %-5s %s\n' "BRANCH" "WORKTREE" "HOW TO SEE" "LIVE" "LAST RUN"
|
|
62
68
|
count=0
|
|
69
|
+
unmanaged=0
|
|
63
70
|
while IFS=$'\t' read -r p b; do
|
|
64
71
|
[ -n "$p" ] || continue
|
|
65
72
|
count=$(( count + 1 ))
|
|
66
73
|
slug="$(wt_slug "$b")"
|
|
67
74
|
shown="${p/#$HOME/~}"
|
|
68
75
|
if wt_is_main "$p"; then
|
|
69
|
-
printf ' %-34s %-50s %-
|
|
76
|
+
printf ' %-34s %-50s %-40s %-5s %s\n' "$b (main checkout)" "$shown" "—" "—" "—"
|
|
77
|
+
continue
|
|
78
|
+
fi
|
|
79
|
+
if ! wt_managed "$p"; then
|
|
80
|
+
unmanaged=$(( unmanaged + 1 ))
|
|
70
81
|
continue
|
|
71
82
|
fi
|
|
72
|
-
|
|
73
|
-
|
|
83
|
+
# The address is whatever the project says it is: a URL, a simulator, a window.
|
|
84
|
+
line="$(wt_preview "$slug")"
|
|
85
|
+
port=""
|
|
86
|
+
if wt_has_ports; then
|
|
87
|
+
port="$(wt_port_for "$slug")"
|
|
88
|
+
[ -n "$line" ] || line="http://localhost:$port"
|
|
89
|
+
fi
|
|
90
|
+
if [ -n "$port" ]; then
|
|
91
|
+
if tcp_up "$port"; then live="up"; else live="down"; fi
|
|
92
|
+
else
|
|
93
|
+
live="—"
|
|
94
|
+
fi
|
|
74
95
|
last="$(wt_verdict "$p")"
|
|
75
|
-
printf ' %-34s %-50s %-
|
|
96
|
+
printf ' %-34s %-50s %-40s %-5s %s\n' "$b" "$shown" "${line:-—}" "$live" "${last:-—}"
|
|
76
97
|
done < <(wt_all)
|
|
77
98
|
|
|
78
99
|
[ "$count" -gt 0 ] || log " no checkouts found — is this a git repository?"
|
|
100
|
+
[ "$unmanaged" -gt 0 ] && hint "$unmanaged worktree(s) not managed here — outside $(wt_home | sed "s|$HOME|~|"), or cut before the wiring"
|
|
101
|
+
true
|
|
@@ -39,15 +39,21 @@ need_git
|
|
|
39
39
|
printf ' %-32s %-9s %-6s %-9s %s\n' "BRANCH" "UPSTREAM" "DIRTY" "UNPUSHED" "ACTION"
|
|
40
40
|
n_candidates=0
|
|
41
41
|
n_removed=0
|
|
42
|
+
unmanaged=0
|
|
42
43
|
while IFS=$'\t' read -r p b; do
|
|
43
44
|
[ -n "$p" ] || continue
|
|
44
45
|
wt_is_main "$p" && continue
|
|
46
|
+
wt_managed "$p" || { unmanaged=$(( unmanaged + 1 )); continue; }
|
|
45
47
|
slug="$(wt_slug "$b")"
|
|
46
48
|
state="$(wt_upstream_state "$p")"
|
|
47
49
|
if wt_dirty "$p"; then dirty="yes"; else dirty="no"; fi
|
|
48
50
|
unpushed="$(wt_unpushed "$p")"
|
|
49
|
-
port="
|
|
50
|
-
|
|
51
|
+
port=""
|
|
52
|
+
live="no"
|
|
53
|
+
if wt_has_ports; then
|
|
54
|
+
port="$(wt_port_for "$slug")"
|
|
55
|
+
tcp_up "$port" && live="yes"
|
|
56
|
+
fi
|
|
51
57
|
|
|
52
58
|
action=""
|
|
53
59
|
if [ "$state" = "unmerged" ]; then
|
|
@@ -57,7 +63,7 @@ while IFS=$'\t' read -r p b; do
|
|
|
57
63
|
elif [ "$unpushed" != "0" ]; then
|
|
58
64
|
action="skipped — $unpushed unpushed"
|
|
59
65
|
elif [ "$live" = "yes" ]; then
|
|
60
|
-
action="skipped — running on :$port"
|
|
66
|
+
action="skipped — running${port:+ on :$port}"
|
|
61
67
|
else
|
|
62
68
|
action="removable"
|
|
63
69
|
n_candidates=$(( n_candidates + 1 ))
|
|
@@ -71,7 +77,9 @@ while IFS=$'\t' read -r p b; do
|
|
|
71
77
|
warn skipped "$b has a before_remove hook — run remove <$slug> so it runs"
|
|
72
78
|
continue
|
|
73
79
|
fi
|
|
74
|
-
git worktree remove "$p"
|
|
80
|
+
git worktree remove "$p" || continue
|
|
81
|
+
[ -n "$port" ] && wt_release "$port" "$slug"
|
|
82
|
+
n_removed=$(( n_removed + 1 ))
|
|
75
83
|
fi
|
|
76
84
|
done < <(wt_all)
|
|
77
85
|
|
|
@@ -79,6 +87,6 @@ if [ "$yes" -eq 1 ]; then
|
|
|
79
87
|
ok pruned "$n_removed removed, $(( n_candidates - n_removed )) left"
|
|
80
88
|
elif [ "$n_candidates" -gt 0 ]; then
|
|
81
89
|
hint "re-run with --yes to remove the $n_candidates removable worktree(s)"
|
|
82
|
-
|
|
83
|
-
|
|
90
|
+
[ "$unmanaged" -gt 0 ] && hint "$unmanaged worktree(s) not managed here — left alone"
|
|
91
|
+
[ "$n_candidates" -eq 0 ] && [ "$unmanaged" -eq 0 ] && ok pruned "nothing to remove"
|
|
84
92
|
fi
|
|
@@ -42,7 +42,7 @@ done
|
|
|
42
42
|
[ -n "$target" ] || { usage >&2; exit 2; }
|
|
43
43
|
|
|
44
44
|
need_git
|
|
45
|
-
rec="$(
|
|
45
|
+
rec="$(wt_require_managed "$target")"
|
|
46
46
|
path="${rec%%$'\t'*}"
|
|
47
47
|
branch="${rec##*$'\t'}"
|
|
48
48
|
slug="$(wt_slug "$branch")"
|
|
@@ -59,9 +59,12 @@ if [ -n "$hooks" ] && [ "$hook_ok" -eq 0 ]; then
|
|
|
59
59
|
exit 3
|
|
60
60
|
fi
|
|
61
61
|
|
|
62
|
-
port="
|
|
63
|
-
if
|
|
64
|
-
|
|
62
|
+
port=""
|
|
63
|
+
if wt_has_ports; then
|
|
64
|
+
port="$(wt_port_for "$slug")"
|
|
65
|
+
if tcp_up "$port"; then
|
|
66
|
+
die "something is still listening on :$port — stop <$slug> first"
|
|
67
|
+
fi
|
|
65
68
|
fi
|
|
66
69
|
|
|
67
70
|
if [ "$force" -eq 0 ]; then
|
|
@@ -79,7 +82,7 @@ if [ "$force" -eq 1 ]; then
|
|
|
79
82
|
else
|
|
80
83
|
git worktree remove "$path"
|
|
81
84
|
fi
|
|
82
|
-
wt_release "$port" "$slug"
|
|
85
|
+
[ -n "$port" ] && wt_release "$port" "$slug"
|
|
83
86
|
|
|
84
|
-
ok released ":$port"
|
|
87
|
+
[ -n "$port" ] && ok released ":$port"
|
|
85
88
|
ok removed "$path"
|
|
@@ -16,7 +16,9 @@ usage() {
|
|
|
16
16
|
Usage: .sassywares/worktree/stop <slug|branch>
|
|
17
17
|
|
|
18
18
|
Kill the processes listening on that worktree's port. Nothing listening is a
|
|
19
|
-
success with a note, so stopping twice is safe.
|
|
19
|
+
success with a note, so stopping twice is safe. Only a project that configured
|
|
20
|
+
`worktrees.ports` has something here to stop — for a simulator or a desktop app,
|
|
21
|
+
stopping belongs to the project.
|
|
20
22
|
EOF
|
|
21
23
|
}
|
|
22
24
|
|
|
@@ -27,12 +29,13 @@ case "${1:-}" in
|
|
|
27
29
|
esac
|
|
28
30
|
|
|
29
31
|
need_git
|
|
30
|
-
rec="$(
|
|
32
|
+
rec="$(wt_require_managed "$1")"
|
|
31
33
|
path="${rec%%$'\t'*}"
|
|
32
34
|
branch="${rec##*$'\t'}"
|
|
33
35
|
slug="$(wt_slug "$branch")"
|
|
34
36
|
|
|
35
|
-
wt_is_main "$path" && die "the main checkout
|
|
37
|
+
wt_is_main "$path" && die "the main checkout is not a worktree — nothing to stop"
|
|
38
|
+
wt_has_ports || die "no port resource here — stopping this preview is the project's job (its before_remove hook or the recipe)"
|
|
36
39
|
port="$(wt_port_for "$slug")"
|
|
37
40
|
|
|
38
41
|
if ! tcp_up "$port"; then
|
|
@@ -86,7 +86,7 @@ hooks:
|
|
|
86
86
|
worktrees:
|
|
87
87
|
enabled: false # true = a run may work in its own checkout
|
|
88
88
|
dir: ~/.sassywares/worktrees # parent of the per-repo folder; ~ is allowed here
|
|
89
|
-
ports: 3000-3099 #
|
|
89
|
+
ports: 3000-3099 # optional; delete for a non-port preview
|
|
90
90
|
dogfood:
|
|
91
91
|
enabled: false # true = sassy-plan writes Mode: Auto QA rows
|
|
92
92
|
recipe: .sassywares/dogfood/recipe.md # the procedure
|
|
@@ -119,7 +119,7 @@ dogfood:
|
|
|
119
119
|
| `dogfood.timeout` | `900` | Wall-clock for one run. A timeout is a failure, never a hang |
|
|
120
120
|
| `worktrees.enabled` | `false` | `true` lets a run work in its own checkout instead of this one. Needs `commit.branch: new` |
|
|
121
121
|
| `worktrees.dir` | `~/.sassywares/worktrees` | Parent of the per-repo worktree folder. The one path here that may be absolute or `~/` |
|
|
122
|
-
| `worktrees.ports` | `3000-3099` | The range a checkout claims its private port from |
|
|
122
|
+
| `worktrees.ports` | `3000-3099` | The range a checkout claims its private port from. **Optional**: without it a checkout holds no port and is addressed by the recipe's preview line — which is how a mobile, desktop, or CLI project previews |
|
|
123
123
|
|
|
124
124
|
Paths are relative to the config's own directory, never to the cwd.
|
|
125
125
|
|
|
@@ -407,7 +407,11 @@ worktrees:
|
|
|
407
407
|
```
|
|
408
408
|
|
|
409
409
|
Three keys, no commands. The scripts in `.sassywares/worktree/` own the
|
|
410
|
-
mechanics and `sassy-worktree` orchestrates them.
|
|
410
|
+
mechanics and `sassy-worktree` orchestrates them.
|
|
411
|
+
|
|
412
|
+
**A port is a resource, not the model.** Delete `ports` for an app whose preview
|
|
413
|
+
is not a URL: no port is derived, `WT_PORT` and `WT_BASE_URL` are absent, and
|
|
414
|
+
`list` shows the recipe's `**Preview:**` line instead. `dir` is the one path in this
|
|
411
415
|
file that may be absolute or start with `~/` — it names machine-local state, not
|
|
412
416
|
something a teammate clones.
|
|
413
417
|
|
|
@@ -471,8 +475,8 @@ report layout, the verdict classes, and the lint are in
|
|
|
471
475
|
- `hooks` is allowed only with the four points under `hooks.pr`, `after_push`
|
|
472
476
|
under `hooks.push`, and `after_create`/`before_remove` under `hooks.worktree`,
|
|
473
477
|
each a list of skill names that resolve to `.agents/skills/<name>/SKILL.md`.
|
|
474
|
-
- `worktrees.enabled` is `true` or `false`; `worktrees.ports` is
|
|
475
|
-
inside 1–65535 with `<from>` no greater than `<to>`. A checkout must resolve
|
|
478
|
+
- `worktrees.enabled` is `true` or `false`; when `worktrees.ports` is present it
|
|
479
|
+
is `<from>-<to>` inside 1–65535 with `<from>` no greater than `<to>`. A checkout must resolve
|
|
476
480
|
outside the working tree, must not hold a branch `base_map` names as a base,
|
|
477
481
|
and must not leave a port claimed by a worktree that no longer exists. An
|
|
478
482
|
`enabled: true` with no tooling installed, or with the wrong tooling version,
|
|
@@ -70,7 +70,12 @@ copy `.env.example` → `.env` and fill `DOGFOOD_USER`, `DOGFOOD_PASS`.
|
|
|
70
70
|
|
|
71
71
|
**Reset:** `bun run db:reset`; `rm -rf .sassywares/dogfood/reports/*`
|
|
72
72
|
|
|
73
|
-
**Preview:**
|
|
73
|
+
**Preview:** open `http://localhost:${WT_PORT:-3000}`
|
|
74
|
+
|
|
75
|
+
**Upstream:** `api.example.com` — a service this run does not control. Down is
|
|
76
|
+
`env`, never a retry.
|
|
77
|
+
|
|
78
|
+
**Uncovered:** mobile (nothing), admin (unit tests only)
|
|
74
79
|
|
|
75
80
|
## catalog — a search returns matching products
|
|
76
81
|
|
|
@@ -101,14 +106,45 @@ a check, and `--check` reports it as drift. `Do` is a command *or* an
|
|
|
101
106
|
instruction ("open `/catalog`, sign in as `DOGFOOD_USER`") — the instruction is
|
|
102
107
|
why the recipe outlives whatever tool the agent happens to have this quarter.
|
|
103
108
|
|
|
104
|
-
**One `Prove it:` per section**,
|
|
109
|
+
**One `Prove it:` per section**, naming a step (`step 5`) or saying `none`. A
|
|
110
|
+
named step's exit code is the verdict; `none` is a legal, explicit "this surface
|
|
111
|
+
has no machine verdict" — the section still records what a person should check,
|
|
112
|
+
and every QA row for it stays `Manual`.
|
|
113
|
+
|
|
114
|
+
**Steps after the `Prove it:` step are cleanup.** They always run, they never
|
|
115
|
+
change the exit code, and that is where a port is freed or a process is stopped.
|
|
116
|
+
Putting teardown before the verdict means a failed run leaves the port held. Steps before
|
|
105
117
|
it set up state and assert along the way; the prove step is the machine-readable
|
|
106
118
|
answer. A section without one has no verdict.
|
|
107
119
|
|
|
108
|
-
**One `**Preview:**` line**, optional:
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
is
|
|
120
|
+
**One `**Preview:**` line**, optional: **what you look at**, not the command that
|
|
121
|
+
starts it. The command belongs in the section's steps, where its `Expect` can be
|
|
122
|
+
checked. The result — a URL, a simulator, a window — is the project's own answer
|
|
123
|
+
to "what is the address", and it is why the suite never has to assume a browser.
|
|
124
|
+
|
|
125
|
+
`$WT_SLUG`, `$WT_NAMESPACE`, `$WT_PATH`, `$WT_PORT`, and `$WT_BASE_URL` are
|
|
126
|
+
substituted into the preview line and into every step. The last two exist only
|
|
127
|
+
when `worktrees.ports` is configured, and a recipe must also run in the **main
|
|
128
|
+
checkout**, where no worktree exists — so write the port with the project's own
|
|
129
|
+
default: `${WT_PORT:-5180}`. One expansion that works in both places is what
|
|
130
|
+
keeps a recipe runnable outside a worktree.
|
|
131
|
+
|
|
132
|
+
| Project | Preview line |
|
|
133
|
+
|---|---|
|
|
134
|
+
| Web | `http://localhost:${WT_PORT:-5180}` |
|
|
135
|
+
| Mobile | `simulator "$WT_NAMESPACE"` — booted by the `after_create` hook |
|
|
136
|
+
| Desktop | `the app window is already open` |
|
|
137
|
+
| CLI | *(none — there is nothing to look at)* |
|
|
138
|
+
|
|
139
|
+
**`**Upstream:**` and `**Uncovered:**`** are optional header lines that make the
|
|
140
|
+
two dangerous facts visible without reading every step: which third-party services
|
|
141
|
+
the recipe depends on, and which parts have no machine verdict at all. `Uncovered`
|
|
142
|
+
may name a sub-area of a covered surface — "the web surface's auth and write
|
|
143
|
+
flows" — which is where a no-third-party-mutation rule usually lands. A section
|
|
144
|
+
with no verdict ends `**Prove it:** none`, so a plan keeps its rows `Manual`
|
|
145
|
+
instead of inventing an Auto row for a check that does not exist.
|
|
146
|
+
|
|
147
|
+
Prose, like every other line here: no tool, no schema.
|
|
112
148
|
|
|
113
149
|
**Rules.**
|
|
114
150
|
|
|
@@ -118,12 +154,22 @@ is prose, like every other line here: no tool, no schema.
|
|
|
118
154
|
step needs one, it names the variable and the project's own gitignored env file
|
|
119
155
|
holds the value.
|
|
120
156
|
- **Local or staging only.** A recipe that names production is a bug.
|
|
157
|
+
- **A prerequisite carries its command.** *Set up once* is commands, not prose: a
|
|
158
|
+
required Node, JDK, or database names the command that provides it (`nvm use 24`)
|
|
159
|
+
as well as the requirement. A run may not improvise activation, so a stated
|
|
160
|
+
requirement with no command only works on machines that happen to be ready.
|
|
161
|
+
- **No dependency churn.** *Set up once* installs frozen when a lockfile exists.
|
|
162
|
+
A broke lockfile is `env`; repairing it silently re-resolves versions and makes
|
|
163
|
+
every checkout dirty.
|
|
164
|
+
- **No third-party mutation.** A step never registers a user, sends mail, or
|
|
165
|
+
writes to a shared service. Log in by hand and copy the session in.
|
|
121
166
|
- **The happy path plus its checks.** Debris ("metro holds 8081") is a learning,
|
|
122
167
|
not a step: it goes to `artifacts.solutions` via `sassy-compound`, which
|
|
123
168
|
scouting already reads. This is what keeps a busy project's recipe at forty
|
|
124
169
|
lines instead of becoming a wiki.
|
|
125
|
-
- **No
|
|
126
|
-
|
|
170
|
+
- **No harness tools.** Never "use Playwright" or "use the Chrome MCP" — a driver,
|
|
171
|
+
MCP server, or emulator is a harness choice, not a procedure. Ordinary shell
|
|
172
|
+
utilities (`curl`, `lsof`, `grep`) are fine: they are how a step is written.
|
|
127
173
|
|
|
128
174
|
## Sessions, and a second checkout
|
|
129
175
|
|
|
@@ -188,11 +234,15 @@ A killed session therefore leaves an accurate breadcrumb, and the next one reads
|
|
|
188
234
|
one file to know where it stopped.
|
|
189
235
|
|
|
190
236
|
- **`status`** — `running` | `pass` | `failed`.
|
|
191
|
-
- **`class`** — `code` (a finding for the rework cycle) | `env` (the
|
|
192
|
-
|
|
237
|
+
- **`class`** — `code` (a finding for the rework cycle) | `env` (the environment
|
|
238
|
+
cannot produce a verdict: a missing dependency, exit 75 or 127, or a third-party
|
|
239
|
+
service nobody in this run owns being down — report and park, never loop) |
|
|
193
240
|
`recipe` (the procedure itself is stale: a renamed script, a dead URL, a step
|
|
194
241
|
that cannot be followed). `recipe` is the rot signal: the run proposes a
|
|
195
242
|
one-line diff and never quietly improvises around it.
|
|
243
|
+
- **A preflight or bring-up failure** has no step id: its log is `steps/00-setup.log`
|
|
244
|
+
and its table row is `setup`. It is a verdict about the environment, so it still
|
|
245
|
+
gets a `class`.
|
|
196
246
|
- **One log per executed step**, capped head-and-tail (~64 KB) with a
|
|
197
247
|
`[truncated N lines]` marker, so a runaway loop cannot fill the disk.
|
|
198
248
|
- **Redaction happens before the write.** Every value of an env var the recipe
|
|
@@ -240,6 +290,7 @@ Structural, never executed:
|
|
|
240
290
|
`.sassywares/session` whenever that directory exists — a committed session is a
|
|
241
291
|
credential leak, not a heavy history.
|
|
242
292
|
- The recipe has at least one `## ` section, every section has a `**Prove it:**`
|
|
243
|
-
line
|
|
244
|
-
secret-shaped strings.
|
|
293
|
+
line whose value names a step (`step 3`) or is `none`, every numbered step has an
|
|
294
|
+
`**Expect**`, and the file carries no secret-shaped strings. A `Prove it:` that
|
|
295
|
+
is neither is a typo, and a typo reads as a verdict.
|
|
245
296
|
- `dogfood.*` is a known key block; anything else in it is an unknown key.
|
|
@@ -50,6 +50,12 @@ DIR="$SW/<purpose>"
|
|
|
50
50
|
|
|
51
51
|
Name files so a run can find its own: a UTC timestamp, a short slug, and a short random suffix (`20261027T101500Z-fix-checkout-4f2a.txt`). The suffix keeps two harnesses writing in the same second apart, now that they share a folder. A clone or any temporary tree gets its own `mktemp -d` under `scratch/` for the same reason. Delete scratch you no longer need; `/tmp` clearing on reboot covers the rest. A new purpose gets a new row here, not a new top-level folder.
|
|
52
52
|
|
|
53
|
+
**A recipe may use fixed paths.** The timestamp-plus-suffix rule exists so two runs
|
|
54
|
+
never collide. A file a *recipe* re-runs — a dev-server log, a pid — must have the
|
|
55
|
+
same path every time, so a step may use a fixed name under `scratch/`, keyed by
|
|
56
|
+
`$WT_NAMESPACE` when the project uses worktrees (`scratch/<namespace>-dev.log`).
|
|
57
|
+
Predictability is the point there; uniqueness is the point everywhere else.
|
|
58
|
+
|
|
53
59
|
**Harness is not a path segment.** It is recorded inside the file where it still matters — a handoff carries `**Harness:**` so a reader knows which agent wrote it — and the resume command is generated for whoever is reading, not for the writer. When a file needs it:
|
|
54
60
|
|
|
55
61
|
```bash
|
|
@@ -44,6 +44,11 @@ overwriting an existing copy — from the first install it is the project's file
|
|
|
44
44
|
one path in the config that may be absolute or start with `~/` — it names
|
|
45
45
|
machine-local state, not something a teammate clones.
|
|
46
46
|
|
|
47
|
+
The folder is named after the repo. When another **live** clone of the same name
|
|
48
|
+
already owns it, this one takes `<repo>-<hash>` instead; a home whose recorded
|
|
49
|
+
owner no longer exists is reclaimed, so a finished project does not squat the name
|
|
50
|
+
for ever. `.repo` is what makes that decision, and `create` rewrites it.
|
|
51
|
+
|
|
47
52
|
**Never put checkouts inside `.git` or inside the working tree.** Inside `.git`
|
|
48
53
|
is undocumented and breaks where `.git` is a file (linked worktrees, submodules,
|
|
49
54
|
`--separate-git-dir`). Inside the working tree is destroyed by `git clean -xdf`
|
|
@@ -62,18 +67,29 @@ work; `remove` and `prune` are the only safe exits.
|
|
|
62
67
|
| `WT_BRANCH` | `feat/catalog` | the branch, as git names it |
|
|
63
68
|
| `WT_SLUG` | `feat-catalog` | the directory name, port key, registry key |
|
|
64
69
|
| `WT_NAMESPACE` | `shop-feat-catalog` | database schema, compose project, simulator name |
|
|
65
|
-
| `WT_PORT` | `3041` |
|
|
66
|
-
| `WT_BASE_URL` | `http://localhost:3041` |
|
|
70
|
+
| `WT_PORT` | `3041` | a private port — **only when `ports:` is configured** |
|
|
71
|
+
| `WT_BASE_URL` | `http://localhost:3041` | the URL on that port — same condition |
|
|
72
|
+
|
|
73
|
+
The same five names expand inside the recipe, including the dashed form
|
|
74
|
+
`${WT_PORT:-5180}` that makes a recipe runnable in the main checkout too.
|
|
67
75
|
|
|
68
76
|
Derived, never invented downstream: a hook that needs a database name uses
|
|
69
77
|
`$WT_NAMESPACE` rather than building its own, so two worktrees cannot collide by
|
|
70
78
|
accident.
|
|
71
79
|
|
|
72
|
-
**
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
80
|
+
**A port is a resource, not the model.** `worktrees.ports` is optional, and
|
|
81
|
+
deleting it is how a project says "my preview is not a URL". Then no port is
|
|
82
|
+
derived, nothing is claimed, `WT_PORT` and `WT_BASE_URL` are absent, and the
|
|
83
|
+
checkout is addressed by the recipe's `**Preview:**` line instead. That covers a
|
|
84
|
+
mobile app (a simulator named `$WT_NAMESPACE`), a desktop app (a window), and a
|
|
85
|
+
CLI or library (nothing to look at).
|
|
86
|
+
|
|
87
|
+
When a range *is* configured: the slug hashes into it, the claim is taken with an
|
|
88
|
+
atomic `mkdir`, and a collision probes forward one port at a time. A claim
|
|
89
|
+
belongs to a slug, so a restarted app returns to the same port and two slugs that
|
|
90
|
+
hash alike do not fight. `list` probes for liveness and never trusts a recorded
|
|
91
|
+
pid. Without a port there is nothing to probe, so `LIVE` reads `—` and stopping
|
|
92
|
+
the preview is the project's job — its `before_remove` hook, or the recipe.
|
|
77
93
|
|
|
78
94
|
## Hooks
|
|
79
95
|
|
|
@@ -100,10 +116,17 @@ records the name; the project writes the body.
|
|
|
100
116
|
|
|
101
117
|
## Previewing a worktree
|
|
102
118
|
|
|
103
|
-
`sassy-worktree mode:preview` brings the product up in a checkout and prints
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
119
|
+
`sassy-worktree mode:preview` brings the product up in a checkout and prints how
|
|
120
|
+
to see it, using the dogfood recipe's bring-up steps — everything up to, but not
|
|
121
|
+
including, that section's `Prove it:` step. It leaves the app running.
|
|
122
|
+
|
|
123
|
+
How to see it is the recipe's `**Preview:**` line with the namespace substituted,
|
|
124
|
+
so it is a URL, a simulator, or a window depending on the project and never a
|
|
125
|
+
guess by this tooling. `list` prints that same line in its `HOW TO SEE` column,
|
|
126
|
+
which is why the column is not called "address".
|
|
127
|
+
|
|
128
|
+
What stops a preview follows from the same split: kill it by port when there is
|
|
129
|
+
one, hand it to the project when there is not.
|
|
107
130
|
|
|
108
131
|
There is no separate preview configuration. How the app comes up is the recipe's
|
|
109
132
|
job, because it is the only place that knowledge is allowed to live.
|
|
@@ -126,9 +149,13 @@ writing down once in the recipe rather than rediscovering it.
|
|
|
126
149
|
| It is the main checkout | the repo itself |
|
|
127
150
|
| Dirty tree | uncommitted work |
|
|
128
151
|
| Commits on no remote | nothing to recover from |
|
|
129
|
-
| Something listening on its port | stop the app first |
|
|
152
|
+
| Something listening on its port | stop the app first (only when `ports:` is set) |
|
|
130
153
|
| A `before_remove` hook not yet run | the project has cleanup to do |
|
|
131
154
|
|
|
155
|
+
`remove` deletes the checkout, the port claim, and nothing else. **The branch
|
|
156
|
+
survives** — git keeps it, so the work is still reachable after the worktree is
|
|
157
|
+
gone. Deleting it is the user's call, or `pr.delete_branch`'s after a merge.
|
|
158
|
+
|
|
132
159
|
`--force` skips the dirty and unpushed checks and nothing else. It is never
|
|
133
160
|
implied.
|
|
134
161
|
|
|
@@ -194,7 +194,14 @@ recipe_lint() {
|
|
|
194
194
|
if (index($0, "-->")) incomment = 0
|
|
195
195
|
next
|
|
196
196
|
}
|
|
197
|
-
index($0, "**Prove it:**") {
|
|
197
|
+
index($0, "**Prove it:**") {
|
|
198
|
+
prove = 1
|
|
199
|
+
val = $0; sub(/^.*\*\*Prove it:\*\*[[:space:]]*/, "", val)
|
|
200
|
+
low = tolower(val)
|
|
201
|
+
if (low !~ /^none/ && low !~ /^step[[:space:]]+[0-9]/)
|
|
202
|
+
printf "a **Prove it:** line must name a step (`step 3`) or say `none` — got \"%s\"\n", val
|
|
203
|
+
next
|
|
204
|
+
}
|
|
198
205
|
/^## / {
|
|
199
206
|
if (sec != "" && !prove)
|
|
200
207
|
printf "section \"%s\" has no **Prove it:** line — it has no verdict\n", sname
|
|
@@ -725,6 +732,9 @@ if (( CHECK )); then
|
|
|
725
732
|
if [[ "$TOPOLOGY" != "repo" ]]; then
|
|
726
733
|
bad "worktrees.enabled needs a repo — this folder is '$TOPOLOGY', and a checkout needs git"
|
|
727
734
|
else
|
|
735
|
+
if [[ -z "$wt_ports" ]]; then
|
|
736
|
+
note " worktrees: no port resource — a checkout is addressed by the recipe's preview line"
|
|
737
|
+
fi
|
|
728
738
|
if [[ "$(yflat "commit${US}branch" 2>/dev/null || true)" == "current" ]]; then
|
|
729
739
|
note " worktrees.enabled with commit.branch: current — a run never cuts a branch, so no run creates one"
|
|
730
740
|
fi
|
|
@@ -748,6 +758,16 @@ if (( CHECK )); then
|
|
|
748
758
|
bad "worktrees.enabled but .sassywares/worktree/_lib.sh is missing — re-run setup"
|
|
749
759
|
fi
|
|
750
760
|
|
|
761
|
+
# A declared worktree hook is how a project prepares a checkout, so say
|
|
762
|
+
# that it resolved — silence reads as "nothing is configured".
|
|
763
|
+
for point in after_create before_remove; do
|
|
764
|
+
declared="$(yflat "hooks${US}worktree${US}*${US}${point}" 2>/dev/null || true)"
|
|
765
|
+
while IFS= read -r entry; do
|
|
766
|
+
[[ -n "$entry" ]] || continue
|
|
767
|
+
note " hooks.worktree.\"*\".$point: ${entry%% *}"
|
|
768
|
+
done < <(list_items "$declared")
|
|
769
|
+
done
|
|
770
|
+
|
|
751
771
|
# A checkout must live outside the working tree — inside it, `git clean
|
|
752
772
|
# -xdf` deletes uncommitted work and every scanner that ignores .gitignore
|
|
753
773
|
# crawls a second copy of the source. And a worktree parked on a configured
|
|
@@ -808,6 +828,12 @@ if (( CHECK )); then
|
|
|
808
828
|
# app is a validator nobody runs.
|
|
809
829
|
dg_enabled="$(block_value dogfood enabled || true)"
|
|
810
830
|
dg_recipe="$(block_value dogfood recipe || true)"
|
|
831
|
+
# The default path applies even when the key is absent: the scripts use it, so
|
|
832
|
+
# --check must lint what they will actually read. Only for a project that has
|
|
833
|
+
# dogfood on, or a recipe already sitting at the default, to avoid noise.
|
|
834
|
+
if [[ -z "$dg_recipe" ]] && { [[ "$dg_enabled" == "true" ]] || [[ -f "$ROOT/.sassywares/dogfood/recipe.md" ]]; }; then
|
|
835
|
+
dg_recipe=".sassywares/dogfood/recipe.md"
|
|
836
|
+
fi
|
|
811
837
|
dg_reports="$(block_value dogfood reports || true)"
|
|
812
838
|
dg_timeout="$(block_value dogfood timeout || true)"
|
|
813
839
|
case "$dg_enabled" in
|
|
@@ -1186,6 +1212,8 @@ EOF
|
|
|
1186
1212
|
printf ' # staging: main # uncomment when a branch releases somewhere else\n'
|
|
1187
1213
|
printf ' # release/*: main # a family of heads, longest prefix wins\n'
|
|
1188
1214
|
cat <<'EOF'
|
|
1215
|
+
# remote: owner/backup # workspace only: the snapshot mirror
|
|
1216
|
+
# mirror_branch: main # workspace only: the mirror's branch
|
|
1189
1217
|
|
|
1190
1218
|
# workspace only: each nested repo folder -> the base its PRs target
|
|
1191
1219
|
# repos:
|
|
@@ -1258,8 +1286,8 @@ kv delete_branch false 24 '# true | false — delete the head branch once merged
|
|
|
1258
1286
|
cat <<'EOF'
|
|
1259
1287
|
|
|
1260
1288
|
# --- Hooks ----------------------------------------------------------------
|
|
1261
|
-
# Project steps injected into the PR pipeline,
|
|
1262
|
-
# commit.branch: current, keyed by the
|
|
1289
|
+
# Project steps injected into the PR pipeline, after a push under
|
|
1290
|
+
# commit.branch: current, or across a worktree's life, keyed by the branch — the
|
|
1263
1291
|
# branch the PR comes from, never the one it targets. `"*"` is the default;
|
|
1264
1292
|
# a name overrides per point, and `release/*` matches a family. Each entry is
|
|
1265
1293
|
# `<skill> <args…>`, resolved at .agents/skills/<name>/SKILL.md; args are passed
|
|
@@ -1280,20 +1308,28 @@ cat <<'EOF'
|
|
|
1280
1308
|
# push: # commit.branch: current only; keyed by the pushed branch
|
|
1281
1309
|
# "*":
|
|
1282
1310
|
# after_push: []
|
|
1311
|
+
# worktree: # worktrees only; keyed by the checkout's branch
|
|
1312
|
+
# "*":
|
|
1313
|
+
# after_create: [] # derive .env, seed the database, copy the session in
|
|
1314
|
+
# before_remove: [] # drop the database, shut the device
|
|
1283
1315
|
EOF
|
|
1284
1316
|
cat <<'EOF'
|
|
1285
1317
|
|
|
1286
1318
|
# --- Worktrees ------------------------------------------------------------
|
|
1287
1319
|
# Parallel work in one repo: a checkout per branch, each with its own derived
|
|
1288
|
-
# namespace
|
|
1289
|
-
#
|
|
1290
|
-
#
|
|
1291
|
-
#
|
|
1320
|
+
# namespace, so two runs never fight over one working tree. enabled: true lets a
|
|
1321
|
+
# run create one instead of working here — and needs commit.branch: new, because
|
|
1322
|
+
# `current` never cuts a branch. The scripts in .sassywares/worktree/ own the
|
|
1323
|
+
# mechanics; nothing else reads these values.
|
|
1324
|
+
#
|
|
1325
|
+
# A port is a resource, not the definition of a preview: delete `ports` for a
|
|
1326
|
+
# mobile, desktop, or CLI project, and the checkout is addressed by the recipe's
|
|
1327
|
+
# preview line instead (`$WT_NAMESPACE` names a simulator, a window, a path).
|
|
1292
1328
|
worktrees:
|
|
1293
1329
|
EOF
|
|
1294
1330
|
kv enabled false 34 '# true = a run may work in its own checkout'
|
|
1295
1331
|
kv dir '~/.sassywares/worktrees' 34 '# parent of the per-repo folder; ~ is allowed'
|
|
1296
|
-
kv ports 3000-3099 34 '#
|
|
1332
|
+
kv ports 3000-3099 34 '# a private port per checkout; delete for non-port previews'
|
|
1297
1333
|
cat <<'EOF'
|
|
1298
1334
|
|
|
1299
1335
|
# --- Dogfood --------------------------------------------------------------
|
|
@@ -23,7 +23,7 @@ argument-hint: "[slug] [mode:create|list|preview|remove|prune] [section:<name>]"
|
|
|
23
23
|
|
|
24
24
|
| Mode | What it does |
|
|
25
25
|
|------|--------------|
|
|
26
|
-
| `list` (default) | The table: branch, worktree,
|
|
26
|
+
| `list` (default) | The table: branch, worktree, how to see it, liveness, last dogfood verdict. Only managed checkouts appear; others are counted in a footer |
|
|
27
27
|
| `create` | Add a worktree for the run's branch, claim its port, dispatch `after_create` |
|
|
28
28
|
| `preview` | Bring that checkout up and print how to see it; leave it running. `stop` reaps it |
|
|
29
29
|
| `remove` | Dispatch `before_remove`, then delete after the script's refusals pass |
|
|
@@ -36,11 +36,11 @@ argument-hint: "[slug] [mode:create|list|preview|remove|prune] [section:<name>]"
|
|
|
36
36
|
1. **Resolve the branch and its start point first**, through the `sassy-setup` skill's `references/branching.md`, exactly as `sassy-work` does. A run that reaches here has already decided; the branch is not created twice. When a human asks for one by hand with no branch named, ask for the branch name — never derive one.
|
|
37
37
|
2. **Run `.sassywares/worktree/create <branch> --from <start-point>`** with the resolved start point. It is idempotent: an existing worktree for that branch is reported, a branch held by the main checkout is refused, and a port is claimed either way. On `--env` it prints the `WT_*` block alone.
|
|
38
38
|
3. **Dispatch the declared hooks.** The script prints one line per `hooks.worktree.after_create` entry; it cannot dispatch a skill, so you do. One `worker` each, in declared order: *load the project skill at `.agents/skills/<name>/SKILL.md` and follow it*, briefed with the `WT_*` block and the fact that the checkout now exists. A missing skill or a `blocked` result stops here — the checkout is real but unprepared, and saying so is the report.
|
|
39
|
-
4. **Report** the path, branch, namespace, port, address, and the hooks that ran or that none are declared. If the caller is a run, tell it to work in `WT_PATH` from now on.
|
|
39
|
+
4. **Report** the path, branch, namespace, port, address, the preview line, and the hooks that ran or that none are declared. If the caller is a run, tell it to work in `WT_PATH` from now on.
|
|
40
40
|
|
|
41
41
|
## `list`
|
|
42
42
|
|
|
43
|
-
Run `.sassywares/worktree/list` and present it as it prints — branch, worktree,
|
|
43
|
+
Run `.sassywares/worktree/list` and present it as it prints — branch, worktree, how to see it, live, last verdict. `--preview <slug>` prints how to see one checkout, `--path <slug>` its path, and `--address <slug>` its URL when the project configured ports. Never summarise the table away: how to see it is the point.
|
|
44
44
|
|
|
45
45
|
## `preview`
|
|
46
46
|
|
|
@@ -48,8 +48,8 @@ Run `.sassywares/worktree/list` and present it as it prints — branch, worktree
|
|
|
48
48
|
2. **Read the recipe** at `dogfood.recipe`. Two things stop the run, and both are reported rather than worked around: no recipe (the project has no stored procedure — say to run `sassy-dogfood mode:discover`), or the section has no `Prove it:` step (nothing marks where bringing-up ends).
|
|
49
49
|
3. **Preflight the session.** If the recipe's *Working in a second checkout* or *Set up once* names a session artifact and `.sassywares/session/` in **that checkout** is empty, that is `class: env`: report it with the line that fixes it and stop. Never open a logged-out app and call it a preview — the human will read the login screen as a broken build.
|
|
50
50
|
4. **Run the bring-up.** In `WT_PATH`: the recipe's *Set up once* when the checkout is cold (no `.env`, no installed deps), then the section's steps in order **up to but not including** its `Prove it:` step. Judge each step by its `Expect`. A failure stops the preview and is reported with the step id and its output tail — a preview that half-started is not a preview.
|
|
51
|
-
5. **Leave it running and report how to see it.**
|
|
52
|
-
6. **To stop it,** run `.sassywares/worktree/stop <slug
|
|
51
|
+
5. **Leave it running and report how to see it.** `list --preview <slug>` prints the recipe's `**Preview:**` line with the namespace substituted — the *result*, a URL or a simulator name or a window, never the command that started it. Print exactly that; never build an address yourself, and never assume one is a URL. When the project has ports and the preview answers on one, say it is up; when it does not, say it is running and that stopping it is the project's job.
|
|
52
|
+
6. **To stop it,** run `.sassywares/worktree/stop <slug>`. It kills by port, so it works only for a project that configured `worktrees.ports`; for a simulator or a window it says so instead of pretending.
|
|
53
53
|
|
|
54
54
|
Preview never judges the work, never writes a report, never commits, and never returns a verdict. If the user wants to know whether it *works*, that is `sassy-dogfood mode:run`.
|
|
55
55
|
|
|
@@ -57,7 +57,8 @@ Preview never judges the work, never writes a report, never commits, and never r
|
|
|
57
57
|
|
|
58
58
|
1. **Dispatch `before_remove` first**, one `worker` per declared entry, briefed with the `WT_*` block and that the checkout is about to go. Its job is the project's cleanup: drop the derived database, shut the simulator.
|
|
59
59
|
2. **Run `.sassywares/worktree/remove <slug> --hook-ok`.** Without `--hook-ok` it exits `3` by design when a hook is declared — that exit is the handshake, not an error to route around.
|
|
60
|
-
3. **
|
|
60
|
+
3. **Say what survives.** `remove` deletes the checkout and its port claim; the **branch stays**, so the work is still reachable. Naming that stops someone assuming the deletion took their commits with it.
|
|
61
|
+
4. **Report a refusal verbatim and stop.** Dirty tree, unpushed commits, a live preview, the main checkout: each is a real reason, and `--force` is the user's call, never yours. On success report the released port and the removed path.
|
|
61
62
|
|
|
62
63
|
## `prune`
|
|
63
64
|
|
|
@@ -71,10 +72,12 @@ Preview never judges the work, never writes a report, never commits, and never r
|
|
|
71
72
|
|------|-------------|
|
|
72
73
|
| The scripts do the git | Never run `git worktree`, never invent a port, never `rm -rf` a checkout. `.sassywares/worktree/*` owns all of it. |
|
|
73
74
|
| One worktree per run | The branch decision belongs to `references/branching.md`. Never create a second worktree for a run already on its branch. |
|
|
74
|
-
|
|
|
75
|
+
| Ours only | A checkout is managed when it sits under `worktrees.dir` **and** carries `.sassywares/config.yaml`. Never list, prune, stop, or remove one that is not — another tool made it, or it was cut before the wiring. `create` says so when that happens. |
|
|
76
|
+
| Names come from the script | `WT_NAMESPACE` is derived once, and `WT_PORT` only when the project configured a range. Never build a database name, a compose project, or a device name by hand. |
|
|
77
|
+
| A preview is not a URL | How to see a checkout is the recipe's preview line. A port is one resource among several; a mobile app's preview is a simulator, and this skill must not invent a URL for it. |
|
|
75
78
|
| Hooks are dispatched, not skipped | A declared `after_create` or `before_remove` runs. `remove` exits `3` rather than skipping it, and that is deliberate. |
|
|
76
79
|
| Never force on your behalf | `--force` skips the dirty and unpushed checks. Only the user's explicit instruction passes it. |
|
|
77
|
-
| Preview is a promise | Report
|
|
80
|
+
| Preview is a promise | Report a URL only when something answers on it. A half-started app is a failure with a step id, not a preview — and an app without a port gets its preview line, not a fabricated address. |
|
|
78
81
|
| No verdicts | This skill never says whether the work is correct. That is `sassy-dogfood`'s job, with a report. |
|
|
79
82
|
| No state of its own | Liveness is probed at read time. There is no registry, no pid file, and nothing to go stale. |
|
|
80
83
|
| Never production | A preview serves the local or staging app. A recipe step pointing at production is refused and reported. |
|