@crouton-kit/capture 1.3.3 → 1.3.5

package/src/vault/docs.ts

@@ -0,0 +1,224 @@
+/**
+ * vault/docs — on-demand library doc generation + sha-keyed cache.
+ *
+ * Reimplements vault's `generateDocs` (northlight-vault
+ * lib-pipeline/build/build-libs.ts:138-184) in-process, dropping the
+ * manifest/sha/scripts half: for a lib we esbuild-bundle its `schemas.ts` to a
+ * self-contained CJS string (zod inlined from node_modules by `bundle:true`),
+ * evaluate it in-memory, then convert each function's Zod input/output to JSON
+ * Schema (Zod-4-native `toJSONSchema()`, with the `void` special-case ported
+ * verbatim). Results are cached gitignored under `vault/.cache/docs/<svc>.json`
+ * with an embedded `_srcSha` = sha256(schemas.ts); a stale/missing sha rebuilds.
+ *
+ * Nothing here imports `esbuild` at the top level — it is loaded lazily via
+ * `loadEsbuild()` so the published package (no `vault/`, no `esbuild`) degrades
+ * to a single `DEV_ONLY_MSG` instead of crashing.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import { createHash } from "crypto";
+import {
+  vaultLibsDir,
+  vaultRepoRoot,
+  listLibs,
+  loadEsbuild,
+  isValidLibName,
+  unknownLibMsg,
+} from "./paths.js";
+
+/** A single library function's doc entry (input/output are JSON Schema). */
+export interface LibraryDocFunction {
+  name: string;
+  description: string;
+  notes?: string;
+  input: unknown;
+  output: unknown;
+}
+
+/** A library's generated doc — same shape `nl lib read --json` returns. */
+export interface LibraryDoc {
+  /** `@vallum/<svc>` */
+  library: string;
+  description: string;
+  notes?: string;
+  loginUrl?: string;
+  /** `'public' | 'chat' | 'hidden'` (default `'public'`). */
+  visibility: string;
+  functions: LibraryDocFunction[];
+}
+
+/** Shape of each entry in a lib's `schemas.ts` exported `allSchemas` array. */
+interface FunctionSchema {
+  name: string;
+  description: string;
+  notes?: string;
+  input: unknown;
+  output: unknown;
+}
+
+/** Mirrors `nl lib`'s agent-visible filter (vault-client.service.ts:49). */
+const AGENT_VISIBLE_VISIBILITIES = new Set(["public", "chat"]);
+
+/** True iff a doc is agent-visible (visibility ∈ {public, chat}). */
+export function isAgentVisible(doc: LibraryDoc): boolean {
+  return AGENT_VISIBLE_VISIBILITIES.has(doc.visibility);
+}
+
+/**
+ * A `require` for the in-memory CJS eval below. zod is inlined by `bundle:true`
+ * so this is never actually hit — it's passed defensively. Ambient `require` is
+ * available under both the built CJS bin (native) and tsx-ESM (injected into a
+ * real module). We avoid `createRequire(import.meta.url)` because `import.meta`
+ * is empty under the CJS bin build (esbuild) and would throw at module load.
+ */
+declare const require: ((id: string) => unknown) | undefined;
+const cjsRequire = (id: string): unknown => {
+  if (typeof require === "function") return require(id);
+  throw new Error(`cannot require('${id}') — unavailable in this runtime`);
+};
+
+function cacheDir(): string {
+  return path.join(vaultRepoRoot(), ".cache", "docs");
+}
+
+function schemasPathFor(svc: string): string {
+  return path.join(vaultLibsDir(), svc, "schemas.ts");
+}
+
+function srcSha(svc: string): string {
+  return createHash("sha256")
+    .update(fs.readFileSync(schemasPathFor(svc), "utf8"))
+    .digest("hex");
+}
+
+/**
+ * Zod → JSON Schema, porting build-libs.ts:155-173 verbatim. `z.void()` has no
+ * JSON-Schema representation, so it maps to `{type:'null'}` (carrying its
+ * description if present); everything else uses Zod 4's `toJSONSchema()`.
+ */
+function toJsonSchema(zodSchema: unknown): unknown {
+  const s = zodSchema as {
+    _zod?: { def?: { type?: string } };
+    description?: string;
+    toJSONSchema?: () => unknown;
+  };
+  if (s?._zod?.def?.type === "void") {
+    const desc = s.description;
+    return desc ? { type: "null", description: desc } : { type: "null" };
+  }
+  if (!s?.toJSONSchema) {
+    throw new Error(
+      "Schema missing toJSONSchema method - ensure Zod 4+ is installed",
+    );
+  }
+  return s.toJSONSchema();
+}
+
+/**
+ * Build one lib's doc from source: esbuild-bundle its `schemas.ts` to a
+ * self-contained CJS string, eval it in-memory, assemble the `LibraryDoc`.
+ */
+async function buildDoc(svc: string): Promise<LibraryDoc> {
+  const esbuild = await loadEsbuild();
+  const result = await esbuild.build({
+    entryPoints: [schemasPathFor(svc)],
+    bundle: true,
+    write: false,
+    format: "cjs",
+    platform: "node",
+    target: "es2020",
+    logLevel: "silent",
+  });
+  const text = result.outputFiles?.[0]?.text;
+  if (!text) throw new Error(`esbuild produced no output for ${svc}/schemas.ts`);
+
+  // In-memory CJS eval (no temp file). zod is inlined by bundle:true, so the
+  // `require` arg is never actually hit — passed defensively for any edge.
+  const mod = { exports: {} as Record<string, unknown> };
+  new Function("module", "exports", "require", text)(
+    mod,
+    mod.exports,
+    cjsRequire,
+  );
+  const x = mod.exports as {
+    allSchemas?: FunctionSchema[];
+    libraryDescription?: string;
+    libraryNotes?: string;
+    loginUrl?: string;
+    libraryVisibility?: string;
+  };
+
+  const allSchemas = x.allSchemas ?? [];
+  const doc: LibraryDoc = {
+    library: `@vallum/${svc}`,
+    description: x.libraryDescription ?? `${svc} service library`,
+    visibility: x.libraryVisibility ?? "public",
+    functions: allSchemas.map((schema) => ({
+      name: schema.name,
+      description: schema.description,
+      ...(schema.notes ? { notes: schema.notes } : {}),
+      input: toJsonSchema(schema.input),
+      output: toJsonSchema(schema.output),
+    })),
+  };
+  if (x.libraryNotes) doc.notes = x.libraryNotes;
+  if (x.loginUrl) doc.loginUrl = x.loginUrl;
+  return doc;
+}
+
+/**
+ * Get one lib's doc — reads the sha-valid cache if present, else (re)builds and
+ * writes it. May read ANY present lib (no visibility filter); used by
+ * `lib read`. Throws `Unknown lib …` if the named lib has no `schemas.ts`.
+ */
+export async function getDoc(name: string): Promise<LibraryDoc> {
+  if (!isValidLibName(name) || !fs.existsSync(schemasPathFor(name))) {
+    throw new Error(unknownLibMsg(name));
+  }
+  const sha = srcSha(name);
+  const cacheFile = path.join(cacheDir(), `${name}.json`);
+  if (fs.existsSync(cacheFile)) {
+    try {
+      const cached = JSON.parse(fs.readFileSync(cacheFile, "utf8")) as
+        & LibraryDoc
+        & { _srcSha?: string };
+      if (cached._srcSha === sha) {
+        delete cached._srcSha;
+        return cached;
+      }
+    } catch {
+      // corrupt/unreadable cache → fall through and rebuild
+    }
+  }
+  const doc = await buildDoc(name);
+  fs.mkdirSync(cacheDir(), { recursive: true });
+  fs.writeFileSync(
+    cacheFile,
+    JSON.stringify({ ...doc, _srcSha: sha }, null, 2),
+  );
+  return doc;
+}
+
+/**
+ * All agent-visible libs' docs (visibility ∈ {public, chat}). Lazily builds any
+ * missing/stale doc, then filters by visibility. A lib whose `schemas.ts` fails
+ * to build is skipped with a stderr warning rather than failing the whole list.
+ * Used by `lib list`/`search`/`show`.
+ */
+export async function listDocs(): Promise<LibraryDoc[]> {
+  const out: LibraryDoc[] = [];
+  for (const name of listLibs()) {
+    let doc: LibraryDoc;
+    try {
+      doc = await getDoc(name);
+    } catch (e) {
+      console.error(
+        `WARN: skipping lib "${name}" — ${(e as Error).message}`,
+      );
+      continue;
+    }
+    if (isAgentVisible(doc)) out.push(doc);
+  }
+  return out;
+}

package/src/vault/paths.ts

@@ -0,0 +1,87 @@
+/**
+ * vault/paths — locate the forked vault lib source on disk + the dev-only guard.
+ *
+ * Shared foundation for the import-driven exec bundler (`bundle.ts`) and the
+ * on-demand doc generator (`docs.ts`). This module must NOT import `esbuild` at
+ * the top level — esbuild is loaded lazily (see `loadEsbuild`) so the published
+ * package (which ships neither `vault/` nor `esbuild`) never crashes at startup.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+
+/**
+ * The single dev-only degradation message. Thrown when `vault/libs` is missing
+ * (published package) or when `esbuild` cannot be loaded. (design §2.6, verbatim)
+ */
+export const DEV_ONLY_MSG =
+  "This is a dev-only feature of capture — run it from a capture checkout\n" +
+  "(vault/ source + `pnpm install`). Not available in the published package.";
+
+/**
+ * Absolute path to the forked `vault/libs` directory. Dual `__dirname`
+ * candidates cover the built bin (`bin/../vault/libs`) and tsx dev
+ * (`src/vault/../../vault/libs`) — mirrors the `__dirname`+`..` precedent in
+ * `capture.ts`. Throws `DEV_ONLY_MSG` if neither candidate holds the source.
+ */
+export function vaultLibsDir(): string {
+  const candidates = [
+    path.resolve(__dirname, "..", "vault", "libs"), // built bin: bin/../vault/libs
+    path.resolve(__dirname, "..", "..", "vault", "libs"), // tsx dev: src/vault/../../vault/libs
+  ];
+  const hit = candidates.find((p) =>
+    fs.existsSync(path.join(p, "_runtime", "index.ts"))
+  );
+  if (!hit) throw new Error(DEV_ONLY_MSG);
+  return hit;
+}
+
+/**
+ * The `vault/` directory (parent of `vault/libs`). Used as esbuild's
+ * `resolveDir` so its native node-resolution finds `node_modules/zod` etc.
+ */
+export function vaultRepoRoot(): string {
+  return path.dirname(vaultLibsDir());
+}
+
+/**
+ * Sorted list of available lib names — directories under `vault/libs`,
+ * excluding `_`-prefixed internal dirs (e.g. `_runtime`). Used by the
+ * resolver's "Available: …" error and by the docs/lib surfaces.
+ */
+export function listLibs(): string[] {
+  return fs
+    .readdirSync(vaultLibsDir(), { withFileTypes: true })
+    .filter((e) => e.isDirectory() && !e.name.startsWith("_"))
+    .map((e) => e.name)
+    .sort();
+}
+
+/**
+ * The friendly "Unknown lib" message, shared by the exec resolver/preflight
+ * (`bundle.ts`) and the doc generator (`docs.ts`) so an unknown OR malformed
+ * lib name surfaces byte-identical text everywhere.
+ */
+export function unknownLibMsg(name: string): string {
+  return `Unknown lib "${name}". Available: ${listLibs().join(", ")}`;
+}
+
+// A lib name is a single path segment of `[A-Za-z0-9_.-]` (covers `hunter.io`)
+// with no `..`. Rejects path separators / traversal (`libs/../x`, `libs/a/b`)
+// before a name reaches `path.join`/esbuild — defense-in-depth (exec already
+// runs arbitrary JS, so this only buys a clearer error, not isolation).
+const VALID_LIB_NAME = /^[A-Za-z0-9_.-]+$/;
+export function isValidLibName(name: string): boolean {
+  return VALID_LIB_NAME.test(name) && !name.includes("..");
+}
+
+/**
+ * Lazily load `esbuild`. Kept here so both `bundle.ts` and `docs.ts` share one
+ * lazy loader and the top-level module never statically imports esbuild — a
+ * published install (no esbuild) only fails when the feature path is exercised.
+ */
+export async function loadEsbuild(): Promise<typeof import("esbuild")> {
+  return await import("esbuild").catch(() => {
+    throw new Error(DEV_ONLY_MSG);
+  });
+}