@sassywares/skills 0.5.13 → 0.5.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sassywares/skills",
-  "version": "0.5.13",
+  "version": "0.5.14",
   "description": "Lean, explicit-invocation Agent Skills for shipping fast: plan, work, review, validate, ship.",
   "type": "module",
   "license": "MIT",

package/skills/sassy-setup/SKILL.md

@@ -52,7 +52,7 @@ A check run never edits the config and never rewrites the tree: it prints what `
    - **Write `.sassywares/README.md`** from `assets/sassywares-readme.md` when absent. Never overwrite it — it may carry project notes.
    - **Tell the user to `/reload`.** The skills are invisible to the harness until it rescans.
 
-6. **Install the snapshot, `workspace` only.** Read `references/workspace.md` and follow it.
+6. **Install the workspace tooling, `workspace` only.** The snapshot plus the `branches` / `pull` / `checkout-bases` git helpers. Read `references/workspace.md` and follow it.
 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`, any unknown key, and in `workspace` mode the installed snapshot's version — plus the vendored pin: every `.agents/skills/sassy-*` folder hashed against `skills-lock.json`, the lock's coverage both ways, and whether git carries the lock. Report every `drift:` line verbatim, or that the config matches the tree. Drift blocks step 8.
 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:
 
@@ -65,7 +65,7 @@ A check run never edits the config and never rewrites the tree: it prints what `
    - **`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.
    - **`none`** — nothing to commit, deliberately.
 
-9. **Report.** The config path, the topology, the resolved artifact and knowledge paths, the commit (hash and branch) or why there is none, and in `workspace` mode what was installed. 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.
+9. **Report.** The config path, the topology, the resolved artifact and knowledge paths, the commit (hash and branch) or why there is none, and in `workspace` mode what was installed, with versions (`snapshot vN`, `workspace-git vN`). 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.
 
 ## Hard rules
 
@@ -76,10 +76,10 @@ A check run never edits the config and never rewrites the tree: it prints what `
 | Verify before commit | A config that fails `--check` is reported, never committed. |
 | Approval to create a remote | Creating the mirror repo needs an explicit yes and a named slug first. |
 | No silent overwrite | An existing config or an existing `.sassywares/workspace/snapshot` is shown and asked about, never replaced blind. |
-| Version is reported | Setup names the snapshot version it installed; `--check` flags an installed copy older than the skill's. |
+| Version is reported | Setup names the snapshot and `workspace-git` versions it installed; `--check` flags an installed copy older than the skill's. |
 | Skills come from upstream | Install with `npx skills add`; never hand-copy skill files or maintain the links yourself. |
 | Never edit the manifest | No dependencies, no scripts, no `postinstall`. Setup installs the suite; the project decides how it updates. |
-| Write boundary | Only `.sassywares/`, the vendored `.agents/skills/sassy-*`, `skills-lock.json`, and one `.gitignore` line — and the same list is step 8's commit. Never `package.json`, never a root `.gitignore` in a workspace. |
+| Write boundary | Only `.sassywares/`, the vendored `.agents/skills/sassy-*`, `skills-lock.json`, and one `.gitignore` line — and the same list is step 8's commit. Never `package.json`, never a root `.gitignore` in a workspace. Workspace git helpers land in `.sassywares/workspace/`, never in a project's `bin/`. |
 | Detect, don't guess | An unknown base branch stays unknown and gets asked about. A probed value is reported as probed. |
 | Comments are part of the file | Every key keeps its description and allowed values. A stripped config is an incomplete config. |
 | Hooks are named, not written | Setup records hook skill names. Creating those skills is the project's work. |

package/skills/sassy-setup/assets/sassywares-readme.md

@@ -31,6 +31,23 @@ If a skill tells you another skill is missing, run `npx skills add sassywares/sa
 
 Or ask for `mode:check` on the setup skill, which runs the same check and reports it. Neither moves the pin: `npx skills check` is an alias of `update`.
 
+## Workspace scripts
+
+In a `workspace` project, `.sassywares/workspace/` holds the scripts that work
+across the sibling repos, next to the `snapshot` that versions the glue:
+
+```bash
+.sassywares/workspace/branches          # branch + dirty marker per repo
+.sassywares/workspace/pull              # fetch, then ff-only per repo
+.sassywares/workspace/checkout-bases    # put each repo on its base
+.sassywares/workspace/snapshot          # commit + push the glue
+```
+
+They read the repo inventory and the PR bases from `repos:` in `config.yaml`, so
+there is no second base map to keep in step. They are this project's files:
+extend them freely — just run the snapshot afterwards, since they live in the
+mirrored tree. The `sassy-*` skills do their own git and never call them.
+
 ## Hooks
 
 `hooks.pr` names project skills that run inside the PR pipeline, keyed by the PR's **head** branch: `"*"` for every PR, an exact branch, or a family such as `release/*`, overriding per point (`before_create`, `after_create`, `before_merge`, `after_merge`). An entry is `<skill> <args…>`; the args mean whatever that skill says they mean — `mode:auto` pre-authorizes the step. Hooks are ordinary skills in `.agents/skills/`, which makes them **code**: review them like code, and never point a hook at a copy of a suite skill.

package/skills/sassy-setup/assets/workspace/_lib.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# Shared helpers for the workspace git scripts: branches, pull, checkout-bases.
+#
+# Installed next to those scripts by sassy-setup, and owned by this project from
+# then on — extend it here rather than forking a copy. The one rule worth keeping
+# is that the repo inventory and the PR bases come from `repos:` in
+# .sassywares/config.yaml; never grow a second base map in this file.
+#
+# workspace-git-version: 1
+
+set -euo pipefail
+
+WORKSPACE_GIT_VERSION="1"
+
+WS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$WS_DIR/../.." && pwd)"
+CONFIG="$ROOT/.sassywares/config.yaml"
+# Nested repos conventionally push to origin; override for a workspace that does not.
+REMOTE="${WORKSPACE_GIT_REMOTE:-origin}"
+
+log()  { printf '%s\n' "$*"; }
+ok()   { printf '  ✓ %s\n' "$*"; }
+warn() { printf '  ! %s\n' "$*" >&2; }
+die()  { printf '  ✗ %s\n' "$*" >&2; exit 1; }
+
+need_git() {
+  command -v git >/dev/null 2>&1 || die "git not found"
+}
+
+[[ -f "$CONFIG" ]] || die "no config at $CONFIG — run sassy-setup"
+
+# Print `<dir><TAB><base>` for every entry under `repos:`, in file order.
+# Deliberately shallow: that one map, not a YAML parser.
+workspace_repos() {
+  awk '
+    /^[[:space:]]*#/ { next }
+    /^repos:[[:space:]]*$/ { in_repos = 1; next }
+    !in_repos { next }
+    /^[^[:space:]]/ { exit }
+    /^[[:space:]]*$/ { next }
+    {
+      line = $0
+      sub(/^[[:space:]]+/, "", line)
+      dir = line; sub(/:.*/, "", dir)
+      base = line; sub(/^[^:]*:[[:space:]]*/, "", base); sub(/[[:space:]]+#.*$/, "", base)
+      if (dir != "" && base != "") printf "%s\t%s\n", dir, base
+    }
+  ' "$CONFIG"
+}
+
+# Immediate children that are their own git repo but carry no `repos:` entry.
+# A drift signal for `branches`: never a base inferred on the project's behalf.
+unmapped_repos() {
+  local path name mapped
+  mapped="$(workspace_repos | cut -f1)"
+  for path in "$ROOT"/*/; do
+    name="$(basename "$path")"
+    [[ "$name" == node_modules || "$name" == .* ]] && continue
+    [[ -d "$path/.git" ]] || continue
+    if ! printf '%s\n' "$mapped" | grep -Fxq -- "$name"; then
+      printf '%s\n' "$name"
+    fi
+  done
+}
+
+repo_has_git() {
+  [[ -d "$1/.git" ]]
+}
+
+current_branch() {
+  git -C "$1" rev-parse --abbrev-ref HEAD 2>/dev/null
+}
+
+is_dirty() {
+  [[ -n "$(git -C "$1" status --porcelain 2>/dev/null)" ]]
+}
+
+short_head() {
+  git -C "$1" rev-parse --short HEAD 2>/dev/null
+}
+
+# The most useful line of captured git output: its first `error:`/`fatal:` line
+# when there is one, else the last non-blank line. Git's advice blocks are noise
+# in a one-line warn.
+git_err() {
+  local line
+  line="$(printf '%s\n' "$1" | grep -m1 -E '^(error|fatal):' || true)"
+  if [[ -n "$line" ]]; then
+    printf '%s\n' "$line"
+    return 0
+  fi
+  printf '%s\n' "$1" | grep -v '^[[:space:]]*$' | tail -n 1
+}

package/skills/sassy-setup/assets/workspace/branches

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# Show the current branch (and a dirty marker) for every repo in `repos:`.
+#
+# Repos that exist on disk but have no `repos:` entry are listed as unmapped —
+# add them to .sassywares/config.yaml rather than letting a base be guessed.
+#
+# Usage: .sassywares/workspace/branches [--version]
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=./_lib.sh
+source "$SCRIPT_DIR/_lib.sh"
+
+usage() {
+  cat <<EOF
+Usage: .sassywares/workspace/branches [--version]
+
+Print the current branch for each repo in the config's \`repos:\` map, with a
+trailing * when the tree is dirty and \`(base: …)\` when it is not on its base.
+
+Repos without a \`repos:\` entry are listed as unmapped; setup fills that map in.
+EOF
+}
+
+case "${1:-}" in
+  -h|--help) usage; exit 0 ;;
+  --version) printf '%s\n' "$WORKSPACE_GIT_VERSION"; exit 0 ;;
+  "") ;;
+  *) die "unknown argument: $1 (try --help)" ;;
+esac
+
+need_git
+
+found=0
+while IFS=$'\t' read -r name base; do
+  [[ -n "$name" ]] || continue
+  path="$ROOT/$name"
+  if ! repo_has_git "$path"; then
+    printf '%-22s (missing)\n' "$name"
+    continue
+  fi
+  found=1
+  branch="$(current_branch "$path")"
+  dirty=""
+  if is_dirty "$path"; then dirty=" *"; fi
+  if [[ "$branch" == "$base" ]]; then
+    printf '%-22s %s%s\n' "$name" "$branch" "$dirty"
+  else
+    printf '%-22s %s%s  (base: %s)\n' "$name" "$branch" "$dirty" "$base"
+  fi
+done < <(workspace_repos)
+
+while IFS= read -r name; do
+  printf '%-22s %s\n' "$name" "(unmapped — add it to repos: in .sassywares/config.yaml)"
+done < <(unmapped_repos)
+
+(( found > 0 )) || die "no git repos found under repos: — is the config complete?"

package/skills/sassy-setup/assets/workspace/checkout-bases

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+# Check out each repo's base branch from `repos:`.
+#
+# Only switches a repo that is on some other branch. A dirty tree that git would
+# clobber stops that repo with an error; nothing is stashed, reset, or forced.
+#
+# Usage: .sassywares/workspace/checkout-bases [--version]
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=./_lib.sh
+source "$SCRIPT_DIR/_lib.sh"
+
+usage() {
+  cat <<EOF
+Usage: .sassywares/workspace/checkout-bases [--version]
+
+For each repo in the config's \`repos:\` map, check out its base branch:
+
+  - base exists locally      → git checkout <base>
+  - base missing locally     → fetch, then track $REMOTE/<base>
+  - already on the base      → reported, untouched
+
+Uncommitted changes are never discarded. Does not fetch or pull a repo it
+already has on the base — run .sassywares/workspace/pull for that.
+EOF
+}
+
+case "${1:-}" in
+  -h|--help) usage; exit 0 ;;
+  --version) printf '%s\n' "$WORKSPACE_GIT_VERSION"; exit 0 ;;
+  "") ;;
+  *) die "unknown argument: $1 (try --help)" ;;
+esac
+
+need_git
+
+checkout_one() {
+  local name="$1" base="$2" path="$3"
+  log "$name → $base"
+
+  if [[ "$(current_branch "$path")" == "$base" ]]; then
+    ok "already on $base ($(short_head "$path"))"
+    return 0
+  fi
+
+  if git -C "$path" show-ref --verify --quiet "refs/heads/$base"; then
+    if ! out="$(git -C "$path" checkout "$base" 2>&1)"; then
+      warn "$name: could not check out $base — $(git_err "$out")"
+      return 1
+    fi
+  else
+    if ! out="$(git -C "$path" fetch --prune "$REMOTE" 2>&1)"; then
+      warn "$name: fetch failed — $(git_err "$out")"
+      return 1
+    fi
+    if ! git -C "$path" show-ref --verify --quiet "refs/remotes/$REMOTE/$base"; then
+      warn "$name: $REMOTE/$base does not exist"
+      return 1
+    fi
+    if ! out="$(git -C "$path" checkout -B "$base" "$REMOTE/$base" 2>&1)"; then
+      warn "$name: could not create $base — $(git_err "$out")"
+      return 1
+    fi
+    git -C "$path" branch --set-upstream-to="$REMOTE/$base" "$base" >/dev/null 2>&1 || true
+  fi
+
+  ok "on $base ($(short_head "$path"))"
+}
+
+found=0
+failed=0
+
+while IFS=$'\t' read -r name base; do
+  [[ -n "$name" ]] || continue
+  path="$ROOT/$name"
+  if ! repo_has_git "$path"; then
+    warn "$name: missing .git — skip"
+    continue
+  fi
+  found=1
+  checkout_one "$name" "$base" "$path" || failed=1
+done < <(workspace_repos)
+
+(( found > 0 )) || die "no git repos found under repos: — is the config complete?"
+
+if (( failed != 0 )); then
+  die "one or more repos could not be put on their base"
+fi
+
+ok "checkout-bases done"

package/skills/sassy-setup/assets/workspace/pull

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# Fetch every repo in `repos:`, then fast-forward the checked-out branch.
+#
+# Nothing is discarded: dirty trees are kept, a branch without an upstream is
+# fetched only, and a divergent branch is reported instead of merged. Switching
+# branches is checkout-bases' job, not this one.
+#
+# Usage: .sassywares/workspace/pull [--version]
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=./_lib.sh
+source "$SCRIPT_DIR/_lib.sh"
+
+usage() {
+  cat <<EOF
+Usage: .sassywares/workspace/pull [--version]
+
+For each repo in the config's \`repos:\` map:
+  1. git fetch --prune $REMOTE
+  2. git pull --ff-only when the checked-out branch has an upstream
+
+Does not switch branches. Uncommitted changes are left as-is. A repo whose base
+is missing from the remote is reported, never fixed here.
+EOF
+}
+
+case "${1:-}" in
+  -h|--help) usage; exit 0 ;;
+  --version) printf '%s\n' "$WORKSPACE_GIT_VERSION"; exit 0 ;;
+  "") ;;
+  *) die "unknown argument: $1 (try --help)" ;;
+esac
+
+need_git
+
+found=0
+failed=0
+
+while IFS=$'\t' read -r name base; do
+  [[ -n "$name" ]] || continue
+  path="$ROOT/$name"
+  if ! repo_has_git "$path"; then
+    warn "$name: missing .git — skip"
+    continue
+  fi
+  found=1
+  branch="$(current_branch "$path")"
+  log "$name ($branch)"
+  if is_dirty "$path"; then
+    warn "dirty working tree on $branch — pulling anyway (uncommitted changes kept)"
+  fi
+
+  if ! out="$(git -C "$path" fetch --prune "$REMOTE" 2>&1)"; then
+    warn "$name: fetch failed — $(git_err "$out")"
+    failed=1
+    continue
+  fi
+
+  if git -C "$path" show-ref --verify --quiet "refs/remotes/$REMOTE/$base"; then
+    ok "fetched $REMOTE/$base"
+  else
+    warn "$REMOTE/$base missing"
+  fi
+
+  upstream="$(git -C "$path" rev-parse --abbrev-ref '@{upstream}' 2>/dev/null || true)"
+  if [[ -z "$upstream" ]]; then
+    warn "no upstream for $branch — fetched only"
+    if [[ "$branch" == "$base" ]]; then
+      git -C "$path" branch --set-upstream-to="$REMOTE/$base" "$base" >/dev/null 2>&1 || true
+      upstream="$REMOTE/$base"
+    else
+      continue
+    fi
+  fi
+
+  if out="$(git -C "$path" pull --ff-only 2>&1)"; then
+    ok "pulled $branch ← $upstream"
+  else
+    warn "ff-only pull failed on $branch — $(git_err "$out")"
+    warn "  .sassywares/workspace/checkout-bases puts it back on $base"
+    failed=1
+  fi
+done < <(workspace_repos)
+
+(( found > 0 )) || die "no git repos found under repos: — is the config complete?"
+
+if (( failed != 0 )); then
+  die "one or more repos could not be fast-forwarded"
+fi
+
+ok "pull done"

package/skills/sassy-setup/references/workspace.md

@@ -1,30 +1,63 @@
 # Workspace install
 
-Read this only when the topology is `workspace`. Everything the snapshot owns
+Read this only when the topology is `workspace`. Everything setup installs
 lives under one directory:
 
 ```text
 .sassywares/
 ├── config.yaml
 └── workspace/
-    ├── snapshot    the script (tracked)
-    ├── .gitignore  exclude patterns for the sync (tracked)
-    └── mirror/     the side clone (untracked, self-excluded)
+    ├── snapshot        sync + commit + push the glue (tracked)
+    ├── branches        current branch per repo (tracked)
+    ├── pull            fetch + fast-forward per repo (tracked)
+    ├── checkout-bases  put each repo on its base (tracked)
+    ├── _lib.sh         shared helpers; reads `repos:` (tracked)
+    ├── .gitignore      exclude patterns for the sync (tracked)
+    └── mirror/         the side clone (untracked, self-excluded)
 ```
 
-- Copy `assets/snapshot` to `.sassywares/workspace/snapshot` and make it
-  executable. **If a `snapshot` file is already there, say so and ask** — it may
-  carry hand edits. Report the version you installed (`snapshot --version`) so a
-  later `--check` can catch a stale copy.
-- Write `.sassywares/workspace/.gitignore` for excluded paths (vendored trees,
-  generated dirs, `.run/`). One pattern per line, `.gitignore` style. Skip it when
-  there is nothing to exclude; the sync works without it. The mirror needs no
-  line — the script excludes it itself.
+## Install
+
+- **Snapshot.** Copy `assets/snapshot` to `.sassywares/workspace/snapshot` and
+  make it executable. **If a `snapshot` file is already there, say so and ask** —
+  it may carry hand edits. Report the version you installed
+  (`snapshot --version`) so a later `--check` can catch a stale copy.
+- **Git helpers.** Copy every file in `assets/workspace/` flat into
+  `.sassywares/workspace/` and make the three scripts executable. Report
+  `_lib.sh`'s `workspace-git-version` (or `branches --version`) the same way.
+  **Ask before overwriting any of them when they already exist** — from the first
+  install on they are the project's files, and extending them is expected.
+- **Excludes.** Write `.sassywares/workspace/.gitignore` for excluded paths
+  (vendored trees, generated dirs, `.run/`). One pattern per line, `.gitignore`
+  style. Skip it when there is nothing to exclude; the sync works without it. The
+  mirror needs no line — the script excludes it itself.
 - Do **not** add a `.gitignore` at the project root, and do not modify one that
-  exists.
+  exists. A workspace's only ignore file is the one in `workspace/`.
 - Do **not** run the snapshot during setup. It clones and pushes; that is the
   user's call. Offer `--dry-run` and run it only if they ask.
 
-The mirror remote comes from `git.remote`; the script falls back to the mirror's
+## What the git helpers are for
+
+`branches`, `pull`, and `checkout-bases` do across the workspace's repos what the
+same commands do in one repo, and they are a **human/CI convenience**. They read
+the repo inventory and the PR bases from `repos:` in `config.yaml` — no second
+base map, no probing, no inference: a repo missing from the map is reported as
+unmapped, never guessed at.
+
+- `branches` — current branch and dirty marker per repo, `(base: …)` when off base.
+- `pull` — `fetch --prune`, then `pull --ff-only` when there is an upstream.
+  Dirty trees are kept, divergent branches are reported, nothing is reset.
+- `checkout-bases` — switch to each repo's base, creating it from the remote when
+  it is missing locally. Refuses to clobber uncommitted work.
+
+They are **not** part of the skill pipeline: skills resolve bases from the config
+themselves and run their own git (`sassy-commit` cuts the branch, `sassy-babysit`
+checks out the PR head). Never point a hook at these scripts. If a project wants
+more — a status summary, a rebase flow — it extends its own copy; setup never
+rewrites them without asking.
+
+## The mirror
+
+The mirror remote comes from `git.remote`. The script falls back to the mirror's
 own `origin` once it exists. Never create the GitHub repository without the
 explicit approval described in the skill.

package/skills/sassy-setup/scripts/detect.sh

@@ -53,6 +53,7 @@ START="$(cd "$START" && pwd -P)"
 
 SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 ASSET_SNAPSHOT="$SKILL_DIR/assets/snapshot"
+ASSET_WORKSPACE="$SKILL_DIR/assets/workspace"
 
 # The nearest config wins, walking up. Report where it is if one exists.
 CONFIG=""
@@ -406,6 +407,29 @@ if (( CHECK )); then
     else
       bad "missing .sassywares/workspace/snapshot"
     fi
+
+    # The git helpers are optional as a set, but a half-installed or stale set is
+    # drift: they read `repos:` from this config, so a version skew means the
+    # project is running a reader written for a different map.
+    installed_lib="$ROOT/.sassywares/workspace/_lib.sh"
+    if [[ -f "$installed_lib" ]]; then
+      lib_v="$(sed -n 's/^# workspace-git-version: //p' "$installed_lib" | head -n 1)"
+      asset_lib_v="$(sed -n 's/^# workspace-git-version: //p' "$ASSET_WORKSPACE/_lib.sh" | head -n 1)"
+      if [[ -z "$lib_v" ]]; then
+        bad "installed .sassywares/workspace/_lib.sh has no workspace-git-version line"
+      elif [[ -n "$asset_lib_v" && "$lib_v" != "$asset_lib_v" ]]; then
+        bad "installed workspace git helpers are v${lib_v}, this skill ships v${asset_lib_v} — re-run setup"
+      else
+        note "  workspace-git v${lib_v}"
+      fi
+      for helper in branches pull checkout-bases; do
+        if [[ ! -x "$ROOT/.sassywares/workspace/$helper" ]]; then
+          bad "missing or not executable: .sassywares/workspace/$helper"
+        fi
+      done
+    else
+      note "  no workspace git helpers installed (optional)"
+    fi
     while IFS= read -r name; do
       [[ -n "$name" ]] || continue
       base="$(detect_base "$ROOT/$name")"