@wirecat/cli-core 0.372.0 → 0.374.0

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

@@ -0,0 +1,29 @@
+import { CliError } from "@wirecat/cli-base";
+import { openStoreContext } from "../sqlite/open-store.js";
+import { SnapshotBudget } from "../sqlite/project-transfer/budget.js";
+import { projectAnnotationSnapshot } from "../sqlite/project-transfer/snapshot.js";
+import { projectAnnotationSnapshotFingerprint } from "./snapshot-model.js";
+export { decodeProjectAnnotationSnapshot, projectAnnotationSnapshotFingerprint, projectAnnotationSnapshotSchema, } from "./snapshot-model.js";
+/** No source maintenance, source fetching or output-file publication belongs to a snapshot read. */
+export const snapshotProjectAnnotations = async (options) => {
+    if (!options || typeof options !== "object" || Array.isArray(options))
+        throw new CliError("validation_error", "snapshot options are required");
+    for (const field of Object.keys(options))
+        if (!["source", "project", "env", "maxReadBytes"].includes(field))
+            throw new CliError("validation_error", `unknown snapshot field ${field}`);
+    if (typeof options.source !== "string" || !options.source.trim() || options.source.length > 4096)
+        throw new CliError("validation_error", "snapshot source is an explicit existing store path");
+    if (typeof options.project !== "string" ||
+        !/^project:[1-9]\d*$/.test(options.project) ||
+        !Number.isSafeInteger(Number(options.project.slice(8))))
+        throw new CliError("validation_error", "snapshot project is a project:<safe integer id> reference");
+    const budget = new SnapshotBudget(options.maxReadBytes ?? 4 * 1024 * 1024);
+    const context = await openStoreContext({ path: options.source, env: options.env, readOnly: true });
+    try {
+        const result = projectAnnotationSnapshot(context.database, Number(options.project.slice(8)), budget);
+        return { ...result, fingerprint: projectAnnotationSnapshotFingerprint(JSON.stringify(result.snapshot)) };
+    }
+    finally {
+        context.database.close();
+    }
+};

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

@@ -0,0 +1,25 @@
+import type { ProjectAnnotationPreview } from "./snapshot-plan.js";
+export interface ProjectAnnotationTargetRequest {
+    snapshot: string;
+    project: string;
+    bindings: Record<string, string>;
+    maxReadBytes?: number;
+}
+export interface ProjectAnnotationRestoreRequest extends ProjectAnnotationTargetRequest {
+    fingerprint: string;
+}
+export interface ProjectAnnotationRestoreReceipt {
+    project: string;
+    fingerprint: string;
+    mappings: Record<string, string>;
+    counts: {
+        aliases: number;
+        facts: number;
+        links: number;
+    };
+}
+/** Hosts authorize restore before calling; historical accepted state is not a new agent decision. */
+export interface ProjectAnnotationStore {
+    preview(request: ProjectAnnotationTargetRequest): Promise<ProjectAnnotationPreview>;
+    restore(request: ProjectAnnotationRestoreRequest): Promise<ProjectAnnotationRestoreReceipt>;
+}

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

@@ -0,0 +1 @@
+export {};

package/dist/store/sqlite/project-transfer/budget.d.ts

@@ -0,0 +1,9 @@
+import type { CacheDatabase, SqlValue } from "../../driver.js";
+export declare class SnapshotBudget {
+    readonly maxBytes: number;
+    records: number;
+    bytes: number;
+    constructor(maxBytes: number);
+    reserve(records: number, bytes: number): void;
+    rows(database: CacheDatabase, from: string, fields: string[], parameters: SqlValue[]): void;
+}

package/dist/store/sqlite/project-transfer/budget.js

@@ -0,0 +1,27 @@
+import { CliError } from "@wirecat/cli-base";
+export class SnapshotBudget {
+    maxBytes;
+    records = 0;
+    bytes = 0;
+    constructor(maxBytes) {
+        this.maxBytes = maxBytes;
+        if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > 4 * 1024 * 1024)
+            throw new CliError("validation_error", "snapshot maxReadBytes takes 1–4194304 bytes");
+    }
+    reserve(records, bytes) {
+        if (!Number.isSafeInteger(records) ||
+            records < 0 ||
+            !Number.isSafeInteger(bytes) ||
+            bytes < 0 ||
+            this.records + records > 1000 ||
+            this.bytes + bytes > this.maxBytes)
+            throw new CliError("validation_error", "project annotation snapshot exceeds its record or input byte budget");
+        this.records += records;
+        this.bytes += bytes;
+    }
+    rows(database, from, fields, parameters) {
+        const bytes = fields.map((field) => `coalesce(length(CAST(${field} AS BLOB)),0)`).join("+");
+        const sized = database.prepare(`SELECT ${bytes} AS bytes ${from} LIMIT 1001`).all(...parameters);
+        this.reserve(sized.length, sized.reduce((sum, row) => sum + Number(row.bytes) + 128, 0));
+    }
+}

package/dist/store/sqlite/project-transfer/preview.d.ts

@@ -0,0 +1,12 @@
+import type { CacheDatabase } from "../../driver.js";
+import { type ProjectAnnotationSnapshot } from "../../project-transfer/snapshot-model.js";
+import type { SnapshotBudget } from "./budget.js";
+export declare const previewAnnotationSnapshot: (database: CacheDatabase, projectId: number, manifest: ProjectAnnotationSnapshot, bindings: Record<string, string>, budget: SnapshotBudget) => {
+    plan: import("../../index.js").ProjectAnnotationsPlan;
+    descriptor_conflicts: ("key" | "name")[];
+    namespace_conflicts: string[];
+    ready: boolean;
+    fingerprint: string;
+    read_bytes: number;
+    records: number;
+};

package/dist/store/sqlite/project-transfer/preview.js

@@ -0,0 +1,74 @@
+import { createHash } from "node:crypto";
+import { normalizeVocabularyName } from "../../../domain/vocabulary.js";
+import { projectAnnotationSnapshotFingerprint, } from "../../project-transfer/snapshot-model.js";
+import { planProjectAnnotationSnapshot } from "../../project-transfer/snapshot-plan.js";
+import { thingOf } from "../things.js";
+import { read } from "../transaction.js";
+import { projectAnnotationSnapshot } from "./snapshot.js";
+import { ProjectSnapshotSources } from "./sources.js";
+export const previewAnnotationSnapshot = (database, projectId, manifest, bindings, budget) => read(database, () => {
+    const current = projectAnnotationSnapshot(database, projectId, budget).snapshot;
+    const sources = new ProjectSnapshotSources(database, budget);
+    for (const ref of new Set(Object.values(bindings))) {
+        if (ref === current.project.ref)
+            continue;
+        const thing = thingOf(database, ref);
+        if (thing)
+            sources.ref(thing.type, thing.id);
+    }
+    const external = sources.external(new Set([current.project.ref]));
+    const projectFields = ["id", "key", "name", "account_id", "deleted_at"];
+    const aliasFields = ["aliasable_id", "name", "account_id"];
+    const projectFrom = "FROM projects ORDER BY id";
+    const aliasFrom = "FROM aliases WHERE aliasable_type='project' ORDER BY id";
+    budget.rows(database, projectFrom, projectFields, []);
+    budget.rows(database, aliasFrom, aliasFields, []);
+    const projects = database.prepare(`SELECT ${projectFields.join(",")} ${projectFrom} LIMIT 1001`).all();
+    const aliases = database.prepare(`SELECT ${aliasFields.join(",")} ${aliasFrom} LIMIT 1001`).all();
+    const names = new Set([manifest.project.key, manifest.project.name, ...manifest.aliases.map((a) => a.name)].map(normalizeVocabularyName));
+    const namespace = new Set();
+    for (const project of projects) {
+        if (project.id === projectId)
+            continue;
+        const keyMatches = names.has(normalizeVocabularyName(String(project.key)));
+        const nameMatches = project.account_id === null &&
+            project.deleted_at === null &&
+            names.has(normalizeVocabularyName(String(project.name)));
+        if (keyMatches || nameMatches)
+            namespace.add(`project:${project.id}`);
+    }
+    for (const alias of aliases) {
+        if (alias.aliasable_id === projectId || alias.account_id !== null)
+            continue;
+        const project = projects.find((p) => p.id === alias.aliasable_id && p.account_id === null && p.deleted_at === null);
+        if (project && names.has(normalizeVocabularyName(String(alias.name))))
+            namespace.add(`project:${project.id}`);
+    }
+    const descriptor_conflicts = ["key", "name"].filter((field) => current.project[field] !== manifest.project[field]);
+    const target = {
+        project: current.project.ref,
+        annotation_count: current.aliases.length + current.facts.length + current.links.length,
+        revision_sha256: createHash("sha256")
+            .update(JSON.stringify({
+            snapshot: projectAnnotationSnapshotFingerprint(JSON.stringify(current)),
+            projects,
+            aliases,
+            external: external.toSorted((a, b) => (a.ref < b.ref ? -1 : a.ref > b.ref ? 1 : 0)),
+        }))
+            .digest("hex"),
+        external,
+    };
+    const plan = planProjectAnnotationSnapshot(JSON.stringify(manifest), target, bindings);
+    const namespace_conflicts = [...namespace].sort();
+    return {
+        plan,
+        descriptor_conflicts,
+        namespace_conflicts,
+        ready: plan.ready && descriptor_conflicts.length === 0 && namespace_conflicts.length === 0,
+        fingerprint: createHash("sha256")
+            .update(JSON.stringify({ plan: plan.fingerprint, descriptor_conflicts, namespace_conflicts }))
+            .digest("hex"),
+        read_bytes: budget.bytes,
+        records: budget.records,
+    };
+});

package/dist/store/sqlite/project-transfer/records.d.ts

@@ -0,0 +1,5 @@
+import type { CacheDatabase } from "../../driver.js";
+import type { ProjectAnnotationSnapshot } from "../../project-transfer/snapshot-model.js";
+export declare const restoreAnnotationRecords: (database: CacheDatabase, projectId: number, snapshot: ProjectAnnotationSnapshot, bindings: Record<string, string>) => {
+    [x: string]: string;
+};

package/dist/store/sqlite/project-transfer/records.js

@@ -0,0 +1,53 @@
+import { CliError } from "@wirecat/cli-base";
+import { fold } from "../../normalize.js";
+import { thingOf } from "../things.js";
+export const restoreAnnotationRecords = (database, projectId, snapshot, bindings) => {
+    const mappings = { ...bindings };
+    const resolve = (ref) => {
+        if (ref === null)
+            return null;
+        const mapped = mappings[ref], thing = mapped === undefined ? undefined : thingOf(database, mapped);
+        if (!thing)
+            throw new CliError("validation_error", "project annotation binding became unavailable");
+        return thing;
+    };
+    const organization = resolve(snapshot.project.organization), owner = resolve(snapshot.project.owner);
+    database
+        .prepare("UPDATE projects SET description=?,type=?,scope=?,organization_id=?,owner_type=?,owner_id=?,status=?,created_at=?,updated_at=? WHERE id=?")
+        .run(snapshot.project.description, snapshot.project.type, snapshot.project.scope, organization?.id ?? null, owner?.type ?? null, owner?.id ?? null, snapshot.project.status, snapshot.project.created_at, snapshot.project.updated_at, projectId);
+    for (const alias of snapshot.aliases)
+        database
+            .prepare("INSERT INTO aliases(aliasable_type,aliasable_id,account_id,name,name_folded,display,source,created_at,updated_at) VALUES('project',?,NULL,?,?,?,?,?,?)")
+            .run(projectId, alias.name, fold(alias.name), Number(alias.display), alias.source, alias.created_at, alias.updated_at);
+    for (const fact of snapshot.facts) {
+        const author = resolve(fact.author), confirmed = resolve(fact.confirmed_by);
+        if (!author)
+            throw new CliError("validation_error", "project annotation author is required");
+        const row = database
+            .prepare("INSERT INTO facts(type,statement,status,project_id,subject_type,subject_id,occurred_at,supersedes_id,author_type,author_id,model,confirmed_by_type,confirmed_by_id,scope,source,created_at,updated_at) VALUES(?,?,?,?,NULL,NULL,?,NULL,?,?,?,?,?,?,?,?,?) RETURNING id")
+            .get(fact.type, fact.statement, fact.status, projectId, fact.occurred_at, author.type, author.id, fact.model, confirmed?.type ?? null, confirmed?.id ?? null, fact.scope, fact.source, fact.created_at, fact.updated_at);
+        if (!row)
+            throw new CliError("configuration_error", "project annotation fact insertion failed");
+        mappings[fact.ref] = `fact:${row.id}`;
+    }
+    for (const fact of snapshot.facts) {
+        const subject = resolve(fact.subject), previous = resolve(fact.supersedes), target = resolve(fact.ref);
+        if (!target)
+            throw new CliError("configuration_error", "project annotation fact mapping is missing");
+        database
+            .prepare("UPDATE facts SET subject_type=?,subject_id=?,supersedes_id=? WHERE id=?")
+            .run(subject?.type ?? null, subject?.id ?? null, previous?.id ?? null, target.id);
+    }
+    for (const link of snapshot.links) {
+        const from = resolve(link.from), to = resolve(link.to);
+        if (!from)
+            throw new CliError("validation_error", "project annotation link source is required");
+        const row = database
+            .prepare("INSERT INTO links(from_type,from_id,to_type,to_id,kind,anchor,source,target_text,target_folded,role,evidence,metadata,confirmed,created_at,author,updated_at) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?) RETURNING id")
+            .get(from.type, from.id, to?.type ?? null, to?.id ?? null, link.kind, link.anchor, link.origin, link.target_text, link.target_text === null ? null : fold(link.target_text), link.role, link.evidence, link.provenance === null ? null : JSON.stringify({ provenance: link.provenance }), Number(link.confirmed), link.created_at, link.author, link.updated_at);
+        if (!row)
+            throw new CliError("configuration_error", "project annotation link insertion failed");
+        mappings[link.ref] = `link:${row.id}`;
+    }
+    return mappings;
+};

package/dist/store/sqlite/project-transfer/snapshot.d.ts

@@ -0,0 +1,78 @@
+import type { CacheDatabase } from "../../driver.js";
+import type { SnapshotBudget } from "./budget.js";
+export declare const projectAnnotationSnapshot: (database: CacheDatabase, projectId: number, budget: SnapshotBudget) => {
+    snapshot: {
+        format: "wirecat.project-annotations";
+        facts: {
+            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;
+        }[];
+        links: {
+            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;
+        }[];
+        external: {
+            ref: string;
+            content_sha256: string | null;
+        }[];
+        version: 2;
+        coverage: {
+            aliases: "complete";
+            facts: "complete";
+            links: "complete";
+            memories: "omitted";
+            tasks: "omitted";
+            labels: "omitted";
+            findings: "omitted";
+            meeting_memberships: "omitted";
+            notes: "omitted";
+        };
+        project: {
+            ref: string;
+            key: string;
+            name: string;
+            type: "client" | "oss" | "other" | "personal" | "work";
+            scope: "personal" | "work";
+            organization: string | null;
+            created_at: number;
+            description: string | null;
+            status: string | null;
+            owner: string | null;
+            updated_at: number;
+            account_scope: "owner";
+        };
+        aliases: {
+            name: string;
+            source: string;
+            display: boolean;
+            created_at: number;
+            updated_at: number;
+        }[];
+    };
+    read_bytes: number;
+    records: number;
+};

package/dist/store/sqlite/project-transfer/snapshot.js

@@ -0,0 +1,183 @@
+import { CliError } from "@wirecat/cli-base";
+import { MIGRATIONS } from "../../migrations.js";
+import { decodeProjectAnnotationSnapshot } from "../../project-transfer/snapshot-model.js";
+import { read } from "../transaction.js";
+import { ProjectSnapshotSources } from "./sources.js";
+const unsupported = () => {
+    throw new CliError("configuration_error", "project snapshot has unsupported metadata, deletion or account scope");
+};
+const nullableText = (value) => (value === null ? null : String(value));
+const flag = (value) => {
+    if (value !== 0 && value !== 1)
+        return unsupported();
+    return value === 1;
+};
+const provenance = (raw) => {
+    if (raw === null)
+        return null;
+    let value;
+    try {
+        value = JSON.parse(String(raw));
+    }
+    catch {
+        return unsupported();
+    }
+    if (!value ||
+        typeof value !== "object" ||
+        Array.isArray(value) ||
+        Object.keys(value).some((key) => key !== "provenance"))
+        return unsupported();
+    const text = value.provenance;
+    if (text !== undefined && text !== null && typeof text !== "string")
+        return unsupported();
+    return text ?? null;
+};
+export const projectAnnotationSnapshot = (database, projectId, budget) => read(database, () => {
+    if (database.prepare("SELECT max(version) AS version FROM schema_migrations").get()?.version !==
+        MIGRATIONS.at(-1)?.version)
+        throw new CliError("configuration_error", "project snapshots require the SDK's current store schema without source migration");
+    const sources = new ProjectSnapshotSources(database, budget);
+    const rows = (from, fields, params) => {
+        budget.rows(database, from, fields, params);
+        return database.prepare(`SELECT ${fields.join(",")} ${from} LIMIT 1001`).all(...params);
+    };
+    const descriptor = database.prepare("SELECT account_id,deleted_at FROM projects WHERE id=?").get(projectId);
+    if (!descriptor)
+        throw new CliError("not_found", "the source project does not exist");
+    if (descriptor.account_id !== null || descriptor.deleted_at !== null)
+        return unsupported();
+    const project = rows("FROM projects WHERE id=?", [
+        "id",
+        "key",
+        "name",
+        "description",
+        "type",
+        "scope",
+        "organization_id",
+        "owner_type",
+        "owner_id",
+        "status",
+        "created_at",
+        "updated_at",
+    ], [projectId])[0];
+    if (!project)
+        throw new CliError("not_found", "the source project does not exist");
+    const aliases = rows("FROM aliases WHERE aliasable_type='project' AND aliasable_id=? ORDER BY id", ["name", "source", "display", "account_id", "created_at", "updated_at"], [projectId]);
+    if (aliases.some((alias) => alias.account_id !== null))
+        return unsupported();
+    if (database
+        .prepare("SELECT 1 FROM facts WHERE project_id=? AND (metadata IS NOT NULL OR deleted_at IS NOT NULL) LIMIT 1")
+        .get(projectId))
+        return unsupported();
+    const facts = rows("FROM facts WHERE project_id=? ORDER BY id", [
+        "id",
+        "type",
+        "statement",
+        "status",
+        "subject_type",
+        "subject_id",
+        "occurred_at",
+        "supersedes_id",
+        "author_type",
+        "author_id",
+        "model",
+        "confirmed_by_type",
+        "confirmed_by_id",
+        "scope",
+        "source",
+        "created_at",
+        "updated_at",
+    ], [projectId]);
+    const links = rows("FROM links WHERE (from_type='project' AND from_id=?) OR (to_type='project' AND to_id=?) OR " +
+        "(from_type='fact' AND from_id IN (SELECT id FROM facts WHERE project_id=?)) OR " +
+        "(to_type='fact' AND to_id IN (SELECT id FROM facts WHERE project_id=?)) ORDER BY id", [
+        "id",
+        "from_type",
+        "from_id",
+        "to_type",
+        "to_id",
+        "kind",
+        "anchor",
+        "source",
+        "target_text",
+        "role",
+        "evidence",
+        "metadata",
+        "confirmed",
+        "author",
+        "created_at",
+        "updated_at",
+    ], [projectId, projectId, projectId, projectId]);
+    const projectRef = `project:${projectId}`;
+    const owned = new Set([projectRef, ...facts.map((row) => `fact:${row.id}`)]);
+    const data = {
+        format: "wirecat.project-annotations",
+        version: 2,
+        project: {
+            ref: projectRef,
+            key: project.key,
+            name: project.name,
+            type: project.type,
+            scope: project.scope,
+            organization: project.organization_id === null ? null : sources.ref("organization", project.organization_id),
+            created_at: project.created_at,
+            description: project.description,
+            status: project.status,
+            owner: sources.ref(project.owner_type, project.owner_id),
+            updated_at: project.updated_at,
+            account_scope: "owner",
+        },
+        coverage: {
+            aliases: "complete",
+            facts: "complete",
+            links: "complete",
+            memories: "omitted",
+            tasks: "omitted",
+            labels: "omitted",
+            findings: "omitted",
+            meeting_memberships: "omitted",
+            notes: "omitted",
+        },
+        aliases: aliases.map((row) => ({
+            name: row.name,
+            source: row.source,
+            display: flag(row.display),
+            created_at: row.created_at,
+            updated_at: row.updated_at,
+        })),
+        facts: facts.map((row) => ({
+            ref: `fact:${row.id}`,
+            type: row.type,
+            statement: row.statement,
+            status: row.status,
+            subject: sources.ref(row.subject_type, row.subject_id),
+            occurred_at: row.occurred_at,
+            supersedes: row.supersedes_id === null ? null : sources.ref("fact", row.supersedes_id),
+            author: sources.ref(row.author_type, row.author_id),
+            model: row.model,
+            confirmed_by: sources.ref(row.confirmed_by_type, row.confirmed_by_id),
+            scope: row.scope,
+            source: row.source,
+            created_at: row.created_at,
+            updated_at: row.updated_at,
+        })),
+        links: links.map((row) => ({
+            ref: `link:${row.id}`,
+            from: sources.ref(row.from_type, row.from_id),
+            to: sources.ref(row.to_type, row.to_id),
+            kind: row.kind,
+            origin: row.source,
+            anchor: nullableText(row.anchor),
+            target_text: nullableText(row.target_text),
+            role: nullableText(row.role),
+            evidence: nullableText(row.evidence),
+            confirmed: flag(row.confirmed),
+            provenance: provenance(row.metadata),
+            created_at: row.created_at,
+            updated_at: row.updated_at,
+            author: nullableText(row.author),
+        })),
+    };
+    const snapshot = decodeProjectAnnotationSnapshot(JSON.stringify({ ...data, external: sources.external(owned) }));
+    return { snapshot, read_bytes: budget.bytes, records: budget.records };
+});

package/dist/store/sqlite/project-transfer/sources.d.ts

@@ -0,0 +1,18 @@
+import type { CacheDatabase } from "../../driver.js";
+import { type Thing } from "../things.js";
+import type { SnapshotBudget } from "./budget.js";
+export declare class ProjectSnapshotSources {
+    private readonly database;
+    private readonly budget;
+    readonly references: Map<string, Thing>;
+    private readonly byThing;
+    constructor(database: CacheDatabase, budget: SnapshotBudget);
+    ref(type: unknown, id: unknown): string | null;
+    external(owned: Set<string>): {
+        ref: string;
+        content_sha256: string | null;
+    }[];
+    private fingerprint;
+    private transcript;
+    private digest;
+}