cloving 1.0.1 → 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

@@ -5,11 +5,19 @@ export type Invocation = {
     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;

package/dist/src/cli/arguments.js

@@ -50,6 +50,8 @@ function textValues(argumentsList) {
 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);
@@ -70,6 +72,17 @@ export function parseInvocation(given) {
         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",
@@ -79,21 +92,89 @@ function chatsImport(argumentsList) {
     if (argumentsList.length === 1 &&
         ["--help", "-h"].includes(String(argumentsList[0])))
         return { kind: "chats-import-help" };
-    const paths = [];
-    let literal = false;
+    const state = {
+        paths: [],
+        roots: [],
+        excludeProjects: [],
+        literal: false,
+        option: undefined,
+        previousImportId: undefined,
+    };
     for (const argument of argumentsList) {
-        if (!literal && argument === "--")
-            literal = true;
-        else if (!literal && argument.startsWith("-"))
-            return error("unexpected-option");
-        else if (argument === "")
-            return error("missing-argument");
-        else
-            paths.push(argument);
+        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;
     }
-    return paths.length === 0
-        ? error("missing-argument")
-        : { kind: "chats-import", paths };
+    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 {

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

@@ -4,6 +4,7 @@ export interface Interruption {
     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>;

package/dist/src/cli/client.js

@@ -1,7 +1,7 @@
 import net from "node:net";
 import { join } from "node:path";
 import { socketAddress } from "../broker/socket-address.js";
-import { parseReplyLine, requestLine, } from "../protocol.js";
+import { parseReplyLine, record, requestLine, } from "../protocol.js";
 const mutations = ["run", "decision", "run-command"];
 function unavailable(runtimeDirectory) {
     return {
@@ -89,6 +89,43 @@ const unobserved = () => undefined;
 export function send(runtimeDirectory, request) {
     return exchange({ runtimeDirectory, request, onEvent: unobserved });
 }
+function listedRuns(result) {
+    const runs = result["runs"];
+    return Array.isArray(runs)
+        ? runs.map(record).filter((run) => run !== undefined)
+        : [];
+}
+export async function listRuns(runtimeDirectory) {
+    const first = await send(runtimeDirectory, {
+        operation: "status",
+        parameters: { limit: 500 },
+    });
+    if (first.kind === "error")
+        return first;
+    const runs = listedRuns(first.result);
+    let next = first.result["next"];
+    let after = "";
+    while (typeof next === "string") {
+        if (next <= after)
+            return {
+                kind: "error",
+                error: {
+                    code: "invalid-run-page",
+                    detail: "The run-list cursor did not advance.",
+                },
+            };
+        after = next;
+        const page = await send(runtimeDirectory, {
+            operation: "status",
+            parameters: { limit: 500, after },
+        });
+        if (page.kind === "error")
+            return page;
+        runs.push(...listedRuns(page.result));
+        next = page.result["next"];
+    }
+    return { kind: "result", result: { ...first.result, runs, next: null } };
+}
 export function mutate(runtimeDirectory, mutation) {
     return exchange({
         runtimeDirectory,

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

@@ -1,3 +1,4 @@
+import type { WatchPrSettings } from "./watch-pr-settings.ts";
 import type { RuntimeInvocation } from "./runtime-arguments.ts";
 export interface Terminal {
     readonly out: (text: string) => void;
@@ -5,6 +6,8 @@ export interface Terminal {
 }
 export interface CommandEnvironment {
     readonly runtimeDirectory: string | undefined;
+    readonly watchActions?: string;
+    readonly watchPr?: WatchPrSettings;
     readonly client?: string;
     readonly workingDirectory: string;
     readonly terminal: Terminal;