@pleri/olam-cli 0.1.110 → 0.1.111

package/dist/index.js

@@ -487,8 +487,8 @@ var init_parseUtil = __esm({
     init_errors();
     init_en();
     makeIssue = (params) => {
-      const { data, path: path53, errorMaps, issueData } = params;
-      const fullPath = [...path53, ...issueData.path || []];
+      const { data, path: path55, errorMaps, issueData } = params;
+      const fullPath = [...path55, ...issueData.path || []];
       const fullIssue = {
         ...issueData,
         path: fullPath
@@ -796,11 +796,11 @@ var init_types = __esm({
     init_parseUtil();
     init_util();
     ParseInputLazyPath = class {
-      constructor(parent, value, path53, key) {
+      constructor(parent, value, path55, key) {
         this._cachedPath = [];
         this.parent = parent;
         this.data = value;
-        this._path = path53;
+        this._path = path55;
         this._key = key;
       }
       get path() {
@@ -4281,7 +4281,7 @@ import YAML from "yaml";
 function bootstrapStepCmd(entry) {
   return typeof entry === "string" ? entry : entry.cmd;
 }
-function refineForbiddenKeys(value, path53, ctx, rejectSource) {
+function refineForbiddenKeys(value, path55, ctx, rejectSource) {
   if (value === null || typeof value !== "object" || Array.isArray(value)) {
     return;
   }
@@ -4289,12 +4289,12 @@ function refineForbiddenKeys(value, path53, ctx, rejectSource) {
     if (FORBIDDEN_KEYS.has(key)) {
       ctx.addIssue({
         code: external_exports.ZodIssueCode.custom,
-        path: [...path53, key],
+        path: [...path55, key],
         message: `forbidden key "${key}" (prototype-pollution surface)`
       });
       continue;
     }
-    if (rejectSource && path53.length === 0 && key === "source") {
+    if (rejectSource && path55.length === 0 && key === "source") {
       ctx.addIssue({
         code: external_exports.ZodIssueCode.custom,
         path: ["source"],
@@ -4302,21 +4302,21 @@ function refineForbiddenKeys(value, path53, ctx, rejectSource) {
       });
       continue;
     }
-    refineForbiddenKeys(value[key], [...path53, key], ctx, false);
+    refineForbiddenKeys(value[key], [...path55, key], ctx, false);
   }
 }
-function rejectForbiddenKeys(value, path53, rejectSource) {
+function rejectForbiddenKeys(value, path55, rejectSource) {
   if (value === null || typeof value !== "object" || Array.isArray(value)) {
     return;
   }
   for (const key of Object.keys(value)) {
     if (FORBIDDEN_KEYS.has(key)) {
-      throw new Error(`[manifest] ${path53}: forbidden key "${key}" (prototype-pollution surface)`);
+      throw new Error(`[manifest] ${path55}: forbidden key "${key}" (prototype-pollution surface)`);
     }
     if (rejectSource && key === "source") {
-      throw new Error(`[manifest] ${path53}: top-level "source" is loader-stamped \u2014 manifests must not author it`);
+      throw new Error(`[manifest] ${path55}: top-level "source" is loader-stamped \u2014 manifests must not author it`);
     }
-    rejectForbiddenKeys(value[key], `${path53}.${key}`, false);
+    rejectForbiddenKeys(value[key], `${path55}.${key}`, false);
   }
 }
 function unknownTopLevelKeys(parsed) {
@@ -5309,8 +5309,8 @@ var init_client = __esm({
           throw new Error(`failed to report rate-limit for ${accountId} (HTTP ${res.status})`);
         }
       }
-      async request(method, path53, body, attempt = 0) {
-        const url = `${this.baseUrl}${path53}`;
+      async request(method, path55, body, attempt = 0) {
+        const url = `${this.baseUrl}${path55}`;
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), this.timeoutMs);
         const headers = {};
@@ -5328,7 +5328,7 @@ var init_client = __esm({
         } catch (err) {
           if (attempt < RETRY_COUNT && isTransient(err)) {
             await sleep(RETRY_BACKOFF_MS * (attempt + 1));
-            return this.request(method, path53, body, attempt + 1);
+            return this.request(method, path55, body, attempt + 1);
           }
           throw err;
         } finally {
@@ -6877,8 +6877,8 @@ var init_provider3 = __esm({
       // -----------------------------------------------------------------------
       // Internal fetch helper
       // -----------------------------------------------------------------------
-      async request(path53, method, body) {
-        const url = `${this.config.workerUrl}${path53}`;
+      async request(path55, method, body) {
+        const url = `${this.config.workerUrl}${path55}`;
         const bearer = await this.config.mintToken();
         const headers = {
           Authorization: `Bearer ${bearer}`
@@ -8170,8 +8170,8 @@ import { execFileSync as execFileSync3 } from "node:child_process";
 import * as fs14 from "node:fs";
 import * as os9 from "node:os";
 import * as path15 from "node:path";
-function expandHome(p, homedir29) {
-  return p.replace(/^~(?=$|\/|\\)/, homedir29());
+function expandHome(p, homedir30) {
+  return p.replace(/^~(?=$|\/|\\)/, homedir30());
 }
 function sanitizeRepoFilename(name) {
   const sanitized = name.replace(/[^A-Za-z0-9._-]/g, "_");
@@ -8194,7 +8194,7 @@ ${stderr}`;
 }
 function snapshotBaselineDiff(repos, workspacePath, deps = {}) {
   const exec = deps.exec ?? ((cmd, args, opts) => execFileSync3(cmd, args, opts));
-  const homedir29 = deps.homedir ?? (() => os9.homedir());
+  const homedir30 = deps.homedir ?? (() => os9.homedir());
   const baselineDir = path15.join(workspacePath, ".olam", "baseline");
   try {
     fs14.mkdirSync(baselineDir, { recursive: true });
@@ -8210,7 +8210,7 @@ function snapshotBaselineDiff(repos, workspacePath, deps = {}) {
       continue;
     const filename = `${sanitizeRepoFilename(repo.name)}.diff`;
     const outPath = path15.join(baselineDir, filename);
-    const repoPath = expandHome(repo.path, homedir29);
+    const repoPath = expandHome(repo.path, homedir30);
     if (!fs14.existsSync(repoPath)) {
       writeBaselineFile(outPath, `# repo: ${repo.name}
 # (skipped: path ${repoPath} does not exist)
@@ -13822,10 +13822,10 @@ async function readHostCpToken2() {
   if (!fs25.existsSync(tp)) return null;
   return fs25.readFileSync(tp, "utf-8").trim();
 }
-async function callHostCpProxy(method, worldId, path53, body) {
+async function callHostCpProxy(method, worldId, path55, body) {
   const token = await readHostCpToken2();
   if (!token) return { ok: false, status: 0, error: "no token (host CP not started)" };
-  const url = `http://127.0.0.1:${HOST_CP_PORT}/api/world/${encodeURIComponent(worldId)}${path53}`;
+  const url = `http://127.0.0.1:${HOST_CP_PORT}/api/world/${encodeURIComponent(worldId)}${path55}`;
   try {
     const headers = {
       Authorization: `Bearer ${token}`
@@ -14285,7 +14285,7 @@ __export(machine_schema_exports, {
   writeMachineConfig: () => writeMachineConfig
 });
 import * as fs41 from "node:fs";
-import * as path45 from "node:path";
+import * as path47 from "node:path";
 import * as os24 from "node:os";
 import { parse as parseYaml5, stringify as stringifyYaml5 } from "yaml";
 function readMachineConfig(configPath) {
@@ -14302,7 +14302,7 @@ function readMachineConfig(configPath) {
 }
 function writeMachineConfig(config, configPath) {
   const p = configPath ?? DEFAULT_CONFIG_PATH;
-  fs41.mkdirSync(path45.dirname(p), { recursive: true });
+  fs41.mkdirSync(path47.dirname(p), { recursive: true });
   fs41.writeFileSync(p, stringifyYaml5({ ...config }), { mode: 420 });
 }
 function initMachineConfig(opts = {}) {
@@ -14326,9 +14326,9 @@ var init_machine_schema = __esm({
       channel: external_exports.enum(["stable", "beta", "edge"]).default("stable"),
       auto_update: external_exports.boolean().default(true),
       telemetry: external_exports.boolean().default(true),
-      worlds_dir: external_exports.string().default(() => path45.join(os24.homedir(), ".olam", "worlds"))
+      worlds_dir: external_exports.string().default(() => path47.join(os24.homedir(), ".olam", "worlds"))
     });
-    DEFAULT_CONFIG_PATH = path45.join(os24.homedir(), ".olam", "config.yaml");
+    DEFAULT_CONFIG_PATH = path47.join(os24.homedir(), ".olam", "config.yaml");
   }
 });
 
@@ -14710,9 +14710,9 @@ var UnknownArchetypeError = class extends Error {
 };
 var ArchetypeCycleError = class extends Error {
   path;
-  constructor(path53) {
-    super(`Archetype inheritance cycle detected: ${path53.join(" \u2192 ")} \u2192 ${path53[0] ?? "?"}`);
-    this.path = path53;
+  constructor(path55) {
+    super(`Archetype inheritance cycle detected: ${path55.join(" \u2192 ")} \u2192 ${path55[0] ?? "?"}`);
+    this.path = path55;
     this.name = "ArchetypeCycleError";
   }
 };
@@ -15359,8 +15359,8 @@ function runStep(label, cmd, args, opts = {}) {
 }
 async function confirm(message) {
   if (!process.stdin.isTTY) return true;
-  const { createInterface: createInterface5 } = await import("node:readline");
-  const rl = createInterface5({ input: process.stdin, output: process.stdout });
+  const { createInterface: createInterface6 } = await import("node:readline");
+  const rl = createInterface6({ input: process.stdin, output: process.stdout });
   return new Promise((resolve11) => {
     rl.question(`${message} [y/N] `, (answer) => {
       rl.close();
@@ -16093,9 +16093,9 @@ function formatFreshnessWarning(result, image = DEFAULT_DEVBOX_IMAGE) {
     "These source files have changed since the image was built; the",
     "changes will NOT take effect in fresh worlds until you rebuild:"
   ];
-  for (const { path: path53, mtimeMs } of result.newerSources) {
+  for (const { path: path55, mtimeMs } of result.newerSources) {
     const when = new Date(mtimeMs).toISOString();
-    lines.push(`  \u2022 ${path53}  (modified ${when})`);
+    lines.push(`  \u2022 ${path55}  (modified ${when})`);
   }
   lines.push("");
   lines.push("Rebuild with:");
@@ -16256,9 +16256,9 @@ async function readHostCpTokenForCreate() {
   try {
     const { default: fs50 } = await import("node:fs");
     const { default: os28 } = await import("node:os");
-    const { default: path53 } = await import("node:path");
-    const tp = path53.join(
-      process.env.OLAM_HOME ?? path53.join(os28.homedir(), ".olam"),
+    const { default: path55 } = await import("node:path");
+    const tp = path55.join(
+      process.env.OLAM_HOME ?? path55.join(os28.homedir(), ".olam"),
       "host-cp.token"
     );
     if (!fs50.existsSync(tp)) return null;
@@ -16627,8 +16627,8 @@ async function readHostCpToken3() {
   try {
     const { default: fs50 } = await import("node:fs");
     const { default: os28 } = await import("node:os");
-    const { default: path53 } = await import("node:path");
-    const tp = path53.join(os28.homedir(), ".olam", "host-cp.token");
+    const { default: path55 } = await import("node:path");
+    const tp = path55.join(os28.homedir(), ".olam", "host-cp.token");
     if (!fs50.existsSync(tp)) return null;
     const raw = fs50.readFileSync(tp, "utf-8").trim();
     return raw.length > 0 ? raw : null;
@@ -20361,11 +20361,11 @@ function zodIssueToError(issue, doc, lineCounter) {
     suggestion: deriveSuggestion(issue)
   };
 }
-function formatJsonPath(path53) {
-  if (path53.length === 0)
+function formatJsonPath(path55) {
+  if (path55.length === 0)
     return "<root>";
   let out = "";
-  for (const seg of path53) {
+  for (const seg of path55) {
     if (typeof seg === "number") {
       out += `[${seg}]`;
     } else {
@@ -20374,11 +20374,11 @@ function formatJsonPath(path53) {
   }
   return out;
 }
-function resolveYamlLocation(path53, doc, lineCounter) {
+function resolveYamlLocation(path55, doc, lineCounter) {
   let bestLine = 0;
   let bestColumn = 0;
-  for (let depth = path53.length; depth >= 0; depth -= 1) {
-    const segment = path53.slice(0, depth);
+  for (let depth = path55.length; depth >= 0; depth -= 1) {
+    const segment = path55.slice(0, depth);
     try {
       const node = doc.getIn(segment, true);
       if (node && typeof node === "object" && "range" in node) {
@@ -20596,11 +20596,11 @@ function topoSort(nodes) {
 }
 function traceCycle(start, byId) {
   const seen = /* @__PURE__ */ new Set();
-  const path53 = [];
+  const path55 = [];
   let current = start;
   while (current && !seen.has(current)) {
     seen.add(current);
-    path53.push(current);
+    path55.push(current);
     const node = byId.get(current);
     const next = node?.dependsOn[0];
     if (next === void 0)
@@ -20608,10 +20608,10 @@ function traceCycle(start, byId) {
     current = next;
   }
   if (current && seen.has(current)) {
-    const idx = path53.indexOf(current);
-    return [...path53.slice(idx), current];
+    const idx = path55.indexOf(current);
+    return [...path55.slice(idx), current];
   }
-  return path53;
+  return path55;
 }
 
 // ../core/dist/executor/types.js
@@ -23018,8 +23018,8 @@ function performRollbackSwap(plan) {
 }
 async function confirm2(message) {
   if (!process.stdin.isTTY) return true;
-  const { createInterface: createInterface5 } = await import("node:readline");
-  const rl = createInterface5({ input: process.stdin, output: process.stdout });
+  const { createInterface: createInterface6 } = await import("node:readline");
+  const rl = createInterface6({ input: process.stdin, output: process.stdout });
   return new Promise((resolve11) => {
     rl.question(`${message} [y/N] `, (answer) => {
       rl.close();
@@ -25493,16 +25493,318 @@ function registerCompletion(program2) {
   });
 }
 
+// src/commands/setup.ts
+init_cli_version();
+import { spawn as spawn5 } from "node:child_process";
+import { existsSync as existsSync45 } from "node:fs";
+import { homedir as homedir23 } from "node:os";
+import path45 from "node:path";
+import { createInterface as createInterface3 } from "node:readline";
+
+// src/lib/shell-rc.ts
+import { copyFileSync as copyFileSync5, existsSync as existsSync44, readFileSync as readFileSync31, renameSync as renameSync4, writeFileSync as writeFileSync20 } from "node:fs";
+import path44 from "node:path";
+function appendIdempotent(opts) {
+  const { rcPath, marker, contentLine, clock = () => /* @__PURE__ */ new Date() } = opts;
+  if (!existsSync44(rcPath)) {
+    return { status: "no-rc-file", backupPath: null };
+  }
+  const content = readFileSync31(rcPath, "utf-8");
+  if (content.includes(marker)) {
+    return { status: "already-present", backupPath: null };
+  }
+  const timestamp = clock().toISOString().replace(/[:.]/g, "-");
+  const backupPath = `${rcPath}.olam-bak.${timestamp}`;
+  copyFileSync5(rcPath, backupPath);
+  const separator = content.length === 0 || content.endsWith("\n") ? "" : "\n";
+  const trailing = contentLine.endsWith("\n") ? "" : "\n";
+  const nextContent = `${content}${separator}${contentLine}${trailing}`;
+  const tmpPath = `${rcPath}.olam-tmp.${process.pid}`;
+  writeFileSync20(tmpPath, nextContent, { encoding: "utf-8" });
+  renameSync4(tmpPath, rcPath);
+  return { status: "appended", backupPath };
+}
+function resolveShellRc(home, shellEnv) {
+  if (!shellEnv) return null;
+  const basename6 = path44.basename(shellEnv);
+  if (basename6 === "zsh") return path44.join(home, ".zshrc");
+  if (basename6 === "bash") return path44.join(home, ".bashrc");
+  return null;
+}
+
+// src/commands/setup.ts
+init_output();
+var REQUIRED_NODE_MAJOR = 20;
+var NEXT_STEPS_DOCS = [
+  "docs/architecture/devbox-contract.md  \u2014 image contract",
+  "docs/architecture/manifest-spec.md    \u2014 per-repo .adb.yaml schema",
+  "docs/architecture/config-spec.md      \u2014 workspace .olam/config.yaml schema"
+];
+var defaultSpawn = (cmd, args) => new Promise((resolve11) => {
+  const child = spawn5(cmd, [...args], { stdio: "inherit" });
+  child.on("exit", (code) => resolve11({ status: code }));
+  child.on("error", () => resolve11({ status: 1 }));
+});
+var defaultPrompt = (question, defaultYes) => {
+  if (!process.stdin.isTTY) {
+    process.stderr.write(
+      `[olam setup] non-TTY stdin detected; using default answer (${defaultYes ? "yes" : "no"}). Re-run with \`--yes\` for explicit non-interactive mode.
+`
+    );
+    return Promise.resolve(defaultYes);
+  }
+  return new Promise((resolve11) => {
+    const rl = createInterface3({ input: process.stdin, output: process.stdout });
+    const suffix = defaultYes ? " [Y/n]: " : " [y/N]: ";
+    rl.question(`${question}${suffix}`, (answer) => {
+      rl.close();
+      const t = answer.trim().toLowerCase();
+      if (t === "") resolve11(defaultYes);
+      else if (t === "y" || t === "yes") resolve11(true);
+      else if (t === "n" || t === "no") resolve11(false);
+      else resolve11(defaultYes);
+    });
+    rl.on("close", () => resolve11(defaultYes));
+  });
+};
+async function phase1SystemCheck(deps) {
+  const dockerProbe = await probeDockerDaemon(deps.dockerExec);
+  if (!dockerProbe.ok) {
+    return phaseFromProbe(dockerProbe);
+  }
+  const nodeVersion = deps.nodeVersion ?? process.version;
+  const nodeMajor = parseNodeMajor(nodeVersion);
+  if (nodeMajor === null || nodeMajor < REQUIRED_NODE_MAJOR) {
+    return {
+      ok: false,
+      message: `Node.js ${nodeVersion} is too old (need \u2265${REQUIRED_NODE_MAJOR})`,
+      remedy: `Install Node.js ${REQUIRED_NODE_MAJOR}+ LTS via nvm/fnm/asdf and re-run \`olam setup\`.`
+    };
+  }
+  return {
+    ok: true,
+    message: `${dockerProbe.message}; node ${nodeVersion}`
+  };
+}
+function parseNodeMajor(version) {
+  const m = version.match(/^v?(\d+)\./);
+  if (!m) return null;
+  const n = Number.parseInt(m[1], 10);
+  return Number.isFinite(n) ? n : null;
+}
+function phaseFromProbe(probe) {
+  if (probe.ok) return { ok: true, message: probe.message };
+  return { ok: false, message: probe.message, remedy: probe.remedy };
+}
+async function phase2CliSanity(deps) {
+  const version = deps.olamCliVersion ?? safeReadCliVersion();
+  if (!version || version === "unknown") {
+    return {
+      ok: false,
+      message: "olam CLI version not detectable",
+      remedy: "Re-install `olam` via `npm install -g @pleri/olam-cli@stable` and re-run."
+    };
+  }
+  return { ok: true, message: `olam ${version}` };
+}
+function safeReadCliVersion() {
+  try {
+    return readCliVersion();
+  } catch {
+    return null;
+  }
+}
+async function phase3Bootstrap(deps) {
+  const spawnFn = deps.spawnSubprocess ?? defaultSpawn;
+  const r = await spawnFn("olam", ["bootstrap", "--skip-auth-login"]);
+  if (r.status === 0) {
+    return { ok: true, message: "olam bootstrap succeeded" };
+  }
+  return {
+    ok: false,
+    message: `olam bootstrap exited ${r.status}`,
+    remedy: "Re-run `olam setup` after inspecting the bootstrap error above (bootstrap is idempotent)."
+  };
+}
+async function phase4ShellInit(opts, deps) {
+  if (opts.skipShellInit) {
+    return { ok: true, skipped: true, message: "skipped via --skip-shell-init" };
+  }
+  const home = deps.home ?? homedir23();
+  const shellEnv = deps.shellEnv ?? process.env.SHELL;
+  const rcPath = resolveShellRc(home, shellEnv);
+  if (rcPath === null) {
+    return {
+      ok: true,
+      skipped: true,
+      message: `unsupported $SHELL (${shellEnv ?? "unset"}); add \`eval "$(olam completion <shell>)"\` to your shell rc manually`
+    };
+  }
+  const shellBasename = path45.basename(shellEnv);
+  const evalLine = `eval "$(olam completion ${shellBasename})"`;
+  const result = appendIdempotent({
+    rcPath,
+    marker: "olam completion",
+    contentLine: evalLine,
+    clock: deps.clock
+  });
+  if (result.status === "no-rc-file") {
+    return {
+      ok: true,
+      skipped: true,
+      message: `${rcPath} not present; skipped (add \`${evalLine}\` to your shell rc manually)`
+    };
+  }
+  if (result.status === "already-present") {
+    return { ok: true, message: `${rcPath}: already configured (no change)` };
+  }
+  return {
+    ok: true,
+    message: `${rcPath}: appended (backup: ${result.backupPath})`
+  };
+}
+async function phase5InitProject(opts, deps) {
+  const cwd = deps.cwd ?? process.cwd();
+  const projectRoot = findProjectRoot(cwd);
+  const configPath = path45.join(projectRoot, ".olam", "config.yaml");
+  if (existsSync45(configPath)) {
+    return { ok: true, message: `${configPath} present (no change)` };
+  }
+  const promptFn = deps.prompt ?? defaultPrompt;
+  const shouldInit = opts.yes ? true : await promptFn(`No .olam/config.yaml in ${cwd}. Initialise project here?`, false);
+  if (!shouldInit) {
+    return {
+      ok: true,
+      skipped: true,
+      message: "declined; run `olam init` later when ready"
+    };
+  }
+  const spawnFn = deps.spawnSubprocess ?? defaultSpawn;
+  const r = await spawnFn("olam", ["init"]);
+  if (r.status === 0) {
+    return { ok: true, message: "olam init completed" };
+  }
+  return {
+    ok: false,
+    message: `olam init exited ${r.status}`,
+    remedy: "Inspect the init error above and re-run `olam setup`."
+  };
+}
+async function phase6Auth(opts, deps) {
+  if (opts.skipAuth) {
+    return {
+      ok: true,
+      skipped: true,
+      message: "skipped via --skip-auth (run `olam auth login` later)"
+    };
+  }
+  const promptFn = deps.prompt ?? defaultPrompt;
+  const shouldLaunch = opts.yes ? true : await promptFn(
+    "`olam auth login` is interactive (PKCE browser flow, 5 min timeout). Launch now?",
+    false
+  );
+  if (!shouldLaunch) {
+    return {
+      ok: true,
+      skipped: true,
+      message: "declined; run `olam auth login` later when ready"
+    };
+  }
+  const spawnFn = deps.spawnSubprocess ?? defaultSpawn;
+  const r = await spawnFn("olam", ["auth", "login"]);
+  if (r.status === 0) {
+    return { ok: true, message: "olam auth login succeeded" };
+  }
+  return {
+    ok: true,
+    skipped: true,
+    message: `olam auth login exited ${r.status}; re-run \`olam auth login\` after resolving`
+  };
+}
+async function phase7Verify(deps) {
+  const spawnFn = deps.spawnSubprocess ?? defaultSpawn;
+  const r = await spawnFn("olam", ["doctor"]);
+  if (r.status === 0) {
+    return { ok: true, message: "olam doctor: all probes green" };
+  }
+  return {
+    ok: false,
+    message: `olam doctor exited ${r.status}`,
+    remedy: "Inspect doctor output above; the specific failing probe names its remedy."
+  };
+}
+var PHASE_TITLES = [
+  "Phase 1: System check",
+  "Phase 2: olam CLI sanity",
+  "Phase 3: Bootstrap",
+  "Phase 4: Shell init",
+  "Phase 5: Init project",
+  "Phase 6: Auth prompt",
+  "Phase 7: Final verification"
+];
+async function runSetup(opts, deps = {}) {
+  printHeader("olam setup");
+  const phaseFns = [
+    () => phase1SystemCheck(deps),
+    () => phase2CliSanity(deps),
+    () => phase3Bootstrap(deps),
+    () => phase4ShellInit(opts, deps),
+    () => phase5InitProject(opts, deps),
+    () => phase6Auth(opts, deps),
+    () => phase7Verify(deps)
+  ];
+  const results = [];
+  let failureAt = null;
+  for (let i = 0; i < phaseFns.length; i += 1) {
+    const name = PHASE_TITLES[i];
+    process.stdout.write(`
+${name}
+`);
+    const result = await phaseFns[i]();
+    results.push({ name, result });
+    if (result.ok && result.skipped) {
+      printWarning(`  \u2298 ${result.message}`);
+    } else if (result.ok) {
+      printSuccess(`  \u2713 ${result.message}`);
+    } else {
+      printError(`  \u2717 ${result.message}`);
+      if (result.remedy) printWarning(`    remedy: ${result.remedy}`);
+      failureAt = i + 1;
+      break;
+    }
+  }
+  process.stdout.write("\n");
+  if (failureAt !== null) {
+    printError(`Setup FAILED at Phase ${failureAt}`);
+    return { phases: results, failureAt, exitCode: 1 };
+  }
+  printSuccess("Setup complete.");
+  process.stdout.write("\nNext steps \u2014 read these in order for the 3-contract pattern:\n");
+  for (const line of NEXT_STEPS_DOCS) {
+    printInfo("docs", line);
+  }
+  process.stdout.write("\n");
+  return { phases: results, failureAt: null, exitCode: 0 };
+}
+function registerSetup(program2) {
+  program2.command("setup").description(
+    "Fresh-host onboarding wizard. Runs 7 phases (system check \u2192 bootstrap \u2192 shell init \u2192 init project \u2192 auth prompt \u2192 doctor verification). Idempotent; safe to re-run."
+  ).option("--skip-shell-init", "Skip Phase 4 (do not append to ~/.zshrc / ~/.bashrc)").option("--skip-auth", "Skip Phase 6 (do not prompt for `olam auth login`)").option("-y, --yes", "Auto-affirm every prompt (non-interactive)").action(async (opts) => {
+    const report = await runSetup(opts);
+    if (report.exitCode !== 0) process.exitCode = report.exitCode;
+  });
+}
+
 // src/commands/update.ts
 import * as fs42 from "node:fs";
 import * as os25 from "node:os";
-import * as path46 from "node:path";
+import * as path48 from "node:path";
 import { execSync as execSync13 } from "node:child_process";
 import pc23 from "picocolors";
 
 // src/lib/symlink-reconcile.ts
 import * as fs40 from "node:fs";
-import * as path44 from "node:path";
+import * as path46 from "node:path";
 var realFs = {
   readdirSync: (p) => fs40.readdirSync(p),
   existsSync: (p) => fs40.existsSync(p),
@@ -25521,8 +25823,8 @@ function reconcileSkillSymlinks(npmSkillsDir, claudeSkillsDir, _fs = realFs) {
   _fs.mkdirSync(claudeSkillsDir, { recursive: true });
   const sourceSkills = _fs.existsSync(npmSkillsDir) ? _fs.readdirSync(npmSkillsDir).filter((d) => d.startsWith("olam-")) : [];
   for (const skill of sourceSkills) {
-    const linkPath = path44.join(claudeSkillsDir, skill);
-    const target = path44.join(npmSkillsDir, skill);
+    const linkPath = path46.join(claudeSkillsDir, skill);
+    const target = path46.join(npmSkillsDir, skill);
     if (!_fs.existsSync(linkPath)) {
       try {
         _fs.symlinkSync(target, linkPath);
@@ -25535,7 +25837,7 @@ function reconcileSkillSymlinks(npmSkillsDir, claudeSkillsDir, _fs = realFs) {
   }
   const deployedEntries = _fs.existsSync(claudeSkillsDir) ? _fs.readdirSync(claudeSkillsDir).filter((d) => d.startsWith("olam-")) : [];
   for (const entry of deployedEntries) {
-    const linkPath = path44.join(claudeSkillsDir, entry);
+    const linkPath = path46.join(claudeSkillsDir, entry);
     let isSymlink = false;
     try {
       isSymlink = _fs.lstatSync(linkPath).isSymbolicLink();
@@ -25560,9 +25862,9 @@ function reconcileSkillSymlinks(npmSkillsDir, claudeSkillsDir, _fs = realFs) {
 
 // src/commands/update.ts
 var PACKAGE_NAME = "@pleri/olam-cli";
-var CACHE_DIR2 = path46.join(os25.homedir(), ".olam", "cache");
-var LOG_DIR2 = path46.join(os25.homedir(), ".olam", "log");
-var LAST_STABLE_FILE = path46.join(CACHE_DIR2, "last-stable.txt");
+var CACHE_DIR2 = path48.join(os25.homedir(), ".olam", "cache");
+var LOG_DIR2 = path48.join(os25.homedir(), ".olam", "log");
+var LAST_STABLE_FILE = path48.join(CACHE_DIR2, "last-stable.txt");
 function defaultExec(cmd) {
   try {
     const stdout = execSync13(cmd, { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] });
@@ -25591,12 +25893,12 @@ function readLastStable(file = LAST_STABLE_FILE) {
   }
 }
 function writeLastStable(version, file = LAST_STABLE_FILE) {
-  fs42.mkdirSync(path46.dirname(file), { recursive: true });
+  fs42.mkdirSync(path48.dirname(file), { recursive: true });
   fs42.writeFileSync(file, version, { mode: 420 });
 }
 function logUpdateFailure(stderr) {
   const ts = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
-  const logFile = path46.join(LOG_DIR2, `update-${ts}.log`);
+  const logFile = path48.join(LOG_DIR2, `update-${ts}.log`);
   try {
     fs42.mkdirSync(LOG_DIR2, { recursive: true });
     fs42.appendFileSync(logFile, `[update-failure ${(/* @__PURE__ */ new Date()).toISOString()}]
@@ -25686,8 +25988,8 @@ async function doUpdate(opts, _exec = defaultExec, _reconcile = reconcileSkillSy
   let symlinkResult = { added: [], removed: [] };
   if (npmRootResult.exitCode === 0) {
     const npmRoot = npmRootResult.stdout.trim();
-    const npmSkillsDir = path46.join(npmRoot, "@pleri", "olam-cli", "plugin", "skills");
-    const claudeSkillsDir = path46.join(os25.homedir(), ".claude", "skills");
+    const npmSkillsDir = path48.join(npmRoot, "@pleri", "olam-cli", "plugin", "skills");
+    const claudeSkillsDir = path48.join(os25.homedir(), ".claude", "skills");
     const rec = _reconcile(npmSkillsDir, claudeSkillsDir);
     symlinkResult = { added: rec.added, removed: rec.removed };
     if (!quiet && (rec.added.length > 0 || rec.removed.length > 0)) {
@@ -25733,8 +26035,8 @@ async function doRollback(_exec = defaultExec, _reconcile = reconcileSkillSymlin
   if (npmRootResult.exitCode === 0) {
     const npmRoot = npmRootResult.stdout.trim();
     _reconcile(
-      path46.join(npmRoot, "@pleri", "olam-cli", "plugin", "skills"),
-      path46.join(os25.homedir(), ".claude", "skills")
+      path48.join(npmRoot, "@pleri", "olam-cli", "plugin", "skills"),
+      path48.join(os25.homedir(), ".claude", "skills")
     );
   }
   return { action: "rolled-back", restoredVersion: prev, exitCode: 0 };
@@ -25826,10 +26128,10 @@ init_store2();
 init_store2();
 import * as fs43 from "node:fs";
 import * as os26 from "node:os";
-import * as path47 from "node:path";
+import * as path49 from "node:path";
 function expandPath(p) {
   if (p === "~" || p.startsWith("~/")) {
-    return path47.join(os26.homedir(), p.slice(1));
+    return path49.join(os26.homedir(), p.slice(1));
   }
   return p;
 }
@@ -26238,8 +26540,8 @@ var SECRET = process.env["OLAM_MCP_AUTH_SECRET"] ?? "";
 function authHeaders() {
   return SECRET ? { "X-Olam-Mcp-Secret": SECRET } : {};
 }
-async function apiFetch(path53, init = {}) {
-  const res = await fetch(`${BASE_URL}${path53}`, {
+async function apiFetch(path55, init = {}) {
+  const res = await fetch(`${BASE_URL}${path55}`, {
     ...init,
     headers: {
       "Content-Type": "application/json",
@@ -26294,11 +26596,11 @@ function getMcpAuthClient() {
 }
 
 // src/commands/mcp/login.ts
-import { spawn as spawn5 } from "node:child_process";
+import { spawn as spawn6 } from "node:child_process";
 function openBrowser2(url) {
   const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
   try {
-    const child = spawn5(cmd, [url], { detached: true, stdio: "ignore" });
+    const child = spawn6(cmd, [url], { detached: true, stdio: "ignore" });
     child.unref();
   } catch {
   }
@@ -26501,7 +26803,7 @@ import pc29 from "picocolors";
 // src/commands/mcp/import-discovery.ts
 import * as fs45 from "node:fs";
 import * as os27 from "node:os";
-import * as path48 from "node:path";
+import * as path50 from "node:path";
 function readJsonFile(filePath) {
   try {
     const raw = fs45.readFileSync(filePath, "utf-8");
@@ -26533,18 +26835,18 @@ function extractMcpServers(obj, source, sourceLabel) {
 }
 function getClaudeDesktopPath() {
   if (process.platform === "darwin") {
-    return path48.join(os27.homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
+    return path50.join(os27.homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
   }
   if (process.platform === "win32") {
-    const appData = process.env["APPDATA"] ?? path48.join(os27.homedir(), "AppData", "Roaming");
-    return path48.join(appData, "Claude", "claude_desktop_config.json");
+    const appData = process.env["APPDATA"] ?? path50.join(os27.homedir(), "AppData", "Roaming");
+    return path50.join(appData, "Claude", "claude_desktop_config.json");
   }
-  return path48.join(os27.homedir(), ".config", "Claude", "claude_desktop_config.json");
+  return path50.join(os27.homedir(), ".config", "Claude", "claude_desktop_config.json");
 }
 function getOlamRepoPaths() {
   const configPaths = [
-    path48.join(os27.homedir(), ".olam", "config.yaml"),
-    path48.join(process.cwd(), ".olam", "config.yaml")
+    path50.join(os27.homedir(), ".olam", "config.yaml"),
+    path50.join(process.cwd(), ".olam", "config.yaml")
   ];
   const paths = [];
   for (const configPath of configPaths) {
@@ -26566,7 +26868,7 @@ async function discoverMcpSources(repoPaths) {
   const sources = [];
   const sourceDefs = [
     {
-      path: path48.join(os27.homedir(), ".claude.json"),
+      path: path50.join(os27.homedir(), ".claude.json"),
       label: "Claude Code (~/.claude.json)"
     },
     {
@@ -26574,19 +26876,19 @@ async function discoverMcpSources(repoPaths) {
       label: "Claude Desktop"
     },
     {
-      path: path48.join(os27.homedir(), ".cursor", "mcp.json"),
+      path: path50.join(os27.homedir(), ".cursor", "mcp.json"),
       label: "Cursor (~/.cursor/mcp.json)"
     },
     {
-      path: path48.join(os27.homedir(), ".codeium", "windsurf", "mcp_config.json"),
+      path: path50.join(os27.homedir(), ".codeium", "windsurf", "mcp_config.json"),
       label: "Windsurf (~/.codeium/windsurf/mcp_config.json)"
     }
   ];
   const resolvedRepoPaths = repoPaths ?? getOlamRepoPaths();
   for (const repoPath of resolvedRepoPaths) {
     sourceDefs.push({
-      path: path48.join(repoPath, ".mcp.json"),
-      label: `.mcp.json (${path48.basename(repoPath)})`
+      path: path50.join(repoPath, ".mcp.json"),
+      label: `.mcp.json (${path50.basename(repoPath)})`
     });
   }
   const reads = await Promise.all(
@@ -26616,7 +26918,7 @@ async function discoverMcpSources(repoPaths) {
 }
 
 // src/commands/mcp/import-validate.ts
-import { spawn as spawn6 } from "node:child_process";
+import { spawn as spawn7 } from "node:child_process";
 var VALIDATION_TIMEOUT_MS = 5e3;
 async function validateMcpEntry(entry) {
   return new Promise((resolve11) => {
@@ -26624,7 +26926,7 @@ async function validateMcpEntry(entry) {
     let timedOut = false;
     let child;
     try {
-      child = spawn6(entry.command, [...entry.args ?? []], {
+      child = spawn7(entry.command, [...entry.args ?? []], {
         stdio: ["ignore", "pipe", "ignore"],
         env: { ...process.env, ...entry.env ?? {} }
       });
@@ -26818,10 +27120,10 @@ function registerMcp(program2) {
 // src/commands/kg-build.ts
 import { spawnSync as spawnSync15 } from "node:child_process";
 import fs48 from "node:fs";
-import path51 from "node:path";
+import path53 from "node:path";
 
 // ../core/dist/kg/storage-paths.js
-import { homedir as homedir27 } from "node:os";
+import { homedir as homedir28 } from "node:os";
 import { join as join48, resolve as resolve10 } from "node:path";
 
 // ../core/dist/world/workspace-name.js
@@ -26843,7 +27145,7 @@ function validateWorkspaceName(name) {
 
 // ../core/dist/kg/storage-paths.js
 function olamHome3() {
-  return process.env.OLAM_HOME ?? join48(homedir27(), ".olam");
+  return process.env.OLAM_HOME ?? join48(homedir28(), ".olam");
 }
 function kgRoot() {
   return join48(olamHome3(), "kg");
@@ -26851,17 +27153,17 @@ function kgRoot() {
 function worldsRoot() {
   return join48(olamHome3(), "worlds");
 }
-function assertWithinPrefix(path53, prefix, label) {
-  if (!path53.startsWith(prefix + "/")) {
-    throw new Error(`${label} escape: ${path53} not under ${prefix}/`);
+function assertWithinPrefix(path55, prefix, label) {
+  if (!path55.startsWith(prefix + "/")) {
+    throw new Error(`${label} escape: ${path55} not under ${prefix}/`);
   }
 }
 function kgPristinePath(workspace) {
   validateWorkspaceName(workspace);
   const root = kgRoot();
-  const path53 = resolve10(join48(root, workspace));
-  assertWithinPrefix(path53, root, "kgPristinePath");
-  return path53;
+  const path55 = resolve10(join48(root, workspace));
+  assertWithinPrefix(path55, root, "kgPristinePath");
+  return path55;
 }
 var KG_PATHS_INTERNALS = Object.freeze({
   olamHome: olamHome3,
@@ -26874,17 +27176,17 @@ init_output();
 
 // src/commands/kg-status.ts
 import fs46 from "node:fs";
-import { homedir as homedir28 } from "node:os";
-import path49 from "node:path";
+import { homedir as homedir29 } from "node:os";
+import path51 from "node:path";
 init_output();
 function olamHome4() {
-  return process.env.OLAM_HOME ?? path49.join(homedir28(), ".olam");
+  return process.env.OLAM_HOME ?? path51.join(homedir29(), ".olam");
 }
 function kgRoot2() {
-  return path49.join(olamHome4(), "kg");
+  return path51.join(olamHome4(), "kg");
 }
 function worldsRoot2() {
-  return path49.join(olamHome4(), "worlds");
+  return path51.join(olamHome4(), "worlds");
 }
 function dirSizeBytes2(dir) {
   if (!fs46.existsSync(dir)) return 0;
@@ -26899,7 +27201,7 @@ function dirSizeBytes2(dir) {
       continue;
     }
     for (const entry of entries) {
-      const full = path49.join(cur, entry.name);
+      const full = path51.join(cur, entry.name);
       if (entry.isSymbolicLink()) continue;
       if (entry.isDirectory()) {
         stack.push(full);
@@ -26920,7 +27222,7 @@ function formatBytes5(n) {
   return `${(n / 1024 / 1024 / 1024).toFixed(2)} GB`;
 }
 function readFreshness(workspace) {
-  const file = path49.join(kgPristinePath(workspace), "freshness.json");
+  const file = path51.join(kgPristinePath(workspace), "freshness.json");
   if (!fs46.existsSync(file)) return null;
   try {
     const raw = JSON.parse(fs46.readFileSync(file, "utf-8"));
@@ -26931,7 +27233,7 @@ function readFreshness(workspace) {
   }
 }
 function readOverlayNodeCount(graphifyOutDir) {
-  const graphPath = path49.join(graphifyOutDir, "graph.json");
+  const graphPath = path51.join(graphifyOutDir, "graph.json");
   if (!fs46.existsSync(graphPath)) return null;
   try {
     const raw = JSON.parse(fs46.readFileSync(graphPath, "utf-8"));
@@ -26957,7 +27259,7 @@ function listOverlays() {
   for (const worldEntry of worldDirs) {
     if (!worldEntry.isDirectory()) continue;
     const worldId = worldEntry.name;
-    const worldDir = path49.join(root, worldId);
+    const worldDir = path51.join(root, worldId);
     let cloneDirs;
     try {
       cloneDirs = fs46.readdirSync(worldDir, { withFileTypes: true });
@@ -26966,7 +27268,7 @@ function listOverlays() {
     }
     for (const cloneEntry of cloneDirs) {
       if (!cloneEntry.isDirectory()) continue;
-      const graphifyOut = path49.join(worldDir, cloneEntry.name, "graphify-out");
+      const graphifyOut = path51.join(worldDir, cloneEntry.name, "graphify-out");
       if (!fs46.existsSync(graphifyOut)) continue;
       records.push({
         world_id: worldId,
@@ -26998,7 +27300,7 @@ function listPristines(overlays) {
       continue;
     }
     const fresh = readFreshness(workspace);
-    const graphifyOut = path49.join(kgPristinePath(workspace), "graphify-out");
+    const graphifyOut = path51.join(kgPristinePath(workspace), "graphify-out");
     const size = dirSizeBytes2(graphifyOut);
     const worldCount = overlays.filter((o) => o.clone_dir === workspace).length;
     records.push({
@@ -27130,12 +27432,12 @@ function registerKgStatusCommand(kg) {
 }
 
 // src/commands/kg-watch.ts
-import { spawn as spawn7 } from "node:child_process";
+import { spawn as spawn8 } from "node:child_process";
 import fs47 from "node:fs";
-import path50 from "node:path";
+import path52 from "node:path";
 init_output();
 function pidFilePath(workspace) {
-  return path50.join(kgPristinePath(workspace), ".watch.pid");
+  return path52.join(kgPristinePath(workspace), ".watch.pid");
 }
 function isPidAlive3(pid) {
   if (!Number.isInteger(pid) || pid <= 0) return false;
@@ -27169,7 +27471,7 @@ function readAndClassifyPid(workspace) {
 }
 function writePidFile(workspace, pid) {
   const file = pidFilePath(workspace);
-  const dir = path50.dirname(file);
+  const dir = path52.dirname(file);
   fs47.mkdirSync(dir, { recursive: true });
   fs47.writeFileSync(file, String(pid), { encoding: "utf-8" });
 }
@@ -27182,7 +27484,7 @@ function removePidFile(workspace) {
 }
 async function runKgWatch(workspaceArg, opts, deps = {}) {
   const cwd = deps.cwd ?? opts.cwd ?? process.cwd();
-  const name = workspaceArg ?? path50.basename(cwd).toLowerCase();
+  const name = workspaceArg ?? path52.basename(cwd).toLowerCase();
   try {
     validateWorkspaceName(name);
   } catch (err) {
@@ -27190,7 +27492,7 @@ async function runKgWatch(workspaceArg, opts, deps = {}) {
     return { exitCode: 1, pidWritten: false };
   }
   const pristinePath = kgPristinePath(name);
-  const graphPath = path50.join(pristinePath, "graphify-out", "graph.json");
+  const graphPath = path52.join(pristinePath, "graphify-out", "graph.json");
   const pidState = readAndClassifyPid(name);
   if (pidState.status === "active") {
     printError(
@@ -27201,7 +27503,7 @@ async function runKgWatch(workspaceArg, opts, deps = {}) {
   if (pidState.status === "stale-reclaimed") {
     printInfo("stale-pid", `reclaimed dead PID file at ${pidFilePath(name)}`);
   }
-  const spawnFn = deps.spawnImpl ?? spawn7;
+  const spawnFn = deps.spawnImpl ?? spawn8;
   const child = spawnFn(
     "graphify",
     [cwd, "--watch", "--update", "--graph", graphPath],
@@ -27256,7 +27558,7 @@ function registerKgWatchCommand(kg) {
 var DEFAULT_DEVBOX_IMAGE2 = "olam-devbox:latest";
 function resolveWorkspace(arg) {
   const cwd = process.cwd();
-  const name = arg ?? path51.basename(cwd).toLowerCase();
+  const name = arg ?? path53.basename(cwd).toLowerCase();
   validateWorkspaceName(name);
   return { name, sourcePath: cwd };
 }
@@ -27278,7 +27580,7 @@ function copyWorkspaceToScratch(source, scratch) {
   return "cp-r";
 }
 function parseNodeCount(graphifyOutDir) {
-  const graphPath = path51.join(graphifyOutDir, "graph.json");
+  const graphPath = path53.join(graphifyOutDir, "graph.json");
   if (!fs48.existsSync(graphPath)) return null;
   try {
     const content = fs48.readFileSync(graphPath, "utf-8");
@@ -27315,7 +27617,7 @@ async function runKgBuild(workspaceArg, options = {}) {
     return { exitCode: 2 };
   }
   const outDir = kgPristinePath(workspace.name);
-  const scratchDir = path51.join(outDir, "scratch");
+  const scratchDir = path53.join(outDir, "scratch");
   fs48.mkdirSync(outDir, { recursive: true });
   if (fs48.existsSync(scratchDir)) fs48.rmSync(scratchDir, { recursive: true, force: true });
   fs48.mkdirSync(scratchDir);
@@ -27346,8 +27648,8 @@ async function runKgBuild(workspaceArg, options = {}) {
       printError(`graphify update failed (exit ${r.status})`);
       return { exitCode: r.status ?? 1 };
     }
-    const scratchOut = path51.join(scratchDir, "graphify-out");
-    const finalOut = path51.join(outDir, "graphify-out");
+    const scratchOut = path53.join(scratchDir, "graphify-out");
+    const finalOut = path53.join(outDir, "graphify-out");
     if (!fs48.existsSync(scratchOut)) {
       printError(`graphify produced no graphify-out/ in scratch (${scratchOut})`);
       return { exitCode: 1 };
@@ -27366,7 +27668,7 @@ async function runKgBuild(workspaceArg, options = {}) {
       scratch_strategy: scratchStrategy
     };
     fs48.writeFileSync(
-      path51.join(outDir, "freshness.json"),
+      path53.join(outDir, "freshness.json"),
       JSON.stringify(freshness, null, 2) + "\n",
       "utf-8"
     );
@@ -27399,12 +27701,12 @@ function registerKg(program2) {
 
 // src/pleri-config.ts
 import * as fs49 from "node:fs";
-import * as path52 from "node:path";
+import * as path54 from "node:path";
 function isPleriConfigured(configDir = process.env.OLAM_CONFIG_DIR ?? ".olam") {
   if (process.env.PLERI_BASE_URL) {
     return true;
   }
-  const configPath = path52.join(configDir, "config.yaml");
+  const configPath = path54.join(configDir, "config.yaml");
   if (!fs49.existsSync(configPath)) {
     return false;
   }
@@ -27448,6 +27750,7 @@ registerBootstrap(program);
 registerDiagnose(program);
 registerDoctor(program);
 registerCompletion(program);
+registerSetup(program);
 registerUpdate(program);
 registerBegin(program);
 registerStop(program);