@fieldwork-ai/cli 0.16.0

package/dist/commands/automations.js

@@ -0,0 +1,178 @@
+import { api, apiJson, getContext, requireOrgId } from "../http.js";
+import { EXIT, confirm, exitCodeFor, fail, note, printData } from "../output.js";
+const TERMINAL_STATUSES = new Set(["succeeded", "failed"]);
+async function resolveAutomation(name) {
+    const body = await apiJson(`/api/organizations/${requireOrgId()}/automations?name=${encodeURIComponent(name)}`);
+    const automation = body.automations?.[0];
+    if (!automation)
+        fail(`no automation named "${name}"`, EXIT.notFound);
+    return automation;
+}
+async function fetchRuns(automationId, query) {
+    const body = await apiJson(`/api/organizations/${requireOrgId()}/automations/${automationId}/runs${query}`);
+    return body.runs ?? [];
+}
+function runStatusLine(run) {
+    const parts = [
+        `run ${run.automation_run_id}`,
+        run.status,
+        `triggered by ${run.source ?? "unknown"}`,
+        `created ${run.created_at}`,
+    ];
+    if (run.finished_at)
+        parts.push(`finished ${run.finished_at}`);
+    return parts.join(" · ");
+}
+/** Print one finished (or latest) run: status line to stderr, log tail to
+ * stdout. Exit code reflects the outcome; an in-flight run exits 0. */
+function printRun(run, json) {
+    if (json) {
+        printData(run, true);
+    }
+    else {
+        note(runStatusLine(run));
+        if (run.error)
+            note(`error: ${run.error}`);
+        if (run.log_tail)
+            printData(run.log_tail, false);
+    }
+    if (run.status === "failed")
+        process.exit(EXIT.server);
+    if (!TERMINAL_STATUSES.has(run.status)) {
+        note("still running — follow it with: fieldwork automations runs <name> --follow");
+    }
+}
+/** Poll one run to a terminal status, narrating transitions on stderr. */
+async function followRun(automationId, runId, intervalSeconds, json) {
+    let lastStatus = null;
+    for (;;) {
+        const run = (await fetchRuns(automationId, `?run=${runId}`))[0];
+        if (!run)
+            fail(`run ${runId} disappeared`, EXIT.notFound);
+        if (run.status !== lastStatus) {
+            note(runStatusLine(run));
+            lastStatus = run.status;
+        }
+        if (TERMINAL_STATUSES.has(run.status)) {
+            if (json)
+                printData(run, true);
+            else {
+                if (run.error)
+                    note(`error: ${run.error}`);
+                if (run.log_tail)
+                    printData(run.log_tail, false);
+            }
+            if (run.status === "failed")
+                process.exit(EXIT.server);
+            return;
+        }
+        await new Promise((resolve) => setTimeout(resolve, intervalSeconds * 1000));
+    }
+}
+export function registerAutomationCommands(program) {
+    const automations = program
+        .command("automations")
+        .description("Standing instructions that run unattended (schedules, webhooks)");
+    automations
+        .command("list")
+        .description("List the automations you can see")
+        .option("--kind <kind>", "filter by kind: action | agent")
+        .action(async (opts) => {
+        const { json } = getContext();
+        const body = await apiJson(`/api/organizations/${requireOrgId()}/automations`);
+        const rows = opts.kind
+            ? body.automations.filter((a) => a.kind === opts.kind)
+            : body.automations;
+        if (json) {
+            printData({ automations: rows }, true);
+            return;
+        }
+        for (const a of rows) {
+            printData(`${a.name}\t${a.kind}\t${a.enabled ? "enabled" : "DISABLED"}`, false);
+        }
+    });
+    automations
+        .command("get <name>")
+        .description("One automation in full (includes the webhook URL — treat as a credential)")
+        .action(async (name) => {
+        const found = await resolveAutomation(name);
+        const body = await apiJson(`/api/organizations/${requireOrgId()}/automations/${found.automation_id}`);
+        printData(body, getContext().json);
+    });
+    const setEnabled = (enabled) => async (name) => {
+        const { json, yes } = getContext();
+        const found = await resolveAutomation(name);
+        await confirm(`${enabled ? "Enable" : "Disable"} "${name}"?`, yes);
+        const body = await apiJson(`/api/organizations/${requireOrgId()}/automations/${found.automation_id}`, { method: "PATCH", body: JSON.stringify({ enabled }) });
+        printData(body, json);
+    };
+    automations.command("enable <name>").description("Enable an automation").action(setEnabled(true));
+    automations
+        .command("disable <name>")
+        .description("Disable an automation")
+        .action(setEnabled(false));
+    automations
+        .command("delete <name>")
+        .description("Delete an automation")
+        .action(async (name) => {
+        const { json, yes } = getContext();
+        const found = await resolveAutomation(name);
+        await confirm(`Delete "${name}"? Its run history is retained.`, yes);
+        const res = await api(`/api/organizations/${requireOrgId()}/automations/${found.automation_id}`, { method: "DELETE" });
+        if (res.status !== 204) {
+            const body = (await res.json().catch(() => null));
+            fail(body?.error ?? `delete failed (${res.status})`, exitCodeFor(res.status));
+        }
+        printData({ deleted: true, automation_id: found.automation_id, name }, json);
+    });
+    automations
+        .command("runs <name>")
+        .description("Recent runs; --follow polls the latest run to completion")
+        .option("--limit <n>", "how many (default 20, max 100)")
+        .option("--follow", "poll the latest run until it succeeds or fails")
+        .option("--interval <s>", "poll interval in seconds (default 3)", "3")
+        .action(async (name, opts) => {
+        const { json } = getContext();
+        const found = await resolveAutomation(name);
+        if (opts.follow) {
+            const latest = (await fetchRuns(found.automation_id, "?limit=1"))[0];
+            if (!latest)
+                fail(`"${name}" has no runs yet`, EXIT.notFound);
+            await followRun(found.automation_id, latest.automation_run_id, Number(opts.interval) || 3, json);
+            return;
+        }
+        const suffix = opts.limit ? `?limit=${opts.limit}` : "";
+        const body = await apiJson(`/api/organizations/${requireOrgId()}/automations/${found.automation_id}/runs${suffix}`);
+        printData(body, json);
+    });
+    automations
+        .command("logs <name>")
+        .description("A run's captured log tail (default: the latest run)")
+        .option("--run <id>", "a specific run id (from automations runs)")
+        .action(async (name, opts) => {
+        const { json } = getContext();
+        const found = await resolveAutomation(name);
+        const query = opts.run ? `?run=${encodeURIComponent(opts.run)}` : "?limit=1";
+        const run = (await fetchRuns(found.automation_id, query))[0];
+        if (!run) {
+            fail(opts.run ? `no run ${opts.run} for "${name}"` : `"${name}" has no runs yet`, EXIT.notFound);
+        }
+        printRun(run, json);
+    });
+    automations
+        .command("run-now <name>")
+        .description("Create a manual run")
+        .option("--follow", "poll the run until it succeeds or fails")
+        .option("--interval <s>", "poll interval in seconds (default 3)", "3")
+        .action(async (name, opts) => {
+        const { json, yes } = getContext();
+        const found = await resolveAutomation(name);
+        await confirm(`Run "${name}" now?`, yes);
+        const body = await apiJson(`/api/organizations/${requireOrgId()}/automations/${found.automation_id}/runs`, { method: "POST" });
+        if (opts.follow) {
+            await followRun(found.automation_id, body.run.automation_run_id, Number(opts.interval) || 3, json);
+            return;
+        }
+        printData(body, json);
+    });
+}

package/dist/commands/connectors.d.ts

@@ -0,0 +1,11 @@
+import { Command } from "commander";
+/**
+ * Secret files are written via a temp file in the target directory: openSync's
+ * mode only applies on create, so writing straight over an existing
+ * looser-mode file would silently keep that mode on the credentials; the
+ * rename also means no reader ever observes a truncated or partial file.
+ */
+export declare function writeSecretsFile(out: string, secrets: Record<string, string>, opts: {
+    force: boolean;
+}): void;
+export declare function registerConnectorCommands(program: Command): void;

package/dist/commands/connectors.js

@@ -0,0 +1,272 @@
+import { closeSync, existsSync, fchmodSync, openSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { readBundle, writeBundle } from "../bundle.js";
+import { apiJson, getContext, requireOrgId } from "../http.js";
+import { EXIT, confirm, fail, note, printData } from "../output.js";
+async function resolveDefinition(key) {
+    const body = await apiJson(`/api/organizations/${requireOrgId()}/connector-definitions?include_drafts=true`);
+    const matches = (body.definitions ?? []).filter((d) => d.key === key);
+    const definition = matches.find((d) => d.org_private) ?? matches[0];
+    if (!definition) {
+        fail(`no connector definition with key "${key}"`, EXIT.notFound);
+    }
+    return definition;
+}
+function parseDotenv(content) {
+    const values = {};
+    for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const idx = trimmed.indexOf("=");
+        if (idx <= 0)
+            continue;
+        values[trimmed.slice(0, idx)] = trimmed.slice(idx + 1);
+    }
+    return values;
+}
+async function readSecretInput(opts) {
+    if (opts.stdin) {
+        if (process.stdin.isTTY)
+            fail("--stdin expects a JSON object piped in", EXIT.usage);
+        const chunks = [];
+        for await (const chunk of process.stdin)
+            chunks.push(chunk);
+        try {
+            const parsed = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+            if (typeof parsed !== "object" || parsed === null)
+                throw new Error("not an object");
+            return parsed;
+        }
+        catch {
+            fail("stdin must carry a JSON object of {name: value}", EXIT.usage);
+        }
+    }
+    if (opts.fromEnvFile) {
+        try {
+            return parseDotenv(readFileSync(opts.fromEnvFile, "utf8"));
+        }
+        catch {
+            fail(`could not read ${opts.fromEnvFile}`, EXIT.usage);
+        }
+    }
+    if (opts.fromEnv) {
+        const values = {};
+        for (const name of opts.fromEnv.split(",").map((n) => n.trim())) {
+            const value = process.env[name];
+            if (value === undefined)
+                fail(`environment variable ${name} is not set`, EXIT.usage);
+            values[name] = value;
+        }
+        return values;
+    }
+    fail("provide secrets via --stdin, --from-env-file <file>, or --from-env NAME,...", EXIT.usage);
+}
+/**
+ * Secret files are written via a temp file in the target directory: openSync's
+ * mode only applies on create, so writing straight over an existing
+ * looser-mode file would silently keep that mode on the credentials; the
+ * rename also means no reader ever observes a truncated or partial file.
+ */
+export function writeSecretsFile(out, secrets, opts) {
+    if (!opts.force && existsSync(out)) {
+        fail(`${out} already exists — pass --force to overwrite`, EXIT.usage);
+    }
+    const tmp = join(dirname(out), `.${basename(out)}.tmp-${process.pid}`);
+    rmSync(tmp, { force: true });
+    const fd = openSync(tmp, "wx", 0o600);
+    try {
+        fchmodSync(fd, 0o600); // openSync's mode is masked by umask; this is not
+        const lines = Object.entries(secrets).map(([name, value]) => `${name}=${value}`);
+        writeFileSync(fd, `${lines.join("\n")}\n`);
+    }
+    finally {
+        closeSync(fd);
+    }
+    try {
+        renameSync(tmp, out);
+    }
+    catch (err) {
+        rmSync(tmp, { force: true });
+        throw err;
+    }
+}
+/** How a connector is addressed in a URL (ADR 20260819): the definition key for
+ * a global system, its id for an org-authored one whose key is only unique
+ * within the org. Mirrors `connectorAddress` in the app. */
+function addressOf(c) {
+    return c.definition_is_global ? c.definition_key : c.connector_definition_id;
+}
+async function listConnectors() {
+    const body = await apiJson(`/api/organizations/${requireOrgId()}/connectors`);
+    return body.connectors;
+}
+export function registerConnectorCommands(program) {
+    const connectors = program.command("connectors").description("Org connectors");
+    connectors
+        .command("list")
+        .description("List the org's connectors")
+        .action(async () => {
+        const { json } = getContext();
+        const connectors = await listConnectors();
+        if (json) {
+            printData({ connectors }, true);
+            return;
+        }
+        for (const c of connectors) {
+            printData(`${addressOf(c)}\t${c.name}${c.connected ? "\tconnected" : ""}`, false);
+        }
+    });
+    connectors
+        .command("connect <key>")
+        .description("Provision a data source: connector + tables + schedule against an existing definition")
+        .requiredOption("--spec <file>", 'JSON spec {connector: {name, config}, tables: [...], schedule: {...}} ("-" reads stdin)')
+        .action(async (key, opts) => {
+        const { json, yes } = getContext();
+        let raw;
+        try {
+            raw = opts.spec === "-" ? readFileSync(0, "utf8") : readFileSync(opts.spec, "utf8");
+        }
+        catch {
+            fail(`could not read ${opts.spec}`, EXIT.usage);
+        }
+        let spec;
+        try {
+            spec = JSON.parse(raw);
+        }
+        catch {
+            fail(`${opts.spec} is not valid JSON`, EXIT.usage);
+        }
+        await confirm(`Connect "${key}" as "${spec.connector?.name ?? "?"}" — ${spec.tables?.length ?? 0} table(s), every ${spec.schedule?.interval ?? "?"}?`, yes);
+        const body = await apiJson(`/api/organizations/${requireOrgId()}/connectors/sync`, {
+            method: "POST",
+            body: JSON.stringify({ definition_key: key, ...spec }),
+        });
+        if (body.connector.awaiting_credentials) {
+            note(`Awaiting credentials — set them with: fieldwork connectors secrets set ${key}`);
+        }
+        printData(body, json);
+    });
+    connectors
+        .command("test <keyOrName>")
+        .description("Test a saved database connector's stored credentials")
+        .action(async (keyOrName) => {
+        const { json } = getContext();
+        const connectors = await listConnectors();
+        const match = connectors.find((c) => c.definition_key === keyOrName) ??
+            connectors.find((c) => c.name === keyOrName);
+        if (!match)
+            fail(`no connector "${keyOrName}"`, EXIT.notFound);
+        // No body on purpose: a body is treated as an unsaved-override test and
+        // skips the persisted read-only re-validation.
+        const body = await apiJson(`/api/connectors/${addressOf(match)}/test`, { method: "POST" });
+        printData(body, json);
+        if (!body.ok)
+            process.exit(EXIT.server);
+    });
+    connectors
+        .command("pull <key>")
+        .description("Download an org-authored connector definition's adapter source")
+        .option("--out <dir>", "target directory (defaults to ./<key>)")
+        .option("--revision <n>", "a historical revision instead of head")
+        .option("--action-name <name>", "the named action under this connector")
+        .action(async (key, opts) => {
+        const { json } = getContext();
+        const definition = await resolveDefinition(key);
+        const query = new URLSearchParams();
+        if (opts.revision)
+            query.set("revision", opts.revision);
+        if (opts.actionName)
+            query.set("action_name", opts.actionName);
+        const suffix = query.size ? `?${query}` : "";
+        const body = await apiJson(`/api/organizations/${requireOrgId()}/connector-definitions/${definition.connector_definition_id}/source${suffix}`);
+        const dir = opts.out ?? key;
+        const pulled = writeBundle(dir, body.files);
+        if (json) {
+            printData({ key, revision: body.revision, dir, pulled }, true);
+            return;
+        }
+        note(`Pulled "${key}" revision ${body.revision} into ${dir}/ — pass --base-revision ${body.revision} when publishing.`);
+    });
+    connectors
+        .command("publish <dir>")
+        .description("Publish an adapter directory as a new revision (creates the definition on first publish)")
+        .requiredOption("--message <message>", "what changed and why")
+        .option("--base-revision <n>", "head revision your changes are based on (required once code is published)")
+        .option("--action-name <name>", "create or update this named action under the connector")
+        .action(async (dir, opts) => {
+        const { json, yes } = getContext();
+        const files = readBundle(dir);
+        // Local parse is only for the confirm prompt — the server re-parses
+        // the manifest authoritatively.
+        let key = "?";
+        try {
+            const manifest = JSON.parse(files["connector.json"] ?? "");
+            if (typeof manifest?.key === "string")
+                key = manifest.key;
+        }
+        catch {
+            // fall through: the server reports the real validation error
+        }
+        if (key === "?") {
+            fail('the tree\'s connector.json must carry a "key" field', EXIT.usage);
+        }
+        await confirm(`Publish ${Object.keys(files).length} files to connector "${key}"${opts.actionName ? `, action "${opts.actionName}"` : ""}?`, yes);
+        const body = await apiJson(`/api/organizations/${requireOrgId()}/connector-definitions/publish`, {
+            method: "POST",
+            body: JSON.stringify({
+                message: opts.message,
+                base_revision: opts.baseRevision ? Number(opts.baseRevision) : undefined,
+                action_name: opts.actionName,
+                files,
+            }),
+        });
+        printData(body, json);
+    });
+    const secrets = connectors
+        .command("secrets")
+        .description("Connector credentials (values never transit argv or stdout)");
+    secrets
+        .command("names <connector>")
+        .description("The secret names currently set, plus the definition's hints")
+        .action(async (connector) => {
+        printData(await apiJson(`/api/connectors/${connector}/secrets`), getContext().json);
+    });
+    secrets
+        .command("set <connector>")
+        .description("Replace the connector's secrets envelope (write-only)")
+        .option("--stdin", "read a JSON object of {name: value} from stdin")
+        .option("--from-env-file <file>", "read NAME=value lines from a dotenv file")
+        .option("--from-env <names>", "comma-separated env var names to copy")
+        .action(async (connector, opts) => {
+        const { json, yes } = getContext();
+        const values = await readSecretInput(opts);
+        const names = Object.keys(values);
+        if (names.length === 0)
+            fail("no secrets to set", EXIT.usage);
+        await confirm(`Replace the secrets envelope with ${names.length} value(s)?`, yes);
+        const body = await apiJson(`/api/connectors/${connector}/secrets`, {
+            method: "PUT",
+            body: JSON.stringify({ secrets: values }),
+        });
+        printData(body, json);
+    });
+    secrets
+        .command("pull <connector>")
+        .description("Materialize an org-authored connector's secret values into a file")
+        .requiredOption("--out <file>", "target dotenv file (written chmod 600)")
+        .option("--force", "overwrite an existing file")
+        .action(async (connector, opts) => {
+        const { json } = getContext();
+        const body = await apiJson(`/api/connectors/${connector}/secrets/values`);
+        writeSecretsFile(opts.out, body.secrets, { force: Boolean(opts.force) });
+        const names = Object.keys(body.secrets);
+        // Names only — the values are in the file, never on a stream.
+        if (json) {
+            printData({ out: opts.out, names }, true);
+            return;
+        }
+        note(`Wrote ${names.length} secret(s) to ${opts.out}: ${names.join(", ")}`);
+        note(`Use them without echoing: set -a && . ${opts.out} && set +a`);
+    });
+}

package/dist/commands/kb-blobs.d.ts

@@ -0,0 +1,16 @@
+export interface FileRow {
+    kb_file_id: string;
+    path: string;
+}
+/**
+ * The three-step upload: POST the row, PUT to the presigned URL, confirm.
+ * Extracted so `kb put` can reach it — the unified command dispatches on
+ * kind, and a document takes exactly this path.
+ */
+export declare function uploadFile(localPath: string, remotePath: string | undefined, contentTypeOverride: string | undefined, yes: boolean): Promise<{
+    fileId: string;
+    path: string;
+    bytes: number;
+}>;
+/** Write one row's bytes to `out` ("-" streams to stdout). */
+export declare function downloadFile(file: FileRow, out: string | undefined, json: boolean): Promise<void>;

package/dist/commands/kb-blobs.js

@@ -0,0 +1,98 @@
+import { readFileSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { apiJson, requireOrgId } from "../http.js";
+import { EXIT, confirm, fail, note, printData } from "../output.js";
+/**
+ * Document primitives for the `kb_files` group: the three-step upload flow
+ * (POST row → PUT to the presigned URL → confirm) and the presigned download.
+ * The presigned URLs are absolute and carry no bearer — raw fetch, never api().
+ *
+ * No command group of its own: `files` split the tree by storage kind, which
+ * is what the Knowledge Base merge removed.
+ */
+const MAX_FILE_BYTES = 100 * 1024 * 1024;
+const CONTENT_TYPES = {
+    ".csv": "text/csv",
+    ".json": "application/json",
+    ".jsonl": "application/jsonl",
+    ".md": "text/markdown",
+    ".txt": "text/plain",
+    ".pdf": "application/pdf",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+    ".parquet": "application/vnd.apache.parquet",
+    ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ".zip": "application/zip",
+};
+function guessContentType(filename) {
+    return CONTENT_TYPES[path.extname(filename).toLowerCase()] ?? "application/octet-stream";
+}
+/**
+ * The three-step upload: POST the row, PUT to the presigned URL, confirm.
+ * Extracted so `kb put` can reach it — the unified command dispatches on
+ * kind, and a document takes exactly this path.
+ */
+export async function uploadFile(localPath, remotePath, contentTypeOverride, yes) {
+    let size;
+    try {
+        size = statSync(localPath).size;
+    }
+    catch {
+        fail(`could not read ${localPath}`, EXIT.usage);
+    }
+    if (size > MAX_FILE_BYTES) {
+        fail(`${localPath} is ${size} bytes — the server caps uploads at 100MB`, EXIT.usage);
+    }
+    const remote = remotePath ?? path.basename(localPath);
+    const contentType = contentTypeOverride ?? guessContentType(remote);
+    await confirm(`Upload ${localPath} (${size} bytes) to "${remote}"?`, yes);
+    const created = await apiJson(`/api/organizations/${requireOrgId()}/knowledge-base`, {
+        method: "POST",
+        body: JSON.stringify({ filename: remote, contentType, sizeBytes: size }),
+    });
+    // Content-Type must match the presign's pinned value exactly. A failed
+    // PUT leaves only an invisible pending row — nothing to clean up.
+    const put = await fetch(created.uploadUrl, {
+        method: "PUT",
+        headers: { "content-type": contentType },
+        body: readFileSync(localPath),
+    }).catch((err) => {
+        fail(`upload failed: ${err instanceof Error ? err.message : "network error"}`, EXIT.server);
+    });
+    if (!put.ok) {
+        fail(`upload failed: storage returned ${put.status}`, EXIT.server);
+    }
+    // Confirm names the revision the bytes landed on: nothing is visible at the
+    // path until it does, so an abandoned upload cannot hold a path.
+    await apiJson(`/api/organizations/${requireOrgId()}/knowledge-base/${created.fileId}/confirm`, {
+        method: "POST",
+        body: JSON.stringify({ path: remote, revisionId: created.revisionId, contentType }),
+    });
+    return { fileId: created.fileId, path: remote, bytes: size };
+}
+/** Write one row's bytes to `out` ("-" streams to stdout). */
+export async function downloadFile(file, out, json) {
+    const remotePath = file.path;
+    const { url } = await apiJson(`/api/organizations/${requireOrgId()}/knowledge-base/${file.kb_file_id}/download`);
+    const res = await fetch(url).catch((err) => {
+        fail(`download failed: ${err instanceof Error ? err.message : "network error"}`, EXIT.server);
+    });
+    if (!res.ok)
+        fail(`download failed: storage returned ${res.status}`, EXIT.server);
+    const bytes = Buffer.from(await res.arrayBuffer());
+    if (out === "-") {
+        // Binary-safe: raw bytes to stdout, nothing else on the stream.
+        process.stdout.write(bytes);
+        return;
+    }
+    const target = out ?? path.basename(remotePath);
+    writeFileSync(target, bytes);
+    if (json) {
+        printData({ file_id: file.kb_file_id, path: remotePath, bytes: bytes.length, out: target }, true);
+        return;
+    }
+    note(`Wrote ${bytes.length} bytes to ${target}`);
+}

package/dist/commands/kb-pages.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Knowledge base family (ADR 20260804 revision: purpose verbs are
+ * REST-backed). Mutations ride the same UI routes the in-app editor uses —
+ * writeKbPage stays the single server-side write path. Local files carry the
+ * page's full content including its frontmatter block, so pull/push
+ * round-trips byte-for-byte.
+ *
+ * Callers resolve a path to a row against the tree listing and pass the id in.
+ * There is deliberately no path lookup here: the merged API addresses a file
+ * by id, and a second path→row mechanism is what left this module pointed at
+ * routes that no longer existed.
+ */
+export interface KbPageDetail {
+    kb_file_id: string;
+    path: string;
+    summary: string | null;
+    latest_revision_number: number;
+    content: string;
+}
+/** One page's full detail, including its serialized content. */
+export declare function lookupPage(kbFileId: string): Promise<KbPageDetail>;
+/** The server's line-based frontmatter shape (src/lib/kb/frontmatter.ts):
+ * `summary:` between `---` fences, body verbatim after the closing fence. */
+export declare function parseKbContent(content: string): {
+    summary: string;
+    body: string;
+} | null;
+/**
+ * Create-or-update one page from full local content. Returns what happened.
+ * `existing` is the tree row when the path is already taken, resolved by the
+ * caller — null creates.
+ */
+export declare function putPage(pagePath: string, content: string, summaryFlag: string | undefined, existing: {
+    kb_file_id: string;
+    latest_revision_number: number;
+} | null): Promise<"created" | "updated">;
+export declare function assertSafeKbPath(pagePath: string): void;
+/** All .md files under dir, keyed by their dir-relative (= KB) path. */
+export declare function readMarkdownTree(dir: string): Record<string, string>;