@sassywares/skills 0.9.0 → 0.11.0
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 +39 -4
- package/README.md +86 -6
- package/package.json +1 -1
- package/skills/sassy-commit/SKILL.md +1 -1
- package/skills/sassy-commit-push-pr/SKILL.md +1 -1
- package/skills/sassy-cycle/SKILL.md +1 -1
- package/skills/sassy-dogfood/SKILL.md +79 -0
- package/skills/sassy-handoff/SKILL.md +2 -1
- package/skills/sassy-handoff/references/read.md +1 -1
- package/skills/sassy-handoff/references/write.md +1 -1
- package/skills/sassy-lfg/SKILL.md +11 -8
- package/skills/sassy-plan/SKILL.md +6 -2
- package/skills/sassy-plan/references/plan-format.md +28 -8
- package/skills/sassy-scout/SKILL.md +4 -3
- package/skills/sassy-setup/SKILL.md +26 -9
- package/skills/sassy-setup/assets/dogfood-recipe.md +31 -0
- package/skills/sassy-setup/assets/roster +2 -0
- package/skills/sassy-setup/assets/worktree/_lib.sh +269 -0
- package/skills/sassy-setup/assets/worktree/create +104 -0
- package/skills/sassy-setup/assets/worktree/list +78 -0
- package/skills/sassy-setup/assets/worktree/prune +84 -0
- package/skills/sassy-setup/assets/worktree/remove +85 -0
- package/skills/sassy-setup/assets/worktree/stop +61 -0
- package/skills/sassy-setup/references/branching.md +19 -5
- package/skills/sassy-setup/references/config.md +104 -5
- package/skills/sassy-setup/references/dogfood.md +245 -0
- package/skills/sassy-setup/references/harness.md +14 -5
- package/skills/sassy-setup/references/worktree.md +151 -0
- package/skills/sassy-setup/scripts/detect.sh +261 -4
- package/skills/sassy-ship/SKILL.md +3 -0
- package/skills/sassy-work/SKILL.md +15 -11
- package/skills/sassy-worktree/SKILL.md +87 -0
|
@@ -12,7 +12,7 @@ argument-hint: "[path] [mode:init|check]"
|
|
|
12
12
|
|
|
13
13
|
# Sassy Setup
|
|
14
14
|
|
|
15
|
-
**Outcome:** `.sassywares/config.yaml` at the project root matching the tree it describes, the skills installed in user or project scope and visible to the harness, the sassy-agents roster installed for the running harness, the snapshot tooling installed in `workspace` mode, and every file setup wrote committed — so the project is wired and the user is good to go in one run.
|
|
15
|
+
**Outcome:** `.sassywares/config.yaml` at the project root matching the tree it describes, the dogfood scaffold when agent QA was asked for, the skills installed in user or project scope and visible to the harness, the sassy-agents roster installed for the running harness, the snapshot tooling installed in `workspace` mode, and every file setup wrote committed — so the project is wired and the user is good to go in one run.
|
|
16
16
|
|
|
17
17
|
**Read `references/config.md` first.** It is the schema and the resolution rules; this skill only decides and writes.
|
|
18
18
|
|
|
@@ -44,7 +44,11 @@ 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 a hook yourself** for the project's checkout prep.
|
|
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
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
|
+
|
|
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.
|
|
48
52
|
5. **Wire the skills and the agents.** Both install the same way: if they are already there in either scope, report which and move on; if not, ask once where to install, recommending user scope.
|
|
49
53
|
|
|
50
54
|
- **Skills.** The suite comes from upstream with the open `skills` CLI. Never copy skill files in by hand, never add the suite as a dependency.
|
|
@@ -71,26 +75,33 @@ A check run never edits the config and never rewrites the tree: it prints what `
|
|
|
71
75
|
**Installed** means all five `<name>.md` files exist in the user scope or the project scope. If they do, report which scope and move on. If any are missing, ask once where to install, recommending user scope:
|
|
72
76
|
|
|
73
77
|
- **User scope** — every project on this machine, updated by `git pull`. Reuse the user's sassy-agents checkout if they have one; otherwise ask where to clone it (`git clone https://github.com/sassywares/sassy-agents.git <dir>`). Then run `<dir>/scripts/install.sh <folder>`, which symlinks the folder into the user scope and never overwrites a differing file.
|
|
74
|
-
- **Project scope** — only this project, pinned with it. Shallow-clone into `/tmp/sassywares
|
|
78
|
+
- **Project scope** — only this project, pinned with it. Shallow-clone into its own `mktemp -d` under `/tmp/sassywares/scratch/` (two runs share that folder now, per `references/harness.md`), copy `<folder>/*.md` into the project scope directory, delete the clone. Never overwrite an existing agent file that differs: show it and ask. The copies join step 8's commit list.
|
|
75
79
|
|
|
76
80
|
- **Tell the user to `/reload`** (or restart the harness). The skills and agents are invisible to the harness until it rescans.
|
|
77
81
|
|
|
78
|
-
6. **Install the
|
|
79
|
-
|
|
82
|
+
6. **Install the git tooling.** Two independent sets, each only when its answer was yes.
|
|
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.
|
|
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
|
+
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
|
+
|
|
88
|
+
The `worktrees` half checks what a run would read: the switch and the port range, that the tooling is installed at the shipped version, that no checkout sits inside the working tree, that none holds a branch `base_map` names as a base, and that no port is still claimed by a worktree that no longer exists.
|
|
89
|
+
|
|
90
|
+
The `dogfood` half is structural and never runs the product: `enabled` and `timeout` are in range, the two paths are relative and stay inside the project, `reports` and `.sassywares/session` are gitignored in a `repo` topology, and the recipe has a `**Prove it:**` line per section with an `**Expect**` per step and no secret-shaped string. A recipe that does not exist yet is a note, not drift — unless `enabled` is `true`, which is the one combination that would let a planner write Auto rows against a check nobody has.
|
|
80
91
|
|
|
81
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.
|
|
82
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:
|
|
83
94
|
|
|
84
|
-
`.sassywares/config.yaml`, `.sassywares/README.md`, `.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 .`.
|
|
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 them, `.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.
|
|
85
96
|
|
|
86
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.
|
|
87
98
|
|
|
88
|
-
**Nothing else** unless the user asks: a plan, a doc, a source file, or anything already dirty in the tree stays uncommitted, because setup's commit is not a place to launder work in progress. A user who says "commit my plan too" widens the list with the file they named — never with a sweep for it. On a `check` run this fires only when something setup owns is dirty: an uncommitted pin, a config edited since the last commit. Nothing dirty, nothing to commit.
|
|
99
|
+
**Nothing else** unless the user asks: a plan, a doc, a source file, or anything already dirty in the tree stays uncommitted, because setup's commit is not a place to launder work in progress. A user who says "commit my plan too" widens the list with the file they named — never with a sweep for it. On a `check` run this fires only when something setup owns is dirty: an uncommitted pin, a config edited since the last commit, a scaffold nobody committed. Nothing dirty, nothing to commit.
|
|
89
100
|
|
|
90
101
|
- **`workspace`** — nothing to commit: the root is not a repo, and `references/workspace.md` forbids running the snapshot here. Say the root config and the pin land with the project's next snapshot.
|
|
91
102
|
- **`none`** — nothing to commit, deliberately.
|
|
92
103
|
|
|
93
|
-
9. **Report.** The config path, the topology, the resolved artifact and knowledge paths, where the skills are installed (scope) and where the agents are (scope and harness), or why either is not, the commit (hash and branch) or why there is none, and in `workspace` mode what was installed, with versions (`snapshot vN`, `workspace-git vN`), and the manifest the `workspace:*` aliases went into — naming it as created when there was no script surface to begin with. Remind: `/reload` so the harness rescans. Close with what is left over — at most dirt setup deliberately did not commit — and nothing else: a clean setup leaves the user good to go.
|
|
104
|
+
9. **Report.** The config path, the topology, the resolved artifact and knowledge paths, whether agent QA is on and — when it is — that the recipe is a skeleton until a `sassy-dogfood mode:discover` run writes it, where the skills are installed (scope) and where the agents are (scope and harness), or why either is not, the commit (hash and branch) or why there is none, and in `workspace` mode what was installed, with versions (`snapshot vN`, `workspace-git vN`), and the manifest the `workspace:*` aliases went into — naming it as created when there was no script surface to begin with. Remind: `/reload` so the harness rescans. Close with what is left over — at most dirt setup deliberately did not commit — and nothing else: a clean setup leaves the user good to go.
|
|
94
105
|
|
|
95
106
|
## Hard rules
|
|
96
107
|
|
|
@@ -104,11 +115,17 @@ A check run never edits the config and never rewrites the tree: it prints what `
|
|
|
104
115
|
| Version is reported | Setup names the snapshot and `workspace-git` versions it installed; `--check` flags an installed copy older than the skill's. |
|
|
105
116
|
| Skills come from upstream | Install with `npx skills add`, `-g` for user scope; never hand-copy skill files or maintain the links yourself. |
|
|
106
117
|
| Agents come from sassy-agents | Only the running harness's folder, as-is: linked by `install.sh` (user scope) or copied verbatim (project scope). Never edit, merge, or overwrite a differing agent file without asking. |
|
|
107
|
-
| Never edit the manifest | No dependencies, no `postinstall`, no `skills:*` scripts. The one exception is step 6's `
|
|
108
|
-
| Write boundary | Only `.sassywares
|
|
118
|
+
| Never edit the manifest | No dependencies, no `postinstall`, no `skills:*` scripts. The one exception is step 6's `worktree:*` and `workspace:*` aliases: appended or corrected, never removed, and nothing else in the file touched. Setup installs the suite; the user or project decides how it updates. |
|
|
119
|
+
| Write boundary | Only `.sassywares/` (the config, the setup README, the dogfood scaffold, and the worktree tooling), the skills and agent files step 5 installed in the scope the user chose, `skills-lock.json` (project scope), and one `.gitignore` line — and the project-scope part of that list is step 8's commit. Never `package.json` outside step 6's `worktree:*` and `workspace:*` aliases, never a root `.gitignore` in a workspace. Workspace git helpers land in `.sassywares/workspace/`, never in a project's `bin/`. |
|
|
109
120
|
| Detect, don't guess | An unknown base branch stays unknown and gets asked about. A probed value is reported as probed. |
|
|
110
121
|
| Comments are part of the file | Every key keeps its description and allowed values. A stripped config is an incomplete config. |
|
|
111
122
|
| Hooks are named, not written | Setup records hook skill names. Creating those skills is the project's work. |
|
|
123
|
+
| Dogfood is a pointer | The block names a recipe, a reports path, a timeout, and whether Auto rows are allowed — four keys. Never a command and never a tool: a copied command duplicates the manifest and cannot express step order. |
|
|
124
|
+
| The recipe is the project's | Setup scaffolds the skeleton and stops. Authoring or "fixing" a procedure is `sassy-dogfood mode:discover`'s job, and a run may never edit the recipe to make its own failure pass. |
|
|
125
|
+
| Run output and sessions never ship | `.sassywares/.gitignore` holds `/session/` and `/dogfood/reports/`. Never remove a line, never add anything from either path to the commit, and never write a credential anywhere else. |
|
|
126
|
+
| No secrets in setup's writes | Env var names only, in the config and in the skeleton. A credential never lands in a file setup commits. |
|
|
127
|
+
| Worktrees need `new` | `worktrees.enabled: true` with `commit.branch: current` is refused, not written: nothing cuts a branch there, so the switch could never fire. |
|
|
128
|
+
| Install the tooling, never use it | Setup copies `.sassywares/worktree/` and wires the aliases. It never creates a checkout, never claims a port, and never runs a script — those are a run's or the user's. |
|
|
112
129
|
| Repair is `check` | Run against an existing config, setup reports drift — it does not rewrite the file without approval. |
|
|
113
130
|
|
|
114
131
|
## What setup is not
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# Dogfood — <project>
|
|
2
|
+
|
|
3
|
+
**Never** production. Local or staging only.
|
|
4
|
+
|
|
5
|
+
**Set up once:** <install, services to start, env files to copy; name variables,
|
|
6
|
+
never values>
|
|
7
|
+
|
|
8
|
+
**Reset:** <back to a known state>
|
|
9
|
+
|
|
10
|
+
**Preview:** <the one command a human runs to look at it — `bun dev --port $PORT` — and what to open>
|
|
11
|
+
|
|
12
|
+
<!--
|
|
13
|
+
Incomplete on purpose. sassy-setup writes this skeleton so the shape is visible;
|
|
14
|
+
`sassy-dogfood mode:discover` fills it by trying the product once and writing down
|
|
15
|
+
what actually worked. Until a section has a **Prove it:** step, every QA row stays
|
|
16
|
+
Manual.
|
|
17
|
+
|
|
18
|
+
Rules: steps are ordered and append-only; every step has **Do** and **Expect**;
|
|
19
|
+
one **Prove it:** per section and its exit code is the verdict; env var names
|
|
20
|
+
only; no tool names. Schema: sassy-setup/references/dogfood.md
|
|
21
|
+
-->
|
|
22
|
+
|
|
23
|
+
## <section> — <one line: what this proves>
|
|
24
|
+
|
|
25
|
+
1. **Do** <command or instruction>
|
|
26
|
+
**Expect** <observable, checkable result>
|
|
27
|
+
|
|
28
|
+
2. **Do** <the proving command>
|
|
29
|
+
**Expect** exit 0
|
|
30
|
+
|
|
31
|
+
**Prove it:** step 2 — its exit code is the verdict.
|
|
@@ -0,0 +1,269 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
# Shared helpers for the worktree scripts: create, list, stop, remove, prune.
|
|
3
|
+
#
|
|
4
|
+
# Installed next to those scripts by sassy-setup, and owned by this project from
|
|
5
|
+
# then on — extend it here rather than forking a copy. Three rules worth keeping:
|
|
6
|
+
#
|
|
7
|
+
# 1. The worktree home, the port range, and the on/off switch come from
|
|
8
|
+
# `worktrees:` in .sassywares/config.yaml. Never grow a second source.
|
|
9
|
+
# 2. A port is claimed, never assumed. The claim directory is the lock.
|
|
10
|
+
# 3. Everything resolves against the MAIN checkout, so running any of these
|
|
11
|
+
# from inside a worktree behaves identically.
|
|
12
|
+
#
|
|
13
|
+
# worktree-version: 1
|
|
14
|
+
|
|
15
|
+
set -euo pipefail
|
|
16
|
+
|
|
17
|
+
WT_VERSION="1"
|
|
18
|
+
WT_LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
|
19
|
+
|
|
20
|
+
log() { printf '%s\n' "$*"; }
|
|
21
|
+
ok() { printf ' %-9s %s\n' "$1" "$2"; }
|
|
22
|
+
warn() { printf ' %-9s %s\n' "!" "$2" >&2; }
|
|
23
|
+
die() { printf ' ✗ %s\n' "$*" >&2; exit 1; }
|
|
24
|
+
hint() { printf ' %-9s %s\n' "→" "$*"; }
|
|
25
|
+
|
|
26
|
+
need_git() {
|
|
27
|
+
command -v git >/dev/null 2>&1 || die "git not found"
|
|
28
|
+
local common
|
|
29
|
+
common="$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)" \
|
|
30
|
+
|| die "not inside a git repository"
|
|
31
|
+
# The common dir is shared by every worktree; its parent is the main checkout.
|
|
32
|
+
MAIN="$(cd "$common/.." && pwd -P)"
|
|
33
|
+
CONFIG="$MAIN/.sassywares/config.yaml"
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
# --- config ---------------------------------------------------------------
|
|
37
|
+
# Flattened to `path<TAB>value`, the same reader sassy-setup's detect.sh uses,
|
|
38
|
+
# so a nested map has exactly one interpretation across the suite.
|
|
39
|
+
WLIB_US=$'\037'
|
|
40
|
+
wt_flat() {
|
|
41
|
+
awk -v us="$(printf '\037')" '
|
|
42
|
+
function ind(s, m) { m = match(s, /^ */); return m ? RLENGTH : 0 }
|
|
43
|
+
{
|
|
44
|
+
line = $0; sub(/#.*$/, "", line)
|
|
45
|
+
if (line ~ /^[[:space:]]*$/) next
|
|
46
|
+
d = ind(line)
|
|
47
|
+
body = line; sub(/^[[:space:]]*/, "", body); sub(/[[:space:]]+$/, "", body)
|
|
48
|
+
if (body ~ /:$/) {
|
|
49
|
+
key = body; sub(/:$/, "", key); gsub(/"/, "", key)
|
|
50
|
+
while (sp > 0 && sd[sp] >= d) sp--
|
|
51
|
+
sd[++sp] = d; sk[sp] = key
|
|
52
|
+
next
|
|
53
|
+
}
|
|
54
|
+
if (body !~ /:/) next
|
|
55
|
+
key = body; sub(/:.*/, "", key); gsub(/"/, "", key)
|
|
56
|
+
val = body; sub(/^[^:]*:[[:space:]]*/, "", val); gsub(/^"|"$/, "", val)
|
|
57
|
+
path = ""
|
|
58
|
+
for (i = 1; i <= sp; i++) if (sd[i] < d) path = path (path == "" ? "" : us) sk[i]
|
|
59
|
+
print path (path == "" ? "" : us) key "\t" val
|
|
60
|
+
}' "${CONFIG:-/dev/null}" 2>/dev/null
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
# wt_cfg KEY DEFAULT — a dotted path under the `worktrees:` block.
|
|
64
|
+
wt_cfg() {
|
|
65
|
+
local v
|
|
66
|
+
v="$(wt_flat | awk -F'\t' -v p="worktrees${WLIB_US}$1" '$1 == p { print $2; exit }')"
|
|
67
|
+
printf '%s' "${v:-$2}"
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
wt_enabled() { [ "$(wt_cfg enabled false)" = "true" ]; }
|
|
71
|
+
|
|
72
|
+
# A list value (`[a b]`) split one per line.
|
|
73
|
+
wt_list_items() {
|
|
74
|
+
printf '%s' "$1" | sed -e 's/^\[//' -e 's/\]$//' | tr ',' '\n' \
|
|
75
|
+
| sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//; s/^"//; s/"$//' | grep -v '^$' || true
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
# --- identity -------------------------------------------------------------
|
|
79
|
+
# The first match wins, so `hooks.worktree."*"` applies when no branch matches.
|
|
80
|
+
wt_hook() { # $1 point (after_create|before_remove), $2 branch — one entry per line
|
|
81
|
+
local point="$1" branch="$2" v=""
|
|
82
|
+
v="$(wt_flat | awk -F'\t' -v b="$branch" -v p="hooks${WLIB_US}worktree${WLIB_US}${branch}${WLIB_US}${point}" '$1 == p { print $2; exit }')"
|
|
83
|
+
if [ -z "$v" ]; then
|
|
84
|
+
v="$(wt_flat | awk -F'\t' -v p="hooks${WLIB_US}worktree${WLIB_US}*${WLIB_US}${point}" '$1 == p { print $2; exit }')"
|
|
85
|
+
fi
|
|
86
|
+
wt_list_items "$v"
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
wt_slug() { printf '%s' "$1" | sed -E 's#[/ ]+#-#g; s#[^A-Za-z0-9._-]#-#g'; }
|
|
90
|
+
|
|
91
|
+
# A name safe for a database, a compose project, or a simulator: lowercase,
|
|
92
|
+
# no slashes, no dots.
|
|
93
|
+
wt_namespace() {
|
|
94
|
+
printf '%s-%s' "$(basename "$MAIN")" "$1" \
|
|
95
|
+
| tr '[:upper:]' '[:lower:]' \
|
|
96
|
+
| sed -E 's#[^a-z0-9]+#-#g; s#^-+##; s#-+$##'
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
# The directory holding every worktree of this repo: one folder per checkout,
|
|
100
|
+
# under a home that survives a reboot. A second clone of the same project gets a
|
|
101
|
+
# suffixed folder instead of sharing this one.
|
|
102
|
+
wt_home() {
|
|
103
|
+
local dir base cand parent
|
|
104
|
+
dir="$(wt_cfg dir "$HOME/.sassywares/worktrees")"
|
|
105
|
+
case "$dir" in
|
|
106
|
+
"~") dir="$HOME" ;;
|
|
107
|
+
"~/"*) dir="$HOME/${dir#\~/}" ;;
|
|
108
|
+
/*) ;;
|
|
109
|
+
*) dir="$MAIN/$dir" ;;
|
|
110
|
+
esac
|
|
111
|
+
# Resolve through the parent, so /tmp and /private/tmp never disagree and the
|
|
112
|
+
# paths match what `git worktree list` reports.
|
|
113
|
+
parent="$(dirname "$dir")"
|
|
114
|
+
[ -d "$parent" ] && dir="$(cd "$parent" && pwd -P)/$(basename "$dir")"
|
|
115
|
+
base="$(basename "$MAIN")"
|
|
116
|
+
cand="$dir/$base"
|
|
117
|
+
if [ -f "$cand/.repo" ] && [ "$(cat "$cand/.repo" 2>/dev/null)" != "$MAIN" ]; then
|
|
118
|
+
cand="$dir/$base-$(printf '%s' "$MAIN" | shasum -a 256 | cut -c1-6)"
|
|
119
|
+
fi
|
|
120
|
+
printf '%s' "$cand"
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
wt_path() { printf '%s/%s' "$(wt_home)" "$1"; }
|
|
124
|
+
|
|
125
|
+
# --- ports ----------------------------------------------------------------
|
|
126
|
+
wt_range() {
|
|
127
|
+
local r lo hi
|
|
128
|
+
r="$(wt_cfg ports 3000-3099)"
|
|
129
|
+
case "$r" in
|
|
130
|
+
*-*) lo="${r%%-*}"; hi="${r##*-}" ;;
|
|
131
|
+
*) lo="$r"; hi="$r" ;;
|
|
132
|
+
esac
|
|
133
|
+
case "$lo$hi" in *[!0-9]*) die "worktrees.ports '$r' is not <from>-<to>" ;; esac
|
|
134
|
+
[ "$lo" -le "$hi" ] || die "worktrees.ports '$r' has an empty range"
|
|
135
|
+
printf '%s %s' "$lo" "$hi"
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
# tcp_up PORT — 0 when something accepts a connection on loopback.
|
|
139
|
+
# Liveness is observed, never read from a state file: a killed preview leaves no
|
|
140
|
+
# trace to go stale. The probe runs in a subshell so a successful connect cannot
|
|
141
|
+
# leave a descriptor (or a fatal `exec`) behind in the caller.
|
|
142
|
+
tcp_up() {
|
|
143
|
+
(exec 3<>"/dev/tcp/127.0.0.1/$1") >/dev/null 2>&1
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
wt_claim_dir() { printf '%s/ports/%s' "$(wt_home)" "$1"; }
|
|
147
|
+
|
|
148
|
+
# wt_owner PORT — the slug that claimed a port, or empty.
|
|
149
|
+
wt_owner() {
|
|
150
|
+
local f
|
|
151
|
+
f="$(wt_claim_dir "$1")/owner"
|
|
152
|
+
[ -f "$f" ] && cat "$f" 2>/dev/null || true
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
# wt_claim SLUG — print the port this slug owns, claiming one when needed.
|
|
156
|
+
# Deterministic first (a restarted preview comes back on the same port), then a
|
|
157
|
+
# linear probe so two slugs that hash alike do not fight.
|
|
158
|
+
# wt_port_for SLUG — the port this slug uses: an existing claim, else the derived
|
|
159
|
+
# one probed forward past claims held by others. Read-only, so `list` may call it.
|
|
160
|
+
wt_port_for() {
|
|
161
|
+
local slug="$1" lo hi span i port owner hex d
|
|
162
|
+
read -r lo hi <<<"$(wt_range)"
|
|
163
|
+
for d in "$(wt_home)/ports"/*; do
|
|
164
|
+
[ -d "$d" ] || continue
|
|
165
|
+
if [ "$(cat "$d/owner" 2>/dev/null)" = "$slug" ]; then
|
|
166
|
+
basename "$d"
|
|
167
|
+
return 0
|
|
168
|
+
fi
|
|
169
|
+
done
|
|
170
|
+
span=$(( hi - lo + 1 ))
|
|
171
|
+
hex="$(printf '%s' "$slug" | shasum -a 256 | cut -c1-8)"
|
|
172
|
+
i=$(( 16#$hex % span ))
|
|
173
|
+
port=$(( lo + i ))
|
|
174
|
+
while :; do
|
|
175
|
+
owner="$(wt_owner "$port")"
|
|
176
|
+
if [ -z "$owner" ] || [ "$owner" = "$slug" ]; then
|
|
177
|
+
printf '%s' "$port"
|
|
178
|
+
return 0
|
|
179
|
+
fi
|
|
180
|
+
port=$(( port + 1 ))
|
|
181
|
+
[ "$port" -gt "$hi" ] && port=$lo
|
|
182
|
+
i=$(( i + 1 ))
|
|
183
|
+
[ "$i" -gt "$span" ] && die "no free port in $(wt_range | sed 's/ /-/')"
|
|
184
|
+
done
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
# wt_claim SLUG — claim and print the port, writing the lock directory.
|
|
188
|
+
wt_claim() {
|
|
189
|
+
local slug="$1" port
|
|
190
|
+
port="$(wt_port_for "$slug")"
|
|
191
|
+
mkdir -p "$(wt_claim_dir "$port")"
|
|
192
|
+
printf '%s' "$slug" > "$(wt_claim_dir "$port")/owner"
|
|
193
|
+
printf '%s' "$port"
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
wt_release() { # $1 port, $2 slug
|
|
197
|
+
local d
|
|
198
|
+
d="$(wt_claim_dir "$1")"
|
|
199
|
+
[ "$(wt_owner "$1")" = "$2" ] && rm -rf "$d"
|
|
200
|
+
return 0
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
# --- checkouts ------------------------------------------------------------
|
|
204
|
+
# Emits one record per worktree: path<TAB>branch.
|
|
205
|
+
wt_all() {
|
|
206
|
+
git worktree list --porcelain | awk '
|
|
207
|
+
/^worktree /{ p = $2 }
|
|
208
|
+
/^branch / { b = $2; sub(/^refs\/heads\//, "", b); print p "\t" b; p = ""; b = "" }
|
|
209
|
+
/^detached/ { print p "\t(detached)"; p = "" }
|
|
210
|
+
'
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
wt_find() { # $1 slug or branch -> path<TAB>branch, or nothing
|
|
214
|
+
local want="$1" p b
|
|
215
|
+
while IFS=$'\t' read -r p b; do
|
|
216
|
+
[ -n "$p" ] || continue
|
|
217
|
+
if [ "$b" = "$want" ] || [ "$(wt_slug "$b")" = "$want" ]; then
|
|
218
|
+
printf '%s\t%s' "$p" "$b"
|
|
219
|
+
return 0
|
|
220
|
+
fi
|
|
221
|
+
done < <(wt_all)
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
wt_require() { # $1 slug or branch -> path<TAB>branch, or die
|
|
225
|
+
local rec
|
|
226
|
+
rec="$(wt_find "$1")"
|
|
227
|
+
[ -n "$rec" ] || die "no worktree for '$1' (try: list)"
|
|
228
|
+
printf '%s' "$rec"
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
wt_is_main() { [ "$(cd "$1" && pwd -P)" = "$MAIN" ]; }
|
|
232
|
+
|
|
233
|
+
wt_dirty() { [ -n "$(git -C "$1" status --porcelain 2>/dev/null)" ]; }
|
|
234
|
+
|
|
235
|
+
# Commits that exist only here: ahead of the upstream, or — with none — reachable
|
|
236
|
+
# from no remote at all.
|
|
237
|
+
wt_unpushed() {
|
|
238
|
+
local p="$1" up n
|
|
239
|
+
up="$(git -C "$p" rev-parse --abbrev-ref --symbolic-full-name '@{upstream}' 2>/dev/null || true)"
|
|
240
|
+
if [ -n "$up" ]; then
|
|
241
|
+
n="$(git -C "$p" rev-list --count "$up..HEAD" 2>/dev/null || echo unknown)"
|
|
242
|
+
else
|
|
243
|
+
n="$(git -C "$p" rev-list --count HEAD --not --remotes 2>/dev/null || echo unknown)"
|
|
244
|
+
fi
|
|
245
|
+
printf '%s' "${n:-0}"
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
wt_upstream_state() { # merged | gone | unmerged
|
|
249
|
+
local p="$1" up
|
|
250
|
+
up="$(git -C "$p" rev-parse --abbrev-ref --symbolic-full-name '@{upstream}' 2>/dev/null || true)"
|
|
251
|
+
if [ -z "$up" ]; then
|
|
252
|
+
printf 'gone'
|
|
253
|
+
elif git -C "$p" merge-base --is-ancestor HEAD "$up" 2>/dev/null; then
|
|
254
|
+
printf 'merged'
|
|
255
|
+
else
|
|
256
|
+
printf 'unmerged'
|
|
257
|
+
fi
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
# Newest dogfood verdict for a checkout, as `status class` — or empty.
|
|
261
|
+
wt_verdict() {
|
|
262
|
+
local dir="$1/.sassywares/dogfood/reports" newest s c
|
|
263
|
+
[ -d "$dir" ] || return 0
|
|
264
|
+
newest="$(ls -1t "$dir" 2>/dev/null | head -n 1)"
|
|
265
|
+
[ -n "$newest" ] || return 0
|
|
266
|
+
s="$(sed -n 's/^\*\*status:\*\* //p' "$dir/$newest/summary.md" 2>/dev/null | head -n 1)"
|
|
267
|
+
c="$(sed -n 's/^\*\*class:\*\* //p' "$dir/$newest/summary.md" 2>/dev/null | head -n 1)"
|
|
268
|
+
printf '%s%s' "${s:-unknown}" "$( [ -n "$c" ] && printf ' %s' "$c" )"
|
|
269
|
+
}
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
# Add a worktree for one branch and claim its port.
|
|
3
|
+
#
|
|
4
|
+
# Idempotent: a branch already in a worktree of ours is reported, not recreated,
|
|
5
|
+
# and nobody else's checkout holding it is a stop rather than a clobber.
|
|
6
|
+
#
|
|
7
|
+
# Usage: .sassywares/worktree/create <branch> [--from <start-point>] [--env]
|
|
8
|
+
# .sassywares/worktree/create --version
|
|
9
|
+
set -euo pipefail
|
|
10
|
+
|
|
11
|
+
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
|
12
|
+
# shellcheck source=./_lib.sh
|
|
13
|
+
source "$SCRIPT_DIR/_lib.sh"
|
|
14
|
+
|
|
15
|
+
usage() {
|
|
16
|
+
cat <<'EOF'
|
|
17
|
+
Usage: .sassywares/worktree/create <branch> [--from <start-point>] [--env]
|
|
18
|
+
|
|
19
|
+
Create (or report) the worktree for <branch>, claim its port, and print the
|
|
20
|
+
namespace a run inherits: WT_PATH, WT_BRANCH, WT_SLUG, WT_NAMESPACE, WT_PORT,
|
|
21
|
+
WT_BASE_URL.
|
|
22
|
+
|
|
23
|
+
--from <ref> where a new branch is cut from (default HEAD). A caller that has
|
|
24
|
+
already resolved the base passes it; this script never guesses.
|
|
25
|
+
--env print only `WT_*=<value>` lines, for eval.
|
|
26
|
+
EOF
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
branch=""
|
|
30
|
+
from="HEAD"
|
|
31
|
+
env_only=0
|
|
32
|
+
while [ $# -gt 0 ]; do
|
|
33
|
+
case "$1" in
|
|
34
|
+
-h|--help) usage; exit 0 ;;
|
|
35
|
+
--version) printf '%s\n' "$WT_VERSION"; exit 0 ;;
|
|
36
|
+
--env) env_only=1 ;;
|
|
37
|
+
--from) shift; from="${1:-}"; [ -n "$from" ] || die "--from needs a start point" ;;
|
|
38
|
+
--from=*) from="${1#*=}" ;;
|
|
39
|
+
-*) die "unknown flag: $1 (try --help)" ;;
|
|
40
|
+
*) [ -z "$branch" ] || die "one branch at a time"; branch="$1" ;;
|
|
41
|
+
esac
|
|
42
|
+
shift
|
|
43
|
+
done
|
|
44
|
+
[ -n "$branch" ] || { usage >&2; exit 2; }
|
|
45
|
+
|
|
46
|
+
need_git
|
|
47
|
+
wt_enabled || die "worktrees are off here — set worktrees.enabled: true in .sassywares/config.yaml"
|
|
48
|
+
|
|
49
|
+
slug="$(wt_slug "$branch")"
|
|
50
|
+
path="$(wt_path "$slug")"
|
|
51
|
+
|
|
52
|
+
report() { # $1 path, $2 branch
|
|
53
|
+
local port addr ns
|
|
54
|
+
ns="$(wt_namespace "$slug")"
|
|
55
|
+
port="$(wt_claim "$slug")"
|
|
56
|
+
addr="http://localhost:$port"
|
|
57
|
+
if [ "$env_only" -eq 1 ]; then
|
|
58
|
+
printf 'WT_PATH=%s\nWT_BRANCH=%s\nWT_SLUG=%s\nWT_NAMESPACE=%s\nWT_PORT=%s\nWT_BASE_URL=%s\n' \
|
|
59
|
+
"$1" "$2" "$slug" "$ns" "$port" "$addr"
|
|
60
|
+
return 0
|
|
61
|
+
fi
|
|
62
|
+
ok worktree "$1"
|
|
63
|
+
ok branch "$2"
|
|
64
|
+
ok namespace "$ns"
|
|
65
|
+
ok port "$port"
|
|
66
|
+
ok address "$addr"
|
|
67
|
+
local hooks n
|
|
68
|
+
hooks="$(wt_hook after_create "$2")"
|
|
69
|
+
if [ -z "$hooks" ]; then
|
|
70
|
+
ok hook "hooks.worktree.after_create — none declared"
|
|
71
|
+
else
|
|
72
|
+
while IFS= read -r n; do
|
|
73
|
+
[ -n "$n" ] || continue
|
|
74
|
+
ok hook "after_create → $n (dispatch it, with WT_* above)"
|
|
75
|
+
done <<<"$hooks"
|
|
76
|
+
fi
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
# Already in a worktree of ours: report and stop. This is the second call in a
|
|
80
|
+
# resumed run, and it must not fail.
|
|
81
|
+
existing="$(wt_find "$branch" || true)"
|
|
82
|
+
if [ -n "$existing" ]; then
|
|
83
|
+
epath="${existing%%$'\t'*}"
|
|
84
|
+
if wt_is_main "$epath"; then
|
|
85
|
+
die "'$branch' is checked out in the main checkout — leave it, or switch the main checkout first"
|
|
86
|
+
fi
|
|
87
|
+
report "$epath" "$branch"
|
|
88
|
+
exit 0
|
|
89
|
+
fi
|
|
90
|
+
|
|
91
|
+
if [ -e "$path" ]; then
|
|
92
|
+
die "'$path' exists but no worktree is registered for '$branch' — inspect it, then prune"
|
|
93
|
+
fi
|
|
94
|
+
|
|
95
|
+
(umask 077; mkdir -p "$(wt_home)/ports")
|
|
96
|
+
printf '%s\n' "$MAIN" > "$(wt_home)/.repo"
|
|
97
|
+
|
|
98
|
+
if git show-ref --verify --quiet "refs/heads/$branch"; then
|
|
99
|
+
git worktree add --quiet "$path" "$branch"
|
|
100
|
+
else
|
|
101
|
+
git worktree add --quiet -b "$branch" "$path" "$from"
|
|
102
|
+
fi
|
|
103
|
+
|
|
104
|
+
report "$path" "$branch"
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
# Show every worktree of this repo: branch, path, address, whether anything is
|
|
3
|
+
# listening there, and the last dogfood verdict.
|
|
4
|
+
#
|
|
5
|
+
# Liveness is probed, never read from a pid file — a killed preview leaves no
|
|
6
|
+
# stale entry to believe.
|
|
7
|
+
#
|
|
8
|
+
# Usage: .sassywares/worktree/list [--address <slug>] [--path <slug>] [--version]
|
|
9
|
+
set -euo pipefail
|
|
10
|
+
|
|
11
|
+
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
|
12
|
+
# shellcheck source=./_lib.sh
|
|
13
|
+
source "$SCRIPT_DIR/_lib.sh"
|
|
14
|
+
|
|
15
|
+
usage() {
|
|
16
|
+
cat <<'EOF'
|
|
17
|
+
Usage: .sassywares/worktree/list [--address <slug>] [--path <slug>]
|
|
18
|
+
|
|
19
|
+
Print every worktree with its address and last verdict.
|
|
20
|
+
|
|
21
|
+
--address <slug> print only the base URL of one worktree
|
|
22
|
+
--path <slug> print only the path of one worktree (for cd "$(...)")
|
|
23
|
+
EOF
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
want="" kind=""
|
|
27
|
+
while [ $# -gt 0 ]; do
|
|
28
|
+
case "$1" in
|
|
29
|
+
-h|--help) usage; exit 0 ;;
|
|
30
|
+
--version) printf '%s\n' "$WT_VERSION"; exit 0 ;;
|
|
31
|
+
--address|--path) kind="${1#--}"; shift; want="${1:-}"; [ -n "$want" ] || die "$kind needs a slug" ;;
|
|
32
|
+
-*) die "unknown flag: $1 (try --help)" ;;
|
|
33
|
+
*) die "unexpected argument: $1 (try --help)" ;;
|
|
34
|
+
esac
|
|
35
|
+
shift
|
|
36
|
+
done
|
|
37
|
+
|
|
38
|
+
need_git
|
|
39
|
+
|
|
40
|
+
one() { # $1 path, $2 branch
|
|
41
|
+
local p="$1" b="$2" slug port
|
|
42
|
+
slug="$(wt_slug "$b")"
|
|
43
|
+
if wt_is_main "$p"; then
|
|
44
|
+
die "the main checkout has no derived port — it uses whatever the app defaults to"
|
|
45
|
+
fi
|
|
46
|
+
case "$kind" in
|
|
47
|
+
path) printf '%s\n' "$p" ;;
|
|
48
|
+
address)
|
|
49
|
+
port="$(wt_port_for "$slug")"
|
|
50
|
+
printf 'http://localhost:%s\n' "$port"
|
|
51
|
+
;;
|
|
52
|
+
esac
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
if [ -n "$kind" ]; then
|
|
56
|
+
rec="$(wt_require "$want")"
|
|
57
|
+
one "${rec%%$'\t'*}" "${rec##*$'\t'}"
|
|
58
|
+
exit 0
|
|
59
|
+
fi
|
|
60
|
+
|
|
61
|
+
printf ' %-34s %-50s %-22s %-5s %s\n' "BRANCH" "WORKTREE" "ADDRESS" "LIVE" "LAST RUN"
|
|
62
|
+
count=0
|
|
63
|
+
while IFS=$'\t' read -r p b; do
|
|
64
|
+
[ -n "$p" ] || continue
|
|
65
|
+
count=$(( count + 1 ))
|
|
66
|
+
slug="$(wt_slug "$b")"
|
|
67
|
+
shown="${p/#$HOME/~}"
|
|
68
|
+
if wt_is_main "$p"; then
|
|
69
|
+
printf ' %-34s %-50s %-22s %-5s %s\n' "$b (main checkout)" "$shown" "—" "—" "—"
|
|
70
|
+
continue
|
|
71
|
+
fi
|
|
72
|
+
port="$(wt_port_for "$slug")"
|
|
73
|
+
if tcp_up "$port"; then live="up"; else live="down"; fi
|
|
74
|
+
last="$(wt_verdict "$p")"
|
|
75
|
+
printf ' %-34s %-50s %-22s %-5s %s\n' "$b" "$shown" "http://localhost:$port" "$live" "${last:-—}"
|
|
76
|
+
done < <(wt_all)
|
|
77
|
+
|
|
78
|
+
[ "$count" -gt 0 ] || log " no checkouts found — is this a git repository?"
|