@fungi.computer/knapsack 0.0.0-stage → 0.0.2

package/dist/index.d.ts

@@ -0,0 +1,70 @@
+import { type CapabilitySource, type InvocationContext, type MyceliumJsonValue } from "@fungi.computer/mycelium";
+import { files, type FilesConnectionOptions } from "./files.js";
+import { mcpServers } from "./mcp.js";
+/** Generic advertised-call interface supplied by one Computer provider. */
+export type KnapsackComputer = Readonly<{
+    /** Knapsack stops waiting when `signal` aborts, whether or not the provider honours it. */
+    getCapabilities: (signal: AbortSignal) => Promise<MyceliumJsonValue>;
+    /** Dispatch one decoded advertised identifier with its JSON payload. */
+    call: (capabilityId: string, input: MyceliumJsonValue, context: InvocationContext) => Promise<MyceliumJsonValue>;
+}>;
+/** Selection and naming required to connect one Computer to Mycelium. */
+export type ComputerConnectionOptions = Readonly<{
+    id: string;
+    name: string;
+    /** Logical parent namespace; the Computer name is its final segment. */
+    namespace?: readonly string[];
+    /** Files scoped by the host to this Computer, under its own authority id. */
+    files?: FilesConnectionOptions;
+    /**
+     * Short parenthetical shown alongside the Computer's real name in forage
+     * discovery, e.g. "home" for the agent's own machine. Omit for Computers
+     * with no such role; never used to rename or hide the Computer itself.
+     */
+    role?: string;
+    computer: KnapsackComputer;
+}>;
+/** Why one Computer contributed no module to an acquisition. */
+export type ComputerUnavailableReason = "rejected" | "timeout" | "invalid-advertisement";
+/** One Computer whose advertisement could not be acquired. */
+export declare class ComputerUnavailableError extends Error {
+    readonly name = "ComputerUnavailableError";
+    readonly computerId: string;
+    readonly reason: ComputerUnavailableReason;
+    constructor(computerId: string, reason: ComputerUnavailableReason, cause?: unknown);
+}
+declare function computer(input: ComputerConnectionOptions): CapabilitySource;
+/** A captured host connection list; authority remains with its supplying host. */
+export type ComputersConnectionOptions = Readonly<{
+    id: string;
+    /** Capture the current host-owned connection list and its revision. */
+    read: () => Readonly<{
+        version: string;
+        connections: readonly ComputerConnectionOptions[];
+    }>;
+    /** Register invalidation and return its release callback. */
+    subscribe: (invalidate: () => void) => () => void;
+    /** Receives each Computer dropped from an acquisition and why. */
+    onUnavailable: (error: ComputerUnavailableError) => void;
+    /** Bound on each Computer's advertisement read; defaults to 10 seconds. */
+    describeTimeoutMillis?: number;
+}>;
+/**
+ * Acquire every captured Computer concurrently. A Computer that rejects, times
+ * out, or advertises an unusable schema is dropped and reported; the remaining
+ * Computers and Files stay available. Aborting the acquisition rejects it.
+ */
+declare function computers(input: ComputersConnectionOptions): CapabilitySource;
+/** Agent tool connections available for composition through Mycelium. */
+export declare const Knapsack: Readonly<{
+    /** Project one Computer's advertised operations into a capability source. */
+    computer: typeof computer;
+    /** Capture a changing Computer list, reporting unavailable providers independently. */
+    computers: typeof computers;
+    /** Build Files operations from one captured host port. */
+    files: typeof files;
+    /** Connect a changing list of remote MCP servers, reporting unavailable ones independently. */
+    mcpServers: typeof mcpServers;
+}>;
+export { McpServerUnavailableError, type McpServerConnection, type McpServerUnavailableReason, type McpServersConnectionOptions, } from "./mcp.js";
+export { FilesEditError, filesEditFailureSchema, type FilesEditErrorReason, type FilesConnectionOptions, type FilesPort, type FilesPatch, type FilesSurface, edit, readInputSchema, readOutputSchema, listInputSchema, listOutputSchema, globInputSchema, globOutputSchema, grepInputSchema, grepOutputSchema, editInputSchema, editOutputSchema, patchInputSchema, patchOutputSchema, type FileTool, type FileToolName, } from "./files.js";

package/dist/index.js

@@ -0,0 +1,178 @@
+import { Mycelium, } from "@fungi.computer/mycelium";
+import * as Effect from "effect/Effect";
+import * as Result from "effect/Result";
+import { z } from "zod";
+import { files } from "./files.js";
+import { mcpServers } from "./mcp.js";
+const maximumCapabilities = 256;
+const describeConcurrency = 8;
+const defaultDescribeTimeoutMillis = 10_000;
+const utf8 = new TextEncoder();
+const jsonValueSchema = z.json();
+const jsonSchemaDocument = z.custom((value) => jsonValueSchema.safeParse(value).success);
+const capabilityNameSchema = z
+    .string()
+    .min(1)
+    .max(128)
+    .regex(/^[A-Za-z][A-Za-z0-9_]*$/);
+const capabilitySchema = z.strictObject({
+    id: capabilityNameSchema,
+    name: capabilityNameSchema,
+    kind: z.string().min(1).max(128),
+    description: z.string().min(1).max(2_048),
+    parameters: jsonSchemaDocument,
+    output: jsonSchemaDocument.optional(),
+});
+const capabilitiesSchema = z.array(capabilitySchema).max(maximumCapabilities);
+function operationSchema(document) {
+    return z.fromJSONSchema(document).pipe(jsonValueSchema);
+}
+function operationOutputSchema(document) {
+    return z.intersection(jsonValueSchema, z.fromJSONSchema(document));
+}
+async function snapshotVersion(serialized) {
+    const bytes = utf8.encode(serialized);
+    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
+    return `computer-${Array.from(digest, (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+}
+/** One Computer whose advertisement could not be acquired. */
+export class ComputerUnavailableError extends Error {
+    name = "ComputerUnavailableError";
+    computerId;
+    reason;
+    constructor(computerId, reason, cause) {
+        super(`Computer ${computerId} is unavailable: ${reason}`, { cause });
+        this.computerId = computerId;
+        this.reason = reason;
+    }
+}
+function projectComputer(input, advertisement) {
+    const capabilities = capabilitiesSchema.parse(advertisement);
+    const operations = {};
+    for (const advertised of capabilities) {
+        const output = advertised.output === undefined
+            ? jsonValueSchema
+            : operationOutputSchema(advertised.output);
+        operations[advertised.id] = Mycelium.operation({
+            // Computer advertisements may execute arbitrary host actions.
+            replay: "unsafe",
+            description: advertised.description,
+            input: operationSchema(advertised.parameters),
+            output,
+            execute: (value, context) => input.computer.call(advertised.id, value, context),
+        });
+    }
+    if (input.files !== undefined) {
+        if (operations.files !== undefined)
+            throw new Error("Computer advertisement reserves the files namespace");
+        operations.files = files(input.files).module;
+    }
+    const description = input.role === undefined
+        ? `Computer "${input.name}": capabilities advertised by this Computer.`
+        : `Computer "${input.name}" (${input.role}): capabilities advertised by this Computer.`;
+    const module = Mycelium.module({
+        id: input.id,
+        name: input.name,
+        namespace: input.namespace ?? [],
+        description,
+        operations,
+    });
+    return { module, serialized: JSON.stringify(capabilities) };
+}
+/** Read and project one advertisement; interruption abandons a hung provider. */
+function describeComputer(input, timeoutMillis) {
+    return Effect.tryPromise({
+        try: (signal) => input.computer.getCapabilities(signal),
+        catch: (cause) => new ComputerUnavailableError(input.id, "rejected", cause),
+    }).pipe(Effect.timeoutOrElse({
+        duration: timeoutMillis,
+        orElse: () => Effect.fail(new ComputerUnavailableError(input.id, "timeout")),
+    }), Effect.flatMap((advertisement) => Effect.try({
+        try: () => projectComputer(input, advertisement),
+        catch: (cause) => new ComputerUnavailableError(input.id, "invalid-advertisement", cause),
+    })), Effect.flatMap(({ module, serialized }) => Effect.promise(() => snapshotVersion(serialized)).pipe(Effect.map((version) => ({ module, version })))));
+}
+async function runAcquisition(effect, signal) {
+    signal.throwIfAborted();
+    try {
+        return await Effect.runPromise(effect, { signal });
+    }
+    catch (error) {
+        signal.throwIfAborted();
+        throw error;
+    }
+}
+function computer(input) {
+    return {
+        id: input.id,
+        acquire: async ({ signal }) => {
+            const described = await runAcquisition(Effect.result(describeComputer(input, defaultDescribeTimeoutMillis)), signal);
+            if (Result.isFailure(described))
+                throw described.failure;
+            return {
+                snapshot: {
+                    version: described.success.version,
+                    modules: [described.success.module],
+                },
+                release: () => Promise.resolve(),
+            };
+        },
+    };
+}
+/**
+ * Acquire every captured Computer concurrently. A Computer that rejects, times
+ * out, or advertises an unusable schema is dropped and reported; the remaining
+ * Computers and Files stay available. Aborting the acquisition rejects it.
+ */
+function computers(input) {
+    const timeoutMillis = input.describeTimeoutMillis ?? defaultDescribeTimeoutMillis;
+    return {
+        id: input.id,
+        acquire: async (context) => {
+            context.signal.throwIfAborted();
+            const unsubscribe = input.subscribe(context.invalidate);
+            try {
+                const captured = input.read();
+                const described = await runAcquisition(Effect.forEach(captured.connections, (connection) => Effect.result(describeComputer(connection, timeoutMillis)), { concurrency: describeConcurrency }), context.signal);
+                const modules = [];
+                const versions = [captured.version];
+                for (const result of described) {
+                    if (Result.isFailure(result)) {
+                        input.onUnavailable(result.failure);
+                        versions.push(`unavailable:${result.failure.computerId}:${result.failure.reason}`);
+                        continue;
+                    }
+                    modules.push(result.success.module);
+                    versions.push(result.success.version);
+                }
+                return {
+                    snapshot: {
+                        version: await snapshotVersion(JSON.stringify(versions)),
+                        modules,
+                    },
+                    release: () => {
+                        unsubscribe();
+                        return Promise.resolve();
+                    },
+                };
+            }
+            catch (error) {
+                unsubscribe();
+                throw error;
+            }
+        },
+    };
+}
+/** Agent tool connections available for composition through Mycelium. */
+export const Knapsack = Object.freeze({
+    /** Project one Computer's advertised operations into a capability source. */
+    computer,
+    /** Capture a changing Computer list, reporting unavailable providers independently. */
+    computers,
+    /** Build Files operations from one captured host port. */
+    files,
+    /** Connect a changing list of remote MCP servers, reporting unavailable ones independently. */
+    mcpServers,
+});
+export { McpServerUnavailableError, } from "./mcp.js";
+export { FilesEditError, filesEditFailureSchema, edit, readInputSchema, readOutputSchema, listInputSchema, listOutputSchema, globInputSchema, globOutputSchema, grepInputSchema, grepOutputSchema, editInputSchema, editOutputSchema, patchInputSchema, patchOutputSchema, } from "./files.js";

package/dist/mcp.d.ts

@@ -0,0 +1,54 @@
+import type { FetchLike } from "@modelcontextprotocol/client";
+import { type CapabilitySource } from "@fungi.computer/mycelium";
+/** One remote MCP server a host has admitted for an Agent. */
+export type McpServerConnection = Readonly<{
+    /** Stable authority id for the server's module; never shown as a secret. */
+    id: string;
+    /** Model-facing identifier: the guest calls `env.<namespace>.<name>.<tool>()`. */
+    name: string;
+    /** Streamable HTTP endpoint. */
+    url: URL;
+    /**
+     * Host-held request headers such as `Authorization`. They are sent only to
+     * `url` by the SDK transport and never enter the snapshot, the catalog or a
+     * tool result.
+     */
+    headers?: Readonly<Record<string, string>>;
+}>;
+/** A captured host list of remote MCP servers; authority stays with the host. */
+export type McpServersConnectionOptions = Readonly<{
+    id: string;
+    /** Capture the current server list and a secret-free revision of it. */
+    read: () => Promise<Readonly<{
+        version: string;
+        servers: readonly McpServerConnection[];
+    }>>;
+    /** Register invalidation and return its release callback. */
+    subscribe: (invalidate: () => void) => () => void;
+    /** Receives each server dropped from an acquisition and why. */
+    onUnavailable: (error: McpServerUnavailableError) => void;
+    /** Host egress for every MCP request; the host chooses where requests may go. */
+    fetch: FetchLike;
+    /** Parent namespace for every server module; defaults to `["mcp"]`. */
+    namespace?: readonly string[];
+    /** Bound on connecting and listing one server; defaults to 10 seconds. */
+    connectTimeoutMillis?: number;
+}>;
+/** Why one MCP server contributed no module to an acquisition. */
+export type McpServerUnavailableReason = "rejected" | "unauthorized" | "timeout" | "invalid-advertisement";
+/** One MCP server whose tools could not be acquired. */
+export declare class McpServerUnavailableError extends Error {
+    readonly name = "McpServerUnavailableError";
+    readonly serverId: string;
+    readonly reason: McpServerUnavailableReason;
+    constructor(serverId: string, reason: McpServerUnavailableReason, cause?: unknown);
+}
+/**
+ * Connect every captured MCP server concurrently with the maintained SDK
+ * client over Streamable HTTP and project its tools into one Mycelium module
+ * per server. A server that rejects, refuses its credential, times out or
+ * advertises nothing usable is dropped and reported; the others stay
+ * available. Releasing the acquisition closes every client.
+ */
+declare function mcpServers(input: McpServersConnectionOptions): CapabilitySource;
+export { mcpServers };

package/dist/mcp.js

@@ -0,0 +1,237 @@
+import { Mycelium, } from "@fungi.computer/mycelium";
+import { jsonSchemaSubset } from "@fungi.computer/forage/json-schema-subset";
+import * as Effect from "effect/Effect";
+import * as Result from "effect/Result";
+import { z } from "zod";
+const maximumServers = 16;
+const maximumTools = 256;
+const maximumToolPages = 16;
+const connectConcurrency = 4;
+const defaultConnectTimeoutMillis = 10_000;
+const maximumDescription = 2_048;
+const utf8 = new TextEncoder();
+const jsonValueSchema = z.json();
+const argumentsSchema = z.record(z.string(), jsonValueSchema);
+const identifierPattern = /^[A-Za-z][A-Za-z0-9_]*$/u;
+/** One MCP server whose tools could not be acquired. */
+export class McpServerUnavailableError extends Error {
+    name = "McpServerUnavailableError";
+    serverId;
+    reason;
+    constructor(serverId, reason, cause) {
+        super(`MCP server ${serverId} is unavailable: ${reason}`, { cause });
+        this.serverId = serverId;
+        this.reason = reason;
+    }
+}
+async function digest(serialized) {
+    const bytes = new Uint8Array(await crypto.subtle.digest("SHA-256", utf8.encode(serialized)));
+    return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/** Map an MCP tool name onto the guest's identifier grammar. */
+function operationKey(toolName) {
+    const mapped = toolName.replace(/[^A-Za-z0-9_]/gu, "_");
+    return identifierPattern.test(mapped) ? mapped : `t_${mapped}`;
+}
+const looseDescription = "Arguments are a JSON object; this server's schema is outside the supported subset, so the server validates them.";
+/** The tool's advertised schema when it fits Forage's subset, else a JSON object. */
+function toolInput(tool) {
+    const subset = jsonSchemaSubset().safeParse(tool.inputSchema);
+    if (!subset.success)
+        return { schema: argumentsSchema, loose: true };
+    try {
+        return {
+            schema: z.fromJSONSchema(subset.data).pipe(argumentsSchema),
+            loose: false,
+        };
+    }
+    catch {
+        return { schema: argumentsSchema, loose: true };
+    }
+}
+function toolDescription(tool, loose) {
+    const text = [tool.title, tool.description]
+        .filter((part) => part !== undefined && part.length > 0)
+        .join(": ");
+    const base = text.length > 0 ? text : tool.name;
+    const described = loose ? `${base}\n\n${looseDescription}` : base;
+    return described.slice(0, maximumDescription);
+}
+function project(server, namespace, client, tools) {
+    const operations = {};
+    for (const tool of tools) {
+        const key = operationKey(tool.name);
+        // A later tool that maps onto a taken key is dropped, never renamed twice.
+        if (key in operations)
+            continue;
+        const input = toolInput(tool);
+        operations[key] = Mycelium.operation({
+            // Only the server's own read-only hint permits replay.
+            replay: tool.annotations?.readOnlyHint === true ? "safe" : "unsafe",
+            description: toolDescription(tool, input.loose),
+            input: input.schema,
+            output: jsonValueSchema,
+            execute: async (args, context) => {
+                const result = await client.callTool({ name: tool.name, arguments: args }, { signal: context.signal });
+                // MCP's own result shape: structured data when the server sends it,
+                // otherwise the content blocks with the error flag.
+                if (result.isError !== true && result.structuredContent !== undefined)
+                    return jsonValueSchema.parse(result.structuredContent);
+                return jsonValueSchema.parse({
+                    isError: result.isError === true,
+                    content: result.content,
+                });
+            },
+        });
+    }
+    return Mycelium.module({
+        id: server.id,
+        name: server.name,
+        namespace,
+        description: `MCP server "${server.name}" at ${server.url.origin}: tools it advertises.`,
+        operations,
+    });
+}
+async function listAllTools(client, signal) {
+    const tools = [];
+    let cursor;
+    for (let page = 0; page < maximumToolPages; page += 1) {
+        const listed = await client.listTools(cursor === undefined ? undefined : { cursor }, { signal });
+        tools.push(...listed.tools);
+        if (tools.length > maximumTools)
+            throw new Error(`MCP server advertises more than ${String(maximumTools)} tools`);
+        cursor = listed.nextCursor;
+        if (cursor === undefined)
+            return tools;
+    }
+    throw new Error(`MCP server tool list exceeds ${String(maximumToolPages)} pages`);
+}
+/**
+ * The SDK builds its whole schema set when its module evaluates, so it loads
+ * on the first connection instead of during a host Worker's startup.
+ */
+function loadClientModule() {
+    return import("@modelcontextprotocol/client");
+}
+function failureReason(mcp, cause) {
+    if (mcp.UnauthorizedError.isInstance(cause))
+        return "unauthorized";
+    if (mcp.SdkHttpError.isInstance(cause) &&
+        (cause.status === 401 || cause.status === 403))
+        return "unauthorized";
+    return "rejected";
+}
+async function connect(server, namespace, fetch, signal) {
+    const mcp = await loadClientModule();
+    const client = new mcp.Client({ name: "fungi-knapsack", version: "1" });
+    const transport = new mcp.StreamableHTTPClientTransport(new URL(server.url), {
+        // Credentials go to this endpoint only; a redirect could carry them away.
+        requestInit: { headers: { ...server.headers }, redirect: "error" },
+        fetch,
+    });
+    try {
+        await client.connect(transport, { signal });
+    }
+    catch (cause) {
+        await client.close();
+        throw new McpServerUnavailableError(server.id, failureReason(mcp, cause), cause);
+    }
+    try {
+        const tools = await listAllTools(client, signal).catch((cause) => {
+            throw new McpServerUnavailableError(server.id, failureReason(mcp, cause) === "unauthorized"
+                ? "unauthorized"
+                : "invalid-advertisement", cause);
+        });
+        let module;
+        try {
+            module = project(server, namespace, client, tools);
+        }
+        catch (cause) {
+            throw new McpServerUnavailableError(server.id, "invalid-advertisement", cause);
+        }
+        const version = await digest(JSON.stringify([
+            server.id,
+            server.name,
+            server.url.href,
+            tools.map((tool) => [
+                tool.name,
+                tool.description ?? null,
+                tool.inputSchema,
+                tool.annotations?.readOnlyHint ?? null,
+            ]),
+        ]));
+        return { module, version, close: () => client.close() };
+    }
+    catch (error) {
+        await client.close();
+        throw error;
+    }
+}
+function connectWithin(server, namespace, fetch, timeoutMillis) {
+    return Effect.tryPromise({
+        try: (signal) => connect(server, namespace, fetch, signal),
+        catch: (cause) => cause instanceof McpServerUnavailableError
+            ? cause
+            : new McpServerUnavailableError(server.id, "rejected", cause),
+    }).pipe(Effect.timeoutOrElse({
+        duration: timeoutMillis,
+        orElse: () => Effect.fail(new McpServerUnavailableError(server.id, "timeout")),
+    }));
+}
+/**
+ * Connect every captured MCP server concurrently with the maintained SDK
+ * client over Streamable HTTP and project its tools into one Mycelium module
+ * per server. A server that rejects, refuses its credential, times out or
+ * advertises nothing usable is dropped and reported; the others stay
+ * available. Releasing the acquisition closes every client.
+ */
+function mcpServers(input) {
+    const timeoutMillis = input.connectTimeoutMillis ?? defaultConnectTimeoutMillis;
+    const namespace = input.namespace ?? ["mcp"];
+    return {
+        id: input.id,
+        acquire: async (context) => {
+            context.signal.throwIfAborted();
+            const unsubscribe = input.subscribe(context.invalidate);
+            const opened = [];
+            const closeAll = async () => {
+                await Promise.allSettled(opened.map((server) => server.close()));
+            };
+            try {
+                const captured = await input.read();
+                if (captured.servers.length > maximumServers)
+                    throw new Error(`At most ${String(maximumServers)} MCP servers per source`);
+                const results = await Effect.runPromise(Effect.forEach(captured.servers, (server) => Effect.result(connectWithin(server, namespace, input.fetch, timeoutMillis).pipe(
+                // Record each open client at once, so an aborted
+                // acquisition still closes the ones that connected.
+                Effect.tap((connected) => Effect.sync(() => opened.push(connected))))), { concurrency: connectConcurrency }), { signal: context.signal });
+                const versions = [captured.version];
+                for (const result of results) {
+                    if (Result.isFailure(result)) {
+                        input.onUnavailable(result.failure);
+                        versions.push(`unavailable:${result.failure.serverId}:${result.failure.reason}`);
+                        continue;
+                    }
+                    versions.push(result.success.version);
+                }
+                context.signal.throwIfAborted();
+                return {
+                    snapshot: {
+                        version: `mcp-${await digest(JSON.stringify(versions))}`,
+                        modules: opened.map((server) => server.module),
+                    },
+                    release: async () => {
+                        unsubscribe();
+                        await closeAll();
+                    },
+                };
+            }
+            catch (error) {
+                unsubscribe();
+                await closeAll();
+                throw error;
+            }
+        },
+    };
+}
+export { mcpServers };

package/dist/patch-grammar.d.ts

@@ -0,0 +1 @@
+export declare const patchGrammar = "start: begin_patch hunk+ end_patch\nbegin_patch: \"*** Begin Patch\" LF\nend_patch: \"*** End Patch\" LF?\n\nhunk: add_hunk | delete_hunk | update_hunk\nadd_hunk: \"*** Add File: \" filename LF add_line+\ndelete_hunk: \"*** Delete File: \" filename LF\nupdate_hunk: \"*** Update File: \" filename LF change_move? change?\n\nfilename: /(.+)/\nadd_line: \"+\" /(.*)/ LF -> line\n\nchange_move: \"*** Move to: \" filename LF\nchange: (change_context | change_line)+ eof_line?\nchange_context: (\"@@\" | \"@@ \" /(.+)/) LF\nchange_line: (\"+\" | \"-\" | \" \") /(.*)/ LF\neof_line: \"*** End of File\" LF\n\n%import common.LF\n";

package/dist/patch-grammar.js

@@ -0,0 +1,3 @@
+// OpenAI Codex rust-v0.154.0 core/assets/tools/apply_patch.lark (Apache-2.0).
+// Kept verbatim; the native engine, not this presentation grammar, validates patches.
+export const patchGrammar = 'start: begin_patch hunk+ end_patch\nbegin_patch: "*** Begin Patch" LF\nend_patch: "*** End Patch" LF?\n\nhunk: add_hunk | delete_hunk | update_hunk\nadd_hunk: "*** Add File: " filename LF add_line+\ndelete_hunk: "*** Delete File: " filename LF\nupdate_hunk: "*** Update File: " filename LF change_move? change?\n\nfilename: /(.+)/\nadd_line: "+" /(.*)/ LF -> line\n\nchange_move: "*** Move to: " filename LF\nchange: (change_context | change_line)+ eof_line?\nchange_context: ("@@" | "@@ " /(.+)/) LF\nchange_line: ("+" | "-" | " ") /(.*)/ LF\neof_line: "*** End of File" LF\n\n%import common.LF\n';

package/dist/patch.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Presentation reading of the Codex `apply_patch` grammar (see
+ * `patch-grammar.ts`). Pure and side-effect free: display consumers import it
+ * through `@fungi.computer/knapsack/patch`. The native patch engine, not this
+ * reader, validates and applies patches, so the reader is tolerant: text that
+ * does not match the grammar is skipped rather than rejected.
+ */
+/** One body line of an update or add hunk. */
+export type CodexPatchLine = Readonly<{
+    kind: "add" | "context" | "remove";
+    text: string;
+}>;
+/** One `@@` change block; `context` is the text after `@@`, when present. */
+export type CodexPatchHunk = Readonly<{
+    context?: string | undefined;
+    lines: readonly CodexPatchLine[];
+}>;
+/** One file operation in a patch, in patch order. */
+export type CodexPatchFile = Readonly<{
+    operation: "add" | "delete" | "update";
+    path: string;
+    /** Destination of an update with `*** Move to:`. */
+    moveTo?: string | undefined;
+    hunks: readonly CodexPatchHunk[];
+}>;
+/** Read the file operations of one Codex patch, in order. */
+export declare function parseCodexPatch(patch: string): readonly CodexPatchFile[];

package/dist/patch.js

@@ -0,0 +1,56 @@
+/**
+ * Presentation reading of the Codex `apply_patch` grammar (see
+ * `patch-grammar.ts`). Pure and side-effect free: display consumers import it
+ * through `@fungi.computer/knapsack/patch`. The native patch engine, not this
+ * reader, validates and applies patches, so the reader is tolerant: text that
+ * does not match the grammar is skipped rather than rejected.
+ */
+const fileHeaders = [
+    ["*** Add File: ", "add"],
+    ["*** Delete File: ", "delete"],
+    ["*** Update File: ", "update"],
+];
+const moveHeader = /^\*\*\* Move to: (.+)$/u;
+function bodyLine(line) {
+    if (line.startsWith("+"))
+        return { kind: "add", text: line.slice(1) };
+    if (line.startsWith("-"))
+        return { kind: "remove", text: line.slice(1) };
+    if (line.startsWith(" "))
+        return { kind: "context", text: line.slice(1) };
+    return undefined;
+}
+/** Read the file operations of one Codex patch, in order. */
+export function parseCodexPatch(patch) {
+    const files = [];
+    let file;
+    for (const line of patch.split("\n")) {
+        const header = fileHeaders.find(([prefix]) => line.startsWith(prefix));
+        if (header !== undefined) {
+            const [prefix, operation] = header;
+            file = { operation, path: line.slice(prefix.length).trim(), hunks: [] };
+            files.push(file);
+            continue;
+        }
+        if (file === undefined)
+            continue;
+        const move = moveHeader.exec(line);
+        if (move !== null) {
+            file.moveTo = (move[1] ?? "").trim();
+            continue;
+        }
+        if (line.startsWith("@@")) {
+            const context = line.slice(2).trim();
+            file.hunks.push(context === "" ? { lines: [] } : { context, lines: [] });
+            continue;
+        }
+        const body = bodyLine(line);
+        if (body === undefined)
+            continue;
+        const hunk = file.hunks.at(-1) ?? { lines: [] };
+        if (file.hunks.length === 0)
+            file.hunks.push(hunk);
+        hunk.lines.push(body);
+    }
+    return files;
+}

package/docs/api/README.md

@@ -0,0 +1,17 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+**@fungi.computer/knapsack**
+
+---
+
+# @fungi.computer/knapsack
+
+## Modules
+
+| Module                                  | Description |
+| --------------------------------------- | ----------- |
+| [files-patch](files-patch.md)           | -           |
+| [files-read-codec](files-read-codec.md) | -           |
+| [files-read](files-read.md)             | -           |
+| [index](index.md)                       | -           |
+| [patch](patch.md)                       | -           |