refactor(install): split bootstrap ownership

Author: kushagrchitkar

docs/intentional-architecture-rewrite-2026-06-27/decision-log.md

@@ -207,6 +207,8 @@ Page-source indexing is indexer-owned, but it is not one bucket. `src/stores/wik
 
 Viewer read models are route-payload owners, not one API bucket. `src/edges/viewer/read-model/api.ts` composes the public viewer API. `db.ts` owns freshness and index open/close mechanics for viewer reads. `overview.ts`, `page.ts`, `topic.ts`, and `search.ts` own the route payloads they return. `types.ts` owns the route-facing viewer API contracts.
 
+Bare-`codealmanac` bootstrap is a flow coordinator, not a package-manager bucket. `src/platform/install/global.ts` owns the high-level bootstrap sequence. `bootstrap-process.ts` owns child-process spawn/capture mechanics. `bootstrap-package.ts` owns package-root detection, package version reads, root equality, and version comparison. `bootstrap-npm.ts` owns npm global-root discovery, global install execution, and npm failure text.
+
 Codex app-server runtime has two layers. `app-server.ts` coordinates provider runtime state: request/config setup, JSON-RPC transport wiring, notification mapping, root-turn completion, turn watchdogs, and final result projection. `app-server-process.ts` owns child-process mechanics: spawning the Codex app-server, decoding stdout JSONL into protocol messages, collecting stderr for close failures, registering signal handlers, writing JSON-RPC messages to stdin, and terminating the managed child.
 
 Codex app-server notifications are routed by notification kind. `app-notifications.ts` owns the top-level method router and generic notification categories. `app-agent-messages.ts` owns agent-message semantics: text deltas, root result capture, structured output parsing, invalid structured-output failure state, and helper-agent completion events. `app-terminal-events.ts` owns terminal event semantics: turn completion, warnings, app-server error notifications, terminal run-state success/failure mutation, and `classifyCodexFailure` calls. Tool display, usage parsing, actor tracing, root-turn detection, and process mechanics stay in their existing named files.

docs/intentional-architecture-rewrite-2026-06-27/status.md

@@ -5,7 +5,7 @@ Branch: `codex/intentional-architecture-rewrite`
 
 ## Current State
 
-The branch has more than 340 committed rewrite commits past `dev`. The worklog records 288 production slices so far.
+The branch has more than 340 committed rewrite commits past `dev`. The worklog records 289 production slices so far.
 
 The diff is broad: more than 680 files changed, with tens of thousands of lines reshaped.
 
@@ -147,6 +147,7 @@ This is no longer a small cleanup branch. It is a real ownership rewrite.
 - Split indexer page-source normalization into coordination, structured projection, legacy projection, source-id generation, and type contracts.
 - Split setup input controls into line prompts, single-choice select, raw input capability, multi-select, and interruption handling.
 - Split viewer read-model route payloads into overview, page, topic, search/file, DB freshness, and type owners.
+- Split bare-`codealmanac` install bootstrap into flow coordination, package-root/version, npm global install, and process-spawn owners.
 - Moved repeated store atomic-write temp-file mechanics into `src/stores/atomic-write.ts`, removing process-PID temp names from job and sync stores.
 - Split most command rendering into command-private render files.
 - Added architecture-boundary tests to stop old dependency leaks from returning.
@@ -163,12 +164,12 @@ This is no longer a small cleanup branch. It is a real ownership rewrite.
 
 ## Latest Checkpoint
 
-The latest slice split the viewer read-model API bucket. `api.ts` now composes the route-facing viewer API, while `db.ts`, `overview.ts`, `page.ts`, `topic.ts`, `search.ts`, and `types.ts` own the individual read-model responsibilities.
+The latest slice split the bare-`codealmanac` install bootstrap bucket. `global.ts` now coordinates the bootstrap flow, while `bootstrap-package.ts`, `bootstrap-npm.ts`, and `bootstrap-process.ts` own package-root/version mechanics, npm mechanics, and child-process mechanics.
 
 Verification passed:
 
 - `npm run lint`
-- `npx vitest run test/viewer-api.test.ts test/viewer-global-api.test.ts test/architecture-wiki-command-boundaries.test.ts`
+- `npx vitest run test/global-bootstrap.test.ts test/architecture-setup-boundaries.test.ts`
 - `npx vitest run test/architecture-*-boundaries.test.ts`
 - `git diff --check`
 - `npm test`

docs/intentional-architecture-rewrite-2026-06-27/worklog.md

@@ -2068,3 +2068,11 @@ Two-hundred-eighty-eighth production slice:
 - Added owner-named viewer read-model files for overview, page detail, topic detail, search/suggest/file mentions, and shared route-facing types.
 - Kept `api.ts` focused on composing the public viewer API over the owner-named route payload builders.
 - Strengthened viewer boundary tests so overview/page/search/topic payload logic and DB freshness mechanics do not collapse back into one API bucket.
+
+Two-hundred-eighty-ninth production slice:
+
+- Split install bootstrap package mechanics out of `src/platform/install/global.ts`.
+- Added `src/platform/install/bootstrap-package.ts` for current package-root detection, package version reads, package-root equality, and version-comparison install decisions.
+- Added `src/platform/install/bootstrap-npm.ts` for npm global-root discovery, global package install execution, and npm-install failure text.
+- Kept `global.ts` focused on the bare-`codealmanac` bootstrap flow: local setup bypass, global-root resolution, global install decision, and rerun through the global launcher.
+- Strengthened setup architecture tests so process spawning, package-root/version probing, and npm install mechanics stay in separate install-platform owners.

src/platform/install/bootstrap-npm.ts

@@ -0,0 +1,70 @@
+import path from "node:path";
+
+import {
+  defaultBootstrapSpawn,
+  spawnCapturedProcess,
+  spawnInheritedProcess,
+  type BootstrapSpawnFn,
+} from "./bootstrap-process.js";
+
+export interface GlobalPackageRootResolution {
+  ok: true;
+  path: string;
+}
+
+export interface GlobalPackageRootResolutionError {
+  ok: false;
+  stderr: string;
+}
+
+export type GlobalPackageRootResult =
+  | GlobalPackageRootResolution
+  | GlobalPackageRootResolutionError;
+
+export async function resolveGlobalPackageRoot(
+  spawnFn: BootstrapSpawnFn = defaultBootstrapSpawn,
+): Promise<GlobalPackageRootResult> {
+  const result = await spawnCapturedProcess(spawnFn, "npm", ["root", "-g"]);
+  if (result.exitCode !== 0) {
+    return {
+      ok: false,
+      stderr:
+        "almanac: could not find npm's global install directory.\n" +
+        "Install Node.js + npm, or install the codealmanac package via your package manager.\n",
+    };
+  }
+
+  const root = result.stdout.trim();
+  if (root.length === 0) {
+    return {
+      ok: false,
+      stderr:
+        "almanac: npm returned an empty global install directory.\n" +
+        "Try: npm root -g\n",
+    };
+  }
+
+  return { ok: true, path: path.join(root, "codealmanac") };
+}
+
+export async function installGlobalCodealmanacPackage(args: {
+  spawnFn?: BootstrapSpawnFn;
+  env: NodeJS.ProcessEnv;
+}): Promise<{ ok: true } | { ok: false; stderr: string; exitCode: number }> {
+  const install = await spawnInheritedProcess(
+    args.spawnFn ?? defaultBootstrapSpawn,
+    "npm",
+    ["i", "-g", "codealmanac@latest"],
+    args.env,
+  );
+  if (install.exitCode === 0) return { ok: true };
+
+  return {
+    ok: false,
+    stderr:
+      `almanac: npm install failed (exit ${install.exitCode}).\n` +
+      `If you see "EACCES" above, try: sudo npm i -g codealmanac@latest\n` +
+      `Or install with a version manager (nvm, volta, fnm) to avoid sudo.\n`,
+    exitCode: install.exitCode,
+  };
+}

src/platform/install/bootstrap-package.ts

@@ -0,0 +1,65 @@
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { isNewerVersion } from "../../shared/version.js";
+
+export async function shouldInstallGlobalPackage(args: {
+  currentRoot: string;
+  globalRoot: string;
+}): Promise<boolean> {
+  const globalVersion = await readPackageVersion(args.globalRoot);
+  if (globalVersion === null) return true;
+
+  const currentVersion = await readPackageVersion(args.currentRoot);
+  if (currentVersion === null) return false;
+
+  return isNewerVersion(currentVersion, globalVersion);
+}
+
+export function samePackageRoot(a: string, b: string): boolean {
+  return path.resolve(a) === path.resolve(b);
+}
+
+export async function readPackageVersion(root: string): Promise<string | null> {
+  try {
+    const raw = await readFile(path.join(root, "package.json"), "utf8");
+    const parsed = JSON.parse(raw) as { version?: unknown };
+    return typeof parsed.version === "string" && parsed.version.length > 0
+      ? parsed.version
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+export function findCurrentPackageRoot(): string {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    // Bundled: `.../codealmanac/dist/launcher.js` -> package root.
+    path.resolve(here, ".."),
+    // Old source/dist layout: `.../codealmanac/src/install/global.ts` -> package root.
+    path.resolve(here, "..", ".."),
+    // Source/dist platform layout: `.../codealmanac/src/platform/install/global.ts`.
+    path.resolve(here, "..", "..", ".."),
+  ];
+
+  for (const candidate of candidates) {
+    if (isCodealmanacPackageRoot(candidate)) return candidate;
+  }
+
+  return path.resolve(here, "..", "..", "..");
+}
+
+function isCodealmanacPackageRoot(candidate: string): boolean {
+  try {
+    const require = createRequire(import.meta.url);
+    const pkg = require(path.join(candidate, "package.json")) as {
+      name?: unknown;
+    };
+    return pkg.name === "codealmanac";
+  } catch {
+    return false;
+  }
+}

src/platform/install/global.ts

@@ -1,15 +1,19 @@
-import { readFile } from "node:fs/promises";
-import { createRequire } from "node:module";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 
-import { isNewerVersion } from "../../shared/version.js";
 import {
   defaultBootstrapSpawn,
-  spawnCapturedProcess,
   spawnInheritedProcess,
   type BootstrapSpawnFn,
 } from "./bootstrap-process.js";
+import {
+  findCurrentPackageRoot,
+  samePackageRoot,
+  shouldInstallGlobalPackage,
+} from "./bootstrap-package.js";
+import {
+  installGlobalCodealmanacPackage,
+  resolveGlobalPackageRoot,
+} from "./bootstrap-npm.js";
 
 /**
  * Bare `codealmanac` is the npm bootstrap surface. When it is invoked
@@ -65,24 +69,19 @@ export async function runCodealmanacBootstrap(
   }
 
   const globalRoot = globalRootResult.path;
-  if (samePath(currentRoot, globalRoot)) {
+  if (samePackageRoot(currentRoot, globalRoot)) {
     return await opts.runLocalSetup();
   }
 
-  if (await shouldInstallGlobal(currentRoot, globalRoot)) {
-    const install = await spawnInheritedProcess(
-      opts.spawnFn ?? defaultBootstrapSpawn,
-      "npm",
-      ["i", "-g", "codealmanac@latest"],
+  if (await shouldInstallGlobalPackage({ currentRoot, globalRoot })) {
+    const install = await installGlobalCodealmanacPackage({
+      spawnFn: opts.spawnFn,
       env,
-    );
-    if (install.exitCode !== 0) {
+    });
+    if (!install.ok) {
       return {
         stdout: "",
-        stderr:
-          `almanac: npm install failed (exit ${install.exitCode}).\n` +
-          `If you see "EACCES" above, try: sudo npm i -g codealmanac@latest\n` +
-          `Or install with a version manager (nvm, volta, fnm) to avoid sudo.\n`,
+        stderr: install.stderr,
         exitCode: install.exitCode,
       };
     }
@@ -105,84 +104,3 @@ export async function runCodealmanacBootstrap(
     exitCode: rerun.exitCode,
   };
 }
-
-async function shouldInstallGlobal(
-  currentRoot: string,
-  globalRoot: string,
-): Promise<boolean> {
-  const globalVersion = await readPackageVersion(globalRoot);
-  if (globalVersion === null) return true;
-
-  const currentVersion = await readPackageVersion(currentRoot);
-  if (currentVersion === null) return false;
-
-  return isNewerVersion(currentVersion, globalVersion);
-}
-
-function samePath(a: string, b: string): boolean {
-  return path.resolve(a) === path.resolve(b);
-}
-
-async function readPackageVersion(root: string): Promise<string | null> {
-  try {
-    const raw = await readFile(path.join(root, "package.json"), "utf8");
-    const parsed = JSON.parse(raw) as { version?: unknown };
-    return typeof parsed.version === "string" && parsed.version.length > 0
-      ? parsed.version
-      : null;
-  } catch {
-    return null;
-  }
-}
-
-function findCurrentPackageRoot(): string {
-  const here = path.dirname(fileURLToPath(import.meta.url));
-  const candidates = [
-    // Bundled: `.../codealmanac/dist/launcher.js` -> package root.
-    path.resolve(here, ".."),
-    // Old source/dist layout: `.../codealmanac/src/install/global.ts` -> package root.
-    path.resolve(here, "..", ".."),
-    // Source/dist platform layout: `.../codealmanac/src/platform/install/global.ts`.
-    path.resolve(here, "..", "..", ".."),
-  ];
-
-  for (const candidate of candidates) {
-    try {
-      const require = createRequire(import.meta.url);
-      const pkg = require(path.join(candidate, "package.json")) as {
-        name?: unknown;
-      };
-      if (pkg.name === "codealmanac") return candidate;
-    } catch {
-      // Try the next layout.
-    }
-  }
-
-  return path.resolve(here, "..", "..", "..");
-}
-
-async function resolveGlobalPackageRoot(
-  spawnFn: BootstrapSpawnFn,
-): Promise<{ ok: true; path: string } | { ok: false; stderr: string }> {
-  const result = await spawnCapturedProcess(spawnFn, "npm", ["root", "-g"]);
-  if (result.exitCode !== 0) {
-    return {
-      ok: false,
-      stderr:
-        "almanac: could not find npm's global install directory.\n" +
-        "Install Node.js + npm, or install the codealmanac package via your package manager.\n",
-    };
-  }
-
-  const root = result.stdout.trim();
-  if (root.length === 0) {
-    return {
-      ok: false,
-      stderr:
-        "almanac: npm returned an empty global install directory.\n" +
-        "Try: npm root -g\n",
-    };
-  }
-
-  return { ok: true, path: path.join(root, "codealmanac") };
-}

test/architecture-setup-boundaries.test.ts

@@ -310,17 +310,44 @@ describe("architecture boundaries: setup and uninstall", () => {
     const bootstrapProcess = await readSource(
       "src/platform/install/bootstrap-process.ts",
     );
+    const bootstrapPackage = await readSource(
+      "src/platform/install/bootstrap-package.ts",
+    );
+    const bootstrapNpm = await readSource("src/platform/install/bootstrap-npm.ts");
 
     expect(existsSync(join(ROOT, "src/platform/install/bootstrap-process.ts")))
       .toBe(true);
+    expect(existsSync(join(ROOT, "src/platform/install/bootstrap-package.ts")))
+      .toBe(true);
+    expect(existsSync(join(ROOT, "src/platform/install/bootstrap-npm.ts"))).toBe(
+      true,
+    );
     expect(bootstrap).toContain("bootstrap-process.js");
+    expect(bootstrap).toContain("bootstrap-package.js");
+    expect(bootstrap).toContain("bootstrap-npm.js");
     expect(bootstrap).not.toContain("node:child_process");
+    expect(bootstrap).not.toContain("node:fs");
+    expect(bootstrap).not.toContain("node:module");
+    expect(bootstrap).not.toContain("fileURLToPath");
+    expect(bootstrap).not.toContain("npm root -g");
+    expect(bootstrap).not.toContain("npm install failed");
+    expect(bootstrap).not.toContain("readPackageVersion");
+    expect(bootstrap).not.toContain("isNewerVersion");
     expect(bootstrap).not.toContain("stdio: \"inherit\"");
     expect(bootstrap).not.toContain("stdio: [\"ignore\", \"pipe\", \"pipe\"]");
     expect(bootstrap).not.toContain("child.stdout");
     expect(bootstrapProcess).toContain("node:child_process");
     expect(bootstrapProcess).toContain("spawnInheritedProcess");
     expect(bootstrapProcess).toContain("spawnCapturedProcess");
+    expect(bootstrapPackage).toContain("findCurrentPackageRoot");
+    expect(bootstrapPackage).toContain("readPackageVersion");
+    expect(bootstrapPackage).toContain("shouldInstallGlobalPackage");
+    expect(bootstrapPackage).toContain("isNewerVersion");
+    expect(bootstrapNpm).toContain("resolveGlobalPackageRoot");
+    expect(bootstrapNpm).toContain("installGlobalCodealmanacPackage");
+    expect(bootstrapNpm).toContain("npm");
+    expect(bootstrapNpm).toContain("spawnInheritedProcess");
+    expect(bootstrapNpm).toContain("spawnCapturedProcess");
   });
 
   it("keeps setup provider login process execution in the platform layer", async () => {