@techgoblin/gobstack 0.4.4-beta.1 → 0.4.4-beta.3

package/README.md

@@ -5,13 +5,34 @@ installs an **executable rule manifest**, a set of **project-local skills**, and
 **installer/verifier pair** into any project — so that an AI coding session never re-improvises,
 and a rule that cannot be checked is counted rather than asserted.
 
-Install it from npm — the one documented install path:
+Install it from npm — globally; it is a CLI, not a library:
 
-    npm i -g @techgoblin/gobstack        # gives you the `goblin` CLI
+    npm install -g @techgoblin/gobstack@beta   # gives you the `goblin` CLI (and `gob`)
+    npx @techgoblin/gobstack@beta init         # or the one-shot: run the wizard, install nothing globally
 
 ## Install
 
-    npm i -g @techgoblin/gobstack
+**Global, not local.** gobstack is a CLI with zero runtime dependencies. Install it once per
+machine:
+
+    npm install -g @techgoblin/gobstack@beta
+
+or run a single command without installing:
+
+    npx @techgoblin/gobstack@beta init
+
+**Do NOT add it to an app project's `package.json`.** A `npm install @techgoblin/gobstack` (or a
+`package.json` dependency) inside your app pollutes the app's lockfile with a package the app
+never imports, and can fail resolution outright with `ERESOLVE` when the app's own peer
+dependencies disagree with npm's. If you see `ERESOLVE` after a local install, remove the
+dependency from `package.json` and install globally instead.
+
+**The two-layer model.** The global install gives you the CLI only. `goblin init` (or
+`goblin install --target <dir> --class A`) then vendors a self-contained engine into the target
+repo under `.goblin/` — verifier, manifest, ban probes, skills, all of it. That second layer is
+why an initialized repo keeps working on machines with **no gobstack installed at all**: the
+engine lives in the repo, not in your `node_modules`, and `bash .goblin/bin/goblin-verify` (or a
+plain `git` + `bash` box) is the only runtime the repo's gate needs.
 
 Then, from any project:
 
@@ -63,7 +84,7 @@ The measurement and the vacuous-pass reading are in `docs/CONTRACTS.md`.
 | `goblin bans` | run the ban list (per-pattern red lines over the source tree) |
 | `goblin audit` | check recorded dependency claims against live advisory feeds — the only command that touches the network |
 | `goblin install` | install the manifest, skills and verifier into a target repo |
-| `goblin uninstall` | remove everything an install wrote (npm shim `goblin install --target <dir> --uninstall`) |
+| `goblin uninstall` | remove everything an install wrote, byte-exactly (`goblin install --target <dir> --uninstall` is the same job) |
 | `goblin upgrade` | migrate a repo to the shared global engine at `~/.goblin/engine` — 8 steps, two commits, one report |
 | `goblin doctor` | one run across the platforms below: DETECTED / NOT-DETECTED / DRIFT per platform |
 | `goblin emit` | write the skills + context block for one platform (`--scope project` or `global`); `--unshadow` removes a hermes project skill whose hash equals the source |
@@ -138,11 +159,44 @@ failure**, so that file is the one that matters most.
 
 ## Uninstall
 
-    goblin install --target <dir> --uninstall
+gobstack lives in three layers. Each is removed by its own command, and removing one never
+touches the others.
+
+**(a) The global CLI** — the npm package itself:
+
+    npm uninstall -g @techgoblin/gobstack
+
+This removes the `goblin` and `gob` commands from the machine and nothing else: no project, no
+repo, no `.goblin/` directory anywhere is touched. Repos you already initialized keep working
+fully — the engine is vendored into each repo's `.goblin/`, so the CLI's absence removes no
+capability (you lose the installer/upgrade/emit entry points, not the gate; see layer (c) for
+the machine-level skills the CLI wrote).
+
+**(b) A project's harness** — the `.goblin/` tree an install created in one repo:
+
+    goblin uninstall --target .
+
+(equivalently `goblin install --target . --uninstall`; through the short alias:
+`gob uninstall --target .`). The uninstall is **byte-exact**: it removes exactly the files
+`installed.json` records — hash-compared preimages, so a file you edited after install is
+reported and kept, never clobbered — then every directory that leaves empty. After it, the repo
+has zero goblin files; only the project's own record (`HANDOFF.md`, `AGENTS.md`, `reviews/`, the
+`.gitignore` block) survives, because that is the project's, not the harness's to delete. And
+because the engine is vendored, the repo needs no gobstack installed to run this — it is
+self-contained until the moment you remove it.
+
+**(c) Global agent skills** — the machine-level skills an `emit --scope global` wrote outside any
+repo:
+
+    goblin emit --undo --platform <p> --scope global
+
+(`--undo` is the same byte-exact reversal as `--uninstall`, under its friendlier name). By hand,
+the same job is deleting the platform's anchor entries: `~/.claude/skills/goblin-*` (and the
+equivalents under `~/.hermes`, `~/.copilot`, `~/.cursor`, `~/.config/opencode`, `~/.codex`,
+`~/.gemini` — `goblin doctor` lists which platforms were detected).
 
-Removes the installed artifacts, `.goblin/goblin.yaml` and every directory that leaves empty, and
-leaves `HANDOFF.md`, `AGENTS.md`, `ROUND-000-SPEC.md`, `reviews/` and the `.gitignore` block —
-the project's record is not the harness's to delete.
+The short version, for a full removal from a machine and its repos: (c) first, then (b) in each
+initialized repo, then (a).
 
 ## Re-pin the referenced standard
 

package/bin/goblin-emit

@@ -80,6 +80,7 @@ goblin emit — per-platform emission (W4a, the seven platforms since W4b).
   --skills     core (the 6 procedure skills), all (every shipped skill), none (context block only)
   --source     the skills payload; default: this CLI checkout's skills/
   --uninstall  reverse every recorded write for the platform, byte-exactly, newest first
+               (--undo is the same job under its friendlier name)
   --unshadow   hermes only: remove project skills whose hash EQUALS the source;
                refuse-and-name on any that differ (a real local edit is never auto-removed)
   --dry-run    print the full write plan (every path + the priced index size), write nothing
@@ -127,6 +128,7 @@ while [ $# -gt 0 ]; do
     --target)    TARGET="${2:-}"; OPT_TARGET=1; shift 2 ;;
     --source)    SRCSKILLS="${2:-}"; shift 2 ;;
     --uninstall) UNINSTALL=1; shift ;;
+    --undo)      UNINSTALL=1; shift ;;
     --unshadow)  UNSHADOW=1; shift ;;
     --dry-run)   DRYRUN=1; shift ;;
     --strict)    STRICT=1; shift ;;

package/bin/goblin-init

@@ -220,7 +220,7 @@ CLASS_DEFAULT=1
 if [ -z "$CLASS" ]; then
   if [ "$TTY_IN" -eq 1 ]; then
     q ""
-    q "      $C_MUTEDwhat kind of work does this repo do?$C_RESET"
+    q "      ${C_MUTED}what kind of work does this repo do?$C_RESET"
     q "      $C_TEXT  1 ▸ app        shipped features, PRs, review gates        ${C_DIM}(class A)$C_RESET"
     q "      $C_TEXT  2   service    backend jobs, config, unattended runs      ${C_DIM}(class B)$C_RESET"
     q "      $C_TEXT  3   game       playable builds, perf budgets              ${C_DIM}(class C)$C_RESET"
@@ -276,7 +276,7 @@ DEF_EMAIL=$( cd "$TARGET" && git config user.email 2>/dev/null )
 if [ -z "$BRANCH" ] || [ -z "$EMAIL" ]; then
   if [ "$TTY_IN" -eq 1 ]; then
     q ""
-    q "      $C_MUTEDthe forge contract — the identity this repo commits with (CM-01)$C_RESET"
+    q "      ${C_MUTED}the forge contract — the identity this repo commits with (CM-01)$C_RESET"
     ask_value "default branch" "$DEF_BRANCH"; BRANCH="${BRANCH:-$REPLY}"
     ask_value "owner email" "$DEF_EMAIL"; EMAIL="${EMAIL:-$REPLY}"
   else
@@ -301,14 +301,14 @@ GATE_DEFAULT="bash tests/run-tests.sh"
 if [ -z "$GATE" ]; then
   if [ "$TTY_IN" -eq 1 ]; then
     q ""
-    q "      $C_MUTEDone real command that must stay green — suggested for a bash suite:$C_RESET"
+    q "      ${C_MUTED}one real command that must stay green — suggested for a bash suite:$C_RESET"
     if [ -f "$TARGET/tests/run-tests.sh" ]; then
       q "      $C_DIM$GATE_DEFAULT$C_RESET"
       ask_value "gate command" "$GATE_DEFAULT"; GATE="$REPLY"
     else
       ask_value "gate command" "true"; GATE="$REPLY"
       if [ "$GATE" = "true" ]; then
-        q "      $C_YELLOWno tests/run-tests.sh found — a placeholder gate is allowed but it proves nothing; replace it in .goblin/goblin.yaml$C_RESET"
+        q "      ${C_YELLOW}no tests/run-tests.sh found — a placeholder gate is allowed but it proves nothing; replace it in .goblin/goblin.yaml$C_RESET"
         Q_LINES=$((Q_LINES + 1))
       fi
     fi
@@ -355,14 +355,14 @@ EMIT_N=$(printf '%s' "$EMIT_SELECTED" | awk 'NF' | wc -l | tr -d '[:space:]')
 
 if [ "$TTY_IN" -eq 1 ] && [ -z "$EMIT" ] && [ "$YES" -eq 0 ]; then
   q ""
-  q "      $C_MUTEDemit now — the skills go into:$C_RESET"
+  q "      ${C_MUTED}emit now — the skills go into:$C_RESET"
   for p in $PLATFORMS; do
     hit=""
     while IFS=$'	' read -r dp _a _b _c; do [ "$dp" = "$p" ] && hit=1; done <<< "$DET_ROWS"
     [ -n "$hit" ] || continue
     q "      $C_GREEN✔$C_RESET $C_TEXT$p$C_RESET"
   done
-  q "      $C_DIMEnter = these; or type platform names to override$C_RESET"
+  q "      ${C_DIM}Enter = these; or type platform names to override$C_RESET"
   printf '      '
   read -r REPLY_EMIT
   ASKED_ANY=1

package/bin/goblin.js

@@ -13,7 +13,13 @@
 //   goblin doctor [...]                   -> bin/goblin-doctor (W4a)
 //   goblin emit   [...]                   -> bin/goblin-emit (W4a)
 //   goblin init   [...]                   -> bin/goblin-init (W6, the first-run wizard)
-//   anything else (install)               -> bin/goblin-install
+//   goblin uninstall [--target <dir>]     -> bin/goblin-install --uninstall
+//   goblin install [...]                  -> bin/goblin-install (the one legacy fallback)
+//   no args | -h/--help | any other unrecognized first arg
+//                                         -> this file's short usage, exit 2. A bare `goblin`
+//                                            used to fall through into the installer; a typo
+//                                            (`goblin inti`) silently installed too. Both now
+//                                            print the usage and stop.
 //
 // Non-negotiables (§4.3): args are passed as an ARRAY, never a shell string (no
 // injection surface); `bash` is named explicitly (a packager stripping the
@@ -40,9 +46,58 @@ if (arg0 === "--version" || arg0 === "-V" || arg0 === "-v") {
 
 const SCRIPT = { verify: "goblin-verify", bans: "goblin-bans", audit: "goblin-audit", upgrade: "goblin-upgrade", doctor: "goblin-doctor", emit: "goblin-emit", init: "goblin-init" };
 const [cmd, ...rest] = process.argv.slice(2);
-const target = SCRIPT[cmd] ?? "goblin-install"; // install → goblin-install (v1); init is a real subcommand since W6
+
+// No args, a help flag, or an unrecognized first arg: short usage, exit 2. The one survivor of
+// the old catch-all fallback is the literal `install` first arg — bare `goblin` mapped to the
+// installer through npm's bin default, and a typo (`goblin inti`) silently installed into
+// whatever directory the shell sat in. A bare subcommand-less `goblin install ...` keeps the
+// installer; everything else stops here and names the word it did not know.
+function usage() {
+  process.stderr.write(
+[
+"goblin <command>",
+"",
+"  goblin init      start here — the guided first step (detect, class, emit, first verify)",
+"  goblin verify    run the rule matrix against the current repo",
+"  goblin bans      run the ban list (per-pattern red lines over the source tree)",
+"  goblin audit     check recorded dependency claims against live advisory feeds",
+"  goblin upgrade   migrate a repo to the shared global engine at ~/.goblin/engine",
+"  goblin doctor    one detection/drift run across the agent platforms",
+"  goblin emit      write the skills + context block for one platform",
+"  goblin uninstall --target .        remove exactly what an install wrote (preimages)",
+"",
+"start here: goblin init",
+"uninstall: npm uninstall -g @techgoblin/gobstack",
+"",
+].join("\n"));
+}
+
+if (cmd === undefined || cmd.startsWith("-")) {
+  usage();
+  process.exit(2);
+}
+if (!SCRIPT[cmd] && cmd !== "install" && cmd !== "uninstall") {
+  process.stderr.write(`goblin: unrecognized command: ${cmd}\n\n`);
+  usage();
+  process.exit(2);
+}
+
+let target;
+let extra = [];
+if (cmd === "install") {
+  target = "goblin-install"; // the one legacy fallback, kept verbatim
+} else if (cmd === "uninstall") {
+  // `goblin uninstall --target <dir>` routes into the installer's uninstall job — the shape
+  // docs/GUIDE.md and README already promise. `--uninstall` is appended FIRST so the user's
+  // own `--target <dir>` and options still parse, and a stray literal `--uninstall` cannot
+  // appear twice.
+  target = "goblin-install";
+  extra = ["--uninstall"];
+} else {
+  target = SCRIPT[cmd];
+}
 const file = path.join(__dirname, "..", "bin", target);
 // execPath-independent: call bash explicitly so Windows-WSL/Git-Bash works and no
 // shebang resolution is needed.
-const r = spawnSync("bash", [file, ...rest], { stdio: "inherit" });
+const r = spawnSync("bash", [file, ...extra, ...rest], { stdio: "inherit" });
 process.exit(r.status ?? 2);

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@techgoblin/gobstack",
-  "version": "0.4.4-beta.1",
+  "version": "0.4.4-beta.3",
   "description": "Agent-discipline toolkit: one verify command, an enforcement matrix, and LIMITS. bash engine, npm shim.",
   "bin": {
-    "goblin": "bin/goblin.js"
+    "goblin": "bin/goblin.js",
+    "gob": "bin/goblin.js"
   },
   "publishConfig": {
     "access": "public"