create-agentic-workspace 0.0.0 → 0.2.1

package/src/run.mjs

@@ -0,0 +1,208 @@
+// run.mjs — the orchestrator. Wires argv -> answers -> preview -> confirm -> reconcile -> identity
+// -> drift report -> trust hand-off. No `import` of a network module anywhere in this closure
+// (AC-BCL-9); the only reachable egress is identity.mjs's bounded `gh api user` probe.
+import fs from 'node:fs';
+import path from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { execFileSync } from 'node:child_process';
+import { QUESTION_TABLE } from './questions.mjs';
+import { parseArgv, renderHelp } from './argv.mjs';
+import { resolveAnswers, isYesMode } from './answers.mjs';
+import { RefusalError, physicalResolve, isNonEmptyDir } from './util.mjs';
+import { loadMap, buildSettings, classifyDrift } from './permissionFloor.mjs';
+import { buildManagedFiles, DECLARED_PATH_SET } from './scaffold.mjs';
+import { planManagedFiles, applyPlan, exitCodeForPlan } from './reconcile.mjs';
+import { renderPreview, TRUST_HANDOFF_TEXT } from './preview.mjs';
+import { validateSlug, resolveIdentity, wireIdentity, plannedMachineScopeWrites } from './identity.mjs';
+
+export { DECLARED_PATH_SET };
+
+function loadPins(pkgDir) {
+  const pkg = JSON.parse(fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf-8'));
+  return pkg.foundry;
+}
+
+function ensureGitRepo(physicalRoot) {
+  if (!fs.existsSync(path.join(physicalRoot, '.git'))) {
+    fs.mkdirSync(physicalRoot, { recursive: true });
+    execFileSync('git', ['init', '--quiet', physicalRoot]);
+  }
+}
+
+/** Read the target's effective permission rules (settings.json unioned with settings.local.json,
+ * origin-tracked) for the drift report. Never throws on absence; reports unreadable JSON. */
+function readEffectiveRules(physicalRoot) {
+  const effective = { allow: [], ask: [], deny: [] };
+  const unreadable = [];
+  for (const name of ['settings.json', 'settings.local.json']) {
+    const p = path.join(physicalRoot, '.claude', name);
+    if (!fs.existsSync(p)) continue;
+    try {
+      const data = JSON.parse(fs.readFileSync(p, 'utf-8'));
+      const perms = data.permissions || {};
+      for (const tierKey of ['allow', 'ask', 'deny']) {
+        for (const rule of perms[tierKey] || []) {
+          effective[tierKey].push({ rule, origin: name, tierKey });
+        }
+      }
+    } catch {
+      unreadable.push(name);
+    }
+  }
+  return { effective, unreadable };
+}
+
+function expandPluginRootGlob(glob, homeDir) {
+  // Non-recursive expansion of ~/.claude/plugins/cache/*/foundry/* against homeDir.
+  const rel = glob.replace(/^~\//, '');
+  const parts = rel.split('/');
+  let dirs = [homeDir];
+  for (const part of parts) {
+    const next = [];
+    for (const d of dirs) {
+      if (part === '*') {
+        // statSync via throwIfNoEntry:false, never a bare statSync (PR #61 security review Risk 4).
+        // This walk runs AFTER applyPlan, over the operator's own home directory, purely to derive
+        // the ADVISORY `stale-plugin-path` finding. A broken symlink inside the plugin cache — not
+        // the CLI's business and not something it can prevent — made the bare statSync throw into
+        // run.mjs's catch-all and turned a SUCCESSFUL scaffold into exit 1 plus a stack trace. An
+        // advisory probe must never be able to fail the run that already did its work.
+        const dStat = fs.statSync(d, { throwIfNoEntry: false });
+        if (dStat && dStat.isDirectory()) {
+          for (const child of fs.readdirSync(d)) {
+            const full = path.join(d, child);
+            const childStat = fs.statSync(full, { throwIfNoEntry: false });
+            if (childStat && childStat.isDirectory()) next.push(full);
+          }
+        }
+      } else {
+        const full = path.join(d, part);
+        if (fs.existsSync(full)) next.push(full);
+      }
+    }
+    dirs = next;
+  }
+  return dirs;
+}
+
+/** Run the CLI end to end. Returns { exitCode, output }. Never throws — every failure path is
+ * caught and turned into a refusal-shaped exit 1 (or, for a bug, exit 1 with the error message). */
+export async function runCli(argv, { cwd, isTTY, input, output, homeDir, pkgDir }) {
+  const lines = [];
+  const print = (s) => lines.push(s);
+
+  try {
+    let parsed;
+    try {
+      parsed = parseArgv(argv, QUESTION_TABLE);
+    } catch (e) {
+      if (e instanceof RefusalError) {
+        print(`refused: ${e.message}`);
+        return { exitCode: 1, output: lines.join('\n') };
+      }
+      throw e;
+    }
+
+    if (parsed.values.help === true) {
+      print(renderHelp(QUESTION_TABLE));
+      return { exitCode: 0, output: lines.join('\n') };
+    }
+
+    const yesMode = isYesMode(parsed.values, isTTY);
+    const answers = await resolveAnswers(QUESTION_TABLE, parsed, { yesMode, input, output });
+
+    const targetRoot = path.resolve(cwd, answers.dir);
+    const nonEmpty = isNonEmptyDir(targetRoot);
+    if (nonEmpty && !answers.existing) {
+      throw new RefusalError(
+        `${targetRoot} exists and is non-empty; use --existing to scaffold into it`,
+        'existing',
+      );
+    }
+    if (nonEmpty && answers.existing && !yesMode) {
+      const rl = createInterface({ input, output });
+      const typed = (await rl.question(`Type the directory's basename to confirm ('${path.basename(targetRoot)}'): `)).trim();
+      rl.close();
+      if (typed !== path.basename(targetRoot)) {
+        throw new RefusalError('basename confirmation did not match; refusing', 'existing');
+      }
+    }
+
+    let slug = '';
+    if (answers.ghAccount) {
+      slug = validateSlug(answers.ghAccount);
+    }
+
+    const physicalRoot = physicalResolve(targetRoot);
+    const map = loadMap(path.join(pkgDir, 'permission-floor.json'));
+    const pins = loadPins(pkgDir);
+    const settingsObj = buildSettings(map, pins);
+    const settingsBytes = Buffer.from(`${JSON.stringify(settingsObj, null, 2)}\n`, 'utf-8');
+
+    const managedFiles = buildManagedFiles({
+      templatesDir: path.join(pkgDir, 'templates'),
+      physicalRoot,
+      projectName: path.basename(targetRoot),
+      stageMode: answers.stageMode,
+      settingsBytes,
+    });
+    const plan = planManagedFiles(managedFiles);
+    const machineScopeWrites = slug ? plannedMachineScopeWrites({ slug, targetRoot, homeDir }) : [];
+
+    print(renderPreview({ plan, machineScopeWrites, map }));
+
+    if (answers.dryRun) {
+      print('(dry-run: no write, no side effect, zero child processes spawned)');
+      return { exitCode: 0, output: lines.join('\n') };
+    }
+
+    if (!yesMode) {
+      const rl = createInterface({ input, output });
+      const confirm = (await rl.question('Write the workspace as previewed above? [y/N]: ')).trim().toLowerCase();
+      rl.close();
+      if (confirm !== 'y' && confirm !== 'yes') {
+        throw new RefusalError('write-phase confirmation declined; writing nothing');
+      }
+    }
+
+    applyPlan(plan);
+
+    if (slug) {
+      ensureGitRepo(physicalRoot);
+      const identity = await resolveIdentity(slug, {
+        gitAuthor: answers.gitAuthor,
+        homeDir,
+        isTTY,
+        promptFn: isTTY
+          ? async (q) => {
+              const rl = createInterface({ input, output });
+              const a = await rl.question(q);
+              rl.close();
+              return a;
+            }
+          : null,
+      });
+      wireIdentity({ slug, name: identity.name, email: identity.email, targetRoot: physicalRoot, homeDir });
+    }
+
+    const { effective, unreadable } = readEffectiveRules(physicalRoot);
+    const pluginRootExpansion = expandPluginRootGlob(map.plugin_root_glob, homeDir);
+    const findings = classifyDrift(map, effective, { pluginRootExpansion, unreadableOrigins: unreadable });
+    if (findings.length > 0) {
+      print('');
+      print(`Permission-floor report (advisory, ${findings.length} finding(s)):`);
+      for (const f of findings) print(`  [${f.class}] ${JSON.stringify(f)}`);
+    }
+
+    print(TRUST_HANDOFF_TEXT(targetRoot));
+
+    return { exitCode: exitCodeForPlan(plan), output: lines.join('\n') };
+  } catch (e) {
+    if (e instanceof RefusalError) {
+      print(`refused: ${e.message}`);
+      return { exitCode: 1, output: lines.join('\n') };
+    }
+    print(`error: ${e.stack || e.message}`);
+    return { exitCode: 1, output: lines.join('\n') };
+  }
+}

package/src/scaffold.mjs

@@ -0,0 +1,71 @@
+// scaffold.mjs — the closed, schema-valid seven-file scaffold (AC-BCL-6) + settings.json,
+// materialized through the confinement join (AC-BCL-9). Template entries are declared once, here.
+import fs from 'node:fs';
+import path from 'node:path';
+import { confinedJoin, RefusalError } from './util.mjs';
+
+/** The closed template-materialization manifest (AC-BCL-6's six template-derived paths;
+ * .claude/settings.json is the seventh, generated separately — see buildManagedFiles). */
+export const TEMPLATE_ENTRIES = Object.freeze([
+  { template: 'CLAUDE.md.tmpl', target: 'CLAUDE.md' },
+  { template: 'gitignore.tmpl', target: '.gitignore' },
+  { template: 'foundry-project.json.tmpl', target: '.claude/foundry-project.json' },
+  { template: 'specs-features-README.md', target: 'specs/features/README.md' },
+  { template: 'specs-lifecycle-README.md', target: 'specs/lifecycle/README.md' },
+  { template: 'foundry-README.md', target: '.foundry/README.md' },
+]);
+
+/** Render a template's raw text with the CLAUDE.md substitutions (the only templated file). */
+function renderTemplate(target, raw, { projectName, stageMode }) {
+  if (target === 'CLAUDE.md') {
+    return raw.replaceAll('{{PROJECT_NAME}}', projectName).replaceAll('{{STAGE_MODE}}', stageMode);
+  }
+  return raw;
+}
+
+/** Build the full managed-file set: the six templated paths + the generated settings.json,
+ * joined onto the physically-resolved target root, refusing (RefusalError) any entry whose
+ * resolution escapes it (AC-BCL-9). `entries` defaults to TEMPLATE_ENTRIES; tests may inject a
+ * mutated list to exercise the traversal refusal without touching the shipped manifest. */
+export function buildManagedFiles({
+  templatesDir,
+  physicalRoot,
+  projectName,
+  stageMode,
+  settingsBytes,
+  entries = TEMPLATE_ENTRIES,
+}) {
+  const files = [];
+  for (const entry of entries) {
+    const joined = confinedJoin(physicalRoot, entry.target);
+    if (joined === null) {
+      throw new RefusalError(
+        `refusing to materialize ${entry.template}: path escapes the target root (${entry.target})`,
+        entry.target,
+      );
+    }
+    const raw = fs.readFileSync(path.join(templatesDir, entry.template), 'utf-8');
+    const rendered = renderTemplate(entry.target, raw, { projectName, stageMode });
+    files.push({ relPath: entry.target, absPath: joined, bytes: Buffer.from(rendered, 'utf-8') });
+  }
+
+  const settingsJoined = confinedJoin(physicalRoot, '.claude/settings.json');
+  if (settingsJoined === null) {
+    throw new RefusalError(
+      'refusing to write .claude/settings.json: path escapes the target root',
+      '.claude/settings.json',
+    );
+  }
+  files.push({ relPath: '.claude/settings.json', absPath: settingsJoined, bytes: settingsBytes });
+  return files;
+}
+
+export const DECLARED_PATH_SET = Object.freeze([
+  'CLAUDE.md',
+  '.gitignore',
+  '.claude/settings.json',
+  '.claude/foundry-project.json',
+  'specs/features/README.md',
+  'specs/lifecycle/README.md',
+  '.foundry/README.md',
+]);

package/src/util.mjs

@@ -0,0 +1,78 @@
+// util.mjs — small shared helpers. No third-party deps; node: builtins and relative imports only.
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** A refusal: the CLI writes nothing and names the offending flag/path/entry. */
+export class RefusalError extends Error {
+  constructor(message, flag) {
+    super(message);
+    this.name = 'RefusalError';
+    this.flag = flag;
+  }
+}
+
+export function sha256(bytes) {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+/** Physically resolve a path (symlinks followed), even if it does not yet exist — resolves the
+ * longest existing ancestor and joins the remaining (non-existent) segments onto it. */
+export function physicalResolve(targetPath) {
+  const abs = path.resolve(targetPath);
+  const parts = abs.split(path.sep);
+  let base = path.sep;
+  let i = 1;
+  // find the longest existing ancestor
+  let existing = abs;
+  const missing = [];
+  while (existing !== path.sep && !fs.existsSync(existing)) {
+    missing.unshift(path.basename(existing));
+    existing = path.dirname(existing);
+  }
+  const realBase = fs.existsSync(existing) ? fs.realpathSync(existing) : existing;
+  return missing.length ? path.join(realBase, ...missing) : realBase;
+}
+
+/** Join a template-relative path onto a physically-resolved target root, refusing (returns null)
+ * any resolution that escapes the root — an absolute template path, a `..` segment, or a
+ * symlinked ancestor that resolves outside. Never throws; callers decide how to report. */
+export function confinedJoin(physicalRoot, relPath) {
+  if (path.isAbsolute(relPath)) return null;
+  const segments = relPath.split(/[\\/]+/);
+  if (segments.some((s) => s === '..')) return null;
+  const joined = path.join(physicalRoot, relPath);
+  const resolved = physicalResolve(joined);
+  const rootWithSep = physicalRoot.endsWith(path.sep) ? physicalRoot : physicalRoot + path.sep;
+  if (resolved !== physicalRoot && !resolved.startsWith(rootWithSep)) return null;
+  return joined;
+}
+
+export function ensureDirFor(filePath) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+export function fileBytesEqual(existingPath, desiredBytes) {
+  // lstat, NOT existsSync (PR #61 security review Block 2). existsSync FOLLOWS symlinks, so a
+  // DANGLING symlink at a managed path reported `false` -> the row was classified `create` ->
+  // writeFileSync followed the link and landed the write at the link's target, OUTSIDE the
+  // physically-resolved target root (AC-BCL-9) and reachable at $HOME/.claude/settings.json
+  // (AC-BCL-4(d)) — a user-scope settings file is NOT gated by the workspace trust dialog, so on
+  // that one path the CLI stopped declaring and started granting. lstat does not follow the final
+  // component, so ANY existing entry — dangling symlink included — is seen and falls to the
+  // `notRegular` arm below, i.e. `drifted`: reported, never written. Symlinks whose targets EXIST
+  // were already caught (realpath resolves them out of root), as were symlinked ancestors; this
+  // closes the dangling-leaf case, the only one that escaped.
+  const stat = fs.lstatSync(existingPath, { throwIfNoEntry: false });
+  if (!stat) return { present: false, equal: false };
+  if (!stat.isFile()) return { present: true, equal: false, notRegular: true };
+  const actual = fs.readFileSync(existingPath);
+  return { present: true, equal: Buffer.compare(actual, Buffer.from(desiredBytes)) === 0 };
+}
+
+export function isNonEmptyDir(dirPath) {
+  if (!fs.existsSync(dirPath)) return false;
+  const stat = fs.lstatSync(dirPath);
+  if (!stat.isDirectory()) return true; // exists as a non-directory: treat as "occupied"
+  return fs.readdirSync(dirPath).length > 0;
+}

package/templates/CLAUDE.md.tmpl

@@ -0,0 +1,16 @@
+# {{PROJECT_NAME}} — an Agentic Foundry workspace
+
+This workspace was scaffolded by `npx create-agentic-workspace`. The Agentic Foundry plugin's
+verbs are `/foundry:*`; run `/foundry:init` inside a trusted Claude Code session to finish the
+logical wiring (operator registry, project config), then `/foundry:doctor` to confirm
+`DOCTOR-GREEN`.
+
+## Stage mode
+
+Stage mode: {{STAGE_MODE}}
+
+`lean` favors the direct loop with lighter ceremony; `scale` enforces the full gates.
+
+## Conventions
+
+Specs are atomic: `specs/features/<domain>/<capability>/feat-<capability>.md`, each with stable AC-IDs, a delimited `<!-- normative -->` region, and a sibling `acceptance-contract.yaml`.

package/templates/foundry-README.md

@@ -0,0 +1,5 @@
+# .foundry/
+
+Runtime state for the Agentic Foundry plugin. Most of this directory is git-ignored by default
+(see the managed block in the workspace's `.gitignore`); only a small, deliberately re-included
+set is tracked — this file among them.

package/templates/foundry-project.json.tmpl

@@ -0,0 +1,9 @@
+{
+  "schema_version": 1,
+  "repos": {
+    "workspace": {
+      "path": ".",
+      "role": "workspace"
+    }
+  }
+}

package/templates/gitignore.tmpl

@@ -0,0 +1,18 @@
+# Managed by create-agentic-workspace. The block below is byte-identical to the shipped
+# scripts/foundry-runtime.gitignore applier's own content (AC-BCL-5) so the two can never diverge.
+# FOUNDRY-RUNTIME-GITIGNORE-BEGIN
+# .foundry/ runtime partitions are ignored by default; the designed-tracked set is re-included.
+/.foundry/*
+!/.foundry/README.md
+!/.foundry/build-provenance.yaml
+!/.foundry/stack-profile.lock
+# FOUNDRY-RUNTIME-GITIGNORE-END
+
+# Local, UNGATED permission overrides — never commit them (PR #61 security review Risk 5).
+# The floor model this workspace is scaffolded around distinguishes the committed
+# .claude/settings.json, whose `allow` rules take effect only after the operator accepts the trust
+# dialog that lists them, from .claude/settings.local.json, which is read with NO trust ceremony
+# (it is where the harness's "always allow" persist option writes). A committed settings.local.json
+# would therefore propagate ungated local grants to every clone, with no dialog and no review —
+# which is precisely the shadowing that /foundry:doctor's permission-floor probe exists to report.
+/.claude/settings.local.json

package/templates/specs-features-README.md

@@ -0,0 +1,7 @@
+# specs/features/
+
+Atomic feature specs live here, one directory per capability:
+`specs/features/<domain>/<capability>/feat-<capability>.md`, each with stable AC-IDs, a
+delimited `<!-- normative -->` region, and a sibling `acceptance-contract.yaml`.
+
+Run `/foundry:intake "…"` inside a trusted Claude Code session to draft the first one.

package/templates/specs-lifecycle-README.md

@@ -0,0 +1,5 @@
+# specs/lifecycle/
+
+Cross-cutting lifecycle records (release notes, decision logs, and similar non-atomic
+governance artifacts) live here, separate from the atomic per-capability specs under
+`specs/features/`.

package/bin.mjs

@@ -1,7 +0,0 @@
-#!/usr/bin/env node
-console.error(
-  "create-agentic-workspace@0.0.0 is a placeholder published only to bootstrap\n" +
-  "npm trusted publishing. It does nothing. Install the latest version instead:\n" +
-  "  npx create-agentic-workspace@latest\n"
-);
-process.exit(1);