@openparachute/vault 0.4.7-rc.2 → 0.4.8-rc.4

package/src/self-register.ts

@@ -0,0 +1,234 @@
+/**
+ * Boot-time self-registration of vault's manifest + `installDir` into
+ * `~/.parachute/services.json` — the POC for retiring hub's
+ * `FIRST_PARTY_FALLBACKS[vault]` (vault#266).
+ *
+ * Background: hub today vendors a `VAULT_FALLBACK` manifest in
+ * `parachute-hub/src/service-spec.ts` and stamps `installDir` onto the
+ * services.json row via `stampInstallDirOnRow` during `parachute install
+ * vault` / API install. That fallback exists because (a) bun-link dev
+ * mode never runs the hub install path so installDir isn't stamped,
+ * and (b) v0.5 vault didn't ship its own `.parachute/module.json` so
+ * hub had no manifest to read at lifecycle time.
+ *
+ * The endgame: every first-party module self-registers its manifest +
+ * installDir on startup so hub's vendored fallbacks retire one by one.
+ * This module is vault's piece of that pattern. Once vault/notes/scribe/
+ * runner all self-register reliably, a hub follow-up deletes
+ * `FIRST_PARTY_FALLBACKS` (see `parachute-hub` for the cleanup PR).
+ *
+ * Design choice — filesystem-direct rather than HTTP:
+ *
+ *   In v0.6 (single-container, hub-as-supervisor — see workspace
+ *   CLAUDE.md), hub and vault share the same filesystem. Writing directly
+ *   to services.json with the existing merge-preserving `upsertService`
+ *   is the simplest shape that works today. The hub-stamped fields the
+ *   row already carries (`installDir`, anything else hub adds in the
+ *   future) ride through because `upsertService` merges rather than
+ *   replaces (see `services-manifest.ts`).
+ *
+ *   v0.7 (multi-container cloud) will need an HTTP `POST
+ *   /api/modules/self-register` on hub so a module on a different
+ *   container can register without filesystem access to the operator's
+ *   `~/.parachute/`. Filed as a separate hub follow-up; this module's
+ *   shape is forward-compatible — `selfRegister` is the single seam that
+ *   would swap from filesystem to HTTP transport.
+ *
+ * Failure mode: every error path logs + returns (never throws). A bad
+ * registration must not crash server boot — the running vault is more
+ * valuable than the discoverability bookkeeping. Symptom of failure is
+ * "vault doesn't appear on hub discovery / admin SPA"; the fix is to
+ * restart vault or run `parachute install vault` to stamp the row via
+ * the hub-side path.
+ */
+
+import { readSelfManifest, resolvePackageRoot, type VaultModuleManifest } from "./module-manifest.ts";
+import {
+  ServicesManifestError,
+  type ServiceEntry,
+  readManifest,
+  upsertService,
+} from "./services-manifest.ts";
+import { listVaults, readGlobalConfig, DEFAULT_PORT } from "./config.ts";
+
+/**
+ * Compute the `paths` array for the parachute-vault services.json entry.
+ *
+ * Mirrors `buildVaultServicePaths` in `cli.ts` so the self-register pass
+ * produces the same multi-vault path advertisement as `parachute-vault
+ * init` / `vault create`. With no vaults yet, falls back to the manifest's
+ * canonical `paths[0]` so early-boot registration is still well-formed.
+ *
+ * Exported for tests; not part of the public module surface.
+ */
+export function buildVaultServicePaths(
+  defaultVault: string | undefined,
+  vaults: readonly string[],
+  fallbackFromManifest: readonly string[],
+): string[] {
+  if (vaults.length === 0) return [...fallbackFromManifest];
+  if (defaultVault && vaults.includes(defaultVault)) {
+    return [
+      `/vault/${defaultVault}`,
+      ...vaults.filter((v) => v !== defaultVault).map((v) => `/vault/${v}`),
+    ];
+  }
+  return vaults.map((v) => `/vault/${v}`);
+}
+
+export interface SelfRegisterDeps {
+  /** Override the manifest reader (tests inject a stub manifest). */
+  readManifest?: () => VaultModuleManifest | null;
+  /** Override the package-root resolver (tests inject a tmp dir). */
+  resolvePackageRoot?: () => string;
+  /** Override the services.json reader (tests inject a tmp-file reader). */
+  readServicesManifest?: typeof readManifest;
+  /** Override the services.json upsert (tests inject a tmp-file writer). */
+  upsertService?: typeof upsertService;
+  /** Override the vault lister (tests pass a fixed list). */
+  listVaults?: typeof listVaults;
+  /** Override the global config reader (tests pass a synthetic config). */
+  readGlobalConfig?: typeof readGlobalConfig;
+  /** Sink for status + warning lines. Production passes a console wrapper. */
+  log?: (msg: string) => void;
+  warn?: (msg: string) => void;
+  /** Vault's runtime version (from `package.json`). Required — no default. */
+  version: string;
+}
+
+/** Result of a `selfRegister` call, surfaced to callers for observability. */
+export type SelfRegisterResult =
+  | { status: "registered"; installDir: string; changed: boolean }
+  | { status: "skipped"; reason: string }
+  | { status: "failed"; reason: string };
+
+/**
+ * Self-register vault's manifest + installDir into `~/.parachute/services.json`.
+ *
+ * Idempotent: re-runs with the same manifest + installDir produce the same
+ * row (the `changed` field on the result telegraphs whether the write
+ * actually mutated the file).
+ *
+ * Never throws. Errors (missing manifest, services.json unreadable,
+ * filesystem write failure) are logged via `warn` and surfaced as a
+ * `failed` / `skipped` result. The caller (server boot) treats failure
+ * as non-fatal — vault keeps serving without the row stamp.
+ */
+export function selfRegister(deps: SelfRegisterDeps): SelfRegisterResult {
+  const log = deps.log ?? ((m) => console.log(m));
+  const warn = deps.warn ?? ((m) => console.warn(m));
+  const readManifestImpl = deps.readManifest ?? readSelfManifest;
+  const resolveRootImpl = deps.resolvePackageRoot ?? resolvePackageRoot;
+  const upsertImpl = deps.upsertService ?? upsertService;
+  const listVaultsImpl = deps.listVaults ?? listVaults;
+  const readGlobalConfigImpl = deps.readGlobalConfig ?? readGlobalConfig;
+
+  let manifest: VaultModuleManifest | null;
+  try {
+    manifest = readManifestImpl();
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    warn(`[self-register] could not read .parachute/module.json: ${msg}`);
+    return { status: "failed", reason: msg };
+  }
+  if (!manifest) {
+    log("[self-register] no .parachute/module.json found — skipping (legacy install or dev tree)");
+    return { status: "skipped", reason: "manifest absent" };
+  }
+
+  // `installDir` is the directory containing both `package.json` and
+  // `.parachute/module.json`. Hub's resolver (`<installDir>/.parachute/module.json`)
+  // expects exactly this shape — see `parachute-hub/src/post-install.ts`'s
+  // `stampInstallDirOnRow`.
+  let installDir: string;
+  try {
+    installDir = resolveRootImpl();
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    warn(`[self-register] could not resolve package root: ${msg}`);
+    return { status: "failed", reason: msg };
+  }
+
+  let globalConfig: ReturnType<typeof readGlobalConfig>;
+  let vaults: string[];
+  try {
+    globalConfig = readGlobalConfigImpl();
+    vaults = listVaultsImpl();
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    warn(`[self-register] could not read vault config: ${msg}`);
+    return { status: "failed", reason: msg };
+  }
+
+  const paths = buildVaultServicePaths(globalConfig.default_vault, vaults, manifest.paths);
+  const port = globalConfig.port ?? DEFAULT_PORT;
+
+  // Build the entry with manifest-sourced metadata (displayName, tagline,
+  // stripPrefix) layered on top of the operationally-determined fields
+  // (port from config, paths from current vault list, version from
+  // package.json). hub-stamped fields on the existing row (installDir
+  // from prior CLI install path, anything future) survive via
+  // `upsertService`'s merge semantics — see services-manifest.ts.
+  const entry: ServiceEntry & {
+    installDir: string;
+    displayName?: string;
+    tagline?: string;
+    stripPrefix?: boolean;
+  } = {
+    name: manifest.manifestName,
+    port,
+    paths,
+    health: manifest.health,
+    version: deps.version,
+    installDir,
+  };
+  if (manifest.displayName !== undefined) entry.displayName = manifest.displayName;
+  if (manifest.tagline !== undefined) entry.tagline = manifest.tagline;
+  if (manifest.stripPrefix !== undefined) entry.stripPrefix = manifest.stripPrefix;
+
+  // Detect whether the existing row already matches (no-op idempotency
+  // signal). We don't gate the write on this — `upsertService` itself is
+  // already idempotent at the byte level — but reporting `changed: false`
+  // lets the boot log say "already registered" instead of restamping noise.
+  let priorRow: (ServiceEntry & { installDir?: string }) | undefined;
+  try {
+    const current = (deps.readServicesManifest ?? readManifest)();
+    priorRow = current.services.find((s) => s.name === manifest.manifestName) as
+      | (ServiceEntry & { installDir?: string })
+      | undefined;
+  } catch (err) {
+    // Read failure here is non-fatal — we'll still attempt the write below.
+    // services.json may not exist yet (fresh boot); upsertService creates it.
+    if (err instanceof ServicesManifestError) {
+      warn(`[self-register] services.json read warning: ${err.message}`);
+    } else {
+      warn(`[self-register] services.json read warning: ${String(err)}`);
+    }
+  }
+
+  const changed =
+    !priorRow ||
+    priorRow.installDir !== installDir ||
+    priorRow.version !== deps.version ||
+    priorRow.port !== port ||
+    JSON.stringify(priorRow.paths) !== JSON.stringify(paths) ||
+    priorRow.health !== manifest.health ||
+    (priorRow as { displayName?: string }).displayName !== manifest.displayName ||
+    (priorRow as { tagline?: string }).tagline !== manifest.tagline ||
+    (priorRow as { stripPrefix?: boolean }).stripPrefix !== manifest.stripPrefix;
+
+  try {
+    upsertImpl(entry);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    warn(`[self-register] services.json write failed: ${msg}`);
+    return { status: "failed", reason: msg };
+  }
+
+  if (changed) {
+    log(`[self-register] registered ${manifest.manifestName} (installDir=${installDir})`);
+  } else {
+    log(`[self-register] already registered ${manifest.manifestName} (no changes)`);
+  }
+  return { status: "registered", installDir, changed };
+}

package/src/server.ts

@@ -24,12 +24,17 @@ import { defaultHookRegistry } from "../core/src/hooks.ts";
 import { registerTriggers } from "./triggers.ts";
 import { route } from "./routing.ts";
 import { startTranscriptionWorker, registerTranscriptionHook, type TranscriptionWorker } from "./transcription-worker.ts";
+import { setTranscriptionWorker } from "./transcription-registry.ts";
 import { assetsDir } from "./routes.ts";
-import { resolveScribeAuthToken } from "./scribe-env.ts";
+import { resolveScribeAuthToken, ensureScribeBearer } from "./scribe-env.ts";
+import { getCachedScribeUrl } from "./scribe-discovery.ts";
+import { readEnvFile, setEnvVar } from "./config.ts";
 import { resolveBindHostname } from "./bind.ts";
 import { MirrorManager } from "./mirror-manager.ts";
 import { setMirrorManager } from "./mirror-registry.ts";
 import { buildMirrorDeps, resolveMirrorVaultName } from "./mirror-deps.ts";
+import { selfRegister } from "./self-register.ts";
+import pkg from "../package.json" with { type: "json" };
 
 // Register webhook triggers from global config. Replaces the old hardcoded
 // tts-hook and transcription-hook with config-driven webhooks.
@@ -47,8 +52,9 @@ function registerConfiguredTriggers(): void {
   // both will process the same attachments. The trigger's `missing_metadata`
   // guard keeps it idempotent once the worker marks `transcript` on the
   // attachment, but the noise is worth flagging.
-  if (process.env.SCRIBE_URL) {
-    const scribeHost = safeHost(process.env.SCRIBE_URL);
+  const probedScribeUrl = getCachedScribeUrl();
+  if (probedScribeUrl) {
+    const scribeHost = safeHost(probedScribeUrl);
     for (const t of config.triggers) {
       if (t.action.send !== "attachment") continue;
       if (scribeHost && safeHost(t.action.webhook) === scribeHost) {
@@ -74,17 +80,35 @@ loadEnvFile();
 registerConfiguredTriggers();
 
 /**
- * Start the transcription worker if SCRIBE_URL is configured. The worker
- * polls every vault for attachments with `metadata.transcribe_status = "pending"`
- * and sends the audio to scribe. Absent SCRIBE_URL, the worker stays off
- * — `{transcribe: true}` uploads still enqueue, they just wait.
+ * Start the transcription worker if scribe is discoverable. Scribe URL
+ * resolution order (per `scribe-discovery.ts`): `SCRIBE_URL` env var, then
+ * `~/.parachute/services.json` `parachute-scribe` entry, then nothing.
+ *
+ * Bearer generation (vault#353): if neither `SCRIBE_AUTH_TOKEN` nor the
+ * legacy `SCRIBE_TOKEN` is set, generate a fresh 32-byte base64url bearer
+ * and persist it to vault's `.env` so subsequent restarts use the same
+ * value. Idempotent — calls after the first see the existing token. The
+ * operator (or hub install) is expected to mirror this bearer to scribe's
+ * `SCRIBE_AUTH_TOKEN`; without that mirror, scribe will reject the
+ * Authorization header on a 401 and transcription fails with a friendly
+ * error captured on the transcript note.
  */
+const scribeUrl = getCachedScribeUrl();
 let transcriptionWorker: TranscriptionWorker | null = null;
-if (process.env.SCRIBE_URL) {
+if (scribeUrl) {
+  // Generate + persist the shared bearer on first boot. Subsequent boots
+  // pick up the existing value and don't rotate. Loading the .env back
+  // into process.env happens above (`loadEnvFile()`); we re-load here to
+  // pick up the just-written value without restart.
+  const { created, token } = ensureScribeBearer(readEnvFile, setEnvVar);
+  if (created) {
+    process.env.SCRIBE_AUTH_TOKEN = token;
+    console.log("[transcribe] generated SCRIBE_AUTH_TOKEN (32 bytes, base64url) — mirror this value into scribe's config");
+  }
   transcriptionWorker = startTranscriptionWorker({
     vaultList: () => listVaults(),
     getStore: (name) => getVaultStore(name),
-    scribeUrl: process.env.SCRIBE_URL,
+    scribeUrl,
     scribeToken: resolveScribeAuthToken(),
     resolveAssetsDir: (vault) => assetsDir(vault),
     getAudioRetention: (vault) => readVaultConfig(vault)?.audio_retention ?? "keep",
@@ -97,9 +121,12 @@ if (process.env.SCRIBE_URL) {
     transcriptionWorker,
     (store) => getVaultNameForStore(store as never),
   );
-  console.log(`[transcribe] worker started → ${process.env.SCRIBE_URL}`);
+  // Expose the worker to the REST retry endpoint so retries kick immediately
+  // instead of waiting for the sweep. Idempotent on second boot.
+  setTranscriptionWorker(transcriptionWorker);
+  console.log(`[transcribe] worker started → ${scribeUrl}`);
 } else {
-  console.log("[transcribe] worker disabled (set SCRIBE_URL to enable)");
+  console.log("[transcribe] worker disabled (no scribe in services.json and SCRIBE_URL unset)");
 }
 
 if (process.env.VAULT_AUTH_TOKEN?.trim()) {
@@ -151,6 +178,14 @@ if (listVaults().length === 0) {
   }
 }
 
+// vault#266 — self-register manifest + installDir into services.json so
+// hub's discovery / admin SPA can find vault without a `parachute install
+// vault` round-trip. Idempotent (re-runs produce the same row when nothing
+// changed); never throws (boot must not fail on bookkeeping). The merge-
+// preserving `upsertService` ensures any hub-stamped fields on the row
+// survive — see self-register.ts header for the v0.6 vs v0.7 design note.
+selfRegister({ version: pkg.version });
+
 // Migrate tag schemas from vault.yaml → DB for each vault.
 // Only inserts schemas that don't already exist in the DB (safe across restarts).
 for (const vaultName of listVaults()) {

package/src/transcript-note.test.ts

@@ -0,0 +1,171 @@
+/**
+ * Tests for vault transcript-note materialization (vault#353).
+ *
+ * Covers two surfaces:
+ *   - `buildTranscriptNote` — pure, frontmatter shape per design Q3.
+ *   - `upsertTranscriptNote` — DB-backed, create + retry-update flow.
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { mkdirSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { BunStore } from "./vault-store.ts";
+import { buildTranscriptNote, transcriptPathFor, upsertTranscriptNote } from "./transcript-note.ts";
+
+let db: Database;
+let store: BunStore;
+let tmpDir: string;
+
+beforeEach(() => {
+  tmpDir = join(tmpdir(), `transcript-note-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(tmpDir, { recursive: true });
+  db = new Database(join(tmpDir, "test.db"));
+  store = new BunStore(db);
+});
+
+afterEach(() => {
+  db.close();
+  rmSync(tmpDir, { recursive: true, force: true });
+});
+
+describe("transcriptPathFor", () => {
+  test("appends `.transcript` to the audio path", () => {
+    expect(transcriptPathFor("inbox/2026-05-21.m4a")).toBe("inbox/2026-05-21.m4a.transcript");
+  });
+
+  test("handles nested paths", () => {
+    expect(transcriptPathFor("a/b/c/voice.webm")).toBe("a/b/c/voice.webm.transcript");
+  });
+});
+
+describe("buildTranscriptNote — success shape", () => {
+  test("frontmatter includes transcript_of, status, attachment id, duration, and provider", () => {
+    const result = buildTranscriptNote({
+      attachmentPath: "inbox/voice.webm",
+      attachmentId: "att-1",
+      attachmentNoteId: "note-1",
+      status: "complete",
+      text: "hello world",
+      provider: "groq",
+      durationMs: 1234,
+      createdAt: new Date("2026-05-21T09:13:42Z"),
+    });
+    expect(result.path).toBe("inbox/voice.webm.transcript");
+    expect(result.content).toBe("hello world");
+    expect(result.tags).toEqual(["transcript", "capture"]);
+    expect(result.metadata.transcript_of).toBe("inbox/voice.webm");
+    expect(result.metadata.transcript_attachment_id).toBe("att-1");
+    expect(result.metadata.transcript_status).toBe("complete");
+    expect(result.metadata.transcript_provider).toBe("groq");
+    expect(result.metadata.transcript_duration_ms).toBe(1234);
+    expect(result.metadata.title).toBe("Transcript of voice.webm");
+    expect(result.createdAt).toBe("2026-05-21T09:13:42.000Z");
+    expect(result.metadata.transcript_error).toBeUndefined();
+  });
+
+  test("provider/duration omitted when not supplied", () => {
+    const result = buildTranscriptNote({
+      attachmentPath: "voice.m4a",
+      attachmentId: "att-x",
+      attachmentNoteId: "note-x",
+      status: "complete",
+      text: "no provider info",
+    });
+    expect(result.metadata.transcript_provider).toBeUndefined();
+    expect(result.metadata.transcript_duration_ms).toBeUndefined();
+  });
+});
+
+describe("buildTranscriptNote — failure shape", () => {
+  test("body is empty + transcript_error captured", () => {
+    const result = buildTranscriptNote({
+      attachmentPath: "inbox/voice.webm",
+      attachmentId: "att-1",
+      attachmentNoteId: "note-1",
+      status: "failed",
+      error: "no transcription provider configured",
+    });
+    expect(result.content).toBe("");
+    expect(result.metadata.transcript_status).toBe("failed");
+    expect(result.metadata.transcript_error).toBe("no transcription provider configured");
+  });
+
+  test("falls back to 'unknown error' when no error string is supplied", () => {
+    const result = buildTranscriptNote({
+      attachmentPath: "voice.m4a",
+      attachmentId: "att-1",
+      attachmentNoteId: "note-1",
+      status: "failed",
+    });
+    expect(result.metadata.transcript_error).toBe("unknown error");
+  });
+});
+
+describe("upsertTranscriptNote", () => {
+  test("creates a new note + link on first call", async () => {
+    const audioOwner = await store.createNote("# Voice memo\n", { id: "owner" });
+    await store.addAttachment(audioOwner.id, "memos/a.webm", "audio/webm");
+
+    const note = await upsertTranscriptNote(store, {
+      attachmentPath: "memos/a.webm",
+      attachmentId: "att-1",
+      attachmentNoteId: audioOwner.id,
+      status: "complete",
+      text: "spoken words",
+      provider: "groq",
+      durationMs: 999,
+    });
+    expect(note.content).toBe("spoken words");
+    expect(note.path).toBe("memos/a.webm.transcript");
+
+    const fetched = await store.getNoteByPath("memos/a.webm.transcript");
+    expect(fetched?.id).toBe(note.id);
+    expect((fetched?.metadata as any)?.transcript_status).toBe("complete");
+    expect(fetched?.tags).toContain("transcript");
+    expect(fetched?.tags).toContain("capture");
+  });
+
+  test("overwrites existing transcript note in place on retry (id preserved)", async () => {
+    const owner = await store.createNote("# Voice memo\n", { id: "owner-2" });
+    await store.addAttachment(owner.id, "memos/b.webm", "audio/webm");
+
+    const first = await upsertTranscriptNote(store, {
+      attachmentPath: "memos/b.webm",
+      attachmentId: "att-2",
+      attachmentNoteId: owner.id,
+      status: "failed",
+      error: "no transcription provider configured",
+    });
+    expect(first.content).toBe("");
+
+    const retried = await upsertTranscriptNote(store, {
+      attachmentPath: "memos/b.webm",
+      attachmentId: "att-2",
+      attachmentNoteId: owner.id,
+      status: "complete",
+      text: "transcript that finally landed",
+      durationMs: 500,
+    });
+    expect(retried.id).toBe(first.id);
+    expect(retried.content).toBe("transcript that finally landed");
+    expect((retried.metadata as any)?.transcript_status).toBe("complete");
+    expect((retried.metadata as any)?.transcript_error).toBeUndefined();
+  });
+
+  test("attempting to upsert when the attachmentNoteId is missing still creates the note (link skipped)", async () => {
+    // No owner note created — the link create will throw or silently skip;
+    // either way the transcript note must still land so the failure has
+    // a visible record. (Defensive: a deleted-attachment race.)
+    const note = await upsertTranscriptNote(store, {
+      attachmentPath: "missing/a.webm",
+      attachmentId: "att-x",
+      attachmentNoteId: "nonexistent-note",
+      status: "failed",
+      error: "audio file not found",
+    });
+    expect(note.path).toBe("missing/a.webm.transcript");
+    expect((note.metadata as any)?.transcript_status).toBe("failed");
+  });
+});