@plune-ai/cli 0.4.0 → 0.6.0

package/dist/index.cjs

@@ -30,13 +30,24 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  NotLoggedInError: () => NotLoggedInError,
   RUN_RESULT_SCHEMA_VERSION: () => RUN_RESULT_SCHEMA_VERSION,
+  SyncFileError: () => SyncFileError,
+  SyncHttpError: () => SyncHttpError,
+  SyncNetworkError: () => SyncNetworkError,
+  TokenRejectedError: () => TokenRejectedError,
   assertionConfigSchema: () => assertionConfigSchema,
   assertionResultRecordSchema: () => assertionResultRecordSchema,
   binaryVerdictSchema: () => binaryVerdictSchema,
+  formatIngestResult: () => formatIngestResult,
+  ingest: () => handleIngest,
   parseRunResult: () => parseRunResult,
+  readCairnRun: () => readCairnRun,
+  reportIngestFailure: () => reportIngestFailure,
+  reportSyncFailure: () => reportSyncFailure,
   run: () => handleRun,
-  runResultSchema: () => runResultSchema
+  runResultSchema: () => runResultSchema,
+  sync: () => handleSync
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -357,7 +368,7 @@ function normalizeProviderError(err, secret, envVar) {
 }
 
 // src/providers/retry.ts
-var defaultSleep = (ms) => new Promise((resolve4) => setTimeout(resolve4, ms));
+var defaultSleep = (ms) => new Promise((resolve5) => setTimeout(resolve5, ms));
 function retryAfterMs(err) {
   if (typeof err !== "object" || err === null || !("headers" in err)) return void 0;
   const raw = readHeader(err.headers, "retry-after");
@@ -637,9 +648,11 @@ var XenovaEmbedder = class {
     return rows.map((row) => Float32Array.from(row));
   }
   load() {
-    this.extractor ??= import("@huggingface/transformers").then(
-      ({ pipeline }) => pipeline("feature-extraction", MODEL_ID)
-    );
+    this.extractor ??= import("@huggingface/transformers").catch(() => {
+      throw new Error(
+        "The `semantic-similarity` and RAG assertions need local embeddings, which ship separately: install @huggingface/transformers to enable them. Every other assertion works without it."
+      );
+    }).then(({ pipeline }) => pipeline("feature-extraction", MODEL_ID));
     return this.extractor;
   }
 };
@@ -1503,6 +1516,10 @@ async function handleRun(options, depsFactory) {
   }
 }
 
+// src/cli/commands/sync.ts
+var fs6 = __toESM(require("fs"), 1);
+var path5 = __toESM(require("path"), 1);
+
 // src/types/run-result-schema.ts
 var import_zod2 = require("zod");
 var RUN_RESULT_SCHEMA_VERSION = 1;
@@ -1561,13 +1578,367 @@ var runResultSchema = import_zod2.z.object({
 function parseRunResult(value) {
   return runResultSchema.parse(value);
 }
+
+// src/cli/credentials.ts
+var import_node_fs = require("fs");
+var import_node_os = require("os");
+var import_node_path = require("path");
+function credentialsFile() {
+  const base = process.env["XDG_CONFIG_HOME"]?.trim() || (0, import_node_path.join)((0, import_node_os.homedir)(), ".config");
+  return (0, import_node_path.join)(base, "plune", "credentials.json");
+}
+function loadToken() {
+  try {
+    const parsed = JSON.parse((0, import_node_fs.readFileSync)(credentialsFile(), "utf-8"));
+    return typeof parsed.token === "string" && parsed.token.length > 0 ? parsed.token : null;
+  } catch {
+    return null;
+  }
+}
+
+// src/cli/commands/sync.ts
+var DEFAULT_API_URL = "https://beta-api.plune.ai";
+var NotLoggedInError = class extends Error {
+  constructor() {
+    super('Not logged in. Run "plune login" first to save your API token.');
+    this.name = "NotLoggedInError";
+  }
+};
+var TokenRejectedError = class extends Error {
+  constructor() {
+    super(
+      'Your API token was rejected (revoked or invalid). Run "plune login" with a fresh token.'
+    );
+    this.name = "TokenRejectedError";
+  }
+};
+var SyncFileError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SyncFileError";
+  }
+};
+var SyncNetworkError = class extends Error {
+  constructor(apiUrl) {
+    super(
+      `Could not reach the Plune API at ${apiUrl}. Check your connection (or PLUNE_API_URL) and try again.`
+    );
+    this.name = "SyncNetworkError";
+  }
+};
+var SyncHttpError = class extends Error {
+  constructor(status, detail) {
+    super(`Sync failed \u2014 the server returned HTTP ${status}${detail ? ` (${detail})` : ""}.`);
+    this.status = status;
+    this.name = "SyncHttpError";
+  }
+  status;
+};
+function resolveApiUrl(explicit) {
+  const raw = explicit ?? process.env["PLUNE_API_URL"] ?? DEFAULT_API_URL;
+  return raw.replace(/\/+$/, "");
+}
+function readRun(cwd, file) {
+  const target = file !== void 0 ? path5.resolve(cwd, file) : path5.join(cwd, ".plune", "last-run.json");
+  let raw;
+  try {
+    raw = fs6.readFileSync(target, "utf8");
+  } catch {
+    throw new SyncFileError(
+      file !== void 0 ? `Run file not found: ${target}` : 'No run to sync. Run "plune run" first (or pass --file <path>).'
+    );
+  }
+  let json;
+  try {
+    json = JSON.parse(raw);
+  } catch {
+    throw new SyncFileError(`Run file is not valid JSON: ${target}`);
+  }
+  try {
+    return parseRunResult(json);
+  } catch {
+    throw new SyncFileError(`Run file does not match the RunResult schema: ${target}`);
+  }
+}
+async function safeErrorDetail(res) {
+  try {
+    const body = await res.json();
+    return typeof body.error === "string" ? body.error : "";
+  } catch {
+    return "";
+  }
+}
+async function handleSync(deps = {}) {
+  const cwd = deps.cwd ?? process.cwd();
+  const apiUrl = resolveApiUrl(deps.apiUrl);
+  const token = (deps.loadToken ?? loadToken)();
+  if (token === null) throw new NotLoggedInError();
+  const run = readRun(cwd, deps.file);
+  const doFetch = deps.fetchImpl ?? fetch;
+  const endpoint = `${apiUrl}/v1/runs`;
+  let res;
+  try {
+    res = await doFetch(endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+      body: JSON.stringify(run)
+    });
+  } catch {
+    throw new SyncNetworkError(apiUrl);
+  }
+  if (!res.ok) {
+    const detail = await safeErrorDetail(res);
+    if (res.status === 401) throw new TokenRejectedError();
+    throw new SyncHttpError(res.status, detail);
+  }
+  const body = await res.json().catch(() => ({}));
+  const id = typeof body.id === "string" ? body.id : "";
+  return { id, url: `${endpoint}/${id}` };
+}
+function reportSyncFailure(err, write) {
+  if (err instanceof NotLoggedInError || err instanceof TokenRejectedError || err instanceof SyncFileError) {
+    write(err.message + "\n");
+    return 2;
+  }
+  if (err instanceof SyncNetworkError || err instanceof SyncHttpError) {
+    write(err.message + "\n");
+    return 1;
+  }
+  return null;
+}
+
+// src/cli/commands/cairn-artifact.ts
+var fs7 = __toESM(require("fs/promises"), 1);
+var path6 = __toESM(require("path"), 1);
+var SUPPORTED_ARTIFACT_VERSION = 1;
+var INGEST_SCHEMA_VERSION = 1;
+var CairnRunNotFoundError = class extends Error {
+  constructor(dir) {
+    super(`No Cairn run found in ${dir} \u2014 expected a report.json written by "cairn design|explore|api".`);
+    this.name = "CairnRunNotFoundError";
+  }
+};
+var CairnRunVersionError = class extends Error {
+  constructor(found) {
+    super(
+      found === void 0 ? "This run predates versioned Cairn artifacts. Re-run it with Cairn 0.7.0 or newer, which stamps the format so it can be read safely." : `Unsupported Cairn artifact version ${String(found)} (this CLI reads version ${SUPPORTED_ARTIFACT_VERSION}). Upgrade @plune-ai/cli.`
+    );
+    this.name = "CairnRunVersionError";
+  }
+};
+var CairnRunPartialError = class extends Error {
+  constructor(reason) {
+    super(`That Cairn run did not finish, so its cases are incomplete: ${reason}`);
+    this.name = "CairnRunPartialError";
+  }
+};
+var CairnEvidenceAmbiguousError = class extends Error {
+  constructor(name) {
+    super(
+      `Cannot attach results safely: the operation "${name}" appears more than once in this run's evidence, and the evidence file carries no case identity to disambiguate it. Nothing was uploaded.`
+    );
+    this.name = "CairnEvidenceAmbiguousError";
+  }
+};
+var asRecord = (v) => typeof v === "object" && v !== null ? v : {};
+var str = (v, fallback = "") => typeof v === "string" && v !== "" ? v : fallback;
+async function readJson(file) {
+  try {
+    return JSON.parse(await fs7.readFile(file, "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+async function defaultReadEvidence(dir) {
+  const raw = await readJson(path6.join(dir, "api-evidence.json"));
+  if (!Array.isArray(raw)) return void 0;
+  return raw.map((r) => {
+    const rec = asRecord(r);
+    return { name: str(rec["name"]), passed: rec["passed"] === true };
+  });
+}
+function casesFromDesign(report) {
+  const list = Array.isArray(report["testCases"]) ? report["testCases"] : [];
+  return list.map((raw) => {
+    const c = asRecord(raw);
+    const steps = (Array.isArray(c["steps"]) ? c["steps"] : []).map((s) => str(s)).filter((s) => s !== "");
+    return {
+      stableId: str(c["stableId"]),
+      title: str(c["title"], "untitled case"),
+      execution: c["execution"] === "manual" ? "manual" : "auto",
+      steps: steps.length > 0 ? steps : ["(no steps recorded)"],
+      expected: str(c["expected"], "(no expected result recorded)"),
+      ...typeof c["technique"] === "string" ? { technique: c["technique"] } : {},
+      ...typeof c["priority"] === "string" ? { priority: c["priority"] } : {}
+    };
+  });
+}
+function casesFromApi(report, verdicts) {
+  const list = Array.isArray(report["cases"]) ? report["cases"] : [];
+  return list.map((raw) => {
+    const c = asRecord(raw);
+    const name = str(c["name"], "unnamed operation");
+    const request = `${str(c["method"], "GET")} ${str(c["path"], "/")}`;
+    const verdict = verdicts.get(name);
+    return {
+      stableId: str(c["stableId"]),
+      title: name,
+      execution: "auto",
+      steps: [request],
+      expected: `HTTP ${str(c["expectedStatus"], "default")}`,
+      ...verdict !== void 0 ? { verdict } : {},
+      ...typeof c["technique"] === "string" ? { technique: c["technique"] } : {}
+    };
+  });
+}
+async function readCairnRun(dir, deps = {}) {
+  const raw = await readJson(path6.join(dir, "report.json"));
+  if (raw === void 0) throw new CairnRunNotFoundError(dir);
+  const report = asRecord(raw);
+  if (report["schemaVersion"] !== SUPPORTED_ARTIFACT_VERSION) {
+    throw new CairnRunVersionError(report["schemaVersion"]);
+  }
+  if (report["partial"] === true) {
+    throw new CairnRunPartialError(str(report["error"], "no reason recorded"));
+  }
+  const mode = report["mode"];
+  if (mode !== "design" && mode !== "explore" && mode !== "api") {
+    throw new CairnRunVersionError(`${SUPPORTED_ARTIFACT_VERSION} (unknown run mode ${String(mode)})`);
+  }
+  let cases;
+  if (mode === "api") {
+    const evidence = await (deps.readEvidence ?? defaultReadEvidence)(dir);
+    const verdicts = /* @__PURE__ */ new Map();
+    for (const e of evidence ?? []) {
+      if (verdicts.has(e.name)) throw new CairnEvidenceAmbiguousError(e.name);
+      verdicts.set(e.name, e.passed ? "passed" : "failed");
+    }
+    cases = casesFromApi(report, verdicts);
+  } else {
+    cases = casesFromDesign(report);
+  }
+  return {
+    schemaVersion: INGEST_SCHEMA_VERSION,
+    run: {
+      runId: str(report["runId"], path6.basename(dir)),
+      mode,
+      target: str(report["url"], "unknown")
+    },
+    cases
+  };
+}
+
+// src/cli/commands/ingest.ts
+var DEFAULT_API_URL2 = "https://beta-api.plune.ai";
+var IngestNotLoggedInError = class extends Error {
+  constructor() {
+    super('Not logged in. Run "plune login" first to save your API token.');
+    this.name = "IngestNotLoggedInError";
+  }
+};
+var IngestTokenRejectedError = class extends Error {
+  constructor() {
+    super('Your API token was rejected (401). Run "plune login" again with a fresh token.');
+    this.name = "IngestTokenRejectedError";
+  }
+};
+var IngestNetworkError = class extends Error {
+  constructor(apiUrl) {
+    super(`Could not reach the Plune API at ${apiUrl}. Check your connection, then try again.`);
+    this.name = "IngestNetworkError";
+  }
+};
+var IngestHttpError = class extends Error {
+  constructor(status, detail) {
+    super(`Plune API returned ${status}${detail !== "" ? ` \u2014 ${detail}` : ""}.`);
+    this.status = status;
+    this.name = "IngestHttpError";
+  }
+  status;
+};
+function resolveApiUrl2(explicit) {
+  const raw = explicit ?? process.env["PLUNE_API_URL"] ?? DEFAULT_API_URL2;
+  return raw.replace(/\/+$/, "");
+}
+async function safeErrorDetail2(res) {
+  try {
+    const body = await res.json();
+    return typeof body.error === "string" ? body.error : "";
+  } catch {
+    return "";
+  }
+}
+async function handleIngest(deps) {
+  const apiUrl = resolveApiUrl2(deps.apiUrl);
+  const token = (deps.loadToken ?? loadToken)();
+  if (token === null) throw new IngestNotLoggedInError();
+  const payload = await readCairnRun(deps.dir);
+  const doFetch = deps.fetchImpl ?? fetch;
+  const endpoint = `${apiUrl}/v1/ingest/cairn`;
+  let res;
+  try {
+    res = await doFetch(endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+      body: JSON.stringify(payload)
+    });
+  } catch {
+    throw new IngestNetworkError(apiUrl);
+  }
+  if (!res.ok) {
+    const detail = await safeErrorDetail2(res);
+    if (res.status === 401) throw new IngestTokenRejectedError();
+    throw new IngestHttpError(res.status, detail);
+  }
+  const body = await res.json().catch(() => ({}));
+  return {
+    runId: typeof body.runId === "string" ? body.runId : "",
+    linked: typeof body.linked === "number" ? body.linked : 0,
+    proposed: typeof body.proposed === "number" ? body.proposed : 0,
+    skipped: typeof body.skipped === "number" ? body.skipped : 0
+  };
+}
+function reportIngestFailure(err, write) {
+  if (err instanceof IngestNotLoggedInError || err instanceof IngestTokenRejectedError || err instanceof CairnRunNotFoundError || err instanceof CairnRunVersionError || err instanceof CairnRunPartialError || err instanceof CairnEvidenceAmbiguousError) {
+    write(`${err.message}
+`);
+    return 2;
+  }
+  if (err instanceof IngestNetworkError || err instanceof IngestHttpError) {
+    write(`${err.message}
+`);
+    return 1;
+  }
+  return null;
+}
+function formatIngestResult(r) {
+  const lines = [
+    `Ingested Cairn run \u2192 ${r.runId}`,
+    `  ${r.linked} result(s) attached to existing cases`,
+    `  ${r.proposed} case(s) proposed \u2014 review them in Plune to accept`,
+    `  ${r.skipped} skipped (already queued, already rejected, repeated, or never executed)`
+  ];
+  return `${lines.join("\n")}
+`;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  NotLoggedInError,
   RUN_RESULT_SCHEMA_VERSION,
+  SyncFileError,
+  SyncHttpError,
+  SyncNetworkError,
+  TokenRejectedError,
   assertionConfigSchema,
   assertionResultRecordSchema,
   binaryVerdictSchema,
+  formatIngestResult,
+  ingest,
   parseRunResult,
+  readCairnRun,
+  reportIngestFailure,
+  reportSyncFailure,
   run,
-  runResultSchema
+  runResultSchema,
+  sync
 });

package/dist/index.d.cts

@@ -214,6 +214,57 @@ interface RunOptions {
 }
 declare function handleRun(options: RunOptions, depsFactory?: (config: Config, baseDir: string) => RunDeps): Promise<RunResult>;
 
+/** No saved token — the user must `plune login` before syncing. (exit 2) */
+declare class NotLoggedInError extends Error {
+    constructor();
+}
+/** The token was present but the server rejected it (401 — revoked or invalid). (exit 2) */
+declare class TokenRejectedError extends Error {
+    constructor();
+}
+/** No run to sync, or the run file is unreadable / not a valid RunResult. (exit 2) */
+declare class SyncFileError extends Error {
+    constructor(message: string);
+}
+/** The API was unreachable (DNS / TLS / offline). Message names the host, never the token. (exit 1) */
+declare class SyncNetworkError extends Error {
+    constructor(apiUrl: string);
+}
+/** The server answered with a non-2xx that is not a 401 (e.g. 400 invalid body, 5xx). (exit 1) */
+declare class SyncHttpError extends Error {
+    readonly status: number;
+    constructor(status: number, detail: string);
+}
+interface SyncDeps {
+    /** Base dir the default run file is read from (config dir or cwd). Defaults to `process.cwd()`. */
+    cwd?: string;
+    /** Explicit run JSON to sync instead of `<cwd>/.plune/last-run.json`. */
+    file?: string;
+    /** Override the API base URL. Falls back to `PLUNE_API_URL`, then the beta default. */
+    apiUrl?: string;
+    /** Token source (injected in tests). Defaults to the real credentials store. */
+    loadToken?: () => string | null;
+    /** HTTP transport (injected in tests — e.g. a real Hono app's `request`). Defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+interface SyncResult {
+    /** Server-assigned run id. */
+    id: string;
+    /** The `GET /v1/runs/:id` URL where the uploaded run can be read back. */
+    url: string;
+}
+/**
+ * Upload the latest (or `--file`) local run to `POST {apiUrl}/v1/runs` with the stored Bearer token.
+ * Returns the server-assigned id + the read-back URL. Throws a typed error (see the classes above) on
+ * every failure path so the CLI can exit cleanly without ever leaking the token or a stack trace.
+ */
+declare function handleSync(deps?: SyncDeps): Promise<SyncResult>;
+/**
+ * Map a `handleSync` rejection to a friendly stderr line + the exit code to use, or `null` if the error
+ * is not a known sync failure (caller then treats it as unexpected).
+ */
+declare function reportSyncFailure(err: unknown, write: (s: string) => void): number | null;
+
 declare const assertionConfigSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     type: z.ZodLiteral<"exact-match">;
     value: z.ZodString;
@@ -748,4 +799,70 @@ type BinaryVerdict = z.infer<typeof binaryVerdictSchema>;
 /** Parse + validate an unknown value as a RunResult. Throws ZodError on failure. */
 declare function parseRunResult(value: unknown): ParsedRunResult;
 
-export { type AssertionResultRecord, type BinaryVerdict, type Config, type EvalResult, type ParsedRunResult, RUN_RESULT_SCHEMA_VERSION, type RowResult, type RunError, type RunOptions, type RunResult, type Summary, type Usage, assertionConfigSchema, assertionResultRecordSchema, binaryVerdictSchema, parseRunResult, handleRun as run, runResultSchema };
+interface IngestDeps {
+    /** The Cairn run directory to read. */
+    dir: string;
+    apiUrl?: string;
+    loadToken?: () => string | null;
+    fetchImpl?: typeof fetch;
+}
+/** What the server recorded — the three counters that account for every case sent. */
+interface IngestResult {
+    runId: string;
+    linked: number;
+    proposed: number;
+    skipped: number;
+}
+declare function handleIngest(deps: IngestDeps): Promise<IngestResult>;
+/**
+ * Map an ingest failure to a stderr line and an exit code, or `null` when it is not ours to explain.
+ *
+ * The split follows `sync`: something the user can fix here and now exits 2, something that may work
+ * on the next attempt exits 1. A malformed or unfinished run is the user's to fix, so it is 2.
+ */
+declare function reportIngestFailure(err: unknown, write: (s: string) => void): number | null;
+/** One line per counter, in the order a reader cares about: what landed, what needs them, what did not. */
+declare function formatIngestResult(r: IngestResult): string;
+
+/** The payload version the Plune ingest endpoint validates — ours, not Cairn's. */
+declare const INGEST_SCHEMA_VERSION = 1;
+type CairnRunMode = 'explore' | 'design' | 'api';
+type CairnExecution = 'auto' | 'manual';
+type CairnVerdict = 'passed' | 'failed';
+interface CairnIngestCase {
+    stableId: string;
+    title: string;
+    execution: CairnExecution;
+    steps: string[];
+    expected: string;
+    /** Absent means the run never executed this case — NOT "no result yet". */
+    verdict?: CairnVerdict;
+    technique?: string;
+    priority?: string;
+}
+interface CairnIngestPayload {
+    schemaVersion: typeof INGEST_SCHEMA_VERSION;
+    run: {
+        runId: string;
+        mode: CairnRunMode;
+        target: string;
+    };
+    cases: CairnIngestCase[];
+}
+interface EvidenceRecord {
+    name: string;
+    passed: boolean;
+}
+interface ReadCairnRunDeps {
+    /** Injected for tests; returns `undefined` when the run executed nothing and wrote no evidence. */
+    readEvidence?: (dir: string) => Promise<EvidenceRecord[] | undefined>;
+}
+/**
+ * Read a Cairn run directory into an upload payload, or throw a typed error explaining why not.
+ *
+ * Pure apart from the two file reads, which are injectable, so the mapping rules can be exercised
+ * against real artifacts without a filesystem dance.
+ */
+declare function readCairnRun(dir: string, deps?: ReadCairnRunDeps): Promise<CairnIngestPayload>;
+
+export { type AssertionResultRecord, type BinaryVerdict, type CairnIngestCase, type CairnIngestPayload, type Config, type EvalResult, type IngestDeps, type IngestResult, NotLoggedInError, type ParsedRunResult, RUN_RESULT_SCHEMA_VERSION, type RowResult, type RunError, type RunOptions, type RunResult, type Summary, type SyncDeps, SyncFileError, SyncHttpError, SyncNetworkError, type SyncResult, TokenRejectedError, type Usage, assertionConfigSchema, assertionResultRecordSchema, binaryVerdictSchema, formatIngestResult, handleIngest as ingest, parseRunResult, readCairnRun, reportIngestFailure, reportSyncFailure, handleRun as run, runResultSchema, handleSync as sync };

package/dist/index.d.ts

@@ -214,6 +214,57 @@ interface RunOptions {
 }
 declare function handleRun(options: RunOptions, depsFactory?: (config: Config, baseDir: string) => RunDeps): Promise<RunResult>;
 
+/** No saved token — the user must `plune login` before syncing. (exit 2) */
+declare class NotLoggedInError extends Error {
+    constructor();
+}
+/** The token was present but the server rejected it (401 — revoked or invalid). (exit 2) */
+declare class TokenRejectedError extends Error {
+    constructor();
+}
+/** No run to sync, or the run file is unreadable / not a valid RunResult. (exit 2) */
+declare class SyncFileError extends Error {
+    constructor(message: string);
+}
+/** The API was unreachable (DNS / TLS / offline). Message names the host, never the token. (exit 1) */
+declare class SyncNetworkError extends Error {
+    constructor(apiUrl: string);
+}
+/** The server answered with a non-2xx that is not a 401 (e.g. 400 invalid body, 5xx). (exit 1) */
+declare class SyncHttpError extends Error {
+    readonly status: number;
+    constructor(status: number, detail: string);
+}
+interface SyncDeps {
+    /** Base dir the default run file is read from (config dir or cwd). Defaults to `process.cwd()`. */
+    cwd?: string;
+    /** Explicit run JSON to sync instead of `<cwd>/.plune/last-run.json`. */
+    file?: string;
+    /** Override the API base URL. Falls back to `PLUNE_API_URL`, then the beta default. */
+    apiUrl?: string;
+    /** Token source (injected in tests). Defaults to the real credentials store. */
+    loadToken?: () => string | null;
+    /** HTTP transport (injected in tests — e.g. a real Hono app's `request`). Defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+interface SyncResult {
+    /** Server-assigned run id. */
+    id: string;
+    /** The `GET /v1/runs/:id` URL where the uploaded run can be read back. */
+    url: string;
+}
+/**
+ * Upload the latest (or `--file`) local run to `POST {apiUrl}/v1/runs` with the stored Bearer token.
+ * Returns the server-assigned id + the read-back URL. Throws a typed error (see the classes above) on
+ * every failure path so the CLI can exit cleanly without ever leaking the token or a stack trace.
+ */
+declare function handleSync(deps?: SyncDeps): Promise<SyncResult>;
+/**
+ * Map a `handleSync` rejection to a friendly stderr line + the exit code to use, or `null` if the error
+ * is not a known sync failure (caller then treats it as unexpected).
+ */
+declare function reportSyncFailure(err: unknown, write: (s: string) => void): number | null;
+
 declare const assertionConfigSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     type: z.ZodLiteral<"exact-match">;
     value: z.ZodString;
@@ -748,4 +799,70 @@ type BinaryVerdict = z.infer<typeof binaryVerdictSchema>;
 /** Parse + validate an unknown value as a RunResult. Throws ZodError on failure. */
 declare function parseRunResult(value: unknown): ParsedRunResult;
 
-export { type AssertionResultRecord, type BinaryVerdict, type Config, type EvalResult, type ParsedRunResult, RUN_RESULT_SCHEMA_VERSION, type RowResult, type RunError, type RunOptions, type RunResult, type Summary, type Usage, assertionConfigSchema, assertionResultRecordSchema, binaryVerdictSchema, parseRunResult, handleRun as run, runResultSchema };
+interface IngestDeps {
+    /** The Cairn run directory to read. */
+    dir: string;
+    apiUrl?: string;
+    loadToken?: () => string | null;
+    fetchImpl?: typeof fetch;
+}
+/** What the server recorded — the three counters that account for every case sent. */
+interface IngestResult {
+    runId: string;
+    linked: number;
+    proposed: number;
+    skipped: number;
+}
+declare function handleIngest(deps: IngestDeps): Promise<IngestResult>;
+/**
+ * Map an ingest failure to a stderr line and an exit code, or `null` when it is not ours to explain.
+ *
+ * The split follows `sync`: something the user can fix here and now exits 2, something that may work
+ * on the next attempt exits 1. A malformed or unfinished run is the user's to fix, so it is 2.
+ */
+declare function reportIngestFailure(err: unknown, write: (s: string) => void): number | null;
+/** One line per counter, in the order a reader cares about: what landed, what needs them, what did not. */
+declare function formatIngestResult(r: IngestResult): string;
+
+/** The payload version the Plune ingest endpoint validates — ours, not Cairn's. */
+declare const INGEST_SCHEMA_VERSION = 1;
+type CairnRunMode = 'explore' | 'design' | 'api';
+type CairnExecution = 'auto' | 'manual';
+type CairnVerdict = 'passed' | 'failed';
+interface CairnIngestCase {
+    stableId: string;
+    title: string;
+    execution: CairnExecution;
+    steps: string[];
+    expected: string;
+    /** Absent means the run never executed this case — NOT "no result yet". */
+    verdict?: CairnVerdict;
+    technique?: string;
+    priority?: string;
+}
+interface CairnIngestPayload {
+    schemaVersion: typeof INGEST_SCHEMA_VERSION;
+    run: {
+        runId: string;
+        mode: CairnRunMode;
+        target: string;
+    };
+    cases: CairnIngestCase[];
+}
+interface EvidenceRecord {
+    name: string;
+    passed: boolean;
+}
+interface ReadCairnRunDeps {
+    /** Injected for tests; returns `undefined` when the run executed nothing and wrote no evidence. */
+    readEvidence?: (dir: string) => Promise<EvidenceRecord[] | undefined>;
+}
+/**
+ * Read a Cairn run directory into an upload payload, or throw a typed error explaining why not.
+ *
+ * Pure apart from the two file reads, which are injectable, so the mapping rules can be exercised
+ * against real artifacts without a filesystem dance.
+ */
+declare function readCairnRun(dir: string, deps?: ReadCairnRunDeps): Promise<CairnIngestPayload>;
+
+export { type AssertionResultRecord, type BinaryVerdict, type CairnIngestCase, type CairnIngestPayload, type Config, type EvalResult, type IngestDeps, type IngestResult, NotLoggedInError, type ParsedRunResult, RUN_RESULT_SCHEMA_VERSION, type RowResult, type RunError, type RunOptions, type RunResult, type Summary, type SyncDeps, SyncFileError, SyncHttpError, SyncNetworkError, type SyncResult, TokenRejectedError, type Usage, assertionConfigSchema, assertionResultRecordSchema, binaryVerdictSchema, formatIngestResult, handleIngest as ingest, parseRunResult, readCairnRun, reportIngestFailure, reportSyncFailure, handleRun as run, runResultSchema, handleSync as sync };