cloving 0.3.20 → 1.1.0

package/dist/src/chats/source.js

@@ -0,0 +1,135 @@
+import { lstat, realpath } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, sep } from "node:path";
+export function contained(root, path) {
+    const suffix = relative(root, path);
+    return (!isAbsolute(suffix) && suffix !== ".." && !suffix.startsWith(`..${sep}`));
+}
+async function inspectComponents(path) {
+    const identities = [];
+    let ancestor = path;
+    const ancestors = [];
+    for (;;) {
+        ancestors.unshift(ancestor);
+        const parent = dirname(ancestor);
+        if (parent === ancestor)
+            break;
+        ancestor = parent;
+    }
+    let stats;
+    for (const component of ancestors) {
+        const next = await lstat(noFollowPath(component));
+        if (next.isSymbolicLink())
+            throw new Error("symbolic-link");
+        identities.unshift({ path: component, device: next.dev, inode: next.ino });
+        stats = next;
+    }
+    if (stats === undefined)
+        throw new Error("source-unreadable");
+    return { identities, stats };
+}
+export async function inspectScanSource(path, root) {
+    const { identities, stats } = await inspectComponents(path);
+    const canonicalPath = await realpath(path);
+    const canonicalRoot = path === root ? canonicalPath : root;
+    if (!contained(canonicalRoot, canonicalPath))
+        throw new Error("outside-root");
+    const canonicalStats = await lstat(noFollowPath(canonicalPath));
+    if (canonicalStats.dev !== stats.dev || canonicalStats.ino !== stats.ino)
+        throw new Error("source-changed");
+    const confirmation = await inspectComponents(path);
+    if (JSON.stringify(confirmation.identities) !== JSON.stringify(identities))
+        throw new Error("source-changed");
+    if (!stats.isDirectory() && !stats.isFile())
+        throw new Error("nonregular-file");
+    return {
+        path,
+        root: canonicalRoot,
+        identities,
+        size: stats.size,
+        modified: stats.mtimeMs,
+        changed: stats.ctimeMs,
+        kind: stats.isDirectory() ? "subtree" : "file",
+    };
+}
+export function noFollowPath(path) {
+    if (process.platform !== "darwin")
+        throw new Error("platform-unsupported");
+    if (!isAbsolute(path))
+        throw new Error("source-unreadable");
+    return `/.nofollow${path}`;
+}
+async function metadata(path) {
+    try {
+        return await lstat(noFollowPath(path));
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return;
+        throw error;
+    }
+}
+async function repositoryMarker(path) {
+    if (await metadata(join(path, ".git")))
+        return true;
+    const [head, objects, references] = await Promise.all([
+        metadata(join(path, "HEAD")),
+        metadata(join(path, "objects")),
+        metadata(join(path, "refs")),
+    ]);
+    return (head?.isFile() === true &&
+        objects?.isDirectory() === true &&
+        references?.isDirectory() === true);
+}
+export async function refuseRepositoryRoot(path) {
+    let ancestor = path;
+    for (;;) {
+        if (await repositoryMarker(ancestor))
+            throw new Error("repository-root");
+        const parent = dirname(ancestor);
+        if (parent === ancestor)
+            return;
+        ancestor = parent;
+    }
+}
+export function sourceFailure(error) {
+    if (error instanceof Error && "code" in error && error.code === "ELOOP")
+        return "symbolic-link";
+    const reason = error instanceof Error ? error.message : "";
+    return [
+        "symbolic-link",
+        "outside-root",
+        "nonregular-file",
+        "repository-root",
+        "source-changed",
+        "non-directory-root",
+    ].includes(reason)
+        ? reason
+        : "source-unreadable";
+}
+export async function verifyScanSource(expected) {
+    const current = await inspectScanSource(expected.path, expected.root);
+    if (JSON.stringify(current.identities) !== JSON.stringify(expected.identities))
+        throw new Error("source-changed");
+    if (expected.kind === "file" &&
+        (current.size !== expected.size ||
+            current.modified !== expected.modified ||
+            current.changed !== expected.changed))
+        throw new Error("source-changed");
+}
+export function verifyOpenSource(expected, stats) {
+    const identity = expected.identities[0];
+    if (!stats.isFile() ||
+        identity === undefined ||
+        stats.dev !== identity.device ||
+        stats.ino !== identity.inode ||
+        stats.size !== expected.size ||
+        stats.mtimeMs !== expected.modified ||
+        stats.ctimeMs !== expected.changed)
+        throw new Error("source-changed");
+}
+export function verifyScanAncestor(expected, current) {
+    const ancestors = current.identities.slice(-expected.identities.length);
+    if (expected.identities.some((identity, index) => identity.device !== ancestors[index]?.device ||
+        identity.inode !== ancestors[index].inode))
+        throw new Error("source-changed");
+}

package/dist/src/chats/structure.d.ts

@@ -0,0 +1,57 @@
+import type { MessageRecord } from "./normalize.ts";
+export interface OccurrenceReference {
+    readonly recordIndex: number;
+    readonly sourceId: string;
+}
+export interface Occurrence extends OccurrenceReference {
+    readonly uuid: string | null;
+    readonly sessionId: string | null;
+    readonly isSidechain: boolean | null;
+    readonly parentUuid?: string | null;
+    readonly copyOf?: OccurrenceReference;
+}
+interface ConflictGroup {
+    readonly uuid: string;
+    readonly variants: readonly (readonly OccurrenceReference[])[];
+}
+interface ParentLink {
+    readonly childUuid: string | null;
+    readonly parentUuid: string | null;
+    readonly occurrences: readonly OccurrenceReference[];
+    readonly status: "root" | "resolved" | "missing" | "ambiguous";
+}
+interface SessionNode {
+    readonly uuid: string | null;
+    readonly occurrences: readonly OccurrenceReference[];
+}
+interface SessionStructure {
+    readonly sessionId: string;
+    readonly nodes: readonly SessionNode[];
+    readonly links: readonly ParentLink[];
+    readonly forkPoints: readonly {
+        parentUuid: string;
+        childUuids: readonly string[];
+    }[];
+    readonly unknownParents: readonly OccurrenceReference[];
+    readonly missingParentTargets: readonly string[];
+    readonly cycles: readonly (readonly string[])[];
+}
+export interface StructureCounts {
+    readonly records: number;
+    readonly knownSessions: number;
+    readonly forks: number;
+    readonly copies: number;
+    readonly conflictGroups: number;
+    readonly unknownIdentities: number;
+    readonly missingParentTargets: number;
+}
+export interface ImportStructure {
+    readonly historyCompleteness: "unknown";
+    readonly counts: StructureCounts;
+    readonly occurrences: readonly Occurrence[];
+    readonly conflictGroups: readonly ConflictGroup[];
+    readonly sessions: readonly SessionStructure[];
+    readonly unknownSessions: readonly OccurrenceReference[];
+}
+export declare function structureImport(records: readonly MessageRecord[]): ImportStructure;
+export {};

package/dist/src/chats/structure.js

@@ -0,0 +1,216 @@
+function reference(occurrence) {
+    return { recordIndex: occurrence.recordIndex, sourceId: occurrence.sourceId };
+}
+function rawJsonApi(value) {
+    return "isRawJSON" in value && typeof value.isRawJSON === "function";
+}
+function canonical(value) {
+    if (rawJsonApi(JSON) && JSON.isRawJSON(value))
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    return `{${Object.entries(value)
+        .sort(([left], [right]) => (left < right ? -1 : Number(left > right)))
+        .map(([key, member]) => `${JSON.stringify(key)}:${canonical(member)}`)
+        .join(",")}}`;
+}
+function occurrence(record, context) {
+    const { recordIndex, identities } = context;
+    const metadata = record.schemaVersion === 2
+        ? {
+            uuid: record.uuid,
+            isSidechain: record.isSidechain,
+            ...(Object.hasOwn(record, "parentUuid")
+                ? { parentUuid: record.parentUuid }
+                : {}),
+        }
+        : { uuid: null, isSidechain: null };
+    const current = {
+        ...reference({ recordIndex, sourceId: record.sourceId }),
+        sessionId: record.sessionId,
+        ...metadata,
+    };
+    if (current.uuid === null)
+        return current;
+    const variants = identities.get(current.uuid) ?? new Map();
+    identities.set(current.uuid, variants);
+    const content = canonical([record.role, record.text, record.blocks]);
+    const matches = variants.get(content) ?? [];
+    variants.set(content, matches);
+    const first = matches[0];
+    matches.push(reference(current));
+    return first === undefined ? current : { ...current, copyOf: { ...first } };
+}
+function groupNodes(occurrences) {
+    const groups = new Map();
+    for (const item of occurrences) {
+        const key = item.uuid ?? item.recordIndex;
+        const group = groups.get(key) ?? [];
+        groups.set(key, group);
+        group.push(item);
+    }
+    return [...groups.values()];
+}
+function parentLinks(group, known) {
+    const parents = new Map();
+    for (const item of group) {
+        if (item.parentUuid === undefined)
+            continue;
+        const references = parents.get(item.parentUuid) ?? [];
+        parents.set(item.parentUuid, references);
+        references.push(reference(item));
+    }
+    const childUuid = group[0]?.uuid ?? null;
+    return [...parents].map(([parentUuid, occurrences]) => {
+        let status = "resolved";
+        if (parentUuid === null)
+            status = "root";
+        if (parentUuid !== null && !known.has(parentUuid))
+            status = "missing";
+        if (childUuid === null || parents.size > 1)
+            status = "ambiguous";
+        return { childUuid, parentUuid, occurrences, status };
+    });
+}
+function forkPoints(links) {
+    const children = new Map();
+    for (const link of links) {
+        if (link.status === "ambiguous" ||
+            link.parentUuid === null ||
+            link.childUuid === null)
+            continue;
+        const ids = children.get(link.parentUuid) ?? new Set();
+        children.set(link.parentUuid, ids);
+        ids.add(link.childUuid);
+    }
+    return [...children]
+        .filter(([, ids]) => ids.size > 1)
+        .map(([parentUuid, ids]) => ({ parentUuid, childUuids: [...ids] }));
+}
+function finishFrom(graph, state) {
+    const { visited, order } = state;
+    const stack = [{ id: state.start, expanded: false }];
+    while (stack.length > 0) {
+        const item = stack.pop();
+        if (item === undefined)
+            break;
+        if (item.expanded) {
+            order.push(item.id);
+            continue;
+        }
+        if (visited.has(item.id))
+            continue;
+        visited.add(item.id);
+        stack.push({ id: item.id, expanded: true });
+        for (const id of graph.get(item.id) ?? [])
+            stack.push({ id, expanded: false });
+    }
+}
+function finishOrder(graph) {
+    const visited = new Set();
+    const order = [];
+    for (const start of graph.keys())
+        finishFrom(graph, { start, visited, order });
+    return order;
+}
+function observedGraph(known, links) {
+    const graph = new Map([...known].map((id) => [id, []]));
+    const reverse = new Map([...known].map((id) => [id, []]));
+    for (const link of links) {
+        if (link.childUuid === null ||
+            link.parentUuid === null ||
+            !known.has(link.parentUuid))
+            continue;
+        graph.get(link.childUuid)?.push(link.parentUuid);
+        reverse.get(link.parentUuid)?.push(link.childUuid);
+    }
+    return { graph, reverse };
+}
+function componentFrom(graph, state) {
+    const component = [];
+    const stack = [state.start];
+    while (stack.length > 0) {
+        const id = stack.pop();
+        if (id === undefined || state.visited.has(id))
+            continue;
+        state.visited.add(id);
+        component.push(id);
+        for (const parent of graph.get(id) ?? [])
+            stack.push(parent);
+    }
+    return component;
+}
+function cycleGroups(known, links) {
+    const { graph, reverse } = observedGraph(known, links);
+    const rank = new Map([...known].map((id, index) => [id, index]));
+    const visited = new Set();
+    const cycles = [];
+    for (const start of finishOrder(graph).reverse()) {
+        if (visited.has(start))
+            continue;
+        const component = componentFrom(reverse, { start, visited });
+        if (component.length > 1 || graph.get(start)?.includes(start))
+            cycles.push(component.sort((left, right) => Number(rank.get(left)) - Number(rank.get(right))));
+    }
+    return cycles.sort((left, right) => Number(rank.get(String(left[0]))) - Number(rank.get(String(right[0]))));
+}
+function sessionStructure(sessionId, occurrences) {
+    const groups = groupNodes(occurrences);
+    const known = new Set(occurrences.flatMap((item) => (item.uuid === null ? [] : [item.uuid])));
+    const links = groups.flatMap((group) => parentLinks(group, known));
+    return {
+        sessionId,
+        nodes: groups.map((group) => ({
+            uuid: group[0]?.uuid ?? null,
+            occurrences: group.map(reference),
+        })),
+        links,
+        forkPoints: forkPoints(links),
+        unknownParents: occurrences
+            .filter((item) => !Object.hasOwn(item, "parentUuid"))
+            .map(reference),
+        missingParentTargets: [
+            ...new Set(links.flatMap((link) => link.parentUuid !== null && !known.has(link.parentUuid)
+                ? [link.parentUuid]
+                : [])),
+        ],
+        cycles: cycleGroups(known, links),
+    };
+}
+export function structureImport(records) {
+    const identities = new Map();
+    const occurrences = records.map((record, index) => occurrence(record, { recordIndex: index, identities }));
+    const grouped = new Map();
+    for (const item of occurrences) {
+        if (item.sessionId === null || item.sessionId === "")
+            continue;
+        const group = grouped.get(item.sessionId) ?? [];
+        grouped.set(item.sessionId, group);
+        group.push(item);
+    }
+    const sessions = [...grouped].map(([id, group]) => sessionStructure(id, group));
+    const conflictGroups = [...identities]
+        .filter(([, variants]) => variants.size > 1)
+        .map(([uuid, variants]) => ({ uuid, variants: [...variants.values()] }));
+    return {
+        historyCompleteness: "unknown",
+        counts: {
+            records: records.length,
+            knownSessions: sessions.length,
+            forks: sessions.reduce((sum, session) => sum + session.forkPoints.length, 0),
+            copies: occurrences.filter((item) => item.copyOf !== undefined).length,
+            conflictGroups: conflictGroups.length,
+            unknownIdentities: occurrences.filter((item) => item.uuid === null)
+                .length,
+            missingParentTargets: sessions.reduce((sum, session) => sum + session.missingParentTargets.length, 0),
+        },
+        occurrences,
+        conflictGroups,
+        sessions,
+        unknownSessions: occurrences
+            .filter((item) => item.sessionId === null || item.sessionId === "")
+            .map(reference),
+    };
+}

package/dist/src/cli/arguments.d.ts

@@ -0,0 +1,31 @@
+import { type RuntimeInvocation } from "./runtime-arguments.ts";
+export type Invocation = {
+    readonly kind: "help";
+} | {
+    readonly kind: "version";
+} | {
+    readonly kind: "validate-help";
+} | {
+    readonly kind: "chats-redact-help";
+} | {
+    readonly kind: "chats-redact";
+    readonly importId: string;
+} | {
+    readonly kind: "chats-import-help";
+} | {
+    readonly kind: "chats-import";
+    readonly paths: readonly string[];
+    readonly roots?: readonly string[];
+    readonly excludeProjects?: readonly string[];
+    readonly previousImportId?: string;
+} | {
+    readonly kind: "validate";
+    readonly manifest: string;
+    readonly input: string | null;
+    readonly json: boolean;
+} | RuntimeInvocation | {
+    readonly kind: "usage-error";
+    readonly code: string;
+    readonly json: boolean;
+};
+export declare function parseInvocation(given: readonly string[]): Invocation;

package/dist/src/cli/arguments.js

@@ -0,0 +1,235 @@
+import { parseArgs } from "node:util";
+import { isRuntimeCommand, runtimeInvocation, } from "./runtime-arguments.js";
+const errorCodes = {
+    ERR_PARSE_ARGS_UNKNOWN_OPTION: "unknown-option",
+    ERR_PARSE_ARGS_INVALID_OPTION_VALUE: "missing-value",
+};
+const options = {
+    help: { type: "boolean", short: "h" },
+    version: { type: "boolean", short: "v" },
+    input: { type: "string" },
+    json: { type: "boolean" },
+    prompt: { type: "string" },
+    ticket: { type: "string" },
+    next: { type: "boolean" },
+    port: { type: "string" },
+    text: { type: "string" },
+    "command-id": { type: "string" },
+    "expected-revision": { type: "string" },
+    generation: { type: "string" },
+    "subject-digest": { type: "string" },
+    limit: { type: "string" },
+    after: { type: "string" },
+    follow: { type: "boolean" },
+};
+const textOptions = ["--prompt", "--text"];
+function knownFlag(token) {
+    if (token.startsWith("--"))
+        return Object.hasOwn(options, token.slice(2));
+    return token === "-h" || token === "-v";
+}
+function attached(option, value) {
+    return value.startsWith("-") && !knownFlag(value)
+        ? [`${option}=${value}`]
+        : [option, value];
+}
+function textValues(argumentsList) {
+    const joined = [];
+    let option;
+    for (const token of argumentsList) {
+        const pending = option;
+        option =
+            pending === undefined && textOptions.includes(token) ? token : undefined;
+        if (pending !== undefined)
+            joined.push(...attached(pending, token));
+        else if (option === undefined)
+            joined.push(token);
+    }
+    return option === undefined ? joined : [...joined, option];
+}
+export function parseInvocation(given) {
+    if (given[0] === "chats" && given[1] === "import")
+        return chatsImport(given.slice(2));
+    if (given[0] === "chats" && given[1] === "redact")
+        return chatsRedact(given.slice(2));
+    const argumentsList = textValues(given);
+    const json = given.includes("--json");
+    const parsed = parsedArguments(argumentsList);
+    if (typeof parsed === "string")
+        return { kind: "usage-error", code: parsed, json };
+    const { values, positionals, tokens } = parsed;
+    const [command, ...remaining] = positionals;
+    if (command === undefined)
+        return topLevel(values);
+    if (command === "workflows" && remaining[0] === "validate")
+        return validation(values, remaining.slice(1));
+    const outcome = runtimeInvocation({
+        command,
+        positionals: remaining,
+        options: givenOptions(tokens),
+    });
+    if (typeof outcome === "string")
+        return { kind: "usage-error", code: outcome, json };
+    return outcome;
+}
+function chatsRedact(argumentsList) {
+    if (argumentsList.length === 1 &&
+        ["--help", "-h"].includes(String(argumentsList[0])))
+        return { kind: "chats-redact-help" };
+    const importId = argumentsList[0];
+    if (argumentsList.length !== 1 ||
+        importId === undefined ||
+        !/^[a-f\d]{8}-[a-f\d]{4}-4[a-f\d]{3}-[89ab][a-f\d]{3}-[a-f\d]{12}$/.test(importId))
+        return { kind: "usage-error", code: "invalid-import-id", json: false };
+    return { kind: "chats-redact", importId };
+}
+function chatsImport(argumentsList) {
+    const error = (code) => ({
+        kind: "usage-error",
+        code,
+        json: false,
+    });
+    if (argumentsList.length === 1 &&
+        ["--help", "-h"].includes(String(argumentsList[0])))
+        return { kind: "chats-import-help" };
+    const state = {
+        paths: [],
+        roots: [],
+        excludeProjects: [],
+        literal: false,
+        option: undefined,
+        previousImportId: undefined,
+    };
+    for (const argument of argumentsList) {
+        const failure = importArgument(state, argument);
+        if (failure !== undefined)
+            return error(failure);
+    }
+    if (state.option !== undefined)
+        return error("missing-value");
+    if (state.excludeProjects.length > 0 && state.roots.length === 0)
+        return error("roots-required");
+    if (state.paths.length + state.roots.length === 0)
+        return error("missing-argument");
+    return importInvocation(state);
+}
+function importInvocation(state) {
+    const previous = state.previousImportId === undefined
+        ? {}
+        : { previousImportId: state.previousImportId };
+    return state.roots.length === 0
+        ? { kind: "chats-import", paths: state.paths, ...previous }
+        : {
+            kind: "chats-import",
+            paths: state.paths,
+            ...previous,
+            roots: state.roots,
+            excludeProjects: state.excludeProjects,
+        };
+}
+function importArgument(state, argument) {
+    if (state.option !== undefined)
+        return importValue(state, argument);
+    if (argument === "")
+        return "missing-argument";
+    if (state.literal) {
+        state.paths.push(argument);
+        return;
+    }
+    if (argument === "--previous-import" && state.previousImportId !== undefined)
+        return "repeated-previous-import";
+    if (["--root", "--exclude-project", "--previous-import"].includes(argument)) {
+        state.option = argument;
+        return;
+    }
+    if (argument === "--") {
+        state.literal = true;
+        return;
+    }
+    if (argument.startsWith("-"))
+        return "unexpected-option";
+    state.paths.push(argument);
+    return;
+}
+function importValue(state, argument) {
+    if (argument === "" || argument.startsWith("-"))
+        return "missing-value";
+    const option = state.option;
+    state.option = undefined;
+    if (option === "--root") {
+        state.roots.push(argument);
+        return;
+    }
+    if (option === "--exclude-project" && !validProjectName(argument))
+        return "invalid-exclusion";
+    if (option === "--exclude-project") {
+        state.excludeProjects.push(argument);
+        return;
+    }
+    if (!/^[a-f\d]{8}-[a-f\d]{4}-4[a-f\d]{3}-[89ab][a-f\d]{3}-[a-f\d]{12}$/.test(argument))
+        return "invalid-import-id";
+    state.previousImportId = argument;
+    return;
+}
+function validProjectName(name) {
+    return (name !== "." &&
+        name !== ".." &&
+        !["/", "\\", "\0", "*", "?", "[", "]"].some((character) => name.includes(character)));
+}
+function parsedArguments(argumentsList) {
+    try {
+        return parseArgs({
+            args: [...argumentsList],
+            allowPositionals: true,
+            options,
+            tokens: true,
+        });
+    }
+    catch (error) {
+        if (!knownCommand(lenientPositionals(argumentsList)))
+            return "unknown-command";
+        const code = error instanceof Error && "code" in error ? String(error.code) : "";
+        return errorCodes[code] ?? "invalid-invocation";
+    }
+}
+function lenientPositionals(argumentsList) {
+    return parseArgs({
+        args: [...argumentsList],
+        allowPositionals: true,
+        options,
+        strict: false,
+    }).positionals;
+}
+function knownCommand(positionals) {
+    const [command, subcommand] = positionals;
+    if (command === undefined)
+        return true;
+    if (command === "workflows")
+        return subcommand === "validate";
+    return isRuntimeCommand(command);
+}
+function givenOptions(tokens) {
+    return tokens.flatMap((token) => token.kind === "option" ? [{ name: token.name, value: token.value }] : []);
+}
+function unexpected(values, allowed) {
+    return Object.keys(values).some((name) => !allowed.includes(name));
+}
+function validation(values, remaining) {
+    const json = values.json === true;
+    if (unexpected(values, ["help", "input", "json"]))
+        return { kind: "usage-error", code: "unexpected-option", json };
+    if (values.help)
+        return { kind: "validate-help" };
+    const [manifest, ...extra] = remaining;
+    if (manifest === undefined)
+        return { kind: "usage-error", code: "missing-argument", json };
+    if (extra.length > 0)
+        return { kind: "usage-error", code: "unexpected-argument", json };
+    return { kind: "validate", manifest, input: values.input ?? null, json };
+}
+function topLevel(values) {
+    const json = values.json === true;
+    if (unexpected(values, ["help", "version"]))
+        return { kind: "usage-error", code: "unexpected-option", json };
+    return values.version ? { kind: "version" } : { kind: "help" };
+}

package/dist/src/cli/client.d.ts

@@ -0,0 +1,16 @@
+import { type Fields, type Reply, type ServiceRequest } from "../protocol.ts";
+export interface Interruption {
+    readonly signal: Promise<void>;
+    readonly reply: Reply;
+}
+export declare function send(runtimeDirectory: string, request: ServiceRequest): Promise<Reply>;
+export declare function listRuns(runtimeDirectory: string): Promise<Reply>;
+export declare function mutate(runtimeDirectory: string, mutation: {
+    readonly request: ServiceRequest;
+    readonly signal: Promise<void>;
+}): Promise<Reply>;
+export declare function follow(runtimeDirectory: string, stream: {
+    readonly request: ServiceRequest;
+    readonly onEvent: (event: Fields) => void;
+    readonly signal: Promise<void>;
+}): Promise<Reply>;