@bragi-gmbh/codebus 1.3.0 → 1.6.0

package/dist/commands/doc.js

@@ -0,0 +1,276 @@
+/**
+ * doc.ts — shared documents on the bus (CB-DOC-…).
+ *
+ * `codebus doc add` stores a text document in the 0035 artifacts registry via
+ * the 0087 `artifact_add` write boundary (membership-gated, producer pinned,
+ * title/body/2MiB/kind validated server-side with typed errors). Every doc
+ * gets a CB-DOC-… display id, which cli/src/commands/refs.ts already accepts
+ * as a typed ref (`--ref CB-DOC-…[@sha]` on send/task) — that is what makes a
+ * stored doc "attached to the graph": any message or task can cite it as
+ * evidence and `codebus resolve-refs` resolves it back.
+ *
+ * Text-only for now (matching artifacts.body being a text column): `doc add`
+ * reads the file as UTF-8 and rejects binary content (NUL-byte probe) and
+ * anything over the 2 MiB cap CLIENT-side with a clear message, so the common
+ * failure never even leaves the machine — the RPC re-checks both anyway
+ * (plus the kind vocabulary, where the server stays the single authority so
+ * the list can't drift between here and 0087).
+ *
+ * Cores are exported for the MCP tools (doc_add / doc_get) — one shared core,
+ * dumb clients, per house pattern (see decision.ts / send.ts).
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { basename } from "node:path";
+import { resolveConfig } from "../config.js";
+import { makeCtx, workspaceId } from "../client.js";
+import { render } from "../output.js";
+import { CodebusError } from "../errors.js";
+import { senderDisplay } from "../sender.js";
+/** 2 MiB, in bytes — MUST match artifact_add's own cap (0087). */
+export const DOC_BODY_MAX_BYTES = 2 * 1024 * 1024;
+/**
+ * The doc kind vocabulary (taxonomy.v1.json product.artifact_kind). Used for
+ * help text and as `doc list`'s default filter; the WRITE-side authority is
+ * artifact_add itself (0087) — the CLI never pre-rejects a kind, so the two
+ * lists cannot disagree about what is storable.
+ */
+export const DOC_KINDS = ["note", "doc", "spec", "plan", "review", "deck"];
+/**
+ * Producer resolved the same way message senders are (sender.ts): alias the
+ * embed to `agents` so senderDisplay() works unchanged — a HUMAN producer
+ * shows their person slug, a machine agent its agent slug. The explicit
+ * `!person_id` FK hint is required (agents has two FKs to people, 0040).
+ */
+const PRODUCER_EMBED = "agents:producer_agent_id(slug, person:people!person_id(slug))";
+/**
+ * Shared core: store a document via the artifact_add write boundary.
+ * Exported for reuse in the MCP doc_add tool.
+ */
+export async function addDocCore(ctx, opts) {
+    // The same one-rule invariant validateDocBody enforces for the CLI (sol
+    // round-2 finding 1), held HERE too so the MCP doc_add path — which never
+    // goes through argv or a file read — cannot store what the CLI refuses:
+    // no U+FFFD in stored docs (v1 limitation; see validateDocBody).
+    if (opts.body.includes("�")) {
+        throw new CodebusError("doc add: body contains the Unicode replacement character (U+FFFD) — stored docs may not " +
+            "contain it (v1 limitation: it is indistinguishable from encoding corruption); remove it, " +
+            "or store the content externally and cite it as a typed ref (path:<repo>/<file> or commit:<sha>)");
+    }
+    const ws = await workspaceId(ctx);
+    const { data, error } = await ctx.supabase.rpc("artifact_add", {
+        p_workspace_id: ws,
+        p_title: opts.title,
+        p_body: opts.body,
+        p_kind: opts.kind ?? "doc",
+    });
+    if (error)
+        throw new CodebusError(error.message);
+    const row = data;
+    return { display_id: row.display_id, kind: row.kind, title: row.title, id: row.id, created_at: row.created_at };
+}
+/**
+ * Shared core: fetch one document (body included) by CB-DOC-… or uuid.
+ * Display ids are only unique per workspace (bus_counters, 0004), so the
+ * display_id lookup is workspace-scoped — same rule as decision.ts.
+ * A trailing @sha ref pin is tolerated and stripped, so an id copied
+ * verbatim out of `resolve-refs` output just works.
+ */
+export async function getDocCore(ctx, idOrDisplay) {
+    const bare = idOrDisplay.replace(/@[0-9a-f]{7,40}$/i, "");
+    const isDisplay = /^CB-DOC-/i.test(bare);
+    let q = ctx.supabase.from("artifacts").select(`id, display_id, kind, title, body, created_at, ${PRODUCER_EMBED}`);
+    q = isDisplay
+        ? q.eq("display_id", bare.toUpperCase()).eq("workspace_id", await workspaceId(ctx))
+        : q.eq("id", bare);
+    const { data, error } = await q.single();
+    if (error || !data) {
+        throw new CodebusError(`doc not found (or not a member of its workspace): ${idOrDisplay}`);
+    }
+    const row = data;
+    return {
+        id: String(row.id),
+        display_id: String(row.display_id),
+        kind: String(row.kind ?? ""),
+        title: String(row.title),
+        body: String(row.body ?? ""),
+        producer: senderDisplay(row),
+        created_at: String(row.created_at),
+    };
+}
+/**
+ * Shared core: list documents in the workspace, newest first.
+ * Defaults to the doc vocabulary so registry-internal artifacts (e.g. the
+ * graph-snapshot rows graph-bootstrap writes) don't drown the listing;
+ * --kind narrows to one kind (any value — the column is open vocabulary).
+ */
+export async function listDocsCore(ctx, opts = {}) {
+    const ws = await workspaceId(ctx);
+    let q = ctx.supabase.from("artifacts")
+        .select(`id, display_id, kind, title, created_at, ${PRODUCER_EMBED}`)
+        .eq("workspace_id", ws)
+        .order("created_at", { ascending: false });
+    q = opts.kind ? q.eq("kind", opts.kind) : q.in("kind", DOC_KINDS);
+    const { data, error } = await q;
+    if (error)
+        throw new CodebusError(error.message);
+    return (data ?? []).map((r) => {
+        const row = r;
+        return {
+            id: String(row.id),
+            display_id: String(row.display_id),
+            kind: String(row.kind ?? ""),
+            title: String(row.title),
+            producer: senderDisplay(row),
+            created_at: String(row.created_at),
+        };
+    });
+}
+/**
+ * Client-side body validation for `doc add` — fails fast with a clearer
+ * message than a round-trip would, for the rules a local check can decide
+ * (size cap, binary content, UTF-8 validity). Exported for unit tests.
+ *
+ * Decoding is FATAL (sol round-1 finding 1): Buffer.toString("utf8") would
+ * silently replace malformed byte sequences with U+FFFD, so a mis-encoded
+ * file (latin-1, UTF-16, …) would upload CORRUPTED with nobody the wiser —
+ * the exact opposite of the "we both see the same file" contract. A file
+ * that does not decode cleanly as UTF-8 is rejected loudly instead.
+ */
+export function validateDocBody(buf, source) {
+    if (buf.length === 0) {
+        throw new CodebusError(`doc add: ${source} is empty — a doc with no content cannot be shared`);
+    }
+    if (buf.length > DOC_BODY_MAX_BYTES) {
+        throw new CodebusError(`doc add: ${source} is ${buf.length} bytes, over the 2 MiB (${DOC_BODY_MAX_BYTES} byte) cap — ` +
+            `store large files externally and cite them as typed refs instead (path:<repo>/<file> or commit:<sha> on a message/task)`);
+    }
+    if (buf.includes(0)) {
+        throw new CodebusError(`doc add: ${source} looks binary (contains NUL bytes) — doc storage is text-only for now; ` +
+            `store the file externally and cite it as a typed ref instead (path:<repo>/<file> or commit:<sha>)`);
+    }
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(buf);
+    }
+    catch {
+        throw new CodebusError(`doc add: ${source} is not valid UTF-8 — doc storage is text-only for now; re-encode it ` +
+            `(e.g. iconv -t UTF-8) or store the file externally and cite it as a typed ref instead ` +
+            `(path:<repo>/<file> or commit:<sha>)`);
+    }
+    // Sol round-2 finding 1: the fatal decoder cannot protect the --body path —
+    // Node has already converted malformed argv bytes to U+FFFD before we ever
+    // see the string, and our own re-encode makes those replacement characters
+    // VALID UTF-8. So the rule is on the DECODED text: no U+FFFD in stored
+    // docs, either path (v1 limitation — a legitimate replacement character is
+    // indistinguishable from encoding corruption at this point).
+    if (text.includes("�")) {
+        throw new CodebusError(source === "--body"
+            ? `doc add: body contains the Unicode replacement character (�) — the shell likely ` +
+                `mangled a non-UTF-8 byte before it reached us; put the content in a file and use ` +
+                `doc add <file> instead`
+            : `doc add: ${source} contains the Unicode replacement character (U+FFFD) — stored docs ` +
+                `may not contain it (v1 limitation: at this point it is indistinguishable from encoding ` +
+                `corruption); remove it, or store the file externally and cite it as a typed ref ` +
+                `(path:<repo>/<file> or commit:<sha>)`);
+    }
+    return text;
+}
+/**
+ * Write a fetched doc body to `out` for `doc get --out`. Refuses to clobber
+ * an existing file unless `force` (sol round-1 finding 3: silent truncation
+ * of whatever already lived at that path is exactly the kind of data loss a
+ * "download" flag must not default to). The refusal is ATOMIC (sol round-2
+ * finding 2): no exists-then-open window — the file is opened with exclusive
+ * creation (O_CREAT|O_EXCL via flag "wx"), so a race or a symlink swapped in
+ * between a check and the write cannot make us truncate it; O_EXCL also
+ * refuses any symlink at the path, dangling or not. Exported for unit tests.
+ */
+export function writeDocBodyToFile(out, body, force) {
+    if (force) {
+        writeFileSync(out, body, "utf8");
+        return;
+    }
+    try {
+        writeFileSync(out, body, { encoding: "utf8", flag: "wx" });
+    }
+    catch (e) {
+        if (e.code === "EEXIST") {
+            throw new CodebusError(`doc get: ${out} already exists — pass --force to overwrite it`);
+        }
+        throw e;
+    }
+}
+async function addDoc(file, o) {
+    if (file && o.body !== undefined) {
+        throw new CodebusError("doc add: pass EITHER a file argument OR --body, not both");
+    }
+    let title;
+    let body;
+    if (file) {
+        let buf;
+        try {
+            buf = readFileSync(file);
+        }
+        catch (e) {
+            throw new CodebusError(`doc add: cannot read ${file}: ${e.message}`);
+        }
+        body = validateDocBody(buf, file);
+        title = o.title ?? basename(file);
+    }
+    else {
+        if (o.body === undefined) {
+            throw new CodebusError("doc add: provide a file argument, or --body \"<text>\" with --title");
+        }
+        if (!o.title) {
+            throw new CodebusError("doc add: --body requires --title (there is no file name to default it from)");
+        }
+        body = validateDocBody(Buffer.from(o.body, "utf8"), "--body");
+        title = o.title;
+    }
+    const ctx = await makeCtx(resolveConfig(o));
+    const r = await addDocCore(ctx, { title, body, kind: o.kind });
+    console.log(render([{ display_id: r.display_id, kind: r.kind, title: r.title }], { json: !!o.json }));
+}
+async function getDoc(id, o) {
+    const ctx = await makeCtx(resolveConfig(o));
+    const doc = await getDocCore(ctx, id);
+    if (o.out) {
+        writeDocBodyToFile(o.out, doc.body, !!o.force);
+        const meta = { display_id: doc.display_id, kind: doc.kind, title: doc.title, bytes: Buffer.byteLength(doc.body, "utf8"), out: o.out };
+        console.log(render([meta], { json: !!o.json }));
+        return;
+    }
+    if (o.json) {
+        console.log(JSON.stringify(doc, null, 2));
+        return;
+    }
+    // Plain mode prints the BODY only — and EXACTLY the body: stdout.write,
+    // not console.log, so `codebus doc get CB-DOC-… > f.md` is byte-identical
+    // to what was stored, including for a body with no trailing newline (sol
+    // round-1 finding 2). Metadata lives behind --json / doc list.
+    process.stdout.write(doc.body);
+}
+async function listDocs(o) {
+    const ctx = await makeCtx(resolveConfig(o));
+    const rows = await listDocsCore(ctx, { kind: o.kind });
+    console.log(render(rows.map((r) => ({ display_id: r.display_id, kind: r.kind, title: r.title, producer: r.producer, created_at: r.created_at })), { json: !!o.json }));
+}
+export function registerDoc(program, g) {
+    const doc = program.command("doc").description("shared documents (CB-DOC-…) — stored on the bus, citable as --ref evidence");
+    g(doc.command("add").argument("[file]", "UTF-8 text file to store (≤ 2 MiB)"))
+        .description("store a document; returns its CB-DOC-… id")
+        .option("--title <t>", "doc title (defaults to the file name)")
+        .option("--kind <k>", `${DOC_KINDS.join("|")}`, "doc")
+        .option("--body <text>", "inline body instead of a file (requires --title)")
+        .action(addDoc);
+    g(doc.command("get").argument("<id>", "CB-DOC-… display id or uuid"))
+        .description("print a document's body (or write it with --out; --json for the full row)")
+        .option("--out <file>", "write the body to a file instead of stdout (refuses to overwrite without --force)")
+        .option("--force", "overwrite an existing --out file")
+        .action((id, o) => getDoc(id, o));
+    g(doc.command("list"))
+        .description("list shared documents in the workspace, newest first")
+        .option("--kind <k>", "filter to one kind")
+        .action(listDocs);
+}
+//# sourceMappingURL=doc.js.map

package/dist/commands/doc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc.js","sourceRoot":"","sources":["../../src/commands/doc.ts"],"names":[],"mappings":"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"}

package/dist/commands/factory-attention.js

@@ -0,0 +1,106 @@
+/**
+ * Console attention view over CLI (`factory-attention`) — routes a single read
+ * through the attention_queue_v1(p_actor_login) RPC defined in 0109_attention_queue.sql.
+ *
+ * The projection yields six categories (ADR 0005: the console reads state over
+ * the API; each stuck/dead/over-cap/waiting-on-human item opens its details):
+ *   blocked-question  execution reported BLOCKED, waiting on a human answer
+ *   stalled           available non-terminal execution with a stale heartbeat
+ *   dead              terminal failed execution (ERROR/CANCELLED/INCOMPLETE) not resumed
+ *   over-cap          execution past its stage max_minutes cap (0098 deadline)
+ *   receipt-ruling    proposed decision awaiting a human ruling (0003/0104)
+ *   gate-approval     human plan gate to approve or release (0104/0107)
+ *
+ * Positive fixture: attention_queue_v1_returns_user_items
+ *   — calling attention_queue_v1(p_actor_login) for the accountable person
+ *     returns exactly the items they own/drive/rule on, scoped by RLS.
+ *
+ * Negative fixture: attention_returns_empty_for_other_user
+ *   — the same RPC called for a login that owns/drives/none of the items
+ *     returns zero rows (the actor_login filter narrows to the named person,
+ *     unknown logins yield nothing, never an error).
+ *
+ * Reusable core exported for tests and future MCP parity.
+ */
+import { resolveConfig } from "../config.js";
+import { makeCtx } from "../client.js";
+import { CodebusError } from "../errors.js";
+import { render } from "../output.js";
+/** Resolve the current agent's accountable person slug to use as the default
+ *  actor_login for attention_queue_v1. Falls back to null (the caller must
+ *  supply --login) since a service agent has no person of its own. Mirrors
+ *  whoami.ts's person-resolution shape. */
+export async function resolveActorLogin(ctx) {
+    const { data, error } = await ctx.supabase
+        .from("agents")
+        .select("people!person_id(id,slug)")
+        .eq("slug", ctx.agentSlug)
+        .single();
+    if (error)
+        throw new CodebusError(`unable to resolve actor identity: ${error.message}`);
+    const me = data?.people ?? null;
+    return me?.slug ?? null;
+}
+/** Shared core — calls the attention_queue_v1 RPC (positive fixture: returns
+ *  the named person's items; negative fixture: empty for another login). The
+ *  RPC itself enforces RLS + the actor_login scope, so no extra client-side
+ *  filtering is applied: the projection is authoritative. */
+export async function factoryAttentionCore(ctx, options) {
+    const actorLogin = options.login || (await resolveActorLogin(ctx));
+    if (!actorLogin) {
+        throw new CodebusError("no actor login available — pass --login <github-login-or-slug> (your accountable person)", 2);
+    }
+    const { data, error } = await ctx.supabase.rpc("attention_queue_v1", {
+        p_actor_login: actorLogin,
+    });
+    if (error)
+        throw new CodebusError(`attention_queue_v1 RPC failed: ${error.message}`);
+    const rows = (Array.isArray(data) ? data : []);
+    return rows;
+}
+function attentionHumanRow(item) {
+    const plural = (n) => n === null ? "—" : `${n}s`;
+    const ageLabel = item.age_seconds !== null && item.age_seconds !== undefined
+        ? `${Math.floor(item.age_seconds / 60)}m ${item.age_seconds % 60}s`
+        : "—";
+    return {
+        category: item.category,
+        severity: item.severity,
+        id: item.item_id.slice(0, 8),
+        plan: item.plan_id ? item.plan_id.slice(0, 8) : "—",
+        stage: item.stage_id ?? "—",
+        owner: item.owner_login ?? "—",
+        reason: (item.reason_or_question ?? "—").slice(0, 60),
+        age: ageLabel,
+        deadline: item.deadline
+            ? new Date(item.deadline).toLocaleString("en-US", {
+                month: "short", day: "numeric", hour: "2-digit", minute: "2-digit", timeZoneName: "short",
+            })
+            : "—",
+    };
+}
+const SEVERITY_ORDER = { critical: 0, high: 1, medium: 2, low: 3 };
+async function attentionCmd(login, o, command) {
+    const ctx = await makeCtx(resolveConfig(command.optsWithGlobals()));
+    const items = await factoryAttentionCore(ctx, { login: login ?? "" });
+    if (o.json) {
+        console.log(JSON.stringify(items, null, 2));
+        return;
+    }
+    if (items.length === 0) {
+        console.log("No attention items.");
+        return;
+    }
+    const sorted = [...items].sort((a, b) => (SEVERITY_ORDER[a.severity] ?? 9) - (SEVERITY_ORDER[b.severity] ?? 9) || a.category.localeCompare(b.category));
+    console.log(render(sorted.map(attentionHumanRow), { json: false }));
+}
+export function registerFactoryAttention(program, g) {
+    const factory = program.commands.find((c) => c.name() === "factory") ??
+        program.command("factory").description("coding factory intake");
+    g(factory.command("attention")
+        .description("console attention view: items needing a human (0109 attention_queue_v1)")
+        .argument("[login]", "GitHub login or person slug to project attention for (default: your agent's person)"))
+        .option("-j, --json", "render raw JSON rows")
+        .action(attentionCmd);
+}
+//# sourceMappingURL=factory-attention.js.map

package/dist/commands/factory-attention.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory-attention.js","sourceRoot":"","sources":["../../src/commands/factory-attention.ts"],"names":[],"mappings":"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"}

package/dist/commands/factory-context-read.js

@@ -0,0 +1,171 @@
+/**
+ * Factory context read command — versioned taxonomy, contracts, ADRs, specs, knowledge, repos, graphs.
+ *
+ * Shared core logic for CLI + MCP (A5: dumb client, one command core).
+ * Exported: `factoryContextReadCore(ctx, contentType?, repoSlug?)` for both paths.
+ * Auth: workspace-scoped via `makeCtx(resolveConfig({}))`.
+ * Contract: com.bragi.contract.factory-context-read-api@0.5.0-proposed + cli-mcp-parity.
+ * Parity pretest fixture: `identical_version_schema_auth_result_and_errors`.
+ * Negative fixture: `stale_local_taxonomy_or_transport_drift`.
+ */
+import { CodebusError } from "../errors.js";
+/**
+ * Core factory context read logic — shared by CLI and MCP handlers.
+ *
+ * Calls CodeBus versioned RPC (pending context-read-api migration 0131),
+ * validates schema, asserts no stale/local-copy fallback, returns versioned digest.
+ *
+ * Errors: thrown as CodebusError with message (used identically by CLI exit code and MCP error).
+ * Fixtures: positive = versioned_taxonomy_contract_ADR_spec_knowledge_repo_reads_with_RLS,
+ *           negative = direct_database_unversioned_or_local_copy_authority.
+ *
+ * @param ctx authenticated context with workspace/person scoping
+ * @param contentType what to read (default "taxonomy")
+ * @param repoSlug optional repo filter for repositories/graphs queries
+ * @throws CodebusError if content is stale, unversioned, or fetched from direct DB / local copy
+ */
+export async function factoryContextReadCore(ctx, contentType = "taxonomy", repoSlug) {
+    // Validate content type
+    const validTypes = [
+        "taxonomy",
+        "contracts",
+        "adrs",
+        "specs",
+        "knowledge",
+        "repositories",
+        "graphs",
+        "configuration",
+    ];
+    if (!validTypes.includes(contentType)) {
+        throw new CodebusError(`Invalid contentType '${contentType}'. Allowed: ${validTypes.join(", ")}`);
+    }
+    // Fix #6: graphs query REQUIRES repoSlug — enforce even when omitted (checked
+    // BEFORE the generic non-empty check so the message is contract-specific)
+    if (contentType === "graphs" && !repoSlug) {
+        throw new CodebusError("repoSlug is required for 'graphs' query");
+    }
+    // Validate repo slug format when provided (non-graphs types)
+    if (repoSlug !== undefined && (typeof repoSlug !== "string" || repoSlug.trim().length === 0)) {
+        throw new CodebusError("repoSlug must be a non-empty string or undefined");
+    }
+    try {
+        // RPC call (pending migration 0131: context_read_versioned RPC).
+        // For now, placeholder that demonstrates the pattern:
+        // Real implementation will query supabase RPC with auth scope.
+        // Actual RPC signature (TBD): context_read_versioned(p_content_type, p_repo_slug?, p_version?)
+        //   -> {version, content, schema_id, source, digest, created_at, authenticated, cascade}
+        // Negative case: if source='local_copy' or 'direct_database' → throw "direct_database_unversioned_or_local_copy_authority"
+        const rpcResult = await ctx.supabase?.rpc?.("context_read_versioned", {
+            p_content_type: contentType,
+            p_repo_slug: repoSlug || null,
+        });
+        if (!rpcResult) {
+            throw new CodebusError(`Failed to fetch ${contentType}${repoSlug ? ` for repo ${repoSlug}` : ""}: context-read-api RPC not ready (migration 0131)`);
+        }
+        // Fix #3: inspect error field — RPC failure must surface the actual transport/database error
+        if (rpcResult.error) {
+            throw new CodebusError(`context_read_versioned RPC failed for ${contentType}${repoSlug ? ` (repo ${repoSlug})` : ""}: ${rpcResult.error.message ?? String(rpcResult.error)}`);
+        }
+        // Negative: reject direct-database or local-copy sources
+        if (rpcResult.data?.source === "direct_database") {
+            throw new CodebusError("Rejected: direct_database query source violates schema (RLS required) — use a versioned ref ('<id>@<version>') or the bounded-cache path; see 'codebus factory-context-read <id>'.");
+        }
+        if (rpcResult.data?.source === "local_copy") {
+            throw new CodebusError("Rejected: local_copy source violates contract (no authoritative local copies)");
+        }
+        // Negative: reject unversioned content
+        if (!rpcResult.data?.version) {
+            throw new CodebusError(`Unversioned ${contentType} returned; contract requires versioned read`);
+        }
+        // Fix #4: digest is content SHA-256 used for cache/staleness. Missing digest
+        // means we cannot verify content — fail-closed instead of returning "unknown".
+        if (typeof rpcResult.data?.digest !== "string" || rpcResult.data.digest.length === 0) {
+            throw new CodebusError(`Missing or empty digest for ${contentType}; content cannot be verified as authoritative`);
+        }
+        // Fix #5: authenticated must come from the RPC's authorization metadata,
+        // not hard-coded. Only trust the response's authenticated flag.
+        const authenticated = Boolean(rpcResult.data?.authenticated);
+        if (!authenticated) {
+            throw new CodebusError(`Unauthorized or unauthenticated response for ${contentType}; RLS scoping required`);
+        }
+        // Build result
+        const result = {
+            version: rpcResult.data.version,
+            contentType,
+            repoSlug,
+            content: rpcResult.data.content,
+            digest: rpcResult.data.digest,
+            timestamp: rpcResult.data.created_at || new Date().toISOString(),
+            authenticated,
+            cached: rpcResult.data.source === "bounded_cache",
+        };
+        // Validate schema (placeholder for actual contract schema check)
+        if (!result.content) {
+            throw new CodebusError(`Empty content for ${contentType}: the contract artifact returned no body — re-run 'codebus factory-context-read <id>' after republishing the artifact.`);
+        }
+        return result;
+    }
+    catch (error) {
+        // Propagate as CodebusError (identical for CLI + MCP error paths)
+        if (error instanceof CodebusError) {
+            throw error;
+        }
+        throw new CodebusError(error instanceof Error
+            ? error.message
+            : `Unknown error fetching ${contentType}: ${String(error)}`);
+    }
+}
+/**
+ * CLI command registration (thin adapter over factoryContextReadCore).
+ * Reads ctx, calls core, renders result to console.
+ * Commander integration for CLI arg parsing.
+ */
+export async function registerFactoryContextRead(program) {
+    program
+        .command("factory-context-read")
+        .alias("fcr")
+        .description("Read versioned Factory context: taxonomy, contracts, ADRs, specs, knowledge, repos, graphs, configuration")
+        .option("-t, --type <contentType>", "Content type: taxonomy|contracts|adrs|specs|knowledge|repositories|graphs|configuration (default: taxonomy)", "taxonomy")
+        .option("-r, --repo <slug>", "Optional repo slug for repositories/graphs queries")
+        .option("-j, --json", "Output raw JSON")
+        .action(async (options) => {
+        try {
+            const contentType = (options.type || "taxonomy");
+            const { makeCtx } = await import("../client.js");
+            const { resolveConfig } = await import("../config.js");
+            const ctx = await makeCtx(resolveConfig({}));
+            const result = await factoryContextReadCore(ctx, contentType, options.repo);
+            if (options.json) {
+                console.log(JSON.stringify(result, null, 2));
+            }
+            else {
+                // Human-readable output
+                console.log(`Factory Context Read — ${contentType}`);
+                console.log(`Version: ${result.version}`);
+                console.log(`Timestamp: ${result.timestamp}`);
+                console.log(`Digest: ${result.digest}`);
+                if (result.repoSlug)
+                    console.log(`Repo: ${result.repoSlug}`);
+                if (result.cached)
+                    console.log("[Cached: bounded non-authoritative]");
+                console.log(`Content:\n${JSON.stringify(result.content, null, 2)}`);
+            }
+        }
+        catch (error) {
+            const message = error instanceof CodebusError
+                ? error.message
+                : error instanceof Error
+                    ? error.message
+                    : String(error);
+            console.error(`Error: ${message}`);
+            process.exit(1);
+        }
+    });
+}
+/**
+ * Export for use by mcp-factory-context-read.ts (MCP handler imports and calls this same core).
+ */
+export function createFactoryContextReadCLI(program) {
+    registerFactoryContextRead(program);
+}
+//# sourceMappingURL=factory-context-read.js.map

package/dist/commands/factory-context-read.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory-context-read.js","sourceRoot":"","sources":["../../src/commands/factory-context-read.ts"],"names":[],"mappings":"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"}