@wirecat/cli-core 0.370.0 → 0.372.0

package/CHANGELOG.md

@@ -7,6 +7,43 @@ shape of this file.
 
 ## Unreleased
 
+## 0.372.0 — 20.10.2026
+
+### Added
+
+- **Setup wizard helpers from `./cli`**: `AGENTS`, `type Agent`, `screenFor(context, quiet, steps)` and
+  `agentFor(context, given, pad, prompt?)`, for the `setup` command of a messenger CLI. `screenFor` prints the
+  numbered step headings (`[2/5] …`, details indented by 6) to stderr for a person, hides them under `--quiet`,
+  and keeps plain notes in a machine mode. `agentFor` asks which agent to install only at a terminal in the pretty
+  format and answers `none` otherwise; an unknown answer is a `validation_error`. Both take the minimum shape they
+  read (`format`, `streams.diagnostic`, `renderer.note`, `stdin`), so tg-cli's and whatsapp-cli's contexts fit as they
+  are. Pass the wizard's step count as `steps`, and the prompt's `input`, `output` and `signal` as `prompt`
+  (`secretInputOf(command)` plus the signal, or `{ input: context.stdin }`). No profile or agent is chosen for the
+  caller. This replaces the copies in both CLIs' `src/commands/setup.ts`.
+- **`restartServers(app, script, env, spawn?)` from `./cli`** restarts the `serve` of every profile that is running,
+  with `<script> <profile> server restart`, and answers `{ restarted, left }`: the shape `upgradeCommand`'s
+  `afterUpdate` port returns, so `afterUpdate: () => restartServers(app, script, env, environment.spawn)` is the whole
+  host side. `script` is the new install's own entry point; `spawn` replaces the child process in a test. A serve started
+  by hand refuses the restart and lands in `left`. This replaces the copies in both CLIs' `src/commands/update.ts` and
+  `src/update.ts`.
+- **`ARGV_LOG` and `argvLogSetup` from `./testing`**: the path `coverage/argv.jsonl` under the working directory, and
+  a vitest `globalSetup` function that clears it, for the test matrix that checks which commands and options a run
+  drove. A CLI's own `src/testing/argv-log.ts` can go. Vitest takes a package specifier as `globalSetup` only with a
+  named `setup` or a default export, so keep a one-line file: `export { argvLogSetup as default } from
+  "@wirecat/cli-core/testing"`.
+
+## 0.371.0 — 20.10.2026
+
+### Added
+
+- **Project annotation manifest validation from `./store`** checks a bounded, versioned JSON graph of
+  project aliases, facts and direct links with explicit external dependencies and omitted facets.
+  `decodeProjectAnnotations` validates it, `projectAnnotationsFingerprint` hashes its normalized
+  form, and `planProjectAnnotations` checks explicit bindings against a complete target snapshot.
+  These helpers do not export a store, restore records or authorize confirmation.
+- **`documentPassage` from `./services`** gives hosts the same bounded paragraph context that project gathering
+  uses, so a findings review can show the paragraphs around its cited document without copying that logic.
+
 ## 0.370.0 — 20.10.2026
 
 ### Changed — may break callers

package/dist/cli/index.d.ts

@@ -127,7 +127,8 @@ export { createProgram, type ProgramDefinition, type ProgramOptions, type RunOpt
 export { fieldsOf, projectFields } from "./result-fields.js";
 export { runsCommand } from "./runs/command.js";
 export { type Config, type Configuration, count, first, flag, fromFile, type GlobalFlags, NONE_NAMED, type ProfileKind, plain, type ResolveOptions, type Settings, type SettingsExtension, type SettingsExtensionContext, type Source, settingsFor, } from "./settings.js";
+export { AGENTS, type Agent, agentFor, screenFor } from "./setup-screen.js";
 export { skillCommand } from "./skill-command.js";
 export { runnable, withSafety } from "./steps.js";
 export { changeStoreSetting, isStoreSetting, STORE_SETTINGS, storeSettings } from "./store-settings.js";
-export { type UpgradeContext, upgradeCommand } from "./upgrade-command.js";
+export { restartServers, type UpgradeContext, upgradeCommand } from "./upgrade-command.js";

package/dist/cli/index.js

@@ -122,7 +122,8 @@ export { createProgram, run } from "./program.js";
 export { fieldsOf, projectFields } from "./result-fields.js";
 export { runsCommand } from "./runs/command.js";
 export { count, first, flag, fromFile, NONE_NAMED, plain, settingsFor, } from "./settings.js";
+export { AGENTS, agentFor, screenFor } from "./setup-screen.js";
 export { skillCommand } from "./skill-command.js";
 export { runnable, withSafety } from "./steps.js";
 export { changeStoreSetting, isStoreSetting, STORE_SETTINGS, storeSettings } from "./store-settings.js";
-export { upgradeCommand } from "./upgrade-command.js";
+export { restartServers, upgradeCommand } from "./upgrade-command.js";

package/dist/cli/setup-screen.d.ts

@@ -0,0 +1,25 @@
+import { type Renderer, type RenderFormat, type Streams } from "@wirecat/cli-base";
+import { type SecretInput } from "../terminal/prompt.js";
+export declare const AGENTS: readonly ["none", "codex", "cursor", "claude", "gemini", "all"];
+export type Agent = (typeof AGENTS)[number];
+/**
+ * A person sees each step as a heading with its details indented under it. `--quiet` hides both, as it
+ * hides notes; a machine mode keeps the plain notes it always had, since stderr there is a log.
+ */
+export declare const screenFor: (context: {
+    format: RenderFormat;
+    streams: Pick<Streams, "diagnostic">;
+    renderer: Pick<Renderer, "note">;
+}, quiet: boolean, steps: number) => {
+    step: (index: number, title: string) => void;
+    detail: (text: string) => void;
+    title: (text: string) => void;
+    indent: number;
+};
+/** Asks only a person at a terminal; every other run gets "none", so no agent is ever installed unasked. */
+export declare const agentFor: (context: {
+    format: RenderFormat;
+    stdin: NodeJS.ReadableStream & {
+        isTTY?: boolean;
+    };
+}, given: Agent | undefined, pad: number, prompt?: Pick<SecretInput, "input" | "output" | "signal">) => Promise<Agent>;

package/dist/cli/setup-screen.js

@@ -0,0 +1,39 @@
+import { CliError, indent } from "@wirecat/cli-base";
+import { readSecret } from "../terminal/prompt.js";
+import { inputPolicy } from "./input-policy.js";
+export const AGENTS = ["none", "codex", "cursor", "claude", "gemini", "all"];
+const DETAIL = 6;
+/**
+ * A person sees each step as a heading with its details indented under it. `--quiet` hides both, as it
+ * hides notes; a machine mode keeps the plain notes it always had, since stderr there is a log.
+ */
+export const screenFor = (context, quiet, steps) => {
+    const person = context.format === "pretty";
+    const say = (text) => {
+        if (!quiet)
+            context.streams.diagnostic(text);
+    };
+    return {
+        step: (index, title) => person ? say(`\n[${index}/${steps}] ${title}`) : context.renderer.note(`${index}/${steps} — ${title}`),
+        detail: (text) => (person ? say(indent(text, DETAIL)) : context.renderer.note(text)),
+        title: (text) => (person ? say(text) : context.renderer.note(text)),
+        indent: person ? DETAIL : 0,
+    };
+};
+/** Asks only a person at a terminal; every other run gets "none", so no agent is ever installed unasked. */
+export const agentFor = async (context, given, pad, prompt = {}) => {
+    if (given)
+        return given;
+    if (context.format !== "pretty" || !context.stdin.isTTY || inputPolicy(context.stdin).noInput)
+        return "none";
+    const answer = (await readSecret(`${" ".repeat(pad)}Agent [codex/cursor/claude/gemini/all/none] (none): `, {
+        ...prompt,
+        echo: true,
+    }))
+        .trim()
+        .toLowerCase() || "none";
+    const agent = AGENTS.find((known) => known === answer);
+    if (agent === undefined)
+        throw new CliError("validation_error", `unknown agent — choose ${AGENTS.join(", ")} with --agent`);
+    return agent;
+};

package/dist/cli/upgrade-command.d.ts

@@ -7,4 +7,13 @@ export interface UpgradeContext extends Omit<PackageUpgradePorts, "onInstall"> {
     format: RenderFormat;
     streams: Streams;
 }
+/**
+ * A running serve keeps the code it started with; the update replaced the files under it. Each is restarted by
+ * the new `script` — `server restart` refuses a serve started by hand, which is then named in `left`.
+ * `spawn` replaces the child process, as in `UpdateEnvironment`.
+ */
+export declare const restartServers: (app: AppIdentity, script: string, env: NodeJS.ProcessEnv, spawn?: (argv: string[]) => number) => {
+    restarted: string[];
+    left: string[];
+};
 export declare const upgradeCommand: (app: AppIdentity, packageName: string, contextFor: (command: Command) => UpgradeContext) => Command;

package/dist/cli/upgrade-command.js

@@ -1,9 +1,35 @@
+import { spawnSync } from "node:child_process";
 import { CliError } from "@wirecat/cli-base";
 import { annotate } from "@wirecat/cli-base/commands";
 import { Command } from "commander";
+import { servingProfiles } from "../background/lock.js";
 import { upgradePackage } from "../services/package-upgrade.js";
 import { grantsAuthority, LOCAL_WRITE } from "./effects.js";
 import { itemOf, renderAnswer, snakeKeys } from "./envelope.js";
+import { usableProfileName } from "./profile.js";
+/**
+ * A running serve keeps the code it started with; the update replaced the files under it. Each is restarted by
+ * the new `script` — `server restart` refuses a serve started by hand, which is then named in `left`.
+ * `spawn` replaces the child process, as in `UpdateEnvironment`.
+ */
+export const restartServers = (app, script, env, spawn) => {
+    const restarted = [];
+    const left = [];
+    for (const profile of servingProfiles(app, env)) {
+        try {
+            usableProfileName(profile);
+        }
+        catch {
+            continue;
+        }
+        const argv = [script, profile, "server", "restart"];
+        const code = spawn
+            ? spawn([process.execPath, ...argv])
+            : (spawnSync(process.execPath, argv, { env, shell: false, stdio: ["ignore", 2, 2] }).status ?? 1);
+        (code === 0 ? restarted : left).push(profile);
+    }
+    return { restarted, left };
+};
 export const upgradeCommand = (app, packageName, contextFor) => grantsAuthority(annotate(new Command("upgrade"), {
     effects: LOCAL_WRITE,
     mcp: false,

package/dist/kit/argv-log.d.ts

@@ -0,0 +1,4 @@
+/** Where each test run records which commands and options it drove (`pnpm test:matrix`). */
+export declare const ARGV_LOG: string;
+/** A vitest `globalSetup`: one run, one log. */
+export declare const argvLogSetup: () => void;

package/dist/kit/argv-log.js

@@ -0,0 +1,9 @@
+import { mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+/** Where each test run records which commands and options it drove (`pnpm test:matrix`). */
+export const ARGV_LOG = join(process.cwd(), "coverage", "argv.jsonl");
+/** A vitest `globalSetup`: one run, one log. */
+export const argvLogSetup = () => {
+    mkdirSync(join(process.cwd(), "coverage"), { recursive: true });
+    rmSync(ARGV_LOG, { force: true });
+};

package/dist/kit/index.d.ts

@@ -1,3 +1,4 @@
+export { ARGV_LOG, argvLogSetup } from "./argv-log.js";
 export { type ContractCase, type ContractOptions, contractCases, OPTIONAL_METHODS } from "./contract.js";
 export { type FakeAdapter, fakeAdapter } from "./fake.js";
 export { type McpStdio, type McpStdioStreams, type McpToolResult, mcpOverStdio } from "./mcp-stdio.js";

package/dist/kit/index.js

@@ -1,3 +1,4 @@
+export { ARGV_LOG, argvLogSetup } from "./argv-log.js";
 export { contractCases, OPTIONAL_METHODS } from "./contract.js";
 export { fakeAdapter } from "./fake.js";
 export { mcpOverStdio } from "./mcp-stdio.js";

package/dist/services/index.d.ts

@@ -6,7 +6,7 @@ export { type DownloadedModel, downloadImageModel, downloadTextModel, type Model
 export type { ProjectEvidenceItem, ProjectGathering, ProjectGatheringPorts, ProjectGatheringStop, ProjectIndexCatchUp, ProjectSourceFetcher, } from "./project-gathering.js";
 export { gatherProjectEvidence } from "./project-gathering.js";
 export type { ProjectNeighbour, ProjectNeighbourReader } from "./project-gathering-around.js";
-export { storedMessageNeighbours, storedNeighbours } from "./project-gathering-around.js";
+export { documentPassage, storedMessageNeighbours, storedNeighbours } from "./project-gathering-around.js";
 export type { EvidenceMention, EvidenceMentions } from "./project-gathering-mentions.js";
 export { findEvidenceMentions } from "./project-gathering-mentions.js";
 export type { ProjectFetchState, ProjectGatheringBudgets, ProjectGatheringRequest, ProjectLane, ProjectLaneKind, ProjectUnitState, } from "./project-gathering-request.js";

package/dist/services/index.js

@@ -3,7 +3,7 @@ export { contextEvidenceFingerprint, createContextEvidenceReader } from "./conte
 export { excerpt } from "./excerpt.js";
 export { downloadImageModel, downloadTextModel, } from "./model-downloads.js";
 export { gatherProjectEvidence } from "./project-gathering.js";
-export { storedMessageNeighbours, storedNeighbours } from "./project-gathering-around.js";
+export { documentPassage, storedMessageNeighbours, storedNeighbours } from "./project-gathering-around.js";
 export { findEvidenceMentions } from "./project-gathering-mentions.js";
 import { accountService } from "./account.js";
 import { adminService } from "./admin.js";

package/dist/store/index.d.ts

@@ -14,6 +14,8 @@ export type { MeetingFindingsBatch, MeetingFindingsStore } from "./meeting-findi
 export { MIGRATIONS, type Migration, migrate } from "./migrations.js";
 export { openCache } from "./open.js";
 export { storePath } from "./path.js";
+export { decodeProjectAnnotations, PROJECT_ANNOTATIONS_MAX_BYTES, type ProjectAnnotations, projectAnnotationsFingerprint, } from "./project-transfer/manifest.js";
+export { type ProjectAnnotationsPlan, type ProjectAnnotationsTarget, planProjectAnnotations, } from "./project-transfer/plan.js";
 export type { AgentAction, AgentActionInput, AgentActionsStore } from "./sqlite/agent-actions.js";
 export { resetAttachmentWords } from "./sqlite/attachment-texts.js";
 export { backfillNormalized, pendingNormalization } from "./sqlite/backfill.js";

package/dist/store/index.js

@@ -6,6 +6,8 @@ export { EVIDENCE_FINDINGS_KIND, validateEvidenceFindings, } from "./evidence-fi
 export { MIGRATIONS, migrate } from "./migrations.js";
 export { openCache } from "./open.js";
 export { storePath } from "./path.js";
+export { decodeProjectAnnotations, PROJECT_ANNOTATIONS_MAX_BYTES, projectAnnotationsFingerprint, } from "./project-transfer/manifest.js";
+export { planProjectAnnotations, } from "./project-transfer/plan.js";
 export { resetAttachmentWords } from "./sqlite/attachment-texts.js";
 export { backfillNormalized, pendingNormalization } from "./sqlite/backfill.js";
 export { CATALOG_QUERY } from "./sqlite/catalog.js";

package/dist/store/project-transfer/manifest.d.ts

@@ -0,0 +1,6 @@
+import { type ProjectAnnotations } from "./schema.js";
+export type { ProjectAnnotations } from "./schema.js";
+export declare const PROJECT_ANNOTATIONS_MAX_BYTES: number;
+/** Decode bounded JSON, never a row/column importer or an implicit whole-project backup. */
+export declare const decodeProjectAnnotations: (json: string) => ProjectAnnotations;
+export declare const projectAnnotationsFingerprint: (json: string) => string;

package/dist/store/project-transfer/manifest.js

@@ -0,0 +1,138 @@
+import { createHash } from "node:crypto";
+import { CliError } from "@wirecat/cli-base";
+import * as v from "valibot";
+import { canonicalReference, parseReference } from "../../domain/references.js";
+import { normalizeVocabularyName } from "../../domain/vocabulary.js";
+import { canonicalMeetingReference } from "../../meetings/index.js";
+import { projectAnnotationsSchema } from "./schema.js";
+export const PROJECT_ANNOTATIONS_MAX_BYTES = 4 * 1024 * 1024;
+const invalid = (field) => {
+    throw new CliError("validation_error", `invalid project annotations.${field}`);
+};
+const canonical = (ref) => {
+    try {
+        return ref.startsWith("meeting:") ? canonicalMeetingReference(ref) : canonicalReference(ref);
+    }
+    catch {
+        return invalid("reference");
+    }
+};
+const graph = (manifest) => {
+    const owned = new Set([manifest.project.ref]);
+    const external = new Set();
+    const used = new Set();
+    const kind = (ref, kinds) => {
+        if (canonical(ref) !== ref || !kinds.includes(parseReference(ref).type) || !/^[a-z]+:[1-9]\d*$/.test(ref))
+            invalid("reference kind");
+    };
+    kind(manifest.project.ref, ["project"]);
+    for (const fact of manifest.facts) {
+        kind(fact.ref, ["fact"]);
+        if (owned.has(fact.ref))
+            invalid("facts.duplicate");
+        owned.add(fact.ref);
+        kind(fact.author, ["person", "bot"]);
+        if (fact.confirmed_by !== null)
+            kind(fact.confirmed_by, ["person", "bot"]);
+        if (fact.updated_at < fact.created_at)
+            invalid("facts.updated_at");
+        if (fact.type !== "decision" && (fact.supersedes !== null || ["superseded", "reversed"].includes(fact.status)))
+            invalid("facts.lifecycle");
+        if (fact.supersedes === fact.ref)
+            invalid("facts.supersedes");
+    }
+    for (const item of manifest.external) {
+        if (canonical(item.ref) !== item.ref || owned.has(item.ref) || external.has(item.ref))
+            invalid("external.ref");
+        external.add(item.ref);
+        const body = /^(msg|document|note|meeting):/.test(item.ref);
+        if (body !== (item.content_sha256 !== null))
+            invalid("external.content_sha256");
+    }
+    const dependency = (ref) => {
+        if (ref === null)
+            return;
+        if (canonical(ref) !== ref || (!owned.has(ref) && !external.has(ref)))
+            invalid("missing dependency");
+        used.add(ref);
+    };
+    if (manifest.project.organization !== null)
+        kind(manifest.project.organization, ["organization"]);
+    dependency(manifest.project.organization);
+    const aliases = new Set([manifest.project.name, manifest.project.key].map(normalizeVocabularyName));
+    for (const alias of manifest.aliases) {
+        const name = normalizeVocabularyName(alias);
+        if (aliases.has(name))
+            invalid("aliases.duplicate");
+        aliases.add(name);
+    }
+    for (const fact of manifest.facts) {
+        for (const ref of [fact.author, fact.confirmed_by, fact.subject, fact.supersedes])
+            dependency(ref);
+        if (fact.supersedes !== null) {
+            kind(fact.supersedes, ["fact"]);
+            if (!manifest.facts.some((previous) => previous.ref === fact.supersedes && previous.type === "decision"))
+                invalid("facts.supersedes outside project");
+        }
+    }
+    const previous = new Map(manifest.facts.map((fact) => [fact.ref, fact.supersedes]));
+    for (const fact of manifest.facts) {
+        const path = new Set();
+        let ref = fact.ref;
+        while (ref) {
+            if (path.has(ref))
+                invalid("facts.supersedes cycle");
+            path.add(ref);
+            ref = previous.get(ref);
+        }
+    }
+    const links = new Set();
+    for (const link of manifest.links) {
+        if (!/^link:[1-9]\d*$/.test(link.ref) || links.has(link.ref))
+            invalid("links.ref");
+        links.add(link.ref);
+        if (!owned.has(link.from) && (link.to === null || !owned.has(link.to)))
+            invalid("links.outside project");
+        if (link.to === null && link.target_text === null)
+            invalid("links.target_text");
+        if (link.updated_at < link.created_at)
+            invalid("links.updated_at");
+        for (const ref of [link.from, link.to])
+            dependency(ref);
+    }
+    for (const ref of external)
+        if (!used.has(ref))
+            invalid("external.unused");
+};
+/** Decode bounded JSON, never a row/column importer or an implicit whole-project backup. */
+export const decodeProjectAnnotations = (json) => {
+    if (typeof json !== "string" || Buffer.byteLength(json) > PROJECT_ANNOTATIONS_MAX_BYTES)
+        invalid("bytes");
+    let input;
+    try {
+        input = JSON.parse(json);
+    }
+    catch {
+        return invalid("json");
+    }
+    const parsed = v.safeParse(projectAnnotationsSchema, input);
+    if (!parsed.success)
+        return invalid(parsed.issues[0]?.path?.map((part) => String(part.key)).join(".") ?? "manifest");
+    const manifest = parsed.output;
+    if (manifest.aliases.length + manifest.facts.length + manifest.links.length + manifest.external.length > 1000)
+        invalid("record budget");
+    graph(manifest);
+    return manifest;
+};
+export const projectAnnotationsFingerprint = (json) => {
+    const manifest = decodeProjectAnnotations(json);
+    const normalized = {
+        ...manifest,
+        aliases: manifest.aliases.toSorted(),
+        facts: manifest.facts.toSorted((a, b) => (a.ref < b.ref ? -1 : a.ref > b.ref ? 1 : 0)),
+        links: manifest.links.toSorted((a, b) => a.ref.localeCompare(b.ref)),
+        external: manifest.external.toSorted((a, b) => a.ref.localeCompare(b.ref)),
+    };
+    // Strict decoding fixes object key order; record arrays have identity, unlike text and timestamps.
+    return createHash("sha256").update(JSON.stringify(normalized)).digest("hex");
+};

package/dist/store/project-transfer/plan.d.ts

@@ -0,0 +1,28 @@
+import * as v from "valibot";
+declare const targetSchema: v.StrictObjectSchema<{
+    readonly project: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>;
+    readonly revision_sha256: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>;
+    readonly annotation_count: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.SafeIntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly external: v.SchemaWithPipe<readonly [v.ArraySchema<v.StrictObjectSchema<{
+        readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 2048, undefined>]>;
+        readonly content_sha256: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>, undefined>;
+    }, undefined>, undefined>, v.MaxLengthAction<{
+        ref: string;
+        content_sha256: string | null;
+    }[], 1000, undefined>]>;
+}, undefined>;
+export type ProjectAnnotationsTarget = v.InferOutput<typeof targetSchema>;
+export interface ProjectAnnotationsPlan {
+    fingerprint: string;
+    manifest_fingerprint: string;
+    target_revision_sha256: string;
+    missing_bindings: string[];
+    conflicts: {
+        reference: string;
+        reason: "missing" | "wrong_kind" | "changed" | "populated" | "duplicate";
+    }[];
+    ready: boolean;
+}
+/** Pure planning over an adapter's complete target snapshot; a ready plan is not write authorization. */
+export declare const planProjectAnnotations: (json: string, target: ProjectAnnotationsTarget, bindings: Record<string, string>) => ProjectAnnotationsPlan;
+export {};

package/dist/store/project-transfer/plan.js

@@ -0,0 +1,106 @@
+import { createHash } from "node:crypto";
+import { CliError } from "@wirecat/cli-base";
+import * as v from "valibot";
+import { canonicalReference, parseReference } from "../../domain/references.js";
+import { canonicalMeetingReference } from "../../meetings/index.js";
+import { decodeProjectAnnotations, projectAnnotationsFingerprint } from "./manifest.js";
+const hash = v.pipe(v.string(), v.regex(/^[a-f0-9]{64}$/));
+const ref = v.pipe(v.string(), v.minLength(1), v.maxLength(2048));
+const targetSchema = v.strictObject({
+    project: v.pipe(v.string(), v.regex(/^project:[1-9]\d*$/)),
+    revision_sha256: hash,
+    annotation_count: v.pipe(v.number(), v.safeInteger(), v.minValue(0)),
+    external: v.pipe(v.array(v.strictObject({ ref, content_sha256: v.nullable(hash) })), v.maxLength(1000)),
+});
+const kind = (ref) => {
+    if (ref.startsWith("meeting:")) {
+        if (canonicalMeetingReference(ref) !== ref)
+            throw new Error("noncanonical");
+        return `meeting:${ref.split("/").length}`;
+    }
+    if (canonicalReference(ref) !== ref)
+        throw new Error("noncanonical");
+    const parsed = parseReference(ref);
+    return "provider" in parsed ? `${parsed.type}:${parsed.provider}` : parsed.type;
+};
+const invalid = (field) => {
+    throw new CliError("validation_error", `invalid project annotation plan.${field}`);
+};
+/** Pure planning over an adapter's complete target snapshot; a ready plan is not write authorization. */
+export const planProjectAnnotations = (json, target, bindings) => {
+    const manifest = decodeProjectAnnotations(json);
+    const checked = v.safeParse(targetSchema, target);
+    if (!checked.success)
+        return invalid(checked.issues[0]?.path?.map((p) => String(p.key)).join(".") ?? "target");
+    if (!bindings || typeof bindings !== "object" || Array.isArray(bindings) || Object.keys(bindings).length > 1001)
+        return invalid("bindings");
+    if (Object.getPrototypeOf(bindings) !== Object.prototype && Object.getPrototypeOf(bindings) !== null)
+        return invalid("bindings");
+    const required = new Set([manifest.project.ref, ...manifest.external.map((item) => item.ref)]);
+    for (const [source, destination] of Object.entries(bindings))
+        if (!required.has(source) || typeof destination !== "string" || destination.length > 2048)
+            return invalid("bindings");
+    const destinations = new Map();
+    for (const item of checked.output.external) {
+        try {
+            kind(item.ref);
+        }
+        catch {
+            return invalid("target.external.ref");
+        }
+        if (destinations.has(item.ref) || item.ref === target.project)
+            return invalid("target.external.duplicate");
+        destinations.set(item.ref, item.content_sha256);
+    }
+    const missing_bindings = [], conflicts = [];
+    const used = new Set();
+    for (const source of required) {
+        const destination = bindings[source];
+        if (destination === undefined) {
+            missing_bindings.push(source);
+            continue;
+        }
+        try {
+            if (kind(source) !== kind(destination)) {
+                conflicts.push({ reference: source, reason: "wrong_kind" });
+                continue;
+            }
+        }
+        catch {
+            return invalid("bindings.reference");
+        }
+        if (used.has(destination))
+            conflicts.push({ reference: source, reason: "duplicate" });
+        used.add(destination);
+        if (source === manifest.project.ref) {
+            if (destination !== target.project)
+                conflicts.push({ reference: source, reason: "missing" });
+            continue;
+        }
+        if (!destinations.has(destination))
+            conflicts.push({ reference: source, reason: "missing" });
+        else if (destinations.get(destination) !== manifest.external.find((item) => item.ref === source)?.content_sha256)
+            conflicts.push({ reference: source, reason: "changed" });
+    }
+    if (target.annotation_count > 0)
+        conflicts.push({ reference: target.project, reason: "populated" });
+    const manifest_fingerprint = projectAnnotationsFingerprint(json);
+    const fingerprint = createHash("sha256")
+        .update(JSON.stringify({
+        manifest_fingerprint,
+        target: {
+            ...checked.output,
+            external: checked.output.external.toSorted((a, b) => (a.ref < b.ref ? -1 : a.ref > b.ref ? 1 : 0)),
+        },
+        bindings: Object.fromEntries(Object.entries(bindings).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))),
+    }))
+        .digest("hex");
+    return {
+        fingerprint,
+        manifest_fingerprint,
+        target_revision_sha256: target.revision_sha256,
+        missing_bindings,
+        conflicts,
+        ready: missing_bindings.length === 0 && conflicts.length === 0,
+    };
+};

package/dist/store/project-transfer/schema.d.ts

@@ -0,0 +1,94 @@
+import * as v from "valibot";
+export declare const projectAnnotationsSchema: v.StrictObjectSchema<{
+    readonly format: v.LiteralSchema<"wirecat.project-annotations", undefined>;
+    readonly version: v.LiteralSchema<1, undefined>;
+    readonly project: v.StrictObjectSchema<{
+        readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>;
+        readonly key: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>;
+        readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>;
+        readonly type: v.PicklistSchema<["work", "client", "personal", "oss", "other"], undefined>;
+        readonly scope: v.PicklistSchema<readonly ["personal", "work"], undefined>;
+        readonly organization: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>, undefined>;
+        readonly created_at: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.SafeIntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    }, undefined>;
+    readonly coverage: v.StrictObjectSchema<{
+        readonly aliases: v.LiteralSchema<"complete", undefined>;
+        readonly facts: v.LiteralSchema<"complete", undefined>;
+        readonly links: v.LiteralSchema<"complete", undefined>;
+        readonly memories: v.LiteralSchema<"omitted", undefined>;
+        readonly tasks: v.LiteralSchema<"omitted", undefined>;
+        readonly labels: v.LiteralSchema<"omitted", undefined>;
+        readonly findings: v.LiteralSchema<"omitted", undefined>;
+    }, undefined>;
+    readonly aliases: v.SchemaWithPipe<readonly [v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>, undefined>, v.MaxLengthAction<string[], 1000, undefined>]>;
+    readonly facts: v.SchemaWithPipe<readonly [v.ArraySchema<v.StrictObjectSchema<{
+        readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>;
+        readonly type: v.PicklistSchema<readonly ["fact", "statement", "question", "decision", "promise"], undefined>;
+        readonly statement: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>;
+        readonly status: v.PicklistSchema<readonly ["proposed", "accepted", "superseded", "reversed"], undefined>;
+        readonly subject: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>, undefined>;
+        readonly occurred_at: v.NullableSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.SafeIntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
+        readonly supersedes: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>, undefined>;
+        readonly author: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>;
+        readonly model: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>, undefined>;
+        readonly confirmed_by: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>, undefined>;
+        readonly scope: v.NullableSchema<v.PicklistSchema<readonly ["personal", "work"], undefined>, undefined>;
+        readonly source: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>;
+        readonly created_at: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.SafeIntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly updated_at: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.SafeIntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    }, undefined>, undefined>, v.MaxLengthAction<{
+        ref: string;
+        type: "decision" | "fact" | "promise" | "question" | "statement";
+        statement: string;
+        status: "accepted" | "proposed" | "reversed" | "superseded";
+        subject: string | null;
+        occurred_at: number | null;
+        supersedes: string | null;
+        author: string;
+        model: string | null;
+        confirmed_by: string | null;
+        scope: "personal" | "work" | null;
+        source: string;
+        created_at: number;
+        updated_at: number;
+    }[], 1000, undefined>]>;
+    readonly links: v.SchemaWithPipe<readonly [v.ArraySchema<v.StrictObjectSchema<{
+        readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>;
+        readonly from: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>;
+        readonly to: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>, undefined>;
+        readonly kind: v.PicklistSchema<readonly ["links-to", "blocked-by", "follow-up-of", "about", "member-of", "labelled", "answered-by", "evidence", "created-from", "duplicate-of", "related-to", "assigned-to"], undefined>;
+        readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message"], undefined>;
+        readonly anchor: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>, undefined>;
+        readonly target_text: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>, undefined>;
+        readonly role: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>, undefined>;
+        readonly evidence: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>, undefined>;
+        readonly confirmed: v.BooleanSchema<undefined>;
+        readonly provenance: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>, undefined>;
+        readonly created_at: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.SafeIntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly updated_at: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.SafeIntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly author: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>, undefined>;
+    }, undefined>, undefined>, v.MaxLengthAction<{
+        ref: string;
+        from: string;
+        to: string | null;
+        kind: "about" | "answered-by" | "assigned-to" | "blocked-by" | "created-from" | "duplicate-of" | "evidence" | "follow-up-of" | "labelled" | "links-to" | "member-of" | "related-to";
+        origin: "file" | "message" | "owner" | "suggested";
+        anchor: string | null;
+        target_text: string | null;
+        role: string | null;
+        evidence: string | null;
+        confirmed: boolean;
+        provenance: string | null;
+        created_at: number;
+        updated_at: number;
+        author: string | null;
+    }[], 1000, undefined>]>;
+    readonly external: v.SchemaWithPipe<readonly [v.ArraySchema<v.StrictObjectSchema<{
+        readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>;
+        readonly content_sha256: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>, undefined>;
+    }, undefined>, undefined>, v.MaxLengthAction<{
+        ref: string;
+        content_sha256: string | null;
+    }[], 1000, undefined>]>;
+}, undefined>;
+export type ProjectAnnotations = v.InferOutput<typeof projectAnnotationsSchema>;

package/dist/store/project-transfer/schema.js

@@ -0,0 +1,68 @@
+import * as v from "valibot";
+import { FACT_STATUSES, FACT_TYPES, MEMORY_SCOPES } from "../../domain/knowledge.js";
+import { LINK_KINDS } from "../sqlite/link-kinds.js";
+import { LINK_ORIGINS } from "../sqlite/notes.js";
+const text = (max) => v.pipe(v.string(), v.minLength(1), v.maxLength(max));
+const ref = text(2048);
+const timestamp = v.pipe(v.number(), v.safeInteger(), v.minValue(0));
+const nullableRef = v.nullable(ref);
+const bounded = (schema) => v.pipe(v.array(schema), v.maxLength(1000));
+export const projectAnnotationsSchema = v.strictObject({
+    format: v.literal("wirecat.project-annotations"),
+    version: v.literal(1),
+    project: v.strictObject({
+        ref,
+        key: v.pipe(v.string(), v.regex(/^[A-Z][A-Z0-9]{2,3}$/)),
+        name: text(200),
+        type: v.picklist(["work", "client", "personal", "oss", "other"]),
+        scope: v.picklist(MEMORY_SCOPES),
+        organization: nullableRef,
+        created_at: timestamp,
+    }),
+    coverage: v.strictObject({
+        aliases: v.literal("complete"),
+        facts: v.literal("complete"),
+        links: v.literal("complete"),
+        memories: v.literal("omitted"),
+        tasks: v.literal("omitted"),
+        labels: v.literal("omitted"),
+        findings: v.literal("omitted"),
+    }),
+    aliases: bounded(text(200)),
+    facts: bounded(v.strictObject({
+        ref,
+        type: v.picklist(FACT_TYPES),
+        statement: text(2000),
+        status: v.picklist(FACT_STATUSES),
+        subject: nullableRef,
+        occurred_at: v.nullable(timestamp),
+        supersedes: nullableRef,
+        author: ref,
+        model: v.nullable(text(200)),
+        confirmed_by: nullableRef,
+        scope: v.nullable(v.picklist(MEMORY_SCOPES)),
+        source: text(200),
+        created_at: timestamp,
+        updated_at: timestamp,
+    })),
+    links: bounded(v.strictObject({
+        ref: text(200),
+        from: ref,
+        to: nullableRef,
+        kind: v.picklist(LINK_KINDS),
+        origin: v.picklist(LINK_ORIGINS),
+        anchor: v.nullable(text(2000)),
+        target_text: v.nullable(text(2000)),
+        role: v.nullable(text(200)),
+        evidence: v.nullable(text(2000)),
+        confirmed: v.boolean(),
+        provenance: v.nullable(text(2000)),
+        created_at: timestamp,
+        updated_at: timestamp,
+        author: v.nullable(text(200)),
+    })),
+    external: bounded(v.strictObject({
+        ref,
+        content_sha256: v.nullable(v.pipe(v.string(), v.regex(/^[a-f0-9]{64}$/))),
+    })),
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.370.0",
+  "version": "0.372.0",
   "description": "The messenger-neutral half of a messaging CLI: domain model, message locators, rendering, name resolution, the SQLite seam, the command skeleton and shared read commands, the send guard, run records and the message store",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",