@hheei/pi-apply-patch 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hheei
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,9 @@
-# Temporary Holding Version
+# @hheei/pi-apply-patch
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Standalone `apply_patch` extension for Pi. Install with `pi install npm:@hheei/pi-apply-patch`. The tool is registered with `defaultActive: false`; enable it through your loadout.
+
+Owns V4A parsing, pure JavaScript jsdiff worker matching, per-path publishing, partial outcomes and the `applyPatch` group in `ext_settings.json`. Confirmed edits persist after failure or cancellation. File mutation locks are shared with `edit` and `write` through ext-core.
+
+No file tools, Bash, Python or UI extension is required. Optional UI rendering comes through ext-core; native tool text remains available without it. Worker code is included in `dist`.
+
+See [architecture](../../docs/architecture/apply-patch.md) and [tool packages](../../docs/ext-tools/README.md).

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,3 @@
+# Third-Party Notices
+
+No third-party code is vendored in this package.

package/dist/apply-patch/executor.d.ts

@@ -0,0 +1,15 @@
+import { type PatchFs } from "./fs.js";
+import type { ApplyPatchInWorkspaceResult, ApplyPatchProgress } from "./outcome.js";
+import { type V4aPatch } from "./parser.js";
+import type { ApplyPatchPolicy } from "./policy.js";
+export interface ApplyPatchInWorkspaceOptions {
+    readonly workspaceRoot: string;
+    readonly patch: string;
+    readonly parsedPatch?: V4aPatch;
+    readonly policy: ApplyPatchPolicy;
+    readonly signal?: AbortSignal;
+    readonly onProgress?: (progress: ApplyPatchProgress) => void;
+    readonly fs?: PatchFs;
+    readonly lockKey?: string;
+}
+export declare function applyPatchInWorkspace(options: ApplyPatchInWorkspaceOptions): Promise<ApplyPatchInWorkspaceResult>;

package/dist/apply-patch/executor.js

@@ -0,0 +1,407 @@
+import { acquireMutationLock, errorMessage } from "@hheei/pi-ext-core";
+import { APPLY_PATCH_MAX_FILE_SIZE, createLocalPatchFs, FsTransportError, fileTooLarge, gcAgentPatchTemps, publishPreparedFile, sftpTimeoutMs, } from "./fs.js";
+import { runJsDiffUpdate } from "./jsdiff.js";
+import { findV4aPatchConflicts, operationTouchedPaths, parseV4aPatch, } from "./parser.js";
+import { assertPatchPath } from "./paths.js";
+const SNAPSHOT_MAX_LINES = 150;
+class PatchUpdateError extends Error {
+    diagnostics;
+    constructor(message, diagnostics) {
+        super(message);
+        this.diagnostics = diagnostics;
+    }
+}
+function lineCount(content) {
+    if (content === undefined || content.length === 0)
+        return 0;
+    const text = typeof content === "string" ? content : new TextDecoder().decode(content);
+    const lines = text.split(/\r\n|\n|\r/);
+    return lines.at(-1) === "" ? lines.length - 1 : lines.length;
+}
+function hunkDelta(hunks) {
+    let addedLines = 0;
+    let removedLines = 0;
+    for (const hunk of hunks)
+        for (const line of hunk.lines)
+            if (line.kind === "add")
+                addedLines += 1;
+            else if (line.kind === "remove")
+                removedLines += 1;
+    return { addedLines, removedLines };
+}
+function plannedDelta(operation, content) {
+    if (operation.kind === "add")
+        return { addedLines: lineCount(operation.content), removedLines: 0 };
+    if (operation.kind === "delete")
+        return { addedLines: 0, removedLines: lineCount(content) };
+    return hunkDelta(operation.hunks);
+}
+function progressTotals(operations) {
+    const paths = new Set();
+    let addedLines = 0;
+    let removedLines = 0;
+    for (const operation of operations) {
+        paths.add(operation.path);
+        if (operation.status === "applied" ||
+            operation.status === "fuzzy" ||
+            operation.status === "partial") {
+            addedLines += operation.addedLines;
+            removedLines += operation.removedLines;
+        }
+    }
+    return { files: paths.size, addedLines, removedLines };
+}
+function splitTextLines(content) {
+    const lines = new TextDecoder().decode(content).split(/\r\n|\n|\r/);
+    if (lines.at(-1) === "")
+        lines.pop();
+    return Object.freeze(lines);
+}
+function fileSnapshot(path, before, after) {
+    return Object.freeze({
+        path,
+        hunkIndex: 1,
+        startLine: 1,
+        afterStartLine: 1,
+        before: Object.freeze((before === undefined ? [] : splitTextLines(before)).slice(0, SNAPSHOT_MAX_LINES)),
+        after: Object.freeze((after === undefined ? [] : splitTextLines(after)).slice(0, SNAPSHOT_MAX_LINES)),
+    });
+}
+function initialRejections(patch) {
+    const rejected = [];
+    const indices = new Set();
+    for (const conflict of findV4aPatchConflicts(patch)) {
+        const operationIndices = Object.freeze([...conflict.operationIndices]);
+        for (const index of operationIndices)
+            indices.add(index);
+        rejected.push(Object.freeze({
+            operationIndices,
+            paths: Object.freeze([conflict.path]),
+            error: conflict.message,
+            diagnostics: Object.freeze([]),
+        }));
+    }
+    return { rejected, indices };
+}
+function rejection(index, paths, error, diagnostics = []) {
+    return Object.freeze({
+        operationIndices: Object.freeze([index]),
+        paths: Object.freeze([...paths]),
+        error: errorMessage(error),
+        diagnostics: Object.freeze([...diagnostics]),
+    });
+}
+async function prepareUpdateBytes(fs, operation, policy, signal) {
+    const followed = await fs.statFollow(operation.path, signal);
+    if (followed.kind === "missing")
+        throw new Error(`Patch source does not exist: ${operation.path}`);
+    if (followed.kind !== "file")
+        throw new Error(`Patch path is not a regular file: ${operation.path}`);
+    if (followed.size > APPLY_PATCH_MAX_FILE_SIZE)
+        throw fileTooLarge(followed.size, operation.path);
+    const before = await fs.readFollow(operation.path, signal, sftpTimeoutMs(followed.size));
+    if (before.length > APPLY_PATCH_MAX_FILE_SIZE)
+        throw fileTooLarge(before.length, operation.path);
+    const stage = await runJsDiffUpdate({
+        before,
+        operation,
+        fuzzFactor: policy.fuzzFactor,
+        ...(signal === undefined ? {} : { signal }),
+    });
+    if (operation.hunks.length > 0 && stage.outcomes.length === 0)
+        throw new PatchUpdateError("One or more update hunks failed", stage.rejected);
+    if (stage.after.length > APPLY_PATCH_MAX_FILE_SIZE)
+        throw fileTooLarge(stage.after.length, operation.moveTo ?? operation.path);
+    return { bytes: stage.after, before, mode: followed.mode, stage };
+}
+function sourceChanged(path) {
+    return new Error(`Patch source changed during patch preparation: ${path}`);
+}
+async function revalidateSourceBaseline(fs, path, before, signal) {
+    const meta = await fs.statFollow(path, signal);
+    if (meta.kind !== "file" || meta.size > APPLY_PATCH_MAX_FILE_SIZE)
+        throw sourceChanged(path);
+    const current = await fs.readFollow(path, signal, sftpTimeoutMs(meta.size));
+    if (current.length > APPLY_PATCH_MAX_FILE_SIZE || Buffer.compare(current, before) !== 0)
+        throw sourceChanged(path);
+}
+async function revalidateDeleteBaseline(fs, path, meta, before, signal) {
+    const current = await fs.lstat(path, signal);
+    if (current.kind !== meta.kind || current.size !== meta.size || current.mode !== meta.mode)
+        throw sourceChanged(path);
+    if (before !== undefined)
+        await revalidateSourceBaseline(fs, path, before, signal);
+}
+async function applyAdd(fs, index, operation, signal) {
+    const existing = await fs.lstat(operation.path, signal);
+    if (existing.kind !== "missing")
+        throw new Error(`Patch add target already exists: ${operation.path}`);
+    const bytes = Buffer.from(operation.content, "utf8");
+    if (bytes.length > APPLY_PATCH_MAX_FILE_SIZE)
+        throw fileTooLarge(bytes.length, operation.path);
+    await publishPreparedFile(fs, operation.path, bytes, undefined, false, signal);
+    return Object.freeze({
+        operationIndex: index,
+        kind: "add",
+        paths: Object.freeze([operation.path]),
+        outcomes: Object.freeze([]),
+        snapshots: Object.freeze([fileSnapshot(operation.path, undefined, bytes)]),
+    });
+}
+async function applyDelete(fs, index, operation, signal) {
+    const meta = await fs.lstat(operation.path, signal);
+    if (meta.kind === "missing")
+        throw new Error(`Patch source does not exist: ${operation.path}`);
+    if (meta.kind === "directory")
+        throw new Error(`Patch path is not a regular file: ${operation.path}`);
+    if (meta.kind === "file" && meta.size > APPLY_PATCH_MAX_FILE_SIZE)
+        throw fileTooLarge(meta.size, operation.path);
+    const before = meta.kind === "file"
+        ? await fs.readFollow(operation.path, signal, sftpTimeoutMs(meta.size))
+        : undefined;
+    if (before !== undefined && before.length > APPLY_PATCH_MAX_FILE_SIZE)
+        throw fileTooLarge(before.length, operation.path);
+    await revalidateDeleteBaseline(fs, operation.path, meta, before, signal);
+    await fs.unlink(operation.path, signal);
+    return {
+        outcome: Object.freeze({
+            operationIndex: index,
+            kind: "delete",
+            paths: Object.freeze([operation.path]),
+            outcomes: Object.freeze([]),
+            snapshots: Object.freeze([fileSnapshot(operation.path, before, undefined)]),
+        }),
+        before,
+    };
+}
+async function applyUpdate(fs, index, operation, policy, signal) {
+    const prepared = await prepareUpdateBytes(fs, operation, policy, signal);
+    const dest = operation.moveTo ?? (await fs.followLeaf(operation.path, signal));
+    if (operation.moveTo !== undefined) {
+        const destMeta = await fs.lstat(operation.moveTo, signal);
+        if (destMeta.kind !== "missing")
+            throw new Error(`Patch move destination already exists: ${operation.moveTo}`);
+    }
+    await publishPreparedFile(fs, dest, prepared.bytes, prepared.mode, operation.moveTo === undefined, signal, () => revalidateSourceBaseline(fs, operation.path, prepared.before, signal));
+    const destPaths = operation.moveTo === undefined ? [operation.path] : [operation.moveTo];
+    const outcome = Object.freeze({
+        operationIndex: index,
+        kind: "update",
+        paths: Object.freeze(destPaths),
+        outcomes: Object.freeze([...prepared.stage.outcomes]),
+        snapshots: Object.freeze([...prepared.stage.snapshots]),
+    });
+    const result = {
+        outcome,
+        mode: prepared.stage.mode,
+        rejectedHunks: prepared.stage.rejected,
+        prepared: prepared.stage,
+    };
+    if (operation.moveTo === undefined)
+        return result;
+    try {
+        await revalidateSourceBaseline(fs, operation.path, prepared.before, signal);
+        await fs.unlink(operation.path, signal);
+        return {
+            ...result,
+            outcome: Object.freeze({
+                ...outcome,
+                paths: Object.freeze([operation.path, operation.moveTo]),
+            }),
+        };
+    }
+    catch (sourceError) {
+        return {
+            ...result,
+            sourceError,
+            sourceUnknown: sourceError instanceof FsTransportError && sourceError.phase !== "write",
+        };
+    }
+}
+export async function applyPatchInWorkspace(options) {
+    options.signal?.throwIfAborted();
+    const fs = options.fs ?? createLocalPatchFs(options.workspaceRoot);
+    const patch = options.parsedPatch ?? parseV4aPatch(options.patch);
+    for (const operation of patch.operations)
+        for (const path of operationTouchedPaths(operation))
+            assertPatchPath(path);
+    const initial = initialRejections(patch);
+    const rejected = [...initial.rejected];
+    const unconfirmed = [];
+    const notApplied = [];
+    const applied = [];
+    const rejectedIndices = new Set(initial.indices);
+    let exactUpdateCount = 0;
+    let fuzzyUpdateCount = 0;
+    let halt;
+    const progressOperations = patch.operations.map((operation, index) => ({
+        operationIndex: index,
+        kind: operation.kind,
+        path: operation.kind === "update" ? (operation.moveTo ?? operation.path) : operation.path,
+        ...plannedDelta(operation, undefined),
+        status: rejectedIndices.has(index) ? "rejected" : "pending",
+    }));
+    const setStatus = (index, status, outcome, update, partialReason, prepared) => {
+        const current = progressOperations[index];
+        if (current === undefined)
+            throw new Error(`Missing patch progress operation: ${index}`);
+        progressOperations[index] = Object.freeze({
+            ...current,
+            ...(update === undefined
+                ? {}
+                : update.kind !== "update" || prepared === undefined
+                    ? plannedDelta(update, undefined)
+                    : { addedLines: prepared.addedLines, removedLines: prepared.removedLines }),
+            status,
+            ...(status === "partial" && update !== undefined && outcome !== undefined
+                ? {
+                    appliedHunks: outcome.outcomes.length,
+                    totalHunks: update.hunks.length,
+                    ...(partialReason === undefined ? {} : { partialReason }),
+                }
+                : {}),
+        });
+    };
+    const emit = (stage) => {
+        const totals = progressTotals(progressOperations);
+        options.onProgress?.(Object.freeze({
+            stage,
+            ...totals,
+            operations: Object.freeze([...progressOperations]),
+        }));
+    };
+    const markNotApplied = (index, operation) => {
+        setStatus(index, "not_applied");
+        notApplied.push(rejection(index, operationTouchedPaths(operation), "NotApplied"));
+    };
+    const release = await acquireMutationLock(options.lockKey ?? fs.scope, options.signal);
+    try {
+        await gcAgentPatchTemps(fs, patch.operations.flatMap((operation) => operationTouchedPaths(operation).map((path) => {
+            const separator = path.lastIndexOf("/");
+            return separator < 0 ? "." : path.slice(0, separator);
+        })), options.signal);
+        emit("parsed");
+        for (const [index, operation] of patch.operations.entries()) {
+            if (rejectedIndices.has(index))
+                continue;
+            if (halt !== undefined) {
+                markNotApplied(index, operation);
+                continue;
+            }
+            if (options.signal?.aborted) {
+                if (applied.length === 0 && unconfirmed.length === 0)
+                    throw options.signal.reason ?? new Error("aborted");
+                halt = "not_applied";
+                markNotApplied(index, operation);
+                continue;
+            }
+            try {
+                if (operation.kind === "add") {
+                    const outcome = await applyAdd(fs, index, operation, options.signal);
+                    applied.push(outcome);
+                    setStatus(index, "applied", outcome);
+                }
+                else if (operation.kind === "delete") {
+                    const deleted = await applyDelete(fs, index, operation, options.signal);
+                    applied.push(deleted.outcome);
+                    const current = progressOperations[index];
+                    if (current !== undefined) {
+                        progressOperations[index] = Object.freeze({
+                            ...current,
+                            ...plannedDelta(operation, deleted.before),
+                            status: "applied",
+                        });
+                    }
+                }
+                else {
+                    const published = await applyUpdate(fs, index, operation, options.policy, options.signal);
+                    if (published.mode === "exact")
+                        exactUpdateCount += 1;
+                    if (published.mode === "fuzzy")
+                        fuzzyUpdateCount += 1;
+                    applied.push(published.outcome);
+                    const partialReason = published.rejectedHunks.length === 0
+                        ? undefined
+                        : published.rejectedHunks[0]?.kind === "context_not_found"
+                            ? "context not found"
+                            : "exact context is ambiguous";
+                    if (published.rejectedHunks.length > 0)
+                        rejected.push(rejection(index, operationTouchedPaths(operation), "One or more update hunks failed", published.rejectedHunks));
+                    if (published.sourceError !== undefined) {
+                        if (published.sourceUnknown === true) {
+                            unconfirmed.push(rejection(index, [operation.path], published.sourceError));
+                            setStatus(index, "unconfirmed", published.outcome, operation, undefined, published.prepared);
+                            halt = "unconfirmed";
+                        }
+                        else {
+                            rejected.push(rejection(index, [operation.path], published.sourceError));
+                            setStatus(index, "partial", published.outcome, operation, partialReason ?? String(published.sourceError), published.prepared);
+                        }
+                    }
+                    else {
+                        setStatus(index, partialReason === undefined
+                            ? published.mode === "fuzzy"
+                                ? "fuzzy"
+                                : "applied"
+                            : "partial", published.outcome, operation, partialReason, published.prepared);
+                    }
+                }
+            }
+            catch (error) {
+                if (options.signal?.aborted && applied.length === 0 && unconfirmed.length === 0)
+                    throw options.signal.reason ?? error;
+                if (error instanceof FsTransportError) {
+                    const bucket = error.phase === "write" ? notApplied : unconfirmed;
+                    const status = error.phase === "write" ? "not_applied" : "unconfirmed";
+                    bucket.push(rejection(index, operationTouchedPaths(operation), error));
+                    setStatus(index, status);
+                    halt = status;
+                }
+                else if (error instanceof PatchUpdateError) {
+                    rejected.push(rejection(index, operationTouchedPaths(operation), error, error.diagnostics));
+                    rejectedIndices.add(index);
+                    setStatus(index, "rejected");
+                }
+                else if (options.signal?.aborted) {
+                    notApplied.push(rejection(index, operationTouchedPaths(operation), error));
+                    setStatus(index, "not_applied");
+                    halt = "not_applied";
+                }
+                else {
+                    rejected.push(rejection(index, operationTouchedPaths(operation), error));
+                    rejectedIndices.add(index);
+                    setStatus(index, "rejected");
+                }
+            }
+            emit("publishing");
+            await new Promise((resolve) => setImmediate(resolve));
+        }
+        if (halt !== undefined) {
+            for (const [index, operation] of patch.operations.entries()) {
+                if (progressOperations[index]?.status !== "pending")
+                    continue;
+                markNotApplied(index, operation);
+            }
+        }
+        emit("done");
+        const totals = progressTotals(progressOperations);
+        return Object.freeze({
+            changedPaths: Object.freeze([
+                ...new Set(applied.flatMap((operation) => [...operation.paths])),
+            ]),
+            addedLines: totals.addedLines,
+            removedLines: totals.removedLines,
+            operations: Object.freeze([...progressOperations]),
+            operationCount: patch.operations.length,
+            exactUpdateCount,
+            fuzzyUpdateCount,
+            applied: Object.freeze(applied),
+            rejected: Object.freeze(rejected),
+            unconfirmed: Object.freeze(unconfirmed),
+            notApplied: Object.freeze(notApplied),
+        });
+    }
+    finally {
+        await release();
+    }
+}

package/dist/apply-patch/fs.d.ts

@@ -0,0 +1,37 @@
+export declare const APPLY_PATCH_MAX_FILE_SIZE: number;
+export declare const SFTP_SMALL_BYTES = 1048576;
+export declare const SFTP_SMALL_TIMEOUT_MS = 30000;
+export declare const SFTP_LARGE_TIMEOUT_MS = 60000;
+export type EntryKind = "missing" | "file" | "symlink" | "directory" | "other";
+export interface EntryMeta {
+    readonly kind: EntryKind;
+    readonly size: number;
+    readonly mode?: number;
+}
+export type PublishPhase = "write" | "replace" | "remove";
+export declare class FsTransportError extends Error {
+    readonly phase: PublishPhase;
+    readonly timedOut: boolean;
+    constructor(phase: PublishPhase, timedOut: boolean, message: string);
+}
+export interface PatchFs {
+    readonly scope: string;
+    lstat(path: string, signal?: AbortSignal): Promise<EntryMeta>;
+    statFollow(path: string, signal?: AbortSignal): Promise<EntryMeta>;
+    followLeaf(path: string, signal?: AbortSignal): Promise<string>;
+    readFollow(path: string, signal?: AbortSignal, timeoutMs?: number): Promise<Uint8Array>;
+    mkdirp(path: string, signal?: AbortSignal): Promise<void>;
+    writeAtomic(path: string, data: Uint8Array, mode: number | undefined, signal?: AbortSignal): Promise<void>;
+    renameNew(from: string, to: string, signal?: AbortSignal): Promise<void>;
+    replace(from: string, to: string, signal?: AbortSignal): Promise<void>;
+    unlink(path: string, signal?: AbortSignal): Promise<void>;
+    list(path: string, signal?: AbortSignal): Promise<readonly string[]>;
+}
+export declare function sftpTimeoutMs(bytes: number): number;
+export declare function agentPatchTempName(base: string): string;
+export declare function isAgentPatchTemp(name: string): boolean;
+export declare function fileTooLarge(size: number, path: string): Error;
+/** Installs fully prepared bytes through one sibling temporary file. */
+export declare function publishPreparedFile(fs: PatchFs, path: string, data: Uint8Array, mode: number | undefined, replaceExisting: boolean, signal?: AbortSignal, beforePublish?: () => Promise<void>): Promise<void>;
+export declare function createLocalPatchFs(workspaceRoot: string): PatchFs;
+export declare function gcAgentPatchTemps(fs: PatchFs, directories: readonly string[], signal?: AbortSignal): Promise<void>;