@sassywares/skills 0.11.2 → 0.11.4
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/package.json +1 -1
- package/skills/sassy-setup/SKILL.md +4 -1
- package/skills/sassy-setup/assets/worktree/_lib.sh +37 -6
- package/skills/sassy-setup/assets/worktree/remove +2 -1
- package/skills/sassy-setup/assets/worktree/stop +2 -1
- package/skills/sassy-setup/references/worktree.md +23 -0
- package/skills/sassy-setup/scripts/detect.sh +10 -0
- package/skills/sassy-worktree/SKILL.md +3 -0
package/package.json
CHANGED
|
@@ -35,6 +35,8 @@ A check run never edits the config and never rewrites the tree: it prints what `
|
|
|
35
35
|
|
|
36
36
|
1. **Resolve the start and the mode.** The path argument, else the working directory; the mode per above. On `check`, run steps 7 → 8 → 9 and stop.
|
|
37
37
|
2. **Detect.** Run `scripts/detect.sh --root <path>`. It prints a proposed config: topology (`repo`, `workspace`, `none`), the remote name, a probed base branch, and nested repos with their bases.
|
|
38
|
+
|
|
39
|
+
**A config that already exists is the proposal.** When `.sassywares/config.yaml` is found — an explicit `init` on a project that is already wired — the detector's output is only the starting point: take every value it **probes** (`git.repo`, `base_map`'s `"*"`, `repos`), and take every value it **emits as a default** from the existing file instead — the other `base_map` rungs, `hooks.*`, `worktrees.*`, `dogfood.*`, `pr.*`, `commit.branch`, `knowledge.*`, `artifacts.*`. A default is not an answer: writing the blank slate here would retarget `"*"` away from the integration branch the project actually uses and delete its hooks. Present the result as a **diff against the file, key by key**, and ask before writing.
|
|
38
40
|
3. **Ask only what detection cannot answer.** Never re-ask what the tree already said.
|
|
39
41
|
- **`workspace`** — the snapshot mirror: create a **private** GitHub repo, or connect an existing one? Creating it needs explicit approval and a named slug first.
|
|
40
42
|
- **`none`** — confirm the intent: this folder is deliberately outside git, so commit, PR, and babysit refuse here.
|
|
@@ -101,7 +103,7 @@ A check run never edits the config and never rewrites the tree: it prints what `
|
|
|
101
103
|
- **`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.
|
|
102
104
|
- **`none`** — nothing to commit, deliberately.
|
|
103
105
|
|
|
104
|
-
9. **Report.** The config path, the topology, the resolved artifact and knowledge paths, whether agent QA is
|
|
106
|
+
9. **Report.** The config path, the topology, the resolved artifact and knowledge paths, whether agent QA is **off** — one line saying every QA row stays a human's, with no suggestion attached — or on, and then whether the recipe is ready or still a skeleton until `sassy-dogfood mode:discover` runs, 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.
|
|
105
107
|
|
|
106
108
|
## Hard rules
|
|
107
109
|
|
|
@@ -118,6 +120,7 @@ A check run never edits the config and never rewrites the tree: it prints what `
|
|
|
118
120
|
| 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
121
|
| 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/`. |
|
|
120
122
|
| Detect, don't guess | An unknown base branch stays unknown and gets asked about. A probed value is reported as probed. |
|
|
123
|
+
| A re-apply is a diff | On a project that already has a config, every key the detector only *defaults* keeps its value from that file. Changing one needs the user to say so — never a detector default, and never a silent deletion. |
|
|
121
124
|
| Comments are part of the file | Every key keeps its description and allowed values. A stripped config is an incomplete config. |
|
|
122
125
|
| Hooks are named, not written | Setup records hook skill names. Creating those skills is the project's work. |
|
|
123
126
|
| 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. |
|
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
# 3. Everything resolves against the MAIN checkout, so running any of these
|
|
11
11
|
# from inside a worktree behaves identically.
|
|
12
12
|
#
|
|
13
|
-
# worktree-version:
|
|
13
|
+
# worktree-version: 2
|
|
14
14
|
|
|
15
15
|
set -euo pipefail
|
|
16
16
|
|
|
@@ -23,11 +23,39 @@ warn() { printf ' %-9s %s\n' "!" "$2" >&2; }
|
|
|
23
23
|
die() { printf ' ✗ %s\n' "$*" >&2; exit 1; }
|
|
24
24
|
hint() { printf ' %-9s %s\n' "→" "$*"; }
|
|
25
25
|
|
|
26
|
+
# The nearest config, walking up from the cwd — used only to explain a refusal
|
|
27
|
+
# when there is no repo to work in at all.
|
|
28
|
+
wt_find_config() {
|
|
29
|
+
local dir
|
|
30
|
+
dir="$(pwd -P)"
|
|
31
|
+
while :; do
|
|
32
|
+
if [ -f "$dir/.sassywares/config.yaml" ]; then
|
|
33
|
+
printf '%s' "$dir/.sassywares/config.yaml"
|
|
34
|
+
return 0
|
|
35
|
+
fi
|
|
36
|
+
[ "$dir" = "/" ] && return 1
|
|
37
|
+
dir="$(dirname "$dir")"
|
|
38
|
+
done
|
|
39
|
+
}
|
|
40
|
+
|
|
26
41
|
need_git() {
|
|
27
42
|
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
|
-
|
|
43
|
+
local common found cfg_repo
|
|
44
|
+
common="$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null || true)"
|
|
45
|
+
if [ -z "$common" ]; then
|
|
46
|
+
# No repo here. A workspace root is that way on purpose, so say why instead of
|
|
47
|
+
# failing as if the directory were wrong.
|
|
48
|
+
found="$(wt_find_config || true)"
|
|
49
|
+
if [ -n "$found" ]; then
|
|
50
|
+
cfg_repo="$(wt_flat "$found" | awk -F'\t' -v p="git${WLIB_US}repo" '$1 == p { print $2; exit }')"
|
|
51
|
+
case "$cfg_repo" in
|
|
52
|
+
workspace|none)
|
|
53
|
+
die "worktrees need the repo topology — git.repo is '$cfg_repo' here; a nested repo carries its own config"
|
|
54
|
+
;;
|
|
55
|
+
esac
|
|
56
|
+
fi
|
|
57
|
+
die "not inside a git repository"
|
|
58
|
+
fi
|
|
31
59
|
# The common dir is shared by every worktree; its parent is the main checkout.
|
|
32
60
|
MAIN="$(cd "$common/.." && pwd -P)"
|
|
33
61
|
CONFIG="$MAIN/.sassywares/config.yaml"
|
|
@@ -57,7 +85,7 @@ wt_flat() {
|
|
|
57
85
|
path = ""
|
|
58
86
|
for (i = 1; i <= sp; i++) if (sd[i] < d) path = path (path == "" ? "" : us) sk[i]
|
|
59
87
|
print path (path == "" ? "" : us) key "\t" val
|
|
60
|
-
}' "${CONFIG:-/dev/null}" 2>/dev/null
|
|
88
|
+
}' "${1:-${CONFIG:-/dev/null}}" 2>/dev/null
|
|
61
89
|
}
|
|
62
90
|
|
|
63
91
|
# wt_cfg KEY DEFAULT — a dotted path under the `worktrees:` block.
|
|
@@ -245,7 +273,10 @@ wt_managed() { # $1 path
|
|
|
245
273
|
|
|
246
274
|
wt_require_managed() { # $1 slug or branch -> path<TAB>branch, or die
|
|
247
275
|
local rec
|
|
248
|
-
|
|
276
|
+
# `wt_require` dies inside the substitution, where its exit cannot reach us, so
|
|
277
|
+
# a failure has to be carried out by hand or the caller prints a second, wrong
|
|
278
|
+
# message ("not managed here" for a branch that does not exist at all).
|
|
279
|
+
rec="$(wt_require "$1")" || exit 1
|
|
249
280
|
wt_managed "${rec%%$'\t'*}" \
|
|
250
281
|
|| die "'$1' is not managed here — it is outside the worktree home, or it was cut before the wiring"
|
|
251
282
|
printf '%s' "$rec"
|
|
@@ -42,12 +42,13 @@ done
|
|
|
42
42
|
[ -n "$target" ] || { usage >&2; exit 2; }
|
|
43
43
|
|
|
44
44
|
need_git
|
|
45
|
-
rec="$(
|
|
45
|
+
rec="$(wt_require "$target")" || exit 1
|
|
46
46
|
path="${rec%%$'\t'*}"
|
|
47
47
|
branch="${rec##*$'\t'}"
|
|
48
48
|
slug="$(wt_slug "$branch")"
|
|
49
49
|
|
|
50
50
|
wt_is_main "$path" && die "that is the main checkout — it cannot be removed"
|
|
51
|
+
wt_managed "$path" || die "'$target' is not managed here — it is outside the worktree home, or it was cut before the wiring"
|
|
51
52
|
|
|
52
53
|
hooks="$(wt_hook before_remove "$branch")"
|
|
53
54
|
if [ -n "$hooks" ] && [ "$hook_ok" -eq 0 ]; then
|
|
@@ -29,12 +29,13 @@ case "${1:-}" in
|
|
|
29
29
|
esac
|
|
30
30
|
|
|
31
31
|
need_git
|
|
32
|
-
rec="$(
|
|
32
|
+
rec="$(wt_require "$1")" || exit 1
|
|
33
33
|
path="${rec%%$'\t'*}"
|
|
34
34
|
branch="${rec##*$'\t'}"
|
|
35
35
|
slug="$(wt_slug "$branch")"
|
|
36
36
|
|
|
37
37
|
wt_is_main "$path" && die "the main checkout is not a worktree — nothing to stop"
|
|
38
|
+
wt_managed "$path" || die "'$1' is not managed here — it is outside the worktree home, or it was cut before the wiring"
|
|
38
39
|
wt_has_ports || die "no port resource here — stopping this preview is the project's job (its before_remove hook or the recipe)"
|
|
39
40
|
port="$(wt_port_for "$slug")"
|
|
40
41
|
|
|
@@ -4,6 +4,12 @@ Parallel work in one repo: each run gets its own checkout, its own branch, and
|
|
|
4
4
|
its own port, without a second clone and without fighting the checkout somebody
|
|
5
5
|
else is using.
|
|
6
6
|
|
|
7
|
+
**Repo topology only.** `git.repo: workspace` means the root is not a repo and each
|
|
8
|
+
nested repo carries its own config, so there is nothing to cut a checkout from; a
|
|
9
|
+
`none` folder has no git at all. Setup writes `worktrees.enabled: false` there and
|
|
10
|
+
says why, `--check` reports an `enabled: true` as drift, and the scripts refuse
|
|
11
|
+
with that reason rather than "not a git repository".
|
|
12
|
+
|
|
7
13
|
Read this when the project has `worktrees.enabled: true`, or when the user asks
|
|
8
14
|
to run two agents in one project.
|
|
9
15
|
|
|
@@ -73,6 +79,17 @@ work; `remove` and `prune` are the only safe exits.
|
|
|
73
79
|
The same five names expand inside the recipe, including the dashed form
|
|
74
80
|
`${WT_PORT:-5180}` that makes a recipe runnable in the main checkout too.
|
|
75
81
|
|
|
82
|
+
**Finding a checkout.** `list` prints paths with `$HOME` shortened to `~`, which
|
|
83
|
+
reads well and does **not** paste into anything:
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
cd "$(worktree:list --path feat-catalog)" # the real absolute path
|
|
87
|
+
worktree:list --address feat-catalog # the URL, when ports are configured
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
`create --env` prints `WT_PATH=` and the rest for scripts, and a slug is just the
|
|
91
|
+
branch with `/` flattened.
|
|
92
|
+
|
|
76
93
|
Derived, never invented downstream: a hook that needs a database name uses
|
|
77
94
|
`$WT_NAMESPACE` rather than building its own, so two worktrees cannot collide by
|
|
78
95
|
accident.
|
|
@@ -84,6 +101,12 @@ checkout is addressed by the recipe's `**Preview:**` line instead. That covers a
|
|
|
84
101
|
mobile app (a simulator named `$WT_NAMESPACE`), a desktop app (a window), and a
|
|
85
102
|
CLI or library (nothing to look at).
|
|
86
103
|
|
|
104
|
+
**One port models a single service.** A stack that serves a web app, a docs site,
|
|
105
|
+
and a backend at once has more than one address per checkout; the claim covers the
|
|
106
|
+
one a human opens, and the recipe's steps carry the rest (distinct ports per
|
|
107
|
+
service, derived from `$WT_PORT` or fixed by the project). Do not add a port list
|
|
108
|
+
to the config for this — it is procedure, not identity.
|
|
109
|
+
|
|
87
110
|
When a range *is* configured: the slug hashes into it, the claim is taken with an
|
|
88
111
|
atomic `mkdir`, and a collision probes forward one port at a time. A claim
|
|
89
112
|
belongs to a slug, so a restarted app returns to the same port and two slugs that
|
|
@@ -790,6 +790,13 @@ if (( CHECK )); then
|
|
|
790
790
|
done < <(git -C "$ROOT" worktree list --porcelain 2>/dev/null \
|
|
791
791
|
| awk '/^worktree /{p=$2} /^branch /{b=$2; sub(/^refs\/heads\//,"",b); print p "\t" b; p=""} /^detached/{print p "\t(detached)"; p=""}')
|
|
792
792
|
|
|
793
|
+
# A registration whose folder is gone is a ghost `list` still believes in.
|
|
794
|
+
while IFS= read -r ghost; do
|
|
795
|
+
[[ -n "$ghost" ]] || continue
|
|
796
|
+
bad "worktree '$ghost' is prunable — the folder is gone; run: git worktree prune"
|
|
797
|
+
done < <(git -C "$ROOT" worktree list --porcelain 2>/dev/null \
|
|
798
|
+
| awk '/^worktree /{p=$2} /^prunable /{print p; p=""}')
|
|
799
|
+
|
|
793
800
|
# Orphan port claims: the worktree is gone but its port is still taken, so
|
|
794
801
|
# a later checkout is pushed off it for no reason.
|
|
795
802
|
wt_homef=""
|
|
@@ -1322,6 +1329,9 @@ cat <<'EOF'
|
|
|
1322
1329
|
# `current` never cuts a branch. The scripts in .sassywares/worktree/ own the
|
|
1323
1330
|
# mechanics; nothing else reads these values.
|
|
1324
1331
|
#
|
|
1332
|
+
# Repo topology only: a workspace root has no repo to cut a checkout from, and a
|
|
1333
|
+
# `none` folder has no git at all.
|
|
1334
|
+
#
|
|
1325
1335
|
# A port is a resource, not the definition of a preview: delete `ports` for a
|
|
1326
1336
|
# mobile, desktop, or CLI project, and the checkout is addressed by the recipe's
|
|
1327
1337
|
# preview line instead (`$WT_NAMESPACE` names a simulator, a window, a path).
|
|
@@ -40,6 +40,8 @@ argument-hint: "[slug] [mode:create|list|preview|remove|prune] [section:<name>]"
|
|
|
40
40
|
|
|
41
41
|
## `list`
|
|
42
42
|
|
|
43
|
+
Paths in the table are shortened to `~`; `--path <slug>` prints the real absolute path, which is what you hand a user who wants to open the checkout in an editor.
|
|
44
|
+
|
|
43
45
|
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
46
|
|
|
45
47
|
## `preview`
|
|
@@ -72,6 +74,7 @@ Preview never judges the work, never writes a report, never commits, and never r
|
|
|
72
74
|
|------|-------------|
|
|
73
75
|
| The scripts do the git | Never run `git worktree`, never invent a port, never `rm -rf` a checkout. `.sassywares/worktree/*` owns all of it. |
|
|
74
76
|
| One worktree per run | The branch decision belongs to `references/branching.md`. Never create a second worktree for a run already on its branch. |
|
|
77
|
+
| Repo topology only | `git.repo: workspace` or `none` means no worktrees at all. Say so in one line and stop — never create a checkout inside a nested repo to work around it. |
|
|
75
78
|
| 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
79
|
| 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
80
|
| 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. |
|