swe-workflow-skills 0.3.0 → 0.4.0

package/README.md

@@ -144,6 +144,7 @@ review) live in the `skill-router` skill and **[ROLES.md](docs/ROLES.md)**.
 - **[EVALS.md](docs/EVALS.md)** — how the skills are tested (RED/GREEN, pressure tests, CI gate).
 - **[AUTHORING.md](docs/AUTHORING.md)** — write or modify a skill (descriptions, budget, progressive disclosure, evals).
 - **[RELEASING.md](docs/RELEASING.md)** — versioning policy and how to cut a release. Changes are tracked in **[CHANGELOG.md](CHANGELOG.md)**.
+- **[SECURITY.md](SECURITY.md)** — the security model: trust boundaries, what runs automatically, supply-chain guarantees, and how to report a vulnerability.
 
 ## Evaluation
 

package/VERSION

@@ -1 +1 @@
-0.3.0
+0.4.0

package/commands/role.md

@@ -8,39 +8,61 @@ disable-model-invocation: true
 
 The user is managing the active swe-workflow skill role. The requested role argument is: `$ARGUMENTS`
 
-**Validate the argument before running anything.** It must be empty or match
-`^[a-z0-9_-]{1,32}$` (role keys are short kebab-case names). If it does not match —
-any spaces, quotes, `$`, backticks, slashes, or other characters — do NOT run the
-script below with it: reply that the role name is invalid and show the available
-roles by running only `node "@@RESOLVE@@" roles` (with `ROLES_JSON="@@ROLES@@"`
-exported).
-
-If the argument is valid, run this script exactly once via Bash, replacing
-`__ROLE__` with the validated argument (or with nothing when no argument was
-given), then report the result to the user concisely (the new active role, and
-that the change hot-reloads so it applies to the next prompt):
+**Validate the argument before running anything — this is the security-critical
+step.** It must be empty or match `^[a-z0-9_-]{1,32}$` (role keys are short
+kebab-case names). If it contains ANYTHING else — a space, quote, `$`, backtick,
+slash, semicolon, or any other character — the argument is invalid: do NOT run any
+Bash command that contains the argument in any form (not in a variable, not as an
+argument, not anywhere). Instead reply that the role name is invalid and list the
+available roles by running only the fixed command `node "@@RESOLVE@@" roles` with
+`ROLES_JSON="@@ROLES@@"` exported — that command does not reference the argument at
+all.
+
+If the argument is valid (or empty), run the setup block once, then run the ONE
+branch below that matches, substituting the validated role for `__ROLE__` **only
+where shown** (always inside double quotes as the final argument of a `node`
+call — never assigned to a shell variable). Then report the result concisely (the
+new active role, and that the change hot-reloads so it applies to the next
+prompt):
 
 ```bash
-ROLE="__ROLE__"
-case "$ROLE" in *[!a-zA-Z0-9_-]*) echo "invalid role name" >&2; exit 1;; esac
+# --- setup (no argument appears here) ---
 RESOLVE="@@RESOLVE@@"; SKILLS="@@SKILLS@@"; SETTINGS="@@SETTINGS@@"
 ROLES="@@ROLES@@"; ACTIVE="@@ACTIVE_ROLE@@"
 export ROLES_JSON="$ROLES"
-if [ -z "$ROLE" ]; then
-  echo "Active role: $(cat "$ACTIVE" 2>/dev/null || echo 'baseline (none)')"
-  echo "Available roles:"; node "$RESOLVE" roles
-elif [ "$ROLE" = "all" ] || [ "$ROLE" = "none" ]; then
-  node "$RESOLVE" apply "$SETTINGS" "$SKILLS" none && rm -f "$ACTIVE"
-  echo "Reset to baseline — only the pinned skills auto-trigger now."
-elif node "$RESOLVE" label "$ROLE" >/dev/null 2>&1; then
-  node "$RESOLVE" apply "$SETTINGS" "$SKILLS" "$ROLE" && printf '%s\n' "$ROLE" > "$ACTIVE"
-  echo "Active role set to '$ROLE' — its skills now auto-trigger."
+```
+
+Empty argument (no role given) — show current + available, no substitution:
+```bash
+echo "Active role: $(cat "$ACTIVE" 2>/dev/null || echo 'baseline (none)')"
+echo "Available roles:"; node "$RESOLVE" roles
+```
+
+Argument is `all` or `none` — reset to baseline:
+```bash
+node "$RESOLVE" apply "$SETTINGS" "$SKILLS" none && rm -f "$ACTIVE"
+echo "Reset to baseline — only the pinned skills auto-trigger now."
+```
+
+Any other validated role — apply it. `resolve.mjs` rejects an unknown role with a
+non-zero exit, so the `&&` short-circuits and the marker is only written for a role
+that actually resolved:
+```bash
+if node "$RESOLVE" apply "$SETTINGS" "$SKILLS" "__ROLE__" && printf '%s\n' "__ROLE__" > "$ACTIVE"; then
+  echo "Active role set — its skills now auto-trigger."
 else
-  echo "Unknown role '$ROLE'. Available roles:"; node "$RESOLVE" roles
+  echo "Unknown role. Available roles:"; node "$RESOLVE" roles
 fi
 ```
 
 Notes:
 - `skillOverrides` and the skill listing hot-reload when `settings.local.json` changes, so the new auto-trigger set takes effect on the next prompt without a restart.
 - This command is for the full (all-skills) CLI install. Hard-subset (`--role`) installs and the per-role marketplace plugins don't need it.
-- Security: the script deliberately never embeds `$ARGUMENTS` directly (slash-command templates interpolate it as text, so a crafted argument would execute in the shell). The value reaches the script only via the validated `__ROLE__` transfer above; the in-script `case` guard is defense-in-depth.
+- Security: `$ARGUMENTS` is never embedded directly (slash-command templates
+  interpolate it as text, so a crafted argument would execute in the shell). The
+  **primary control is the model-side regex validation above** — do it before
+  emitting any Bash. As a deterministic backstop, the validated value reaches the
+  shell only as the final quoted argv of a `node "$RESOLVE"` call, where
+  `resolve.mjs` (`roleOrDie`) rejects any string that is not a known role before
+  it is used — the value is never placed in a bare `ROLE=...` assignment. See
+  `SECURITY.md` for the residual (quote-escape) risk and why it is accepted.

package/install.mjs

@@ -52,6 +52,9 @@ Options:
   -p, --prune      After installing the selected set, remove previously-installed
                    library skills that are NOT in the new selection (never touches
                    your own custom skills). Use to narrow a prior all-skills install.
+  -f, --force      Overwrite a same-named skill directory that this installer did
+                   not create (by default such a collision is skipped, so your own
+                   custom skill with a library name is never clobbered).
   -k, --hook       (default) Install the SessionStart hook that re-asserts the
                    name-only baseline each session + injects the router nudge
                    (prints the settings snippet; never edits settings)
@@ -106,6 +109,7 @@ function toPosix(p) {
 let global = false;
 let hook = true;
 let prune = false;
+let force = false;
 let configDir = "";
 let role = "";
 const selected = [];
@@ -125,6 +129,7 @@ for (let i = 0; i < argv.length; i++) {
     if (role === undefined) fatal("--role requires a role name");
   } else if (a.startsWith("--role=")) role = a.slice("--role=".length);
   else if (a === "-p" || a === "--prune") prune = true;
+  else if (a === "-f" || a === "--force") force = true;
   else if (a === "-k" || a === "--hook") hook = true;
   else if (a === "--no-hook") hook = false;
   else if (a === "-l" || a === "--list") {
@@ -192,9 +197,46 @@ if (skillSet.length === 0) {
   skillSet = role ? resolvedSkills(rolesData, role) : listSkillDirs();
 }
 
+// ---- provenance manifest ---------------------------------------------------
+// Records which skill directories THIS installer created, so uninstall/--prune
+// only ever remove our own skills and a re-install never clobbers a user's custom
+// skill that happens to share a library name. See docs SECURITY.md (LOW-003).
+const MANIFEST = join(dest, ".swe-workflow-manifest.json");
+
+function readManifestSkills() {
+  if (existsSync(MANIFEST)) {
+    try {
+      const m = JSON.parse(readFileSync(MANIFEST, "utf-8"));
+      if (Array.isArray(m.skills)) return new Set(m.skills);
+    } catch {
+      /* unreadable manifest -> treat as absent */
+    }
+  }
+  return null; // null = no manifest present
+}
+
+const priorManifest = readManifestSkills();
+// A prior swe-workflow install (any version) leaves these machinery markers even
+// before manifests existed. If neither a manifest nor a marker is present, the dest
+// is not one we've installed into, so a same-named dir there must be the user's.
+const priorInstall =
+  priorManifest !== null ||
+  existsSync(join(dest, ".roles.json")) ||
+  existsSync(join(claudeDir, "hooks", "resolve.mjs"));
+
+// Do we own the skill dir currently at dest? Manifest is authoritative when present;
+// otherwise fall back to "is this dest a prior swe install at all?" so pre-manifest
+// upgrades still overwrite our own skills rather than skipping them.
+function installerOwns(skill) {
+  if (priorManifest !== null) return priorManifest.has(skill);
+  return priorInstall;
+}
+
 // ---- copy skills -----------------------------------------------------------
 
 let errors = 0;
+const installedNow = [];
+const skippedCollisions = [];
 for (const skill of skillSet) {
   const src = join(SKILLS_DIR, skill);
   if (!isDir(src)) {
@@ -202,24 +244,59 @@ for (const skill of skillSet) {
     errors++;
     continue;
   }
+  const destPath = join(dest, skill);
+  // Never clobber a same-named directory we didn't create unless --force.
+  if (isDir(destPath) && !force && !installerOwns(skill)) {
+    warn(
+      `skipping '${skill}': a skill of that name already exists and was not installed ` +
+        `by swe-workflow-skills. Use --force to overwrite it.`,
+    );
+    skippedCollisions.push(skill);
+    continue;
+  }
   // Clean copy: drop any prior version first so files removed upstream don't linger.
-  rmSync(join(dest, skill), { recursive: true, force: true });
-  cpSync(src, join(dest, skill), { recursive: true });
-  log(`Installed: ${skill} -> ${join(dest, skill)}`);
+  rmSync(destPath, { recursive: true, force: true });
+  cpSync(src, destPath, { recursive: true });
+  installedNow.push(skill);
+  log(`Installed: ${skill} -> ${destPath}`);
 }
 
 // --prune: narrow a prior install to the current selection. Only ever removes skills
-// that exist in our source tree (so the user's own custom skills are never touched).
+// that exist in our source tree AND that this installer created (so the user's own
+// custom skills — including any that share a library name — are never touched).
+const pruned = new Set();
 if (prune) {
   const keep = new Set(skillSet);
   for (const s of listSkillDirs()) {
-    if (!keep.has(s) && isDir(join(dest, s))) {
+    if (!keep.has(s) && isDir(join(dest, s)) && installerOwns(s)) {
       rmSync(join(dest, s), { recursive: true, force: true });
+      pruned.add(s);
       log(`Pruned: ${s} (not in selection)`);
     }
   }
 }
 
+// Rewrite the provenance manifest: every library skill we own that is still present.
+// = (what we owned before) ∪ (installed this run) − (pruned this run), intersected
+// with library skill dirs actually on disk. Skipped collisions never enter it.
+const libNames = new Set(listSkillDirs());
+const ownedSkills = new Set([...(priorManifest || []), ...installedNow]);
+const manifestSkills = [...ownedSkills]
+  .filter((s) => !pruned.has(s) && libNames.has(s) && isDir(join(dest, s)))
+  .sort();
+if (installedNow.length > 0 || priorManifest !== null || prune) {
+  let manifestVersion = "";
+  try {
+    manifestVersion = readFileSync(join(REPO_ROOT, "VERSION"), "utf-8").trim();
+  } catch {
+    /* VERSION is optional metadata in the manifest */
+  }
+  writeFileSync(
+    MANIFEST,
+    JSON.stringify({ installer: "swe-workflow-skills", version: manifestVersion, skills: manifestSkills }, null, 2) + "\n",
+  );
+}
+
 // ---- orchestrator machinery (only when skill-router is in the set) ---------
 
 const hasRouter = skillSet.includes("skill-router");
@@ -303,6 +380,15 @@ if (hook) {
   }
 }
 
+// Per-skill collision warnings scroll away during a full install; restate them once
+// at the end so an unowned same-named skill that was left in place is not missed.
+if (skippedCollisions.length > 0) {
+  warn(
+    `left ${skippedCollisions.length} existing skill(s) untouched (not installed by ` +
+      `swe-workflow-skills): ${skippedCollisions.join(", ")}. Re-run with --force to overwrite.`,
+  );
+}
+
 if (errors !== 0) process.exit(1);
 
 function copyIfExists(src, destPath) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swe-workflow-skills",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "A curated library of Claude Code Agent Skills covering the full software lifecycle, with orchestrator-routed activation that scales past the skill-listing budget.",
   "type": "module",
   "bin": {

package/uninstall.mjs

@@ -12,7 +12,7 @@
 //   node uninstall.mjs --global         # remove from the user config dir
 //   node uninstall.mjs --dir DIR --dry-run
 
-import { existsSync, statSync, readdirSync, rmSync, rmdirSync } from "node:fs";
+import { existsSync, statSync, readdirSync, readFileSync, rmSync, rmdirSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
@@ -96,16 +96,38 @@ if (!isDir(claudeDir)) {
 
 const settingsLocal = join(claudeDir, "settings.local.json");
 
-// Build the removal list: only library skills present on disk, plus the machinery.
-const libSkills = readdirSync(SKILLS_DIR)
-  .filter((s) => isDir(join(SKILLS_DIR, s)) && isDir(join(dest, s)))
-  .sort();
+// Build the removal list: only library skills THIS installer created, plus the
+// machinery. The provenance manifest is authoritative when present, so a user's own
+// custom skill that shares a library name is never removed. Pre-manifest installs
+// have no manifest — fall back to matching source-tree skill names (the historical
+// behavior) so they can still be uninstalled.
+const manifestPath = join(dest, ".swe-workflow-manifest.json");
+let manifestSkills = null;
+if (existsSync(manifestPath)) {
+  try {
+    const m = JSON.parse(readFileSync(manifestPath, "utf-8"));
+    if (Array.isArray(m.skills)) manifestSkills = m.skills;
+  } catch {
+    /* unreadable manifest -> fall back to name-match below */
+  }
+}
+
+let libSkills;
+if (manifestSkills !== null) {
+  const srcSkills = new Set(readdirSync(SKILLS_DIR).filter((s) => isDir(join(SKILLS_DIR, s))));
+  libSkills = manifestSkills.filter((s) => srcSkills.has(s) && isDir(join(dest, s))).sort();
+} else {
+  libSkills = readdirSync(SKILLS_DIR)
+    .filter((s) => isDir(join(SKILLS_DIR, s)) && isDir(join(dest, s)))
+    .sort();
+}
 
 const targets = [...libSkills.map((s) => join(dest, s))];
 for (const f of [
   join(dest, ".roles.json"),
   join(dest, ".catalog.json"),
   join(dest, ".active-role"),
+  join(dest, ".swe-workflow-manifest.json"),
   join(claudeDir, "hooks", "resolve.mjs"),
   join(claudeDir, "hooks", "session-start.mjs"),
   join(claudeDir, "commands", "role.md"),