@friedbotstudio/create-baseline 0.4.0 → 0.6.0

package/README.md

@@ -41,7 +41,7 @@ A discipline layer for Claude Code. Hooks at every tool boundary, a workflow tha
 
 ## What this is
 
-The Claude Code Baseline is a repository overlay shipped via `npx @friedbotstudio/create-baseline ./target`. It installs **22 hooks** at Claude's tool boundaries, **37 skills** organised into nine categories, **1 subagent** for parallel work in isolated worktrees, an **11-phase workflow** from intake to commit, and **3 user-typed consent gates** that Claude cannot forge.
+The Claude Code Baseline is a repository overlay shipped via `npx @friedbotstudio/create-baseline ./target`. It installs **22 hooks** at Claude's tool boundaries, **38 skills** organised into ten categories, **1 subagent** for parallel work in isolated worktrees, an **11-phase workflow** from intake to commit, and **3 user-typed consent gates** that Claude cannot forge.
 
 Every soft engineering rule a team usually repeats every session — *don't push, don't `--amend`, don't self-approve specs, don't skip phases, don't mock internal modules* — becomes a structural guarantee because the hooks run **outside Claude's tool boundary**. Claude cannot disable a hook with a flag, cannot write a consent marker, cannot reorder the phases without an explicit exception that triage records on disk.
 

package/bin/cli.js

@@ -7,7 +7,7 @@ import { existsSync } from 'node:fs';
 
 import * as io from '../src/cli/io.js';
 import { scanSentinels } from '../src/cli/conflict.js';
-import { freshInstall, forceInstall } from '../src/cli/install.js';
+import { freshInstall, forceInstall, COPY_EXCLUDE } from '../src/cli/install.js';
 import { threeWayMerge } from '../src/cli/merge.js';
 import { loadManifest, buildManifestFromDir } from '../src/cli/manifest.js';
 import { fetchPlantumlIfMissing, FETCH_OUTCOMES } from '../src/cli/plantuml.js';
@@ -18,7 +18,7 @@ const PKG_ROOT = resolve(__dirname, '..');
 
 const HELP_TEXT = `Usage:
   create-baseline <target> [options]      install the baseline
-  create-baseline upgrade [target]        three-way merge against an installed baseline
+  create-baseline upgrade [target]        three-tier merge (mechanical / semantic / binary-prompt)
   create-baseline doctor [target]         report drift in an installed target
 
 Materializes the Claude Code baseline (.claude/, CLAUDE.md, .mcp.json,
@@ -31,10 +31,15 @@ Install modes:
 
 Upgrade:
   Replaces the prior --merge flag. Reads <target>/.claude/.baseline-manifest.json
-  and runs a three-way merge against the shipped template. Prunes baseline files
-  removed upstream that the user hadn't touched; customized-stale files are
-  preserved (exit 3) — or interactively resolved when stdout is a TTY (keep
-  mine / take theirs / abort).
+  and runs a three-tier merge against the shipped template:
+    - tier 1 (binary prompt): customized files prompt "Keep your version / Use
+      new baseline / Show diff" in TTY mode (exit 3 on any skipped).
+    - tier 2 (mechanical): files routed through git merge-file --diff3 with
+      BASE recovered from .claude/.baseline-prior/ cache or npm fallback;
+      clean merges land silently, conflicts surface with markers (exit 4).
+    - tier 3 (semantic): staged at .claude/state/upgrade/<ts>/ for the
+      /upgrade-project Claude Code skill to reconcile (exit 5).
+  Prunes baseline files removed upstream that the user hadn't touched.
   --dry-run        Print intended actions without writing.
 
 Doctor:
@@ -100,7 +105,13 @@ function getTemplateDir() {
 async function listShippedFiles(templateDir) {
   const out = [];
   await walkFiles(templateDir, templateDir, out);
-  return out;
+  // COPY_EXCLUDE was used to keep the legacy `manifest.json` at the template
+  // root from being copied to the consumer target root. The manifest now
+  // ships at `.claude/manifest.json` so no path-level exclusion is needed;
+  // COPY_EXCLUDE is currently empty but the filter stays so future entries
+  // (e.g., dev-only artifacts that accidentally leak into obj/template) can
+  // be added in one place. See src/cli/install.js → COPY_EXCLUDE.
+  return out.filter((p) => !COPY_EXCLUDE.includes(p));
 }
 
 async function walkFiles(dir, base, acc) {
@@ -111,6 +122,34 @@ async function walkFiles(dir, base, acc) {
   }
 }
 
+// Renders a usage error and the canonical HELP_TEXT through the branded TUI
+// when stderr is a TTY, falling back to plain `Error: <msg>` + help body
+// otherwise. Every non-success exit from `main()` flows through here so the
+// user always sees usage guidance alongside the failure.
+async function usageError(msg) {
+  const version = await readPackageVersion();
+  const meta = await import('../src/cli/tui/meta.js');
+  meta.renderUsageError(msg, HELP_TEXT, version);
+}
+
+// Translates Node's parseArgs error noise into a short, branded message.
+// Node emits e.g. `Unknown option '--upgrade'. To specify a positional ...`
+// which leaks library implementation detail; we collapse it and, where we
+// can identify the user's likely intent (typing `--upgrade` for the
+// `upgrade` subcommand), we hint at the correct shape.
+function friendlyParseArgsMessage(rawMessage) {
+  const firstLine = (rawMessage || '').split('\n')[0];
+  if (/Unknown option ['"]?--upgrade['"]?/.test(firstLine)) {
+    return 'Did you mean `create-baseline upgrade <target>`? `upgrade` is a subcommand, not a flag.';
+  }
+  if (/Unknown option ['"]?--doctor['"]?/.test(firstLine)) {
+    return 'Did you mean `create-baseline doctor <target>`? `doctor` is a subcommand, not a flag.';
+  }
+  const unknown = /Unknown option ['"]?([^'"]+?)['"]?(?:\.|$)/.exec(firstLine);
+  if (unknown) return `Unknown option '${unknown[1]}'.`;
+  return firstLine;
+}
+
 async function dispatchInstall(target, values, templateDir) {
   const dryRun = !!values['dry-run'];
   if (process.stdout.isTTY && !values.force && !dryRun) {
@@ -136,13 +175,13 @@ async function runPlainInstall(target, values, templateDir) {
   const dryRun = !!values['dry-run'];
   if (values.force) {
     if (!process.stdin.isTTY) {
-      io.error('--force requires an interactive TTY for the confirmation prompt');
+      await usageError('--force requires an interactive TTY for the confirmation prompt');
       return 2;
     }
     if (!dryRun) {
       const answer = await io.ask("type 'overwrite' to proceed: ");
       if (answer.toLowerCase() !== 'overwrite') {
-        io.error('confirmation declined');
+        await usageError('confirmation declined');
         return 1;
       }
     }
@@ -157,7 +196,7 @@ async function runPlainInstall(target, values, templateDir) {
       else await freshInstall(templateDir, target, { withNpmrc: !!values['with-npmrc'] });
     }
   } catch (err) {
-    io.error(`install failed: ${err.message}`);
+    await usageError(`install failed: ${err.message}`);
     return 1;
   }
 
@@ -181,7 +220,7 @@ async function fetchPlantumlPlain(target, values) {
     return 0;
   }
   if (result.outcome === FETCH_OUTCOMES.ERRORED_REQUIRE_PLANTUML) {
-    io.error(`--require-plantuml: ${result.reason}`);
+    await usageError(`--require-plantuml: ${result.reason}`);
     return 4;
   }
   return 0;
@@ -190,9 +229,16 @@ async function fetchPlantumlPlain(target, values) {
 async function dispatchUpgrade(target, values, templateDir) {
   const manifestPath = join(target, '.claude/.baseline-manifest.json');
   if (!existsSync(manifestPath)) {
-    io.error(`No baseline manifest at ${manifestPath}. Run a fresh install first.`);
+    await usageError(`No baseline manifest at ${manifestPath}. Run a fresh install first.`);
     return 2;
   }
+  const { findPendingStage } = await import('../src/cli/upgrade-tiers.js');
+  const pending = await findPendingStage(target);
+  if (pending) {
+    const fileLines = pending.files.map((f) => `  - ${f}`).join('\n');
+    io.log(`Pending semantic-merge stage at ${pending.stage_ts}.\n${pending.files.length} file(s) awaiting reconciliation:\n${fileLines}\nOpen Claude Code and run /upgrade-project to reconcile.`);
+    return 5;
+  }
   if (process.stdout.isTTY) {
     const tui = await import('../src/cli/tui/upgrade.js');
     return tui.run({
@@ -207,17 +253,32 @@ async function runPlainUpgrade(target, values, templateDir, manifestPath) {
   const oldManifest = await loadManifest(manifestPath);
   const tplFiles = await listShippedFiles(templateDir);
   const newManifest = await buildManifestFromDir(templateDir, tplFiles);
+  await overlayShippedTiers(templateDir, newManifest);
   if (values['dry-run']) {
     io.log(`Would upgrade ${tplFiles.length} files into ${target}`);
     return 0;
   }
   const report = await threeWayMerge(templateDir, target, oldManifest, newManifest);
   for (const action of report.actions) {
-    io.log(`${action.kind.padEnd(24)} ${action.path}`);
+    io.log(`${action.kind.padEnd(28)} ${action.path}`);
   }
   return report.exitCode;
 }
 
+async function overlayShippedTiers(templateDir, newManifest) {
+  const shippedPath = join(templateDir, '.claude/manifest.json');
+  if (!existsSync(shippedPath)) return;
+  const { readFile: rf } = await import('node:fs/promises');
+  const shipped = JSON.parse(await rf(shippedPath, 'utf8'));
+  if (!shipped?.files) return;
+  for (const rel of Object.keys(newManifest.files)) {
+    const shippedEntry = shipped.files[rel];
+    if (shippedEntry && typeof shippedEntry === 'object' && typeof shippedEntry.tier === 'string') {
+      newManifest.files[rel] = { sha256: newManifest.files[rel], tier: shippedEntry.tier };
+    }
+  }
+}
+
 async function dispatchDoctor(positionals, values) {
   const target = resolve(positionals[1] ?? '.');
   const report = await runDoctor(target, { strict: !!values.strict });
@@ -245,10 +306,10 @@ async function main(argv) {
     });
   } catch (err) {
     if (/--merge/.test(err.message)) {
-      io.error('--merge has been removed; use `create-baseline upgrade <target>` instead.');
+      await usageError('--merge has been removed; use `create-baseline upgrade <target>` instead.');
       return 2;
     }
-    io.error(err.message);
+    await usageError(friendlyParseArgsMessage(err.message));
     return 2;
   }
 
@@ -285,23 +346,34 @@ async function main(argv) {
     try {
       templateDir = getTemplateDir();
     } catch (err) {
-      io.error(err.message);
+      await usageError(err.message);
       return 2;
     }
     return await dispatchUpgrade(target, values, templateDir);
   }
 
   if (values['no-plantuml'] && values['require-plantuml']) {
-    io.error('--no-plantuml and --require-plantuml are mutually exclusive');
+    await usageError('--no-plantuml and --require-plantuml are mutually exclusive');
     return 2;
   }
   if (positionals.length === 0) {
-    io.error('missing required <target> argument');
-    io.error(HELP_TEXT);
+    // TTY landing: render the branded splash (skills.sh-style marquee) so the
+    // empty invocation reads as "here's what this tool does" instead of an
+    // angry error. Non-TTY keeps the strict error+help+exit-2 contract so
+    // scripts and CI still detect the missing argument.
+    if (process.stdout.isTTY) {
+      const splash = await import('../src/cli/tui/splash.js');
+      process.stdout.write(splash.renderSplash({
+        tryLine: 'npx @friedbotstudio/create-baseline ./my-project',
+        discoverUrl: 'https://baseline.friedbotstudio.com/',
+      }));
+      return 0;
+    }
+    await usageError('missing required <target> argument');
     return 2;
   }
   if (positionals.length > 1) {
-    io.error(`unexpected positional arguments: ${positionals.slice(1).join(', ')}`);
+    await usageError(`unexpected positional arguments: ${positionals.slice(1).join(', ')}`);
     return 2;
   }
 
@@ -310,15 +382,17 @@ async function main(argv) {
   try {
     templateDir = getTemplateDir();
   } catch (err) {
-    io.error(err.message);
+    await usageError(err.message);
     return 2;
   }
 
   const sentinels = await scanSentinels(target);
   const hasConflict = sentinels.length > 0;
   if (hasConflict && !values.force) {
-    io.error(`existing baseline detected at ${target}: ${sentinels.join(', ')}`);
-    io.error('pass --force to overwrite or use `create-baseline upgrade <target>` to three-way merge');
+    await usageError(
+      `existing baseline detected at ${target}: ${sentinels.join(', ')}. ` +
+        'Pass --force to overwrite or use `create-baseline upgrade <target>` to three-way merge.'
+    );
     return 1;
   }