@sassywares/skills 0.11.2 → 0.11.3

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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sassywares/skills",
3
- "version": "0.11.2",
3
+ "version": "0.11.3",
4
4
  "description": "Lean, explicit-invocation Agent Skills for shipping fast: plan, work, review, validate, ship.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -101,7 +101,7 @@ A check run never edits the config and never rewrites the tree: it prints what `
101
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.
102
102
  - **`none`** — nothing to commit, deliberately.
103
103
 
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.
104
+ 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
105
 
106
106
  ## Hard rules
107
107
 
@@ -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
- || die "not inside a git repository"
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
- rec="$(wt_require "$1")"
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="$(wt_require_managed "$target")"
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="$(wt_require_managed "$1")"
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.
@@ -1322,6 +1322,9 @@ cat <<'EOF'
1322
1322
  # `current` never cuts a branch. The scripts in .sassywares/worktree/ own the
1323
1323
  # mechanics; nothing else reads these values.
1324
1324
  #
1325
+ # Repo topology only: a workspace root has no repo to cut a checkout from, and a
1326
+ # `none` folder has no git at all.
1327
+ #
1325
1328
  # A port is a resource, not the definition of a preview: delete `ports` for a
1326
1329
  # mobile, desktop, or CLI project, and the checkout is addressed by the recipe's
1327
1330
  # 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. |