@openparachute/hub 0.7.3-rc.6 → 0.7.3-rc.8

package/src/__tests__/wizard-transcription.test.ts

@@ -0,0 +1,334 @@
+/**
+ * CLI wizard transcription step (onboarding-streamline hub PR1).
+ *
+ * Exercises `walkTranscriptionStep` against an injected command runner + RAM
+ * probe + platform — NOTHING installs and no subprocess is spawned. Covers the
+ * four branches the brief calls for: the CLI transcription question, the
+ * platform mapping, the RAM gate, and install-or-skip (mocked scribe
+ * subprocess).
+ */
+
+import { describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { walkTranscriptionStep } from "../commands/wizard-transcription.ts";
+import { scribeConfigPath } from "../scribe-config.ts";
+
+function makeHarness(): { dir: string; cleanup: () => void } {
+  const dir = mkdtempSync(join(tmpdir(), "pcli-wztrans-"));
+  return { dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+}
+
+/** Records every command the step would have spawned, returns scripted codes. */
+function recordingRunner(codes: number[] = []) {
+  const cmds: string[][] = [];
+  let i = 0;
+  return {
+    cmds,
+    run: async (cmd: readonly string[]): Promise<number> => {
+      cmds.push([...cmd]);
+      const code = codes[i++];
+      return code ?? 0;
+    },
+  };
+}
+
+function readCfg(dir: string): Record<string, unknown> | undefined {
+  const p = scribeConfigPath(dir);
+  if (!existsSync(p)) return undefined;
+  return JSON.parse(readFileSync(p, "utf8")) as Record<string, unknown>;
+}
+
+describe("walkTranscriptionStep — mode resolution (the CLI question)", () => {
+  test("none: writes no scribe config, runs no command", async () => {
+    const h = makeHarness();
+    try {
+      const r = recordingRunner();
+      const logs: string[] = [];
+      const code = await walkTranscriptionStep({
+        configDir: h.dir,
+        log: (l) => logs.push(l),
+        transcribeMode: "none",
+        runCommand: r.run,
+        platform: "linux",
+      });
+      expect(code).toBe(0);
+      expect(r.cmds).toEqual([]);
+      expect(readCfg(h.dir)).toBeUndefined();
+      expect(logs.join("\n")).toContain("Transcription off");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("interactive prompt: '1' chooses none", async () => {
+    const h = makeHarness();
+    try {
+      const r = recordingRunner();
+      const answers = ["1"];
+      let i = 0;
+      const code = await walkTranscriptionStep({
+        configDir: h.dir,
+        log: () => {},
+        prompt: async () => answers[i++] ?? "",
+        runCommand: r.run,
+        platform: "linux",
+      });
+      expect(code).toBe(0);
+      expect(r.cmds).toEqual([]);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("interactive prompt: '3' then 'g' chooses groq cloud", async () => {
+    const h = makeHarness();
+    try {
+      const r = recordingRunner([0]);
+      const answers = ["3", "g", "gsk_interactive"];
+      let i = 0;
+      const code = await walkTranscriptionStep({
+        configDir: h.dir,
+        log: () => {},
+        prompt: async () => answers[i++] ?? "",
+        runCommand: r.run,
+        platform: "linux",
+      });
+      expect(code).toBe(0);
+      // One install command, with the groq provider + key.
+      expect(r.cmds.length).toBe(1);
+      expect(r.cmds[0]).toEqual([
+        "parachute",
+        "install",
+        "scribe",
+        "--scribe-provider",
+        "groq",
+        "--scribe-key",
+        "gsk_interactive",
+      ]);
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
+describe("walkTranscriptionStep — cloud (install-or-skip via the one-shot)", () => {
+  test("groq with a key: install one-shot carries provider + key", async () => {
+    const h = makeHarness();
+    try {
+      const r = recordingRunner([0]);
+      const code = await walkTranscriptionStep({
+        configDir: h.dir,
+        log: () => {},
+        transcribeMode: "groq",
+        transcribeApiKey: "gsk_abc123",
+        runCommand: r.run,
+        platform: "linux",
+      });
+      expect(code).toBe(0);
+      expect(r.cmds[0]).toEqual([
+        "parachute",
+        "install",
+        "scribe",
+        "--scribe-provider",
+        "groq",
+        "--scribe-key",
+        "gsk_abc123",
+      ]);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("openai without a key: install one-shot omits --scribe-key + tells operator how to add it", async () => {
+    const h = makeHarness();
+    try {
+      const r = recordingRunner([0]);
+      const logs: string[] = [];
+      const code = await walkTranscriptionStep({
+        configDir: h.dir,
+        log: (l) => logs.push(l),
+        transcribeMode: "openai",
+        transcribeApiKey: "",
+        runCommand: r.run,
+        platform: "darwin",
+      });
+      expect(code).toBe(0);
+      expect(r.cmds[0]).toEqual(["parachute", "install", "scribe", "--scribe-provider", "openai"]);
+      expect(logs.join("\n")).toContain("OPENAI_API_KEY");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("cloud install failure: surfaces the non-zero exit + a retry hint, still exits 0", async () => {
+    const h = makeHarness();
+    try {
+      const r = recordingRunner([1]); // install fails
+      const logs: string[] = [];
+      const code = await walkTranscriptionStep({
+        configDir: h.dir,
+        log: (l) => logs.push(l),
+        transcribeMode: "groq",
+        transcribeApiKey: "gsk_x",
+        runCommand: r.run,
+        platform: "linux",
+      });
+      expect(code).toBe(0); // non-fatal — doesn't block the wizard
+      expect(logs.join("\n")).toContain("returned 1");
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
+describe("walkTranscriptionStep — local install-or-skip", () => {
+  test("Linux, ample RAM, install succeeds: install-backend uses onnx-asr; provider kept", async () => {
+    const h = makeHarness();
+    try {
+      // module install (writes provider via --scribe-provider), install-backend, restart
+      const r = recordingRunner([0, 0, 0]);
+      const code = await walkTranscriptionStep({
+        configDir: h.dir,
+        log: () => {},
+        transcribeMode: "local",
+        runCommand: r.run,
+        platform: "linux",
+        availableRamMib: 4096,
+      });
+      expect(code).toBe(0);
+      // Module install pins the resolved Linux backend, NOT parakeet-mlx.
+      expect(r.cmds[0]).toEqual([
+        "parachute",
+        "install",
+        "scribe",
+        "--scribe-provider",
+        "onnx-asr",
+      ]);
+      // scribe's own runnable install routine, targeting onnx-asr.
+      expect(r.cmds[1]).toEqual(["parachute-scribe", "install-backend", "--provider", "onnx-asr"]);
+      // A restart so the running scribe picks up the engine.
+      expect(r.cmds[2]).toEqual(["parachute", "restart", "scribe"]);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("macOS local resolves to parakeet-mlx", async () => {
+    const h = makeHarness();
+    try {
+      const r = recordingRunner([0, 0, 0]);
+      await walkTranscriptionStep({
+        configDir: h.dir,
+        log: () => {},
+        transcribeMode: "local",
+        runCommand: r.run,
+        platform: "darwin",
+        availableRamMib: 16384,
+      });
+      expect(r.cmds[1]).toEqual([
+        "parachute-scribe",
+        "install-backend",
+        "--provider",
+        "parakeet-mlx",
+      ]);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("install-backend FAILS: clears the provisional provider (no dead string) + points at cloud", async () => {
+    const h = makeHarness();
+    try {
+      // module install OK, install-backend FAILS (exit 3). No restart should run.
+      const r = recordingRunner([0, 3]);
+      const logs: string[] = [];
+      const code = await walkTranscriptionStep({
+        configDir: h.dir,
+        log: (l) => logs.push(l),
+        transcribeMode: "local",
+        runCommand: r.run,
+        platform: "linux",
+        availableRamMib: 4096,
+      });
+      expect(code).toBe(0);
+      // Only two commands ran — the failed install-backend, no restart.
+      expect(r.cmds.length).toBe(2);
+      expect(r.cmds.some((c) => c[0] === "parachute" && c[1] === "restart")).toBe(false);
+      // The provisional provider write (by the install one-shot in production)
+      // is cleared. We simulate the install having written it by checking the
+      // step never leaves a transcribe.provider on its own write path — and the
+      // honest cloud steer is logged.
+      expect(logs.join("\n")).toContain("install failed");
+      expect(logs.join("\n")).toContain("Cloud alternative");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("RAM below floor: REFUSES local, records nothing, steers to cloud one-shot", async () => {
+    const h = makeHarness();
+    try {
+      const r = recordingRunner();
+      const logs: string[] = [];
+      const code = await walkTranscriptionStep({
+        configDir: h.dir,
+        log: (l) => logs.push(l),
+        transcribeMode: "local",
+        runCommand: r.run,
+        platform: "linux",
+        availableRamMib: 900, // 1 GB droplet
+      });
+      expect(code).toBe(0);
+      // Nothing installed, nothing recorded.
+      expect(r.cmds).toEqual([]);
+      expect(readCfg(h.dir)).toBeUndefined();
+      const joined = logs.join("\n");
+      expect(joined).toContain("isn't possible");
+      expect(joined).toContain("parachute install scribe --scribe-provider groq");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("unsupported platform: REFUSES local + steers to cloud, no install", async () => {
+    const h = makeHarness();
+    try {
+      const r = recordingRunner();
+      const code = await walkTranscriptionStep({
+        configDir: h.dir,
+        log: () => {},
+        transcribeMode: "local",
+        runCommand: r.run,
+        platform: "win32",
+        availableRamMib: 99999,
+      });
+      expect(code).toBe(0);
+      expect(r.cmds).toEqual([]);
+      expect(readCfg(h.dir)).toBeUndefined();
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("module install fails before the engine: clears provider, no install-backend run", async () => {
+    const h = makeHarness();
+    try {
+      const r = recordingRunner([5]); // module install fails
+      const code = await walkTranscriptionStep({
+        configDir: h.dir,
+        log: () => {},
+        transcribeMode: "local",
+        runCommand: r.run,
+        platform: "linux",
+        availableRamMib: 4096,
+      });
+      expect(code).toBe(0);
+      expect(r.cmds.length).toBe(1);
+      expect(r.cmds[0]?.[1]).toBe("install");
+    } finally {
+      h.cleanup();
+    }
+  });
+});

package/src/__tests__/wizard.test.ts

@@ -293,6 +293,29 @@ describe("parseWizardArgs", () => {
     expect(r.opts.vaultMode).toBe("import");
     expect(r.opts.vaultImportRemoteUrl).toBe("https://github.com/me/v.git");
   });
+
+  test("parses --transcribe-mode + --transcribe-key + --config-dir", () => {
+    const r = parseWizardArgs([
+      "--hub-url",
+      "http://x",
+      "--transcribe-mode",
+      "groq",
+      "--transcribe-key",
+      "gsk_test",
+      "--config-dir",
+      "/tmp/ph",
+    ]);
+    expect("error" in r).toBe(false);
+    if ("error" in r) throw new Error(r.error);
+    expect(r.opts.transcribeMode).toBe("groq");
+    expect(r.opts.transcribeApiKey).toBe("gsk_test");
+    expect(r.opts.configDir).toBe("/tmp/ph");
+  });
+
+  test("rejects invalid --transcribe-mode", () => {
+    const r = parseWizardArgs(["--hub-url", "http://x", "--transcribe-mode", "garbage"]);
+    expect("error" in r).toBe(true);
+  });
 });
 
 describe("runCliWizard", () => {
@@ -509,4 +532,127 @@ describe("runCliWizard", () => {
     });
     expect(code).toBe(1);
   });
+
+  test("password validator floor is 12 (matches the server) — an 11-char password is rejected", async () => {
+    const { fetchImpl } = makeFakeHub();
+    const logs: string[] = [];
+    const code = await runCliWizard({
+      hubUrl: "http://127.0.0.1:1939",
+      log: (l) => logs.push(l),
+      fetchImpl,
+      sleep: async () => {},
+      accountUsername: "admin",
+      accountPassword: "elevenchar.", // 11 chars
+      vaultMode: "skip",
+      exposeMode: "localhost",
+    });
+    expect(code).toBe(1);
+    expect(logs.join("\n")).toContain("at least 12 characters");
+  });
+
+  test("exactly 12 chars passes the validator (no early bounce)", async () => {
+    const { state, fetchImpl } = makeFakeHub();
+    const code = await runCliWizard({
+      hubUrl: "http://127.0.0.1:1939",
+      log: () => {},
+      fetchImpl,
+      sleep: async () => {},
+      accountUsername: "admin",
+      accountPassword: "twelvecharss", // 12 chars
+      vaultMode: "skip",
+      exposeMode: "localhost",
+    });
+    expect(code).toBe(0);
+    expect(state.posted.some((p) => p.path === "/admin/setup/account")).toBe(true);
+  });
+
+  test("transcription step runs between vault and expose when configDir is set", async () => {
+    const { state, fetchImpl } = makeFakeHub();
+    const transcribeCmds: string[][] = [];
+    const code = await runCliWizard({
+      hubUrl: "http://127.0.0.1:1939",
+      log: () => {},
+      fetchImpl,
+      sleep: async () => {},
+      accountUsername: "admin",
+      accountPassword: "longpassword",
+      vaultMode: "skip",
+      exposeMode: "localhost",
+      configDir: "/tmp/never-written-none-mode",
+      transcribeMode: "none", // none writes nothing + spawns nothing
+      transcribeRunCommand: async (cmd) => {
+        transcribeCmds.push([...cmd]);
+        return 0;
+      },
+    });
+    expect(code).toBe(0);
+    // The vault + expose POSTs still happened in order.
+    expect(state.posted.map((p) => p.path)).toEqual([
+      "/admin/setup/account",
+      "/admin/setup/vault",
+      "/admin/setup/expose",
+    ]);
+    // mode=none → no transcription subprocess.
+    expect(transcribeCmds).toEqual([]);
+  });
+
+  test("transcription step (cloud) drives the install one-shot via the injected runner", async () => {
+    const { fetchImpl } = makeFakeHub();
+    const transcribeCmds: string[][] = [];
+    const code = await runCliWizard({
+      hubUrl: "http://127.0.0.1:1939",
+      log: () => {},
+      fetchImpl,
+      sleep: async () => {},
+      accountUsername: "admin",
+      accountPassword: "longpassword",
+      vaultMode: "skip",
+      exposeMode: "localhost",
+      configDir: "/tmp/never-written-cloud-mode",
+      transcribeMode: "groq",
+      transcribeApiKey: "gsk_wired",
+      platform: "linux",
+      transcribeRunCommand: async (cmd) => {
+        transcribeCmds.push([...cmd]);
+        return 0;
+      },
+    });
+    expect(code).toBe(0);
+    expect(transcribeCmds[0]).toEqual([
+      "parachute",
+      "install",
+      "scribe",
+      "--scribe-provider",
+      "groq",
+      "--scribe-key",
+      "gsk_wired",
+    ]);
+  });
+
+  test("transcription step is skipped when configDir is absent", async () => {
+    const { state, fetchImpl } = makeFakeHub();
+    let ran = false;
+    const code = await runCliWizard({
+      hubUrl: "http://127.0.0.1:1939",
+      log: () => {},
+      fetchImpl,
+      sleep: async () => {},
+      accountUsername: "admin",
+      accountPassword: "longpassword",
+      vaultMode: "skip",
+      exposeMode: "localhost",
+      // no configDir
+      transcribeRunCommand: async () => {
+        ran = true;
+        return 0;
+      },
+    });
+    expect(code).toBe(0);
+    expect(ran).toBe(false);
+    expect(state.posted.map((p) => p.path)).toEqual([
+      "/admin/setup/account",
+      "/admin/setup/vault",
+      "/admin/setup/expose",
+    ]);
+  });
 });

package/src/api-modules.ts

@@ -15,11 +15,21 @@
  *     / `crashed` / `starting` / `restarting`) + pid. Absent when the
  *     hub is in CLI mode (no supervisor injected through HubFetchDeps).
  *
- * `focus` ("core" | "experimental") comes from each module's `module.json`
- * when declared, else `focusForShort`'s default map. The SPA groups core first
- * + de-emphasizes experimental — it NEVER hides a module. This is what makes a
- * running, self-registered module (channel) visible + installable; the old
- * `CURATED_MODULES = ["vault","scribe"]` whitelist made it invisible.
+ * `focus` ("core" | "experimental" | "deprecated") comes from each module's
+ * `module.json` when declared, else `focusForShort`'s default map. The SPA
+ * groups core first, de-emphasizes experimental, and de-emphasizes
+ * `deprecated` (notes-daemon / runner) further — it NEVER hides an installed
+ * module (so an existing operator can still manage / uninstall a deprecated
+ * one). This is what makes a running, self-registered module (channel) visible
+ * + installable; the old `CURATED_MODULES = ["vault","scribe"]` whitelist made
+ * it invisible.
+ *
+ * `available_to_install` is the fresh-install OFFER (2026-06-25): a module the
+ * hub will push as a new install. It's `available && focus !== "deprecated"`
+ * — so a `deprecated` module that is ALREADY installed still surfaces (via the
+ * `modules` union + `installed: true`) and is manageable, but a deprecated
+ * module is never offered as a fresh install. `agent` (`experimental`) stays
+ * offered.
  *
  * Bearer-gated on `parachute:host:auth` to match the rest of `/api/auth/*`
  * and `/api/grants` — the admin SPA mints this scope via
@@ -199,14 +209,33 @@ interface ModuleWireShape {
   display_name: string;
   tagline: string;
   /**
-   * Discovery tier (2026-06-09 modular-UI architecture). `core` modules render
-   * in the headline group; `experimental` modules render in a de-emphasized
-   * "Experimental" group below — never hidden. Resolved from the module's
-   * `module.json` `focus` when declared, else `focusForShort`'s default map
-   * (vault/scribe/hub/surface → core, channel/runner/others → experimental).
+   * Discovery tier (2026-06-09 modular-UI architecture; `deprecated` added
+   * 2026-06-25). `core` modules render in the headline group; `experimental`
+   * modules render in a de-emphasized "Experimental" group; `deprecated`
+   * modules (notes-daemon / runner) render in a further-de-emphasized
+   * "Deprecated" group — never hidden when installed. Resolved from the
+   * module's `module.json` `focus` when declared, else `focusForShort`'s
+   * default map (vault/scribe/hub/surface → core, notes/runner → deprecated,
+   * others → experimental).
    */
   focus: ModuleFocus;
+  /**
+   * True iff the hub knows how to install this module (`package`/`manifest`
+   * resolvable). Historically "in the curated install catalog". Still set for
+   * every known module; a purely third-party services.json row is false.
+   * NOTE: this is NOT the fresh-install OFFER — a `deprecated` module is still
+   * `available: true` (it's installable for back-compat / re-install) but is
+   * excluded from `available_to_install`.
+   */
   available: boolean;
+  /**
+   * The fresh-install OFFER (2026-06-25): whether the hub presents this module
+   * in the "available to install fresh" set. `available && focus !==
+   * "deprecated"`. The SPA's "Install a module" catalog filters on this so
+   * notes-daemon / runner aren't pushed on a fresh box; an already-installed
+   * deprecated module still surfaces (in the Installed section) for management.
+   */
+  available_to_install: boolean;
   installed: boolean;
   installed_version: string | null;
   latest_version: string | null;
@@ -562,8 +591,8 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
   // module's manifest-declared `focus` (when installed + declared) wins; else
   // the `focusForShort` default map. Sort: `core` group first (with the
   // CURATED_MODULES recommended-install order floated to the top of that
-  // group), then `experimental` — the SPA renders the two groups; `focus`
-  // never hides a module.
+  // group), then `experimental`, then `deprecated` (notes / runner) last — the
+  // SPA renders the groups; `focus` never hides an installed module.
   const recommendedOrder = new Map<string, number>(
     (CURATED_MODULES as readonly string[]).map((s, i) => [s, i]),
   );
@@ -585,6 +614,11 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
       // known modules; a purely third-party services.json row (no install
       // package) is not hub-installable → false.
       available: m !== undefined,
+      // Fresh-install OFFER (2026-06-25): installable AND not deprecated. A
+      // deprecated short (notes / runner) stays `available` (re-installable
+      // for back-compat) but is dropped from the offer set so the SPA's
+      // "Install a module" catalog doesn't push it on a fresh box.
+      available_to_install: m !== undefined && focus !== "deprecated",
       installed: installed !== undefined,
       installed_version: installed?.version ?? null,
       latest_version: latestByShort.get(short) ?? null,
@@ -598,7 +632,7 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
     };
     return row;
   });
-  const focusRank = (f: ModuleFocus): number => (f === "core" ? 0 : 1);
+  const focusRank = (f: ModuleFocus): number => (f === "core" ? 0 : f === "experimental" ? 1 : 2);
   rows.sort((a, b) => {
     if (a.focus !== b.focus) return focusRank(a.focus) - focusRank(b.focus);
     const ai = recommendedOrder.get(a.short) ?? Number.POSITIVE_INFINITY;

package/src/commands/init.ts

@@ -172,7 +172,11 @@ export interface InitOpts {
    * Test seam: shim for the CLI wizard chain (hub#168 Cut 3). Production
    * lazy-imports `runCliWizard` from `./wizard.ts`. Tests pass a stub.
    */
-  runCliWizardImpl?: (opts: { hubUrl: string; log: (l: string) => void }) => Promise<number>;
+  runCliWizardImpl?: (opts: {
+    hubUrl: string;
+    log: (l: string) => void;
+    configDir?: string;
+  }) => Promise<number>;
   /**
    * Skip the "browser or CLI?" wizard-choice prompt (hub#168 Cut 4). Used
    * by pre-Cut-4 tests that don't expect the new prompt + by the
@@ -485,6 +489,7 @@ async function defaultInstallVaultModule(configDir: string, manifestPath: string
 async function defaultRunCliWizard(opts: {
   hubUrl: string;
   log: (l: string) => void;
+  configDir?: string;
 }): Promise<number> {
   const { runCliWizard } = await import("./wizard.ts");
   return await runCliWizard(opts);
@@ -895,7 +900,10 @@ export async function init(opts: InitOpts = {}): Promise<number> {
     // (the loopback-gated GET /admin/setup probe) — the operator never has to
     // copy the token out of the startup logs.
     const cliWizardUrl = `http://127.0.0.1:${hubPort}`;
-    return await runCliWizardImpl({ hubUrl: cliWizardUrl, log });
+    // Pass the resolved configDir so the CLI wizard's transcription step can
+    // write scribe's config (onboarding-streamline hub PR1). Without it the
+    // step is skipped.
+    return await runCliWizardImpl({ hubUrl: cliWizardUrl, log, configDir });
   }
 
   // Step 5: offer to open the browser. Skip in non-TTY shells (CI),