@aefree/pi-plastic 0.7.5 → 0.8.0

package/src/operations/object-write-receipt.ts

@@ -0,0 +1,105 @@
+import { captureWorkspaceMergeCommand, emptyWorkspaceMergeAttempt } from "../execution/workspace-merge-command";
+
+export const OBJECT_WRITE_ACTIONS = ["shelveset-create", "shelveset-apply", "code-review-create", "code-review-update"] as const;
+export type ObjectWriteAction = typeof OBJECT_WRITE_ACTIONS[number];
+type Common = { workdir: string; preflight: boolean; output: "text"|"json" };
+export type ObjectWriteRequests = {
+    "shelveset-create": Common & { paths: string[]|null; comment: string|null; commentsFile: string|null; all: boolean; dependencies: boolean; summaryFormat: boolean };
+    "shelveset-apply": Common & { shelveset: string; changePaths: string[]|null; preview: boolean; dontCheckout: boolean; comparisonMethod: string|null };
+    "code-review-create": Common & { target: string; title: string; status: string|null; assignee: string|null; repository: string|null; format: string|null };
+    "code-review-update": Common & { id: string; status: string|null; assignee: string|null; repository: string|null };
+};
+export type ObjectWriteRequest = ObjectWriteRequests[ObjectWriteAction];
+export type EmittedObjectIdentity = { kind: "shelveset"|"code-review"; value: string; basis: "default-scalar"|"summary-scalar" };
+export type ObjectWriteData = {
+    requested: ObjectWriteRequest|null; intendedArgv: string[];
+    attempt: ReturnType<typeof emptyWorkspaceMergeAttempt>;
+    capture: Awaited<ReturnType<typeof captureWorkspaceMergeCommand>>["capture"]|null;
+    commandOutput: { kind: "opaque-command-output"; text: string }|null;
+    observedCreatedIdentity: EmittedObjectIdentity|null;
+    observedAppliedItems: null; observedUpdatedState: null; observedRepositoryIdentity: null;
+    scope: "requested-only"; rollback: "not-proven";
+    effect: "not-attempted"|"not-proven"|"identity-emitted"|"uncertain";
+};
+export type ObjectWriteReceipt<A extends ObjectWriteAction=ObjectWriteAction> = {
+    schemaVersion:1; action:A; provenance:{source:"plastic";producer:"@aefree/pi-plastic";contentTrust:"external"};
+    completeness:{capture:"complete"|"incomplete"|"unknown";projection:true};
+    data: ObjectWriteData & {requested:ObjectWriteRequests[A]|null};
+} & ({ok:true;outcome:"preflight"|"command-completed"}|{ok:false;outcome:"failed"|"uncertain";error:{code:"invalid_request"|"editor_configured"|"launch_failed"|"aborted"|"uncertain"|"producer_failed";message:string}});
+const keys = {
+    "shelveset-create": ["paths","comment","commentsFile","all","dependencies","summaryFormat"],
+    "shelveset-apply": ["shelveset","changePaths","preview","dontCheckout","comparisonMethod"],
+    "code-review-create": ["target","title","status","assignee","repository","format"],
+    "code-review-update": ["id","status","assignee","repository"],
+} as const;
+const comparisons=["ignoreeol","ignorewhitespaces","ignoreeolandwhitespaces","recognizeall"];
+export function validWriteText(v:unknown, multiline=false, empty=false):v is string {
+    return typeof v==="string"&&v.length<=4096&&(empty||v.trim().length>0)&&!(multiline?/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/:/[\u0000-\u001f\u007f-\u009f]/).test(v)&&!/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u.test(v);
+}
+export function validWriteOperand(v:unknown):v is string {return validWriteText(v)&&!v.trimStart().startsWith("-");}
+export function validWritePaths(v:unknown):v is string[] {return Array.isArray(v)&&v.length<=256&&Array.from(v).every(validWriteOperand)&&Buffer.byteLength(JSON.stringify(v),"utf8")<=32768;}
+export function validObjectWriteRequest(a:ObjectWriteAction,r:ObjectWriteRequest):boolean {
+    if(!validWriteText(r.workdir)||typeof r.preflight!=="boolean"||!["text","json"].includes(r.output)||Buffer.byteLength(JSON.stringify(r),"utf8")>32768)return false;
+    const v=r as unknown as Record<string,unknown>;
+    if(a==="shelveset-create")return (v.paths===null||validWritePaths(v.paths))&&(v.comment===null||validWriteText(v.comment,true))&&(v.commentsFile===null||validWriteText(v.commentsFile))&&!(v.comment!==null&&v.commentsFile!==null)&&[v.all,v.dependencies,v.summaryFormat].every(x=>typeof x==="boolean");
+    if(a==="shelveset-apply")return validWriteOperand(v.shelveset)&&(v.changePaths===null||validWritePaths(v.changePaths))&&[v.preview,v.dontCheckout].every(x=>typeof x==="boolean")&&(v.comparisonMethod===null||comparisons.includes(v.comparisonMethod as string));
+    if(![v.status,v.assignee,v.repository].every(x=>x===null||validWriteText(x,false,true)))return false;
+    return a==="code-review-create"?validWriteOperand(v.target)&&validWriteOperand(v.title)&&(v.format===null||validWriteText(v.format,true,true)):validWriteOperand(v.id);
+}
+export function objectWritePrefix(a:ObjectWriteAction) {return a==="shelveset-create"?["shelveset","create"]:a==="shelveset-apply"?["shelveset","apply"]:a==="code-review-create"?["codereview"]:["codereview","-e"];}
+export function objectWriteArgv(a:ObjectWriteAction,r:ObjectWriteRequest):string[] {
+    const v=r as any,argv=objectWritePrefix(a);
+    if(a==="shelveset-create") {
+        argv.push(...(v.paths??[]));if(v.all)argv.push("--all");if(v.dependencies)argv.push("--dependencies");if(v.summaryFormat)argv.push("--summaryformat");if(v.comment!==null)argv.push(`-c=${v.comment}`);if(v.commentsFile!==null)argv.push(`-commentsfile=${v.commentsFile}`);
+    } else if(a==="shelveset-apply") {
+        argv.push(v.shelveset,...(v.changePaths??[]));if(v.preview)argv.push("--preview");if(v.dontCheckout)argv.push("--dontcheckout");if(v.comparisonMethod!==null)argv.push(`--comparisonmethod=${v.comparisonMethod}`);
+    } else {
+        argv.push(...(a==="code-review-create"?[v.target,v.title]:[v.id]));if(v.status)argv.push(`--status=${v.status}`);if(v.assignee)argv.push(`--assignee=${v.assignee}`);if(v.repository)argv.push(`--repository=${v.repository}`);if(a==="code-review-create"&&v.format)argv.push(`--format=${v.format}`);
+    }
+    return argv;
+}
+export function parseObjectWriteIdentity(a:ObjectWriteAction,r:ObjectWriteRequest,stdout:string):EmittedObjectIdentity|null {
+    const line=stdout.replace(/\r?\n$/,""); // One emitted scalar, not a match buried in diagnostic text.
+    if(!validWriteText(line)||line!==line.trim())return null;
+    if(a==="shelveset-create"&&/^sh:[1-9][0-9]*@[^@\r\n]+@[^@\r\n]+(?:@(cloud|unity))?$/.test(line))return {kind:"shelveset",value:line,basis:(r as ObjectWriteRequests["shelveset-create"]).summaryFormat?"summary-scalar":"default-scalar"};
+    if(a==="code-review-create"&&!(r as ObjectWriteRequests["code-review-create"]).format&&/^(?:[1-9][0-9]*|[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12})$/i.test(line))return {kind:"code-review",value:line,basis:"default-scalar"};
+    return null; // Custom creation formatting and apply/update progress are opaque, never identity/state.
+}
+export function emptyObjectWriteData(a:ObjectWriteAction):ObjectWriteData {return {requested:null,intendedArgv:objectWritePrefix(a),attempt:emptyWorkspaceMergeAttempt(),capture:null,commandOutput:null,observedCreatedIdentity:null,observedAppliedItems:null,observedUpdatedState:null,observedRepositoryIdentity:null,scope:"requested-only",rollback:"not-proven",effect:"not-attempted"};}
+function header(a:ObjectWriteAction,d:ObjectWriteData) {return {schemaVersion:1 as const,action:a,provenance:{source:"plastic" as const,producer:"@aefree/pi-plastic" as const,contentTrust:"external" as const},completeness:{capture:d.capture?d.capture.complete?"complete" as const:"incomplete" as const:"unknown" as const,projection:true as const},data:d};}
+export function objectWriteFailure(a:ObjectWriteAction,d:ObjectWriteData,code:Extract<ObjectWriteReceipt,{ok:false}>["error"]["code"],message:string):ObjectWriteReceipt {return {...header(a,d),ok:false,outcome:["started","unknown"].includes(d.attempt.state)?"uncertain":"failed",error:{code,message}} as ObjectWriteReceipt;}
+export async function assembleObjectWriteReceipt(a:ObjectWriteAction,args:unknown):Promise<ObjectWriteReceipt> {
+    const d=emptyObjectWriteData(a);let entered=false;
+    try {
+        if(!args||typeof args!=="object"||Array.isArray(args)||Object.keys(args).some(k=>![...keys[a],"workdir","preflight","output"].includes(k)))return objectWriteFailure(a,d,"invalid_request","Use only declared bounded object-write controls.");
+        const i={...args} as Record<string,unknown>,r:any={workdir:i.workdir===undefined?process.cwd():i.workdir,preflight:i.preflight===undefined?false:i.preflight,output:i.output===undefined?"text":i.output};
+        for(const k of keys[a]) {
+            if(Object.hasOwn(i,k)&&i[k]===null)return objectWriteFailure(a,d,"invalid_request","Explicit null controls are unsupported; omit optional controls.");
+            const v=i[k];r[k]=v===undefined?(["all","dependencies","summaryFormat","preview","dontCheckout"].includes(k)?false:null):["paths","changePaths"].includes(k)&&Array.isArray(v)&&v.length<=256?Array.from(v):v;
+        }
+        if(!validObjectWriteRequest(a,r))return objectWriteFailure(a,d,"invalid_request","Use exact non-option operands, bounded lists/text, exclusive comments, strict booleans and declared output/comparison modes.");
+        d.requested=r;d.intendedArgv=objectWriteArgv(a,r);
+        if(r.preflight)return {...header(a,d),ok:true,outcome:"preflight"} as ObjectWriteReceipt;
+        if(a==="shelveset-create"&&r.comment===null&&r.commentsFile===null&&process.env.PLASTICEDITOR?.trim())return objectWriteFailure(a,d,"editor_configured","Comment-less creation with PLASTICEDITOR configured could launch an editor. Supply comment/commentsFile; no environment override or dispatch.");
+        entered=true;const o=await captureWorkspaceMergeCommand([...d.intendedArgv],r.workdir);d.attempt=o.attempt;d.capture=o.capture;
+        const completed=o.capture.complete&&!o.failed&&o.attempt.state==="started"&&o.attempt.exitCode===0;
+        if(completed) {
+            d.commandOutput={kind:"opaque-command-output",text:o.stdout!};d.observedCreatedIdentity=parseObjectWriteIdentity(a,r,o.stdout!);
+            d.effect=d.observedCreatedIdentity?"identity-emitted":"not-proven";
+            if(o.capture.stderrBytes===0)return {...header(a,d),ok:true,outcome:"command-completed"} as ObjectWriteReceipt;
+            if(!d.observedCreatedIdentity)d.effect="uncertain";
+        } else d.effect=["started","unknown"].includes(d.attempt.state)?"uncertain":"not-attempted";
+        return objectWriteFailure(a,d,o.attempt.aborted?"aborted":["started","unknown"].includes(d.attempt.state)?"uncertain":"launch_failed","Object-write completion/state is not admitted. Earlier emitted identities remain recorded; no automatic retry, conflict choice or rollback.");
+    } catch {
+        if(entered&&d.capture===null){d.attempt={...emptyWorkspaceMergeAttempt(),state:"unknown"};d.effect="uncertain";}
+        return objectWriteFailure(a,d,"producer_failed","Object-write observation failed. Earlier possible/emitted effects remain; no automatic recovery or retry.");
+    }
+}
+export function presentObjectWriteReceipt(d:ObjectWriteReceipt):string {
+    if(d.data.requested?.output==="json")return JSON.stringify(d);
+    const identity=d.data.observedCreatedIdentity?` Emitted ${d.data.observedCreatedIdentity.kind}: ${d.data.observedCreatedIdentity.value}.`:"";
+    if(!d.ok)return `${d.action} ${d.outcome}: ${d.error.message} Effect: ${d.data.effect}.${identity}`;
+    if(d.outcome==="preflight")return `${d.action} command-only preview (not executed): ${JSON.stringify(d.data.intendedArgv)}. No existence/conflict/state analysis.`;
+    const opaque=d.data.commandOutput?.text?`\n${d.data.commandOutput.text}`:"";
+    return `${d.action} command completed.${identity} Applied items, requested review state, repository scope and rollback remain unverified.${opaque}`;
+}

package/src/operations/patch-receipt.ts

@@ -0,0 +1,96 @@
+import { promises as fs } from "node:fs";
+import { createHash } from "node:crypto";
+import { isUtf8 } from "node:buffer";
+import { isAbsolute, join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { captureWorkspaceMergeCommand, emptyWorkspaceMergeAttempt } from "../execution/workspace-merge-command";
+import { boundDiffOutput } from "../diff/text";
+import { buildPatchCommandArgs, resolvePatchToolPath, resolvePatchBranchSpecs, ensurePatchOutputDoesNotExist, readBoundedPatchFile } from "./patch-support";
+
+export const PATCH_FILE_MAX_BYTES = 4194304;
+export const PATCH_RECEIPT_MAX_BYTES = 524288;
+export type PatchRequest = { source: string; destination: string|null; output: string|null; toolPath: string|null; clean: boolean; integration: boolean; workdir: string; preflight: boolean; format: "text"|"json" };
+export type PatchArtifact = { bytes: number; sha256: string; utf8: boolean; empty: boolean; binaryLimited: boolean; totalChars: number|null; truncated: boolean; content: string|null };
+export type PatchData = {
+    requested: PatchRequest|null;
+    resolved: {source: string; destination: string|null; toolPath: string; output: string|null}|null;
+    intendedArgv: string[];
+    attempt: ReturnType<typeof emptyWorkspaceMergeAttempt>;
+    capture: Awaited<ReturnType<typeof captureWorkspaceMergeCommand>>["capture"]|null;
+    artifact: PatchArtifact|null;
+    publication: "not-requested"|"not-published"|"published"|"unknown";
+    cleanup: "not-created"|"completed"|"failed"|"retained"|"unknown";
+    retainedStagingDirectory: string|null;
+    effect: "not-attempted"|"unverified"|"artifact-observed"|"published";
+    workspaceEffects: "unverified"; moveRepresentation: "backend-determined";
+};
+export type PatchReceipt = {schemaVersion:1; action:"patch"; provenance:{source:"plastic";producer:"@aefree/pi-plastic";contentTrust:"external"}; completeness:{capture:"complete"|"incomplete"|"unknown";projection:true};data:PatchData}&
+    ({ok:true;outcome:"preflight"|"generated"|"empty"}|{ok:false;outcome:"failed"|"uncertain";error:{code:"invalid_request"|"setup_failed"|"command_failed"|"uncertain"|"backend_incompatible"|"artifact_failed"|"publication_failed"|"cleanup_failed"|"producer_failed";message:string}});
+export function validPatchText(v: unknown): v is string { return typeof v==="string" && v.length<=4096 && v.trim().length>0 && !/[\u0000-\u001f\u007f-\u009f]/.test(v); }
+export function validPatchRequest(r: PatchRequest) { return validPatchText(r.source)&&!r.source.trimStart().startsWith("-")&&
+    (r.destination===null||validPatchText(r.destination)&&!r.destination.trimStart().startsWith("-"))&&
+    [r.output,r.toolPath].every(v=>v===null||validPatchText(v))&&validPatchText(r.workdir)&&typeof r.clean==="boolean"&&typeof r.integration==="boolean"&&typeof r.preflight==="boolean"&&["text","json"].includes(r.format)&&Buffer.byteLength(JSON.stringify(r),"utf8")<=32768; }
+export function patchReceiptArgv(r: PatchRequest, v: NonNullable<PatchData["resolved"]>) {
+    return buildPatchCommandArgs({source:v.source,...(v.destination===null?{}:{destination:v.destination}),output:"<package-owned-staging-file>",toolPath:v.toolPath,clean:r.clean,integration:r.integration});
+}
+export function emptyPatchData(): PatchData { return {requested:null,resolved:null,intendedArgv:["patch"],attempt:emptyWorkspaceMergeAttempt(),capture:null,artifact:null,publication:"not-requested",cleanup:"not-created",retainedStagingDirectory:null,effect:"not-attempted",workspaceEffects:"unverified",moveRepresentation:"backend-determined"}; }
+function header(d: PatchData) {return {schemaVersion:1 as const,action:"patch" as const,provenance:{source:"plastic" as const,producer:"@aefree/pi-plastic" as const,contentTrust:"external" as const},completeness:{capture:d.capture?d.capture.complete?"complete" as const:"incomplete" as const:"unknown" as const,projection:true as const},data:d};}
+export function patchFailure(d: PatchData, code: Extract<PatchReceipt,{ok:false}>["error"]["code"], message: string): PatchReceipt {
+    return {...header(d),ok:false,outcome:["started","unknown"].includes(d.attempt.state)&&!d.artifact?"uncertain":"failed",error:{code,message}};
+}
+export async function assemblePatchReceipt(args: unknown): Promise<PatchReceipt> {
+    const d=emptyPatchData();let stage: string|null=null;let entered=false;let failure: {code:Extract<PatchReceipt,{ok:false}>["error"]["code"];message:string}|null=null;
+    try {
+        if (!args||typeof args!=="object"||Array.isArray(args)||Object.keys(args).some(k=>!["source","destination","output","toolPath","clean","integration","workdir","preflight","format"].includes(k)))
+            return patchFailure(d,"invalid_request","Use declared bounded patch controls only.");
+        const i={...args} as Record<string,unknown>;
+        const r={source:i.source,destination:i.destination===undefined?null:i.destination,output:i.output===undefined?null:i.output,toolPath:i.toolPath===undefined?null:i.toolPath,clean:i.clean===undefined?false:i.clean,integration:i.integration===undefined?false:i.integration,workdir:i.workdir===undefined?process.cwd():i.workdir,preflight:i.preflight===undefined?false:i.preflight,format:i.format===undefined?"json":i.format} as PatchRequest;
+        if (!validPatchRequest(r)||["destination","output","toolPath"].some(k=>Object.hasOwn(i,k)&&i[k]===null)) return patchFailure(d,"invalid_request","Use non-option source/destination, nonblank paths, strict booleans and text/json.");
+        d.requested=r;d.publication=r.output===null?"not-requested":"not-published";
+        const toolPath=resolvePatchToolPath(r.toolPath??undefined);
+        if (!validPatchText(toolPath)) throw new Error("Invalid patch backend.");
+        const branch=await resolvePatchBranchSpecs({source:r.source,...(r.destination===null?{}:{destination:r.destination})},r.workdir);
+        const v={source:branch.source,destination:branch.destination??null,toolPath,output:r.output===null?null:isAbsolute(r.output)?r.output:resolve(r.workdir,r.output)};
+        if ([v.source,v.destination,v.toolPath,v.output].some(s=>s!==null&&(s.length>8192||/[\u0000-\u001f\u007f-\u009f]/.test(s)))) throw new Error("Resolved patch controls exceed limits.");
+        d.resolved=v;d.intendedArgv=patchReceiptArgv(r,v);
+        if (r.preflight) return {...header(d),ok:true,outcome:"preflight"};
+        if (v.output!==null) await ensurePatchOutputDoesNotExist(v.output);
+        stage=await fs.mkdtemp(join(v.output===null?tmpdir():resolve(v.output,".."),".pi-plastic-patch-"));
+        const staged=join(stage,"patch-output");
+        entered=true;
+        const o=await captureWorkspaceMergeCommand(buildPatchCommandArgs({...v,destination:v.destination??undefined,output:staged,clean:r.clean,integration:r.integration}),r.workdir);
+        d.attempt=o.attempt;d.capture=o.capture;d.effect=["started","unknown"].includes(o.attempt.state)?"unverified":"not-attempted";
+        if (!o.capture.complete||o.failed||o.attempt.state!=="started"||o.attempt.exitCode!==0||o.capture.stderrBytes>0) {
+            const incompatible=/unrecognized option [`']?--binary/i.test(o.stderr??"");
+            failure={code:incompatible?"backend_incompatible":["started","unknown"].includes(o.attempt.state)?"uncertain":"command_failed",message:incompatible?"Patch backend rejected --binary. Configure a verified GNU-compatible patch backend; no automatic substitution.":"Patch command completion is not admitted. Inspect possible effects; no automatic retry."};
+        } else {
+            try {
+                const bytes=await readBoundedPatchFile(staged,PATCH_FILE_MAX_BYTES),utf8=isUtf8(bytes),body=utf8?bytes.toString("utf8"):null,bounded=body===null?null:boundDiffOutput(body);
+                d.artifact={bytes:bytes.length,sha256:createHash("sha256").update(bytes).digest("hex"),utf8,empty:bytes.length===0,binaryLimited:!utf8||/Binary files? .* differ|cannot diff|binary (?:content|file) (?:is )?not supported/i.test((body??"")+"\n"+(o.stdout??"")),totalChars:body===null?null:body.length,truncated:!!bounded?.truncated&&r.output===null,content:r.output===null&&utf8?bounded!.output:null};
+                d.effect="artifact-observed";
+            } catch { failure={code:"artifact_failed",message:"Completed command did not yield an admitted stable regular patch file within 4MiB. No publication or retry."}; }
+            if (!failure&&v.output!==null) {
+                if (d.artifact!.empty) failure={code:"publication_failed",message:"Refusing to publish an empty patch; requested output was not published."};
+                else try { await fs.link(staged,v.output);d.publication="published";d.effect="published"; }
+                catch { failure={code:"publication_failed",message:"Atomic no-overwrite publication failed. Observed generated bytes remain recorded; no replacement or retry."}; }
+            }
+        }
+    } catch {
+        if (entered&&d.capture===null) {d.attempt={...emptyWorkspaceMergeAttempt(),state:"unknown"};d.effect="unverified";}
+        failure={code:entered?"producer_failed":"setup_failed",message:entered?"Patch observation failed; earlier observed effects remain recorded, no automatic retry.":"Patch setup unavailable. Verify exact selector repository, backend and new output parent; no command was dispatched."};
+    } finally {
+        if (stage!==null) {
+            if (entered&&(d.attempt.state==="unknown"||d.attempt.state==="started")&&(d.attempt.terminal!=="observed"||d.attempt.aborted||d.attempt.timedOut)) {d.cleanup="retained";d.retainedStagingDirectory=stage;}
+            else try {await fs.rm(stage,{recursive:true,force:true});d.cleanup="completed";}
+            catch {d.cleanup="failed";d.retainedStagingDirectory=stage;failure??={code:"cleanup_failed",message:"Owned staging cleanup failed. Earlier generated/published artifact evidence remains; no rollback or retry."};}
+        }
+    }
+    if (failure) return patchFailure(d,failure.code,failure.message);
+    return {...header(d),ok:true,outcome:d.artifact!.empty?"empty":"generated"};
+}
+export function presentPatchReceipt(d: PatchReceipt) {
+    if (d.data.requested?.format!=="text") return JSON.stringify(d);
+    if (!d.ok) return `Patch ${d.outcome}: ${d.error.message} Effect: ${d.data.effect}; cleanup: ${d.data.cleanup}.`;
+    if (d.outcome==="preflight") return `Patch command-only preview: ${JSON.stringify(d.data.intendedArgv)}. No generation/backend/readiness analysis.`;
+    return `Patch ${d.outcome}: ${d.data.artifact!.bytes} observed bytes; publication: ${d.data.publication}; cleanup: ${d.data.cleanup}. Workspace effects/move encoding remain unverified.`;
+}

package/src/operations/patch-support.ts

@@ -0,0 +1,375 @@
+import { spawnAndCollect, ExecutableEnvironment, resolveExecutable } from "../execution/process";
+import { discoverPlasticWorkspace, parsePlasticSelector } from "../plastic-workspace";
+import { promises as fs, realpathSync } from "node:fs";
+import { join, dirname, basename, isAbsolute, resolve } from "path";
+import { tmpdir } from "os";
+import { isUtf8 } from "node:buffer";
+import { constants } from "node:fs";
+import { boundDiffOutput } from "../diff/text";
+
+export const PLASTIC_PATCH_EXECUTABLE_ENV = "PI_PLASTIC_PATCH_EXECUTABLE";
+
+export type PatchExecutableProbe = (command: string) => Promise<boolean>;
+// Plastic's server/backend determines whether a moved item is encoded as a
+// move or as delete/add records. Do not claim either without a live fixture.
+
+export const PATCH_MOVE_REPRESENTATION = "backend-determined" as const;
+
+export type PatchCommandArgs = {
+    source: string;
+    destination?: string;
+    output?: string;
+    toolPath?: string;
+    clean?: boolean;
+    integration?: boolean;
+};
+
+export const assertRequiredPatchValue = (name: keyof PatchCommandArgs, value: string | undefined): void =>
+{
+    if (value === undefined || value.trim().length === 0)
+    {
+        throw new Error(`${name} must be non-empty.`);
+    }
+};
+
+export const assertNonBlankPatchValue = (name: keyof PatchCommandArgs, value: string | undefined): void =>
+{
+    if (value !== undefined && value.trim().length === 0)
+    {
+        throw new Error(`${name} must be non-empty when provided.`);
+    }
+};
+
+export const probePatchExecutable = async (command: string): Promise<boolean> =>
+{
+    try
+    {
+        // This establishes only that the configured executable can launch.
+        // `cm patch` remains the authoritative verifier for its --binary contract.
+        const result = await spawnAndCollect(command, ["--version"], process.cwd(), undefined, AbortSignal.timeout(3000), {
+            abortKillDelayMs: 100,
+            outputLimitChars: 1024,
+        });
+        return !result.aborted;
+    }
+    catch
+    {
+        return false;
+    }
+};
+
+export const getPatchBackendCapabilityWarning = async (
+    environment: ExecutableEnvironment = process.env,
+    platform: NodeJS.Platform = process.platform,
+    probe: PatchExecutableProbe = probePatchExecutable,
+): Promise<string | undefined> =>
+{
+    const configuredPatchExecutable = environment[PLASTIC_PATCH_EXECUTABLE_ENV]?.trim();
+    if (configuredPatchExecutable)
+    {
+        if (await probe(configuredPatchExecutable))
+        {
+            return undefined;
+        }
+
+        return "Pi Plastic capability warning: the configured PI_PLASTIC_PATCH_EXECUTABLE could not be launched. Set it to a verified patch-capable non-GUI diff executable, or remove the override to use this platform's documented fallback. The configured path is not shown for privacy.";
+    }
+
+    if (platform === "win32")
+    {
+        return "Pi Plastic capability warning: plastic_patch requires PI_PLASTIC_PATCH_EXECUTABLE on Windows. Set it to a verified patch-capable non-GUI diff executable (for example Git's diff.exe). PI_PLASTIC_DIFF_EXECUTABLE is only for text diffs.";
+    }
+
+    return undefined;
+};
+
+export const resolvePatchToolPath = (
+    toolPath?: string,
+    environment: ExecutableEnvironment = process.env,
+    platform: NodeJS.Platform = process.platform,
+): string =>
+{
+    // A per-call path is deliberately the strongest override: callers may
+    // select a known patch-capable executable without changing process policy.
+    if (toolPath?.trim())
+    {
+        return toolPath.trim();
+    }
+
+    const configuredPatchExecutable = environment[PLASTIC_PATCH_EXECUTABLE_ENV]?.trim();
+    if (configuredPatchExecutable)
+    {
+        return configuredPatchExecutable;
+    }
+
+    if (platform === "win32")
+    {
+        // GnuWin32 diff 2.8.7 is known to reject cm patch directory operands.
+        // Do not inherit PI_PLASTIC_DIFF_EXECUTABLE here: that setting remains
+        // for text diffs and may name the incompatible executable.
+        throw new Error(
+            "cm patch requires a patch-capable non-GUI diff executable on Windows. Set PI_PLASTIC_PATCH_EXECUTABLE to a verified tool (for example Git's diff.exe), or pass toolPath for this one call. PI_PLASTIC_DIFF_EXECUTABLE is used only for text diffs and is not a safe Windows patch default.",
+        );
+    }
+
+    // Retain the pre-existing non-Windows fallback while keeping the patch-specific
+    // environment variable authoritative. The caller must verify that the resolved
+    // executable supports the local Plastic client's patch argument contract.
+    return resolveExecutable(environment, "PI_PLASTIC_DIFF_EXECUTABLE", "diff");
+};
+
+export type ResolvedPatchBranchSpecs = Pick<PatchCommandArgs, "source" | "destination">;
+
+// Repository selectors are a single cm argv value, so spaces within a repository
+// name are not shell separators. Require non-empty @-separated components without
+// edge whitespace, while retaining Plastic's valid internal spaces and punctuation.
+
+export const isSafePatchRepositorySelector = (repository: string | undefined): repository is string =>
+{
+    if (!repository || repository !== repository.trim() || /[\u0000-\u001f\u007f-\u009f]/.test(repository))
+    {
+        return false;
+    }
+
+    return repository.split("@").every((component) => /^[^@\s](?:[^@]*[^@\s])?$/.test(component));
+};
+
+export const qualifyPatchBranchSpec = (branchSpec: string, repository?: string): string =>
+{
+    const normalizedBranchSpec = branchSpec.trim();
+    if (!/^br:\/.+/i.test(normalizedBranchSpec) || normalizedBranchSpec.includes("@"))
+    {
+        return normalizedBranchSpec;
+    }
+
+    if (!isSafePatchRepositorySelector(repository))
+    {
+        throw new Error(
+            `Cannot safely qualify unqualified branch selector '${normalizedBranchSpec}' against this workspace. Use the exact repository-qualified syntax 'br:/<branch>@<repository>@<server>'.`,
+        );
+    }
+
+    return `${normalizedBranchSpec}@${repository}`;
+};
+
+export const resolvePatchBranchSpecs = async (args: PatchCommandArgs, cwd: string): Promise<ResolvedPatchBranchSpecs> =>
+{
+    const branchSpecs = [args.source, args.destination].filter((value): value is string => Boolean(value && /^br:\/.+/i.test(value.trim())));
+    const needsQualification = branchSpecs.some((value) => !value.includes("@"));
+    if (!needsQualification)
+    {
+        return { source: args.source.trim(), ...(args.destination ? { destination: args.destination.trim() } : {}) };
+    }
+
+    const workspace = await discoverPlasticWorkspace(cwd);
+    if (workspace.kind !== "found")
+    {
+        throw new Error("Cannot safely qualify an unqualified branch selector because the current Plastic workspace repository is unavailable. Use exact repository-qualified syntax 'br:/<branch>@<repository>@<server>'.");
+    }
+
+    const selectorBytes = await readBoundedPatchFile(join(workspace.value.plasticDir, "plastic.selector"), 65536);
+    if (!isUtf8(selectorBytes)) throw new Error("Patch selector metadata must be valid UTF-8.");
+    const selectorText = selectorBytes.toString("utf8");
+    const selector = selectorText === undefined ? { kind: "not_found" as const } : parsePlasticSelector(selectorText);
+    const repository = selector.kind === "found" ? selector.value.repository : undefined;
+    return {
+        source: qualifyPatchBranchSpec(args.source, repository),
+        ...(args.destination ? { destination: qualifyPatchBranchSpec(args.destination, repository) } : {}),
+    };
+};
+
+export type PatchOutputStaging = {
+    requestedOutput: string;
+    stagingOutput: string;
+    cleanup: () => Promise<void>;
+};
+
+export const ensurePatchOutputDoesNotExist = async (requestedOutput: string): Promise<void> =>
+{
+    const existing = await fs.lstat(requestedOutput).catch((error: unknown) =>
+    {
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+        throw error;
+    });
+    if (existing)
+    {
+        throw new Error(`Refusing to overwrite existing patch output '${requestedOutput}'. Choose a new output path.`);
+    }
+};
+
+export const createPatchOutputStaging = async (requestedOutput: string): Promise<PatchOutputStaging> =>
+{
+    await ensurePatchOutputDoesNotExist(requestedOutput);
+    let stagingDirectory: string;
+    try
+    {
+        stagingDirectory = await fs.mkdtemp(join(dirname(requestedOutput), ".pi-plastic-patch-"));
+    }
+    catch (error)
+    {
+        throw new Error(`Cannot create package-owned patch staging beside '${requestedOutput}'. Ensure its parent directory exists and is writable. ${error instanceof Error ? error.message : String(error)}`);
+    }
+
+    return {
+        requestedOutput,
+        stagingOutput: join(stagingDirectory, "patch-output"),
+        cleanup: async () => fs.rm(stagingDirectory, { recursive: true, force: true }),
+    };
+};
+
+export const validatePatchStagingOutput = async (stagingOutput: string, requireContent = false): Promise<void> =>
+{
+    const patchStat = await fs.lstat(stagingOutput).catch(() => null);
+    if (!patchStat?.isFile())
+    {
+        throw new Error("Plastic reported patch generation success but did not create package-owned staging output.");
+    }
+    if (requireContent && patchStat.size === 0)
+    {
+        // An omitted output may intentionally report an empty patch. A caller
+        // who requested a file, however, must never receive a zero-byte file
+        // that is indistinguishable from a failed/truncated backend outcome.
+        throw new Error("Refusing to publish an empty patch output. Plastic produced no patch bytes; rerun without output to inspect the empty result or verify the patch backend.");
+    }
+};
+
+// Creating a hard link is atomic and fails if the requested path appeared
+// after our preflight. Unlike rename(), it can never replace an existing file.
+
+export const publishPatchOutput = async (stagingOutput: string, requestedOutput: string): Promise<void> =>
+{
+    await validatePatchStagingOutput(stagingOutput, true);
+    try
+    {
+        await fs.link(stagingOutput, requestedOutput);
+    }
+    catch (error)
+    {
+        const code = (error as NodeJS.ErrnoException).code;
+        if (code === "EEXIST")
+        {
+            throw new Error(`Refusing to overwrite existing patch output '${requestedOutput}'. Choose a new output path.`);
+        }
+        throw new Error(`Could not atomically publish patch output '${requestedOutput}'. ${error instanceof Error ? error.message : String(error)}`);
+    }
+};
+
+export const runPatchOutputTransaction = async (requestedOutput: string, generate: (stagingOutput: string) => Promise<void>): Promise<void> =>
+{
+    const staging = await createPatchOutputStaging(requestedOutput);
+    try
+    {
+        await generate(staging.stagingOutput);
+        await publishPatchOutput(staging.stagingOutput, staging.requestedOutput);
+    }
+    finally
+    {
+        await staging.cleanup();
+    }
+};
+
+export const redactPatchStagingOutput = (message: string, stagingOutput: string): string =>
+{
+    const stagingPaths = new Set([stagingOutput]);
+    try
+    {
+        // macOS commonly exposes /var through the canonical /private/var path.
+        // cm may report the latter even though it received the former.
+        stagingPaths.add(join(realpathSync.native(dirname(stagingOutput)), basename(stagingOutput)));
+    }
+    catch
+    {
+        // The staging parent normally exists; retain raw-path redaction if it does not.
+    }
+
+    return Array.from(stagingPaths)
+        .sort((left, right) => right.length - left.length)
+        .reduce((redacted, path) => redacted.split(path).join("<package-owned-staging-file>"), message);
+};
+
+export const withPatchBackendContractDiagnostic = (error: unknown, toolPath: string, stagingOutput: string): Error =>
+{
+    const message = redactPatchStagingOutput(error instanceof Error ? error.message : String(error), stagingOutput);
+    // Plastic 11 on macOS invokes its patch backend with --binary. Apple's BSD
+    // /usr/bin/diff rejects that flag, while GNU diffutils accepts it. Detect
+    // the observed contract failure instead of guessing from a path or OS.
+    if (/unrecognized option [`']?--binary/i.test(message))
+    {
+        return new Error(
+            `${message}\n\nPlastic patch requires a diff executable that accepts --binary. '${toolPath}' rejected that argument. Configure PI_PLASTIC_PATCH_EXECUTABLE (or this call's toolPath) to a verified GNU diffutils-compatible non-GUI diff executable. Text diff configuration is independent; Apple BSD diff may still be used for text-only diffs.`,
+        );
+    }
+    return new Error(message);
+};
+
+export const buildPatchCommandArgs = (args: PatchCommandArgs): string[] =>
+{
+    assertRequiredPatchValue("source", args.source);
+    assertNonBlankPatchValue("destination", args.destination);
+    assertNonBlankPatchValue("output", args.output);
+    assertNonBlankPatchValue("toolPath", args.toolPath);
+
+    const cmdArgs: string[] = ["patch", args.source];
+
+    if (args.destination)
+    {
+        cmdArgs.push(args.destination);
+    }
+
+    if (args.output)
+    {
+        cmdArgs.push(`--output=${args.output}`);
+    }
+
+    if (args.toolPath)
+    {
+        cmdArgs.push(`--tool=${args.toolPath}`);
+    }
+
+    if (args.clean)
+    {
+        cmdArgs.push("--clean");
+    }
+
+    if (args.integration)
+    {
+        cmdArgs.push("--integration");
+    }
+
+    return cmdArgs;
+};
+
+export const __plasticPatchInternals = {
+    buildPatchCommandArgs,
+    resolvePatchToolPath,
+    getPatchBackendCapabilityWarning,
+    qualifyPatchBranchSpec,
+    resolvePatchBranchSpecs,
+    createPatchOutputStaging,
+    publishPatchOutput,
+    runPatchOutputTransaction,
+    withPatchBackendContractDiagnostic,
+    PATCH_MOVE_REPRESENTATION,
+};
+
+
+/** One bounded file observation, not an atomic filesystem snapshot. */
+export async function readBoundedPatchFile(path: string, limit: number): Promise<Buffer> {
+    const before = await fs.lstat(path);
+    if (!before.isFile() || before.isSymbolicLink() || before.size > limit) throw new Error("Unsupported patch file or byte limit.");
+    const handle = await fs.open(path, constants.O_RDONLY | constants.O_NONBLOCK | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const opened = await handle.stat();
+        if (!opened.isFile() || opened.dev !== before.dev || opened.ino !== before.ino || opened.size > limit) throw new Error("Patch file changed or exceeds byte limit.");
+        const buffer = Buffer.alloc(limit + 1);
+        let length = 0;
+        while (length < buffer.length) {
+            const read = await handle.read(buffer, length, buffer.length - length, length);
+            if (read.bytesRead === 0) break;
+            length += read.bytesRead;
+        }
+        const after = await handle.stat();
+        if (length > limit || length !== opened.size || after.size !== opened.size || after.mtimeMs !== opened.mtimeMs || after.ctimeMs !== opened.ctimeMs) throw new Error("Patch file changed or exceeds byte limit.");
+        return buffer.subarray(0, length);
+    } finally { await handle.close(); }
+}

package/src/operations/patch.ts

@@ -0,0 +1,25 @@
+import { tool } from "../tool-definition";
+import { workdirArg } from "./arguments";
+import { assemblePatchReceipt, presentPatchReceipt } from "./patch-receipt";
+export { __plasticPatchInternals, getPatchBackendCapabilityWarning, PLASTIC_PATCH_EXECUTABLE_ENV } from "./patch-support";
+
+export const patch = tool({
+    description: "Generate a Plastic SCM review patch with a patch-specific non-GUI diff backend; branch selectors are qualified to the current workspace repository and requested outputs publish atomically without overwrite (cm patch).",
+    args: {
+        source: tool.schema.string().min(1).describe("Source changeset or branch spec. Unqualified br:/ selectors are qualified only from the exact current workspace repository."),
+        destination: tool.schema.string().optional().describe("Optional second changeset or branch spec for two-spec patch generation."),
+        output: tool.schema.string().optional().describe("Optional new output file path. The package stages then atomically publishes it and refuses any existing path. If omitted, patch content is returned."),
+        toolPath: tool.schema.string().optional().describe("Optional patch-capable non-GUI diff executable for this call (highest priority). Otherwise use PI_PLASTIC_PATCH_EXECUTABLE; non-Windows falls back to PI_PLASTIC_DIFF_EXECUTABLE/diff, which must support the local Plastic patch argument contract."),
+        clean: tool.schema.boolean().optional().describe("Exclude content that arrived via merges and include only direct checkins."),
+        integration: tool.schema.boolean().optional().describe("Show branch changes pending integration into the parent branch."),
+        preflight: tool.schema.boolean().optional().describe("Command-only preview; no staging, backend probe or generation."),
+        format: tool.schema.enum(["text", "json"]).optional().describe("Receipt presentation; defaults to JSON."),
+        workdir: workdirArg,
+    },
+    async execute(args) {
+        const dto = await assemblePatchReceipt(Object.freeze({ ...args }));
+        const text = presentPatchReceipt(dto);
+        if (!dto.ok) throw new Error(text);
+        return text;
+    },
+});