@openparachute/hub 0.3.0-rc.1

package/src/__tests__/vault-tokens-create-interactive.test.ts

@@ -0,0 +1,183 @@
+import { describe, expect, test } from "bun:test";
+import { runVaultTokensCreateInteractive } from "../commands/vault-tokens-create-interactive.ts";
+
+interface Harness {
+  logs: string[];
+  prompts: string[];
+  promptAnswers: string[];
+  commands: string[][];
+  exitCode: number;
+}
+
+function makeHarness(
+  answers: string[],
+  opts: { exitCode?: number } = {},
+): {
+  harness: Harness;
+  wire: {
+    log: (l: string) => void;
+    prompt: (q: string) => Promise<string>;
+    interactiveRunner: (cmd: readonly string[]) => Promise<number>;
+  };
+} {
+  const harness: Harness = {
+    logs: [],
+    prompts: [],
+    promptAnswers: [...answers],
+    commands: [],
+    exitCode: opts.exitCode ?? 0,
+  };
+  let i = 0;
+  return {
+    harness,
+    wire: {
+      log: (line) => harness.logs.push(line),
+      prompt: async (q) => {
+        harness.prompts.push(q);
+        const a = harness.promptAnswers[i++];
+        if (a === undefined) throw new Error(`prompt exhausted at: ${q}`);
+        return a;
+      },
+      interactiveRunner: async (cmd) => {
+        harness.commands.push([...cmd]);
+        return harness.exitCode;
+      },
+    },
+  };
+}
+
+describe("runVaultTokensCreateInteractive — scope picker", () => {
+  test("Enter defaults to read (safer choice)", async () => {
+    const { harness, wire } = makeHarness(["", ""]); // scope=default, label=skip
+    const code = await runVaultTokensCreateInteractive({ args: [], ...wire });
+    expect(code).toBe(0);
+    expect(harness.commands).toHaveLength(1);
+    const cmd = harness.commands[0]!;
+    expect(cmd).toEqual(["parachute-vault", "tokens", "create", "--read"]);
+  });
+
+  test("'1' also selects read", async () => {
+    const { harness, wire } = makeHarness(["1", ""]);
+    await runVaultTokensCreateInteractive({ args: [], ...wire });
+    expect(harness.commands[0]).toContain("--read");
+  });
+
+  test("'2' selects write (vault:write scope)", async () => {
+    const { harness, wire } = makeHarness(["2", ""]);
+    await runVaultTokensCreateInteractive({ args: [], ...wire });
+    const cmd = harness.commands[0]!;
+    expect(cmd).toEqual(["parachute-vault", "tokens", "create", "--scope", "vault:write"]);
+  });
+
+  test("'3' selects admin (vault:admin scope)", async () => {
+    const { harness, wire } = makeHarness(["3", ""]);
+    await runVaultTokensCreateInteractive({ args: [], ...wire });
+    const cmd = harness.commands[0]!;
+    expect(cmd).toEqual(["parachute-vault", "tokens", "create", "--scope", "vault:admin"]);
+  });
+
+  test("'4' cancels with exit 0 and no subprocess", async () => {
+    const { harness, wire } = makeHarness(["4"]);
+    const code = await runVaultTokensCreateInteractive({ args: [], ...wire });
+    expect(code).toBe(0);
+    expect(harness.commands).toHaveLength(0);
+    expect(harness.logs.join("\n")).toContain("Cancelled");
+  });
+
+  test("'q' also cancels", async () => {
+    const { harness, wire } = makeHarness(["q"]);
+    const code = await runVaultTokensCreateInteractive({ args: [], ...wire });
+    expect(code).toBe(0);
+    expect(harness.commands).toHaveLength(0);
+  });
+
+  test("word aliases accepted case-insensitively", async () => {
+    for (const [answer, expected] of [
+      ["READ", "--read"],
+      ["Write", "vault:write"],
+      ["admin", "vault:admin"],
+    ] as const) {
+      const { harness, wire } = makeHarness([answer, ""]);
+      await runVaultTokensCreateInteractive({ args: [], ...wire });
+      expect(harness.commands[0]!.join(" ")).toContain(expected);
+    }
+  });
+
+  test("garbage input reprompts, keeping the scope picker tight", async () => {
+    const { harness, wire } = makeHarness(["bogus", "5", "2", ""]);
+    await runVaultTokensCreateInteractive({ args: [], ...wire });
+    expect(harness.commands).toHaveLength(1);
+    expect(harness.commands[0]).toContain("vault:write");
+    // Three scope prompts were asked (bogus, 5, then the valid 2); one label.
+    expect(harness.prompts.filter((p) => p.startsWith("Choice"))).toHaveLength(3);
+  });
+});
+
+describe("runVaultTokensCreateInteractive — label prompt", () => {
+  test("blank label = no --label flag forwarded", async () => {
+    const { harness, wire } = makeHarness(["1", ""]);
+    await runVaultTokensCreateInteractive({ args: [], ...wire });
+    expect(harness.commands[0]!.includes("--label")).toBe(false);
+  });
+
+  test("non-blank label is appended verbatim", async () => {
+    const { harness, wire } = makeHarness(["1", "n8n-sync"]);
+    await runVaultTokensCreateInteractive({ args: [], ...wire });
+    const cmd = harness.commands[0]!;
+    expect(cmd).toContain("--label");
+    expect(cmd[cmd.indexOf("--label") + 1]).toBe("n8n-sync");
+  });
+
+  test("label with spaces is passed as a single arg (not re-split)", async () => {
+    const { harness, wire } = makeHarness(["1", "pendant prototype"]);
+    await runVaultTokensCreateInteractive({ args: [], ...wire });
+    const cmd = harness.commands[0]!;
+    expect(cmd[cmd.indexOf("--label") + 1]).toBe("pendant prototype");
+  });
+
+  test("pre-supplied --label skips the label prompt entirely", async () => {
+    const { harness, wire } = makeHarness(["1"]); // ONLY the scope prompt
+    await runVaultTokensCreateInteractive({
+      args: ["--label", "existing"],
+      ...wire,
+    });
+    // Prompts only include the scope picker, not a label prompt.
+    expect(harness.prompts.some((p) => p.toLowerCase().includes("label"))).toBe(false);
+    // The user-supplied --label stays in place; we didn't double-append.
+    const cmd = harness.commands[0]!;
+    const labelIdxs: number[] = [];
+    cmd.forEach((a, idx) => {
+      if (a === "--label") labelIdxs.push(idx);
+    });
+    expect(labelIdxs).toHaveLength(1);
+    expect(cmd[labelIdxs[0]! + 1]).toBe("existing");
+  });
+});
+
+describe("runVaultTokensCreateInteractive — passthrough of pre-supplied args", () => {
+  test("--vault / --expires forwarded verbatim, scope appended", async () => {
+    const { harness, wire } = makeHarness(["1", ""]);
+    await runVaultTokensCreateInteractive({
+      args: ["--vault", "work", "--expires", "30d"],
+      ...wire,
+    });
+    const cmd = harness.commands[0]!;
+    // Original argv stays in order, scope flag appended after.
+    expect(cmd).toEqual([
+      "parachute-vault",
+      "tokens",
+      "create",
+      "--vault",
+      "work",
+      "--expires",
+      "30d",
+      "--read",
+    ]);
+  });
+
+  test("subprocess exit code is returned to the caller", async () => {
+    const { wire } = makeHarness(["1", ""], { exitCode: 5 });
+    const code = await runVaultTokensCreateInteractive({ args: [], ...wire });
+    expect(code).toBe(5);
+  });
+});

package/src/__tests__/well-known.test.ts

@@ -0,0 +1,214 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ServiceEntry } from "../services-manifest.ts";
+import {
+  buildWellKnown,
+  isVaultEntry,
+  shortName,
+  vaultInstanceName,
+  writeWellKnownFile,
+} from "../well-known.ts";
+
+const vault: ServiceEntry = {
+  name: "parachute-vault",
+  port: 1940,
+  paths: ["/vault/default"],
+  health: "/vault/default/health",
+  version: "0.2.4",
+};
+
+const notes: ServiceEntry = {
+  name: "parachute-notes",
+  port: 5173,
+  paths: ["/notes"],
+  health: "/notes/health",
+  version: "0.0.1",
+};
+
+const scribe: ServiceEntry = {
+  name: "parachute-scribe",
+  port: 3200,
+  paths: ["/scribe"],
+  health: "/scribe/health",
+  version: "0.1.0",
+};
+
+describe("shortName", () => {
+  test("strips parachute- prefix", () => {
+    expect(shortName("parachute-vault")).toBe("vault");
+    expect(shortName("parachute-notes")).toBe("notes");
+    expect(shortName("custom-service")).toBe("custom-service");
+  });
+});
+
+describe("isVaultEntry", () => {
+  test("matches bare parachute-vault", () => {
+    expect(isVaultEntry(vault)).toBe(true);
+  });
+
+  test("matches prefixed vault instances", () => {
+    expect(isVaultEntry({ ...vault, name: "parachute-vault-work" })).toBe(true);
+    expect(isVaultEntry({ ...vault, name: "parachute-vault-personal" })).toBe(true);
+  });
+
+  test("rejects non-vault services", () => {
+    expect(isVaultEntry(notes)).toBe(false);
+    expect(isVaultEntry(scribe)).toBe(false);
+  });
+
+  test("does not match an unrelated name that merely starts with parachute-vaultish", () => {
+    expect(isVaultEntry({ ...vault, name: "parachute-vaultkeeper" })).toBe(false);
+  });
+});
+
+describe("vaultInstanceName", () => {
+  test("prefers /vault/<name> path segment", () => {
+    expect(vaultInstanceName({ ...vault, paths: ["/vault/work"] })).toBe("work");
+    expect(vaultInstanceName({ ...vault, paths: ["/vault/default"] })).toBe("default");
+  });
+
+  test("falls back to manifest-name suffix when path is non-vault", () => {
+    expect(vaultInstanceName({ ...vault, name: "parachute-vault-personal", paths: ["/"] })).toBe(
+      "personal",
+    );
+  });
+
+  test("defaults to 'default' when nothing else matches", () => {
+    expect(vaultInstanceName({ ...vault, paths: ["/"] })).toBe("default");
+    expect(vaultInstanceName({ ...vault, paths: [] })).toBe("default");
+  });
+
+  test("path wins over name suffix", () => {
+    expect(
+      vaultInstanceName({
+        ...vault,
+        name: "parachute-vault-work",
+        paths: ["/vault/override"],
+      }),
+    ).toBe("override");
+  });
+});
+
+describe("buildWellKnown", () => {
+  test("vaults is always an array, other services are flat entries, services[] includes all", () => {
+    const doc = buildWellKnown({
+      services: [vault, notes, scribe],
+      canonicalOrigin: "https://parachute.taildf9ce2.ts.net",
+    });
+    expect(doc.vaults).toEqual([
+      {
+        name: "default",
+        url: "https://parachute.taildf9ce2.ts.net/vault/default",
+        version: "0.2.4",
+      },
+    ]);
+    expect(doc.notes).toEqual({
+      url: "https://parachute.taildf9ce2.ts.net/notes",
+      version: "0.0.1",
+    });
+    expect(doc.scribe).toEqual({
+      url: "https://parachute.taildf9ce2.ts.net/scribe",
+      version: "0.1.0",
+    });
+    expect(doc.services.map((s) => s.name)).toEqual([
+      "parachute-vault",
+      "parachute-notes",
+      "parachute-scribe",
+    ]);
+  });
+
+  test("services[] entries include infoUrl pointing at /.parachute/info", () => {
+    const doc = buildWellKnown({
+      services: [vault, notes],
+      canonicalOrigin: "https://x.example",
+    });
+    expect(doc.services).toEqual([
+      {
+        name: "parachute-vault",
+        url: "https://x.example/vault/default",
+        path: "/vault/default",
+        version: "0.2.4",
+        infoUrl: "https://x.example/vault/default/.parachute/info",
+      },
+      {
+        name: "parachute-notes",
+        url: "https://x.example/notes",
+        path: "/notes",
+        version: "0.0.1",
+        infoUrl: "https://x.example/notes/.parachute/info",
+      },
+    ]);
+  });
+
+  test("infoUrl for root-mounted service has no double slash", () => {
+    const rootSvc: ServiceEntry = { ...notes, paths: ["/"] };
+    const doc = buildWellKnown({
+      services: [rootSvc],
+      canonicalOrigin: "https://x.example",
+    });
+    expect(doc.services[0]?.infoUrl).toBe("https://x.example/.parachute/info");
+  });
+
+  test("vaults array is present even when no vault is installed", () => {
+    const doc = buildWellKnown({
+      services: [notes],
+      canonicalOrigin: "https://x.example",
+    });
+    expect(doc.vaults).toEqual([]);
+    expect(doc.services).toHaveLength(1);
+    expect(doc.notes).toEqual({ url: "https://x.example/notes", version: "0.0.1" });
+  });
+
+  test("multiple vault instances all land in the vaults array", () => {
+    const work: ServiceEntry = {
+      ...vault,
+      name: "parachute-vault-work",
+      paths: ["/vault/work"],
+      port: 1941,
+      version: "0.2.4",
+    };
+    const doc = buildWellKnown({
+      services: [vault, work],
+      canonicalOrigin: "https://x.example",
+    });
+    expect(doc.vaults).toHaveLength(2);
+    expect(doc.vaults.map((v) => v.name).sort()).toEqual(["default", "work"]);
+  });
+
+  test("handles canonicalOrigin with trailing slash", () => {
+    const doc = buildWellKnown({
+      services: [vault],
+      canonicalOrigin: "https://parachute.taildf9ce2.ts.net/",
+    });
+    expect(doc.vaults[0]?.url).toBe("https://parachute.taildf9ce2.ts.net/vault/default");
+  });
+
+  test("falls back to / for empty paths", () => {
+    const entry: ServiceEntry = { ...vault, paths: [] };
+    const doc = buildWellKnown({
+      services: [entry],
+      canonicalOrigin: "https://x.example",
+    });
+    expect(doc.vaults[0]?.url).toBe("https://x.example/");
+  });
+});
+
+describe("writeWellKnownFile", () => {
+  test("writes pretty JSON and creates nested directories", () => {
+    const dir = mkdtempSync(join(tmpdir(), "pcli-wk-"));
+    try {
+      const path = join(dir, "nested", "parachute.json");
+      const doc = buildWellKnown({
+        services: [vault],
+        canonicalOrigin: "https://x.example",
+      });
+      writeWellKnownFile(doc, path);
+      const round = JSON.parse(readFileSync(path, "utf8"));
+      expect(round).toEqual(doc);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/auto-wire.ts

@@ -0,0 +1,184 @@
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { restart as lifecycleRestart } from "./commands/lifecycle.ts";
+import { parseEnvFile, upsertEnvLine, writeEnvFile } from "./env-file.ts";
+import { type AliveFn, defaultAlive, processState } from "./process-state.ts";
+import { PORT_RESERVATIONS } from "./service-spec.ts";
+
+/**
+ * Cross-service auto-wiring for shared secrets.
+ *
+ * Vault's transcription worker authenticates to scribe over loopback using a
+ * shared bearer token, and reaches scribe at SCRIBE_URL. On install, when both
+ * services are present, we mint the secret and pin the URL on vault's side so
+ * the operator never has to. Missing either service → no-op; values already
+ * present in vault's .env → preserved.
+ *
+ * Storage locations (convention, matches what each service reads at boot):
+ *   ~/.parachute/vault/.env        SCRIBE_AUTH_TOKEN=<value>
+ *                                  SCRIBE_URL=http://127.0.0.1:1943
+ *   ~/.parachute/scribe/config.json  { "auth": { "required_token": "<value>" } }
+ *
+ * Idempotency rule: we don't regenerate the token if vault's .env already
+ * carries it, and we don't overwrite SCRIBE_URL if already set. This preserves
+ * operator-set overrides and keeps repeat installs from churning state in a
+ * way that would break an already-running vault worker.
+ *
+ * After writing, if vault is running, restart it so the worker re-reads the
+ * .env. Without the restart vault keeps the old (or empty) values in process
+ * env and voice memos sit with `_Transcript pending._` forever — exactly the
+ * launch-day footgun this auto-wire exists to prevent.
+ */
+
+export const SCRIBE_AUTH_ENV_KEY = "SCRIBE_AUTH_TOKEN";
+export const SCRIBE_URL_ENV_KEY = "SCRIBE_URL";
+
+export interface AutoWireOpts {
+  configDir: string;
+  /** Override for tests; must return a hex string of any reasonable length. */
+  randomToken?: () => string;
+  log?: (line: string) => void;
+  /** Test seam: liveness check used to decide whether to restart vault. */
+  alive?: AliveFn;
+  /**
+   * Test seam: restart hook for vault. Defaults to `lifecycle.restart("vault")`.
+   * Tests inject a fake to assert the call without spawning a real child.
+   */
+  restartService?: (short: string) => Promise<number>;
+}
+
+export interface AutoWireResult {
+  /** True when a token was written this call (vs. preserved from a prior wire). */
+  generated: boolean;
+  /** The token value, whether newly minted or pre-existing. */
+  token: string;
+  /** The SCRIBE_URL value present in vault .env after this call. */
+  scribeUrl: string;
+  vaultEnvPath: string;
+  scribeConfigPath: string;
+  /** True when vault was running and we issued a restart. */
+  restartedVault: boolean;
+}
+
+function defaultRandomToken(): string {
+  return randomBytes(32).toString("hex");
+}
+
+function defaultScribeUrl(): string {
+  // Pull scribe's canonical port from the single source of truth so a future
+  // port change doesn't drift between auto-wire and the rest of the CLI.
+  const port = PORT_RESERVATIONS.find((p) => p.name === "parachute-scribe")?.port ?? 1943;
+  return `http://127.0.0.1:${port}`;
+}
+
+function writeScribeConfig(path: string, token: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  let current: Record<string, unknown> = {};
+  if (existsSync(path)) {
+    try {
+      const parsed = JSON.parse(readFileSync(path, "utf8"));
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        current = parsed as Record<string, unknown>;
+      }
+    } catch {
+      // Malformed config — overwrite. Auto-wire owns this file's auth block;
+      // repairing a user-broken JSON is not our job.
+    }
+  }
+  const existingAuth =
+    typeof current.auth === "object" && current.auth !== null && !Array.isArray(current.auth)
+      ? (current.auth as Record<string, unknown>)
+      : {};
+  const next = {
+    ...current,
+    auth: { ...existingAuth, required_token: token },
+  };
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`);
+  renameSync(tmp, path);
+}
+
+/**
+ * Mint (or preserve) a shared secret and persist it to vault and scribe, plus
+ * pin SCRIBE_URL on vault's side. Caller has already confirmed both services
+ * are installed. Restarts vault if it's running so the worker re-reads .env.
+ */
+export async function autoWireScribeAuth(opts: AutoWireOpts): Promise<AutoWireResult> {
+  const random = opts.randomToken ?? defaultRandomToken;
+  const log = opts.log ?? (() => {});
+  const alive = opts.alive ?? defaultAlive;
+  const restartService =
+    opts.restartService ??
+    ((short: string) =>
+      lifecycleRestart(short, {
+        configDir: opts.configDir,
+        log,
+      }));
+
+  const vaultEnvPath = join(opts.configDir, "vault", ".env");
+  const scribeConfigPath = join(opts.configDir, "scribe", "config.json");
+
+  const parsed = parseEnvFile(vaultEnvPath);
+  let lines = parsed.lines;
+  let didWriteEnv = false;
+
+  const existingToken = parsed.values[SCRIBE_AUTH_ENV_KEY];
+  const tokenAlreadySet = existingToken !== undefined && existingToken.length > 0;
+  const token = tokenAlreadySet ? existingToken : random();
+  if (!tokenAlreadySet) {
+    lines = upsertEnvLine(lines, SCRIBE_AUTH_ENV_KEY, token);
+    didWriteEnv = true;
+  }
+
+  const existingUrl = parsed.values[SCRIBE_URL_ENV_KEY];
+  const urlAlreadySet = existingUrl !== undefined && existingUrl.length > 0;
+  const scribeUrl = urlAlreadySet ? existingUrl : defaultScribeUrl();
+  if (!urlAlreadySet) {
+    lines = upsertEnvLine(lines, SCRIBE_URL_ENV_KEY, scribeUrl);
+    didWriteEnv = true;
+  }
+
+  if (didWriteEnv) writeEnvFile(vaultEnvPath, lines);
+  writeScribeConfig(scribeConfigPath, token);
+
+  if (tokenAlreadySet && urlAlreadySet) {
+    log(
+      `${SCRIBE_AUTH_ENV_KEY} and ${SCRIBE_URL_ENV_KEY} already set in vault .env — preserved. Synced scribe config.json.`,
+    );
+  } else if (tokenAlreadySet) {
+    log(
+      `${SCRIBE_AUTH_ENV_KEY} already set in vault .env — preserved. Wired ${SCRIBE_URL_ENV_KEY}=${scribeUrl}. Synced scribe config.json.`,
+    );
+  } else {
+    log(
+      `Auto-wired shared secret + ${SCRIBE_URL_ENV_KEY} for vault → scribe transcription. Stored in ${vaultEnvPath} and ${scribeConfigPath}.`,
+    );
+  }
+
+  // Vault caches .env on process start; without a restart the worker keeps
+  // running with stale (or absent) SCRIBE_URL/SCRIBE_AUTH_TOKEN and voice
+  // memos never transcribe. Mirrors the auto-restart-on-expose pattern from
+  // PR #39 — skip silently if vault isn't running.
+  let restartedVault = false;
+  if (didWriteEnv && processState("vault", opts.configDir, alive).status === "running") {
+    log("Restarting vault to pick up new transcription wiring…");
+    const code = await restartService("vault");
+    if (code === 0) {
+      restartedVault = true;
+    } else {
+      log(
+        "⚠ vault restart failed. Run manually once the issue is resolved: parachute restart vault",
+      );
+    }
+  }
+
+  return {
+    generated: !tokenAlreadySet,
+    token,
+    scribeUrl,
+    vaultEnvPath,
+    scribeConfigPath,
+    restartedVault,
+  };
+}