@aefree/pi-plastic 0.7.6 → 0.8.1

package/src/operations/code-review-find.ts

@@ -0,0 +1,97 @@
+import { cmWhereEquals, cmWhereLike } from "../domain/branches";
+import { toStructuredResult } from "../presentation/results";
+import { runCm, normalizeFindOutputLines } from "../execution/cm";
+import { spawnAndCollect, getCmExecutable } from "../execution/process";
+import { commandExecutionStorage, getActiveAbortSignal } from "../execution/context";
+import { runCodeReviewFindIdsCommand, CodeReviewFindCommandError, CODE_REVIEW_FIND_CAPTURE_LIMITS } from "../execution/code-review-find-command";
+
+export type CodeReviewFindArgs = { status?: string; assignee?: string; owner?: string; target?: string; targetType?: "branch" | "changeset"; titleLike?: string; orderBy?: "date" | "modifieddate" | "status"; descending?: boolean; limit?: number; format?: string; dateFormat?: string; source?: "native" | "ids"; output?: "text" | "json"; maxItems?: number; workdir?: string };
+export type CodeReviewFindQuery = { status: string | null; assignee: string | null; owner: string | null; target: string | null; targetType: "branch" | "changeset" | null; titleLike: string | null; orderBy: "date" | "modifieddate" | "status" | null; descending: boolean | null; limit: number | null };
+export class CodeReviewFindError extends Error {
+    constructor(readonly code: "invalid_identity" | "malformed_output" | "unsupported_query" | "invalid_producer_data" | "output_overflow") { super(`Code review find read failed (${code}); no reusable rows are available.`); }
+}
+export const CODE_REVIEW_FIND_MAX_BYTES = 131072;
+export const validCodeReviewQueryString = (s: string) => s.length <= 4096 && !/[\u0000-\u001f\u007f-\u009f\uD800-\uDFFF]/u.test(s);
+export const validCodeReviewTemplate = (s: string) => s.length <= 4096 && !/[\u0000\uD800-\uDFFF]/u.test(s);
+// Decimal strings retain exact integers beyond JavaScript's safe-number range.
+export const validCodeReviewId = (s: string) => s.length <= 20 && /^(?:0|[1-9][0-9]*)$/.test(s);
+export function codeReviewFindRequest(args: CodeReviewFindArgs) {
+    for (const value of [args.status, args.assignee, args.owner, args.target, args.titleLike])
+        if (value !== undefined && (typeof value !== "string" || !validCodeReviewQueryString(value))) throw new CodeReviewFindError("invalid_identity");
+    for (const value of [args.format, args.dateFormat])
+        if (value !== undefined && (typeof value !== "string" || !validCodeReviewTemplate(value))) throw new CodeReviewFindError("invalid_producer_data");
+    if ((args.source !== undefined && args.source !== "native" && args.source !== "ids")
+        || (args.targetType !== undefined && args.targetType !== "branch" && args.targetType !== "changeset")
+        || (args.orderBy !== undefined && !["date", "modifieddate", "status"].includes(args.orderBy))
+        || (args.descending !== undefined && typeof args.descending !== "boolean")
+        || (args.output !== undefined && args.output !== "text" && args.output !== "json")
+        || (args.limit !== undefined && (!Number.isSafeInteger(args.limit) || args.limit < 1))
+        || (args.maxItems !== undefined && (!Number.isSafeInteger(args.maxItems) || args.maxItems < 1 || args.maxItems > 500))) throw new CodeReviewFindError("invalid_producer_data");
+    const source = args.source ?? "native";
+    if (source === "ids" && (args.format || args.dateFormat)) throw new CodeReviewFindError("unsupported_query");
+    return { source, maxItems: args.maxItems ?? 100, query: { status: args.status ?? null, assignee: args.assignee ?? null, owner: args.owner ?? null, target: args.target ?? null, targetType: args.targetType ?? null, titleLike: args.titleLike ?? null, orderBy: args.orderBy ?? null, descending: args.descending ?? null, limit: args.limit ?? null } };
+}
+export function codeReviewFindCommand(args: CodeReviewFindArgs): string[] {
+    const { source, query } = codeReviewFindRequest(args);
+    const where: string[] = [];
+    for (const field of ["status", "assignee", "owner", "target", "targetType"] as const)
+        if (query[field]) where.push(cmWhereEquals(field === "targetType" ? "targettype" : field, query[field]));
+    if (query.titleLike) where.push(cmWhereLike("title", query.titleLike));
+    return ["find", "review", ...(where.length ? [`where ${where.join(" and ")}`] : []),
+        ...(query.orderBy ? [`order by ${query.orderBy}${query.descending ? " desc" : " asc"}`] : []),
+        ...(query.limit ? [`limit ${query.limit}`] : []),
+        ...(source === "native" && args.format ? [`--format=${args.format}`] : []),
+        ...(source === "native" && args.dateFormat ? [`--dateformat=${args.dateFormat}`] : []),
+        "--nototal", ...(source === "ids" ? ["--format={id}", "--encoding=utf-8"] : [])];
+}
+export function parseCodeReviewFindIds(bytes: Uint8Array): { ids: string[]; duplicateRecords: number } {
+    if (bytes.byteLength > CODE_REVIEW_FIND_CAPTURE_LIMITS.stdoutBytes) throw new CodeReviewFindCommandError("capture_incomplete");
+    if (bytes.some(byte => byte > 127)) throw new CodeReviewFindError("invalid_identity");
+    if (!bytes.length) return { ids: [], duplicateRecords: 0 };
+    const ids = Buffer.from(bytes).toString("ascii").split(/\r?\n/);
+    if (ids.at(-1) === "") ids.pop();
+    if (ids.length > CODE_REVIEW_FIND_CAPTURE_LIMITS.records) throw new CodeReviewFindCommandError("capture_incomplete");
+    if (ids.some(id => !validCodeReviewId(id))) throw new CodeReviewFindError("invalid_identity");
+    return { ids, duplicateRecords: ids.length - new Set(ids).size };
+}
+export type CodeReviewFindObservation = ReturnType<typeof codeReviewFindRequest> & ({ source: "native"; command: string[]; rawResult: string } | { source: "ids"; ids: string[]; duplicateRecords: number });
+export async function assembleCodeReviewFindObservation(args: CodeReviewFindArgs, typedNative = false): Promise<CodeReviewFindObservation> {
+    const request = codeReviewFindRequest(args), command = codeReviewFindCommand(args);
+    if (request.source === "ids") {
+        const bytes = await runCodeReviewFindIdsCommand(command, args.workdir);
+        if (getActiveAbortSignal()?.aborted) throw new CodeReviewFindCommandError("aborted");
+        const parsed = parseCodeReviewFindIds(bytes);
+        if (request.query.limit !== null && parsed.ids.length > request.query.limit) throw new CodeReviewFindError("invalid_producer_data");
+        if (getActiveAbortSignal()?.aborted) throw new CodeReviewFindCommandError("aborted");
+        return { ...request, source: "ids", ...parsed };
+    }
+    if (!typedNative) return { ...request, source: "native", command, rawResult: await runCm(command, args.workdir) };
+    const signal = getActiveAbortSignal();
+    if (signal?.aborted) throw new CodeReviewFindCommandError("aborted");
+    let result;
+    try { result = await spawnAndCollect(getCmExecutable(), command, args.workdir ?? process.cwd(), undefined, signal, commandExecutionStorage.getStore()); }
+    catch { throw new CodeReviewFindCommandError(signal?.aborted ? "aborted" : "command_failed"); }
+    if (result.aborted || signal?.aborted) throw new CodeReviewFindCommandError("aborted");
+    if (result.timedOut || result.stdoutTruncated || result.stderrTruncated) throw new CodeReviewFindCommandError("capture_incomplete");
+    if (result.exitCode !== 0) throw new CodeReviewFindCommandError("command_failed");
+    return { ...request, source: "native", command, rawResult: [result.stdout, result.stderr].filter(Boolean).join("\n").trim() || "(no output)" };
+}
+export function codeReviewFindPayload(observation: CodeReviewFindObservation) {
+    const common = { schemaVersion: 1, action: "code-review-find", provenance: { source: "plastic", producer: "@aefree/pi-plastic", contentTrust: "external" }, ok: true } as const;
+    const data = { scope: "workspace_repository", qualifierVerified: false, query: observation.query, limits: { maxItems: observation.maxItems, idDigits: 20, queryCodeUnits: 4096, compactUtf8Bytes: CODE_REVIEW_FIND_MAX_BYTES } } as const;
+    const payload = observation.source === "native"
+        ? { ...common, completeness: { read: "unknown", capture: "unknown", projection: false }, data: { ...data, mode: "native", basis: "find_review_native", rows: null, counts: null, countBasis: "unavailable" } }
+        : { ...common, completeness: { read: "complete", capture: "complete", projection: observation.ids.length <= observation.maxItems }, data: { ...data, mode: "ids", basis: "find_review_id_utf8", diagnostics: { duplicateRecords: observation.duplicateRecords }, rows: observation.ids.slice(0, observation.maxItems).map(id => ({ id })), countBasis: "observed_query_rows", counts: { observed: observation.ids.length, returned: Math.min(observation.ids.length, observation.maxItems), omitted: Math.max(0, observation.ids.length - observation.maxItems), excluded: 0 } } };
+    if (Buffer.byteLength(JSON.stringify(payload), "utf8") > CODE_REVIEW_FIND_MAX_BYTES) throw new CodeReviewFindError("output_overflow");
+    return payload;
+}
+export async function presentCodeReviewFindObservation(observation: CodeReviewFindObservation, args: CodeReviewFindArgs): Promise<string> {
+    if (observation.source === "native") return toStructuredResult("code-review-find", args.output ?? "text", observation.rawResult,
+        { command: ["cm", ...observation.command], rawOutput: observation.rawResult, resultCount: normalizeFindOutputLines(observation.rawResult).length }, args.workdir);
+    if (args.output === "json") return JSON.stringify(codeReviewFindPayload(observation));
+    const ids = observation.ids.slice(0, observation.maxItems), omitted = observation.ids.length - ids.length;
+    return [...(ids.length ? ids : ["(no observed query rows)"]), ...(omitted ? [`(${omitted} observed query rows omitted from presentation.)`] : [])].join("\n");
+}
+export async function executeCodeReviewFind(args: CodeReviewFindArgs): Promise<string> {
+    return presentCodeReviewFindObservation(await assembleCodeReviewFindObservation(args), args);
+}

package/src/operations/consolidated-diff.ts

@@ -0,0 +1,144 @@
+import { promises as fs } from "node:fs";
+import { createHash } from "node:crypto";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { createAsciiTempDirectory, isBinaryContent } from "../diff/text";
+import { snapshotLocalFile } from "../diff/local-snapshot";
+import { parseLoadedFileInfo, parseLoadedLs } from "../domain/diff-base-xml";
+import { parseDiffPending, type DiffPendingItem, type DiffPendingSnapshot } from "../domain/diff-pending-xml";
+import { resolveDiffFileRevision } from "../domain/revisions";
+import { getCmExecutable } from "../execution/process";
+import { getActiveAbortSignal } from "../execution/context";
+import { runDiffRevisionsCommand } from "../execution/diff-revisions-command";
+import { assembleDiffRevisionsObservation, compareDiffBytes, diffRevisionsPayload, materializeDiffRevision, validDiffRevisionsSelector, type DiffRevisionsObservation } from "./diff-revisions";
+
+export type DiffRequest = { workdir?:string;format?:"text"|"json";maxChars?:number } & (
+    {mode:"revisions";leftRevision:string;rightRevision:string} |
+    {mode:"file";path:string;revision?:string} |
+    {mode:"workspace";paths:string[];allPending?:never;includePrivate?:never;maxFiles?:number} |
+    {mode:"workspace";allPending:true;paths?:never;includePrivate?:boolean;maxFiles?:number}
+);
+export class ConsolidatedDiffError extends Error {
+    constructor(readonly code:string,readonly stage:string) { super("The requested diff could not be verified."); }
+}
+const fail=(code:string,stage:string):never=>{throw new ConsolidatedDiffError(code,stage);};
+const aborted=()=>{if(getActiveAbortSignal()?.aborted)fail("aborted","comparison");};
+const safe=(s:unknown,max:number):s is string=>typeof s==="string"&&s.length>0&&s.length<=max&&s.trim()===s&&!/[\u0000-\u001f\u007f-\u009f]|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/.test(s);
+export function validateDiffRequest(input:unknown):asserts input is DiffRequest {
+    if(!input||typeof input!=="object"||Array.isArray(input))fail("invalid_request","input");
+    const r=input as Record<string,unknown>,allowed=new Set(["mode","workdir","format","maxChars"]);
+    if(r.mode==="revisions") {allowed.add("leftRevision");allowed.add("rightRevision");if(!validDiffRevisionsSelector(r.leftRevision)||!validDiffRevisionsSelector(r.rightRevision))fail("invalid_selector","input");}
+    else if(r.mode==="file") {allowed.add("path");allowed.add("revision");if(!safe(r.path,1024)||r.revision!==undefined&&!safe(r.revision,4096))fail("invalid_request","input");}
+    else if(r.mode==="workspace") {
+        allowed.add("maxFiles");
+        if(r.paths!==undefined){allowed.add("paths");if(!Array.isArray(r.paths)||!r.paths.length||r.paths.length>20||r.paths.some(p=>!safe(p,1024)))fail("invalid_request","input");}
+        else {allowed.add("allPending");allowed.add("includePrivate");if(r.allPending!==true||r.includePrivate!==undefined&&typeof r.includePrivate!=="boolean")fail("invalid_request","input");}
+        if(r.maxFiles!==undefined&&(!Number.isInteger(r.maxFiles)||Number(r.maxFiles)<1||Number(r.maxFiles)>20))fail("invalid_request","input");
+    } else fail("invalid_request","input");
+    if(Object.keys(r).some(k=>!allowed.has(k))||r.format!==undefined&&r.format!=="text"&&r.format!=="json"||r.workdir!==undefined&&!safe(r.workdir,4096))fail("invalid_request","input");
+    if(r.maxChars!==undefined&&(!Number.isInteger(r.maxChars)||Number(r.maxChars)<500||Number(r.maxChars)>(r.mode==="workspace"?8000:20000)))fail("invalid_request","input");
+}
+const key=(p:string)=>{const normalized=resolve(p);return process.platform==="win32"?normalized.toLowerCase():normalized;};
+const contains=(root:string,p:string)=>{const r=relative(root,p);return r!==".."&&!r.startsWith(".."+sep)&&!isAbsolute(r);};
+async function inspectPath(path:string,code:string,stage:string) {
+    try { return await fs.lstat(path); }
+    catch (error) {
+        const errno=(error as NodeJS.ErrnoException)?.code;
+        if(errno==="ENOENT"||errno==="ENOTDIR")return null;
+        return fail(code,stage);
+    }
+}
+async function workspaceRoot(cwd:string):Promise<string>{
+    let p=await fs.realpath(cwd).catch(()=>fail("workspace_unavailable","selection"));
+    for(let i=0;i<128;i++){
+        const marker=await inspectPath(join(p,".plastic"),"workspace_unavailable","selection");
+        if(marker){
+            if(!marker.isDirectory()||marker.isSymbolicLink())return fail("workspace_unavailable","selection");
+            const config=await inspectPath(join(p,".plastic","plastic.workspace"),"workspace_unavailable","selection");
+            if(config){
+                if(!config.isFile()||config.isSymbolicLink())return fail("workspace_unavailable","selection");
+                return p;
+            }
+        }
+        const parent=dirname(p);if(parent===p)break;p=parent;
+    }
+    return fail("workspace_unavailable","selection");
+}
+async function xmlCommand(args:string[],cwd:string,stage:string):Promise<Buffer>{
+    aborted();try{return (await runDiffRevisionsCommand(getCmExecutable(),args,cwd,[0])).stdout;}catch{return fail(getActiveAbortSignal()?.aborted?"aborted":"command_failed",stage);}
+}
+export type LoadedIdentity={revisionId:string;changeset:string;repository:string;server:string};
+export type DiffSide={origin:"historical"|"local-snapshot"|"synthetic-empty";selector:string|null;path:string|null;identity:LoadedIdentity|null;bytes:number;binary:boolean};
+export type Comparison={atomicSnapshot:false;kind:string;pendingKind:string|null;left:DiffSide;right:DiffSide;status:"changed"|"unchanged"|"binary-different"|"added-empty";changed:boolean;binary:boolean;comparisonBasis:"byte_equality"|"diff_u";hunkCount:number;capture:{diffStdoutBytes:number|null;diffExitCode:number|null};excerpt:ReturnType<typeof diffRevisionsPayload>["data"]["excerpt"]};
+function comparison(observation:DiffRevisionsObservation,left:DiffSide,right:DiffSide,kind:string,pendingKind:string|null):Comparison {
+    const d=diffRevisionsPayload(observation).data;
+    return {atomicSnapshot:false,kind,pendingKind,left,right,status:!d.changed&&pendingKind==="added"?"added-empty":d.status,changed:d.changed,binary:d.binary,comparisonBasis:d.comparisonBasis,hunkCount:d.hunkCount,capture:d.capture,excerpt:d.excerpt};
+}
+const side=(origin:DiffSide["origin"],bytes:Buffer,path:string|null,selector:string|null,identity:LoadedIdentity|null=null):DiffSide=>({origin,path,selector,identity,bytes:bytes.length,binary:isBinaryContent(bytes)});
+async function pending(cwd:string):Promise<DiffPendingSnapshot>{try{return parseDiffPending(await xmlCommand(["status","--xml","--encoding=utf-8","--fullpaths","--iscochanged"],cwd,"status"));}catch(e){if(e instanceof ConsolidatedDiffError)throw e;return fail("malformed_output","status");}}
+async function base(path:string,cwd:string,snapshot:DiffPendingSnapshot,item:DiffPendingItem|null):Promise<{selector:string;identity:LoadedIdentity;hash:string;algorithm:"md5"|"sha1"}>{
+    try {
+        const info=parseLoadedFileInfo(await xmlCommand(["fileinfo",path,"--fields=ClientPath,ServerPath,RevisionChangeset,Hash,RepSpec,Status,Type","--xml","--encoding=utf-8"],cwd,"base"));
+        if(key(info.clientPath)!==key(path)||!["txt","bin","file"].includes(info.type.toLowerCase()))return fail("base_unavailable","base");
+        // DE removes live-tree membership/RepSpec. Deliberately inspect the
+        // frozen loaded root tree, never retry a failed live-tree lookup or
+        // guess a parent owning repository. Require loaded changeset/hash match.
+        const deleted=item?.code==="DE";
+        if(deleted&&info.status!=="deleted")return fail("base_changed","base");
+        const query=deleted?["ls",info.serverPath,"--tree=cs:"+snapshot.changeset+"@"+snapshot.repository+"@"+snapshot.server,"--xml","--encoding=utf-8"]:["ls",path,"--xml","--encoding=utf-8"];
+        const row=parseLoadedLs(await xmlCommand(query,cwd,"base"));
+        if((deleted?row.path!==info.serverPath:key(row.path)!==key(path))||row.changeset!==info.changeset||row.hash!==info.hash||!deleted&&info.repSpec!==row.repository+"@"+row.server)return fail("base_changed","base");
+        const selector="revid:"+row.revisionId+"@rep:"+row.repository+"@repserver:"+row.server;
+        if(!validDiffRevisionsSelector(selector))return fail("invalid_selector","base");
+        return {selector,identity:{revisionId:row.revisionId,changeset:row.changeset,repository:row.repository,server:row.server},hash:row.hash,algorithm:row.algorithm};
+    }catch(e){if(e instanceof ConsolidatedDiffError)throw e;return fail("base_unavailable","base");}
+}
+async function fileComparison(args:DiffRequest&{mode:"file"},cwd:string,root:string,snapshot:DiffPendingSnapshot|null,item:DiffPendingItem|null):Promise<Comparison>{
+    const path=resolve(cwd,args.path);if(!contains(root,path))return fail("outside_workspace","selection");
+    let selector:string|null=null,identity:LoadedIdentity|null=null,expected:{hash:string;algorithm:"md5"|"sha1"}|null=null;
+    if(args.revision!==undefined){try{selector=resolveDiffFileRevision(args.path,args.revision).resolved;}catch{return fail("invalid_selector","input");}if(!validDiffRevisionsSelector(selector))return fail("invalid_selector","input");}
+    else if(item?.kind!=="added"&&item?.kind!=="private") {const lookup=item?.code==="LM"?item.sourcePath!:path;if(!contains(root,lookup))return fail("outside_workspace","selection");const b=await base(lookup,cwd,snapshot!,item);selector=b.selector;identity=b.identity;expected=b;}
+    const temp=await createAsciiTempDirectory("pi-plastic-file-diff-");
+    try {
+        const l=selector?await materializeDiffRevision(selector,join(temp,"base"),"left",cwd):Buffer.alloc(0);
+        if(expected&&createHash(expected.algorithm).update(l).digest("base64")!==expected.hash)return fail("base_changed","base");
+        const deleted=!args.revision&&item?.kind==="deleted";
+        if(deleted&&await inspectPath(path,"read_failed","right"))return fail("file_changed","right");
+        const r=deleted?Buffer.alloc(0):(await snapshotLocalFile(path,root,getActiveAbortSignal())).bytes;
+        const left=side(selector?"historical":"synthetic-empty",l,null,selector,identity),right=side(deleted?"synthetic-empty":"local-snapshot",r,path,null);
+        const raw=await compareDiffBytes(l,r,selector??args.path+" (empty before add)",args.path+(deleted?" (empty after delete)":" (local snapshot)"));
+        const obs:DiffRevisionsObservation={...raw,maxChars:args.maxChars??8000,left:{selector:selector??"synthetic empty",kind:"global-revision",resolvedIdentity:null,bytes:l.length,binary:left.binary},right:{selector:args.path,kind:"file-qualified",resolvedIdentity:null,bytes:r.length,binary:right.binary}};
+        return comparison(obs,left,right,args.revision!==undefined?"explicit-revision-to-local":"loaded-base-to-local",args.revision!==undefined?null:item?.kind??null);
+    } finally {await fs.rm(temp,{recursive:true,force:true}).catch(()=>fail("cleanup_failed","cleanup"));}
+}
+export type DiffOutcome={path:string;sourcePath:string|null;kind:string;status:"compared";comparison:Comparison}|{path:string;sourcePath:string|null;kind:string;status:"skipped-directory"}|{path:string;sourcePath:string|null;kind:string;status:"unavailable";error:{code:string;stage:string;message:string}};
+export function diffError(e:unknown){const r=e as {code?:unknown;stage?:unknown};const codes=new Set(["invalid_request","invalid_selector","workspace_unavailable","outside_workspace","base_unavailable","base_changed","malformed_output","command_failed","aborted","cleanup_failed","materialization_failed","materialization_limit","invalid_utf8","capture_incomplete","output_overflow","missing_file","unsupported_file","file_limit","file_changed","read_failed"]);return {code:typeof r?.code==="string"&&codes.has(r.code)?r.code:"comparison_failed",stage:typeof r?.stage==="string"&&["input","selection","status","base","left","right","comparison","cleanup","producer"].includes(r.stage)?r.stage:"comparison",message:"The requested diff could not be verified."};}
+export async function assembleConsolidatedDiff(input:unknown){
+    validateDiffRequest(input);const args=input;aborted();
+    const header={schemaVersion:1 as const,action:"diff" as const,mode:args.mode,provenance:{source:"plastic" as const,producer:"@aefree/pi-plastic" as const,contentTrust:"external" as const}};
+    if(args.mode==="revisions") {
+        const obs=await assembleDiffRevisionsObservation(args),d=diffRevisionsPayload(obs);
+        const left:DiffSide={origin:"historical",selector:args.leftRevision,path:null,identity:null,bytes:obs.left.bytes,binary:obs.left.binary};
+        const right:DiffSide={origin:"historical",selector:args.rightRevision,path:null,identity:null,bytes:obs.right.bytes,binary:obs.right.binary};
+        return {...header,mode:"revisions" as const,ok:true,completeness:d.completeness,data:comparison(obs,left,right,"revision-to-revision",null)};
+    }
+    const cwd=await fs.realpath(args.workdir??process.cwd()).catch(()=>fail("workspace_unavailable","selection")),root=await workspaceRoot(cwd);
+    if(args.mode==="file") {
+        const snapshot=args.revision!==undefined?null:await pending(cwd),item=snapshot?.items.find(i=>key(i.path)===key(resolve(cwd,args.path)))??null;
+        const data=await fileComparison(args,cwd,root,snapshot,item);
+        return {...header,mode:"file" as const,ok:true,completeness:{read:"complete",capture:"complete",projection:!data.excerpt?.truncated},data};
+    }
+    const snapshot=await pending(cwd),requestedPaths=args.paths??null,scopes=requestedPaths?.map(p=>resolve(cwd,p))??[];
+    if(scopes.some(p=>!contains(root,p)))return fail("outside_workspace","selection");
+    if(scopes.some(p=>key(p)===key(root)))return fail("invalid_request","selection");
+    const matches=(p:string,i:DiffPendingItem)=>contains(p,i.path)||i.sourcePath!==null&&contains(p,i.sourcePath);
+    const eligible=snapshot.items.filter(i=>scopes.length?scopes.some(p=>matches(p,i)):i.kind!=="private"||"includePrivate"in args&&args.includePrivate);
+    const maxFiles=args.maxFiles??(scopes.length?20:3),selected=eligible.slice(0,maxFiles),outcomes:DiffOutcome[]=[];
+    let attempted=0,completed=0,failed=0,skipped=0;
+    for(const i of selected){if(getActiveAbortSignal()?.aborted)break;if(i.directory){outcomes.push({path:i.path,sourcePath:i.sourcePath,kind:i.kind,status:"skipped-directory"});skipped++;continue;}
+        attempted++;try{const c=await fileComparison({mode:"file",path:i.path,workdir:cwd,maxChars:args.maxChars??3000},cwd,root,snapshot,i);outcomes.push({path:i.path,sourcePath:i.sourcePath,kind:i.kind,status:"compared",comparison:c});completed++;}catch(e){outcomes.push({path:i.path,sourcePath:i.sourcePath,kind:i.kind,status:"unavailable",error:diffError(e)});failed++;}}
+    const unattempted=selected.length-outcomes.length,ok=!failed&&!unattempted;
+    const data={scope:scopes.length?"selected":"all-pending",requestedPaths,includePrivate:"includePrivate"in args?args.includePrivate??false:false,excludedPrivate:scopes.length?0:snapshot.items.filter(i=>i.kind==="private"&&!("includePrivate"in args&&args.includePrivate)).length,counts:{parsed:snapshot.items.length,eligible:eligible.length,selected:selected.length,attempted,completed,failed,skipped,unattempted,limited:eligible.length-selected.length,returned:outcomes.length,omitted:0},unmatched:requestedPaths?requestedPaths.filter((p,index)=>!snapshot.items.some(i=>matches(scopes[index],i))):[],outcomes};
+    const payload={...header,mode:"workspace" as const,ok,completeness:{read:ok&&!data.counts.limited&&!data.unmatched.length&&!data.counts.skipped?"complete":"incomplete",capture:ok?"complete":"unknown",projection:outcomes.every(o=>o.status!=="compared"||!o.comparison.excerpt?.truncated)&&!data.counts.limited},data,...(!ok?{error:{code:unattempted?"aborted":"partial_comparison",stage:"comparison",message:"Some requested comparisons could not be verified."}}:{})};
+    while(Buffer.byteLength(JSON.stringify(payload),"utf8")>131072&&data.outcomes.length){data.outcomes.pop();data.counts.returned--;data.counts.omitted++;payload.completeness.projection=false;}
+    if(Buffer.byteLength(JSON.stringify(payload),"utf8")>131072)return fail("output_overflow","producer");return payload;
+}

package/src/operations/diff-revisions.ts

@@ -0,0 +1,157 @@
+import { promises as fs } from "node:fs";
+import { TextDecoder } from "node:util";
+import { join } from "node:path";
+import { createAsciiTempDirectory, safeTempExtension, isBinaryContent, stableDiffHeaders, type TextDiffResult } from "../diff/text";
+import { DIFF_OUTPUT_MAX_CHARS } from "../diff/text";
+import { normalizeDiffResponseMaxChars, formatTextDiff } from "../presentation/diff-results";
+import { isValidDiffRevisionSpec } from "../domain/revisions";
+import { getActiveAbortSignal } from "../execution/context";
+import { getCmExecutable, getDiffExecutable } from "../execution/process";
+import { runDiffRevisionsCommand, DiffRevisionsCommandError } from "../execution/diff-revisions-command";
+
+export const DIFF_REVISIONS_FILE_BYTES = 4 * 1024 * 1024;
+export const DIFF_REVISIONS_MAX_BYTES = 131072;
+export type DiffRevisionsArgs = { leftRevision: string; rightRevision: string; maxChars?: number; format?: "text" | "json"; workdir?: string };
+export type DiffRevisionsStage = "input" | "left" | "right" | "comparison" | "cleanup" | "producer";
+export type DiffRevisionsErrorCode = "invalid_selector" | "invalid_producer_data" | "materialization_failed" | "materialization_limit" | "cleanup_failed" | "invalid_utf8" | "malformed_output" | "command_failed" | "aborted" | "capture_incomplete" | "output_overflow";
+export class DiffRevisionsError extends Error {
+    constructor(readonly code: DiffRevisionsErrorCode, readonly stage: DiffRevisionsStage) { super("Historical revision comparison failed; no verified comparison is available."); }
+}
+const abort = (stage: DiffRevisionsStage) => { if (getActiveAbortSignal()?.aborted) throw new DiffRevisionsError("aborted", stage); };
+export const validDiffRevisionsSelector = (s: unknown): s is string => {
+    if (typeof s !== "string" || !s.length || s.length > 4096 || s.trim() !== s
+        || /[;\u0000-\u001f\u007f-\u009f\uD800-\uDFFF]/u.test(s) || s.startsWith("-")) return false;
+    const parts = s.split("#");
+    if (parts.length > 2) return false;
+    const validGlobal = (value: string) => /^revid:(?:0|[1-9][0-9]*)(?:@rep:[^@]+@repserver:\S+)?$/i.test(value) || /^rev:[^\s#]+$/i.test(value);
+    if (parts.length === 1) return validGlobal(s);
+    const [path, selector] = parts;
+    if (!path || path.trim() !== path || path.startsWith("-") || /^itemid:/i.test(path) && !/^itemid:(?:0|[1-9][0-9]*)$/i.test(path)) return false;
+    return /^cs:\d+$/i.test(selector) || /^br:\/.+$/i.test(selector) || /^lb:[^\s#]+$/i.test(selector) || validGlobal(selector);
+};
+export function diffRevisionsRequest(args: DiffRevisionsArgs) {
+    if (!validDiffRevisionsSelector(args.leftRevision) || !validDiffRevisionsSelector(args.rightRevision)) throw new DiffRevisionsError("invalid_selector", "input");
+    if (args.format !== undefined && args.format !== "text" && args.format !== "json") throw new DiffRevisionsError("invalid_producer_data", "input");
+    return { leftRevision: args.leftRevision, rightRevision: args.rightRevision, maxChars: normalizeDiffResponseMaxChars(args.maxChars) };
+}
+export type RevisionSide = { selector: string; kind: "file-qualified" | "global-revision"; resolvedIdentity: null; bytes: number; binary: boolean };
+export type DiffRevisionsObservation = { left: RevisionSide; right: RevisionSide; maxChars: number; binary: boolean; changed: boolean; normalized: string; hunkCount: number; diffStdoutBytes: number | null; diffExitCode: number | null; legacyResult: TextDiffResult };
+
+// Fully validate unified syntax/counts, not just an exit code or a plausible header.
+// Backend-provided header identities are never published as resolved revisions.
+export function validateRevisionUnifiedDiff(raw: string): number {
+    if (raw.includes("\0")) throw new DiffRevisionsError("malformed_output", "comparison");
+    const lines = raw.split(/\r?\n/); if (lines.at(-1) === "") lines.pop();
+    if (!lines[0]?.startsWith("--- ") || lines[0].length <= 4 || !lines[1]?.startsWith("+++ ") || lines[1].length <= 4) throw new DiffRevisionsError("malformed_output", "comparison");
+    let left = 0, right = 0, hunks = 0, changes = 0, markerAllowed = false;
+    for (const line of lines.slice(2)) {
+        const header = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@(?: .*)?$/.exec(line);
+        if (header) {
+            if (left || right) throw new DiffRevisionsError("malformed_output", "comparison");
+            const values = [header[1], header[2] ?? "1", header[3], header[4] ?? "1"].map(Number);
+            if (values.some(n => !Number.isSafeInteger(n) || n > DIFF_REVISIONS_FILE_BYTES + 1)) throw new DiffRevisionsError("malformed_output", "comparison");
+            left = values[1]; right = values[3]; if (!left && !right) throw new DiffRevisionsError("malformed_output", "comparison");
+            hunks++; markerAllowed = false; continue;
+        }
+        if (line === "\" && markerAllowed) { markerAllowed = false; continue; }
+        if (!hunks || (!left && !right)) throw new DiffRevisionsError("malformed_output", "comparison");
+        if (line.startsWith(" ")) { left--; right--; }
+        else if (line.startsWith("-")) { left--; changes++; }
+        else if (line.startsWith("+")) { right--; changes++; }
+        else throw new DiffRevisionsError("malformed_output", "comparison");
+        if (left < 0 || right < 0) throw new DiffRevisionsError("malformed_output", "comparison");
+        markerAllowed = true;
+    }
+    if (!hunks || !changes || left || right) throw new DiffRevisionsError("malformed_output", "comparison");
+    return hunks;
+}
+export async function materializeDiffRevision(selector: string, path: string, stage: "left" | "right", cwd: string): Promise<Buffer> {
+    abort(stage);
+    await runDiffRevisionsCommand(getCmExecutable(), ["cat", selector, "--file=" + path], cwd, [0])
+        .catch(error => { throw error instanceof DiffRevisionsCommandError ? new DiffRevisionsError(error.code, stage) : new DiffRevisionsError("materialization_failed", stage); });
+    abort(stage);
+    try {
+        // Reject symlink/directory output; read through the same descriptor whose size was checked.
+        const stat = await fs.lstat(path);
+        if (!stat.isFile() || stat.isSymbolicLink()) throw new DiffRevisionsError("materialization_failed", stage);
+        const file = await fs.open(path, "r");
+        try {
+            const size = (await file.stat()).size;
+            if (size > DIFF_REVISIONS_FILE_BYTES) throw new DiffRevisionsError("materialization_limit", stage);
+            const bytes = Buffer.alloc(size + 1); // one extra byte detects growth after the size check
+            let length = 0;
+            while (length < bytes.length) { abort(stage); const result = await file.read(bytes, length, bytes.length - length, length); if (!result.bytesRead) break; length += result.bytesRead; }
+            if (length !== size || (await file.stat()).size !== size) throw new DiffRevisionsError("materialization_failed", stage);
+            return bytes.subarray(0, size);
+        } finally { await file.close(); }
+    } catch (error) { throw error instanceof DiffRevisionsError ? error : new DiffRevisionsError("materialization_failed", stage); }
+}
+export async function assembleDiffRevisionsObservation(args: DiffRevisionsArgs): Promise<DiffRevisionsObservation> {
+    const request = diffRevisionsRequest(args); abort("input");
+    let root: string;
+    try { root = await createAsciiTempDirectory("pi-plastic-revisions-"); } catch { throw new DiffRevisionsError("materialization_failed", "left"); }
+    try {
+        const leftPath = join(root, "left" + safeTempExtension(request.leftRevision));
+        const rightPath = join(root, "right" + safeTempExtension(request.rightRevision));
+        const leftBytes = await materializeDiffRevision(request.leftRevision, leftPath, "left", args.workdir ?? process.cwd());
+        const rightBytes = await materializeDiffRevision(request.rightRevision, rightPath, "right", args.workdir ?? process.cwd());
+        const side = (selector: string, bytes: Buffer): RevisionSide => ({ selector, kind: selector.includes("#") ? "file-qualified" : "global-revision", resolvedIdentity: null, bytes: bytes.length, binary: isBinaryContent(bytes) });
+        return { left: side(request.leftRevision,leftBytes), right: side(request.rightRevision,rightBytes), maxChars:request.maxChars, ...await compareDiffBytes(leftBytes,rightBytes,request.leftRevision.replace("#","@"),request.rightRevision.replace("#","@")) };
+    } finally { await fs.rm(root, { recursive: true, force: true }).catch(() => { throw new DiffRevisionsError("cleanup_failed", "cleanup"); }); }
+}
+
+export async function compareDiffBytes(leftBytes: Buffer, rightBytes: Buffer, leftLabel: string, rightLabel: string): Promise<Omit<DiffRevisionsObservation,"left"|"right"|"maxChars">> {
+    abort("comparison");
+        const binary = isBinaryContent(leftBytes) || isBinaryContent(rightBytes);
+        if (binary) return { binary: true, changed: !leftBytes.equals(rightBytes), normalized: "", hunkCount: 0, diffStdoutBytes: null, diffExitCode: null, legacyResult: { backend: "diff", binary: true, changed: !leftBytes.equals(rightBytes), output: "", truncated: false, totalChars: 0 } };
+        // Match the old portable helper: ASCII-safe immutable backend operands and no logical labels in argv.
+        const operands = await createAsciiTempDirectory("pi-plastic-diff-");
+        try {
+            const l = join(operands, "left" + safeTempExtension(leftLabel)), r = join(operands, "right" + safeTempExtension(rightLabel));
+            await Promise.all([fs.writeFile(l, leftBytes, { flag: "wx" }), fs.writeFile(r, rightBytes, { flag: "wx" })]);
+            abort("comparison");
+            const capture = await runDiffRevisionsCommand(getDiffExecutable(), ["-u", l, r], operands, [0, 1])
+                .catch(error => { throw new DiffRevisionsError(error instanceof DiffRevisionsCommandError ? error.code : "command_failed", "comparison"); });
+            let raw: string;
+            try { raw = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(capture.stdout); }
+            catch { throw new DiffRevisionsError("invalid_utf8", "comparison"); }
+            if (capture.exitCode === 0 && raw !== "") throw new DiffRevisionsError("malformed_output", "comparison");
+            const hunks = capture.exitCode === 1 ? validateRevisionUnifiedDiff(raw) : 0;
+            const normalized = stableDiffHeaders(raw, leftLabel, rightLabel);
+            const legacyOutput = stableDiffHeaders(raw.slice(0, DIFF_OUTPUT_MAX_CHARS), leftLabel, rightLabel);
+            const truncated = raw.length > DIFF_OUTPUT_MAX_CHARS;
+            const legacyResult: TextDiffResult = { backend: "diff", changed: capture.exitCode === 1, binary: false, output: truncated ? legacyOutput + "\n\n[Diff output truncated at " + DIFF_OUTPUT_MAX_CHARS + " characters; inspect a narrower file or generate a review patch for the complete change.]" : normalized, truncated, totalChars: truncated ? raw.length : normalized.length };
+            abort("comparison");
+            return { binary: false, changed: capture.exitCode === 1, normalized, hunkCount: hunks, diffStdoutBytes: capture.stdout.length, diffExitCode: capture.exitCode, legacyResult };
+        } finally { await fs.rm(operands, { recursive: true, force: true }).catch(() => { throw new DiffRevisionsError("cleanup_failed", "cleanup"); }); }
+}
+
+export type RevisionExcerpt = { countBasis: "normalized_diff_utf16"; text: string; observedChars: number; sourceChars: number; returnedChars: number; omittedChars: number; markerChars: number; truncated: boolean };
+export const DIFF_REVISIONS_EXCERPT_MARKER = "\n\n[Diff excerpt truncated; not a complete/applyable patch.]";
+const prefix = (s: string, count: number) => { let end = Math.min(count, s.length); if (end > 0 && end < s.length && /[\uD800-\uDBFF]/.test(s[end - 1])) end--; return s.slice(0, end); };
+export function diffRevisionsPayload(observation: DiffRevisionsObservation) {
+    const excerpt = (count: number): RevisionExcerpt => {
+        const selected = prefix(observation.normalized, count), omitted = observation.normalized.length - selected.length;
+        const marker = omitted ? DIFF_REVISIONS_EXCERPT_MARKER : "";
+        return { countBasis: "normalized_diff_utf16", text: selected + marker, observedChars: observation.normalized.length, sourceChars: selected.length, returnedChars: selected.length + marker.length, omittedChars: omitted, markerChars: marker.length, truncated: omitted > 0 };
+    };
+    const markerReserve = DIFF_REVISIONS_EXCERPT_MARKER.length;
+    const selected = observation.normalized.length > observation.maxChars ? Math.max(0, observation.maxChars - markerReserve) : observation.normalized.length;
+    const data = { ...({ scope: "explicit_selector_pair", qualifierVerified: false, resolvedIdentities: null, comparisonKind: "revision-to-revision", left: observation.left, right: observation.right, status: observation.changed ? observation.binary ? "binary-different" : "changed" : "unchanged", changed: observation.changed, binary: observation.binary, comparisonBasis: observation.binary ? "byte_equality" : "diff_u", hunkCount: observation.hunkCount, capture: { diffStdoutBytes: observation.diffStdoutBytes, diffExitCode: observation.diffExitCode }, limits: { maxChars: observation.maxChars, selectorCodeUnits: 4096, materializedBytesPerSide: DIFF_REVISIONS_FILE_BYTES, compactUtf8Bytes: DIFF_REVISIONS_MAX_BYTES }, excerpt: observation.binary ? null : excerpt(selected) } as const) };
+    const completeness = { read: "complete" as const, capture: "complete" as const, projection: !data.excerpt?.truncated };
+    const payload = { schemaVersion: 1, action: "diff-revisions", provenance: { source: "plastic", producer: "@aefree/pi-plastic", contentTrust: "external" }, ok: true, completeness, data } as const;
+    if (Buffer.byteLength(JSON.stringify(payload), "utf8") > DIFF_REVISIONS_MAX_BYTES && !observation.binary) {
+        let low = 0, high = selected;
+        while (low < high) { const mid = Math.ceil((low + high) / 2); data.excerpt = excerpt(mid); completeness.projection = !data.excerpt.truncated; if (Buffer.byteLength(JSON.stringify(payload), "utf8") <= DIFF_REVISIONS_MAX_BYTES) low = mid; else high = mid - 1; }
+        data.excerpt = excerpt(low);
+        completeness.projection = !data.excerpt.truncated;
+    }
+    if (Buffer.byteLength(JSON.stringify(payload), "utf8") > DIFF_REVISIONS_MAX_BYTES) throw new DiffRevisionsError("output_overflow", "producer");
+    return payload;
+}
+export async function presentDiffRevisions(observation: DiffRevisionsObservation, args: DiffRevisionsArgs): Promise<string> {
+    return formatTextDiff("diffRevisions", args.format, "revision-to-revision", observation.legacyResult, args.workdir, {}, args.maxChars);
+}
+export async function executeDiffRevisions(args: DiffRevisionsArgs): Promise<string> {
+    return presentDiffRevisions(await assembleDiffRevisionsObservation(args), args);
+}

package/src/operations/diff.ts

@@ -0,0 +1,53 @@
+import { DIFF_OUTPUT_MAX_CHARS, isBinaryContent, stableDiffHeaders, boundDiffOutput, runPortableTextDiff, safeTempExtension, isAsciiPath, createAsciiTempDirectory, materializeRevision, isNoDataError, withWorkspaceBaseUnavailableDiagnostic, TextDiffResult } from "../diff/text";
+import { DIFF_RESPONSE_DEFAULT_MAX_CHARS, DIFF_RESPONSE_MAX_CHARS, DIFF_RESPONSE_MIN_CHARS, DIFF_RESPONSE_TOTAL_MAX_CHARS, normalizeDiffResponseMaxChars, boundTextDiffResult, formatTextDiff, WORKSPACE_DIFF_PATH_MAX_CHARS, WORKSPACE_DIFF_MAX_PATHS, WORKSPACE_DIFF_MAX_FILES, WORKSPACE_DIFF_DEFAULT_MAX_FILES, WORKSPACE_DIFF_MIN_CHARS, WORKSPACE_DIFF_PER_FILE_MAX_CHARS, WORKSPACE_DIFF_DEFAULT_MAX_CHARS, boundWorkspaceValue, WORKSPACE_DIFF_CONTENT_MAX_CHARS, WORKSPACE_DIFF_DISPLAY_PATH_MAX_CHARS, boundWorkspaceDiffResult, WORKSPACE_DIFF_ERROR_MAX_CHARS, workspacePathPreview, WORKSPACE_DIFF_TOTAL_MAX_CHARS, formatWorkspaceDiffResult } from "../presentation/diff-results";
+import { resolveDiffFileRevision, isUnscopedDiffRevisionSpec, extractBranchSelectorFromRevision, extractBranchNameFromSelector, PendingBaseIdentityResolver, isRevisionNotFoundError, createPendingBaseIdentityResolver } from "../domain/revisions";
+import { listRecentBranchNames } from "../domain/branches";
+import { tool } from "../tool-definition";
+import { workdirArg } from "./arguments";
+import { outputFormatArg } from "../presentation/results";
+import { join, isAbsolute } from "path";
+import { promises as fs } from "node:fs";
+import { PendingItem, getMachineReadablePendingItems, filterPendingItemsByScope } from "../domain/pending";
+import { toNormalizedAbsolutePath, toCommandPath, toPathComparisonKeyFromAbsolutePath } from "../domain/paths";
+import { assembleConsolidatedDiff } from "./consolidated-diff";
+
+export const __plasticDiffInternals = {
+    DIFF_OUTPUT_MAX_CHARS,
+    DIFF_RESPONSE_DEFAULT_MAX_CHARS,
+    DIFF_RESPONSE_MAX_CHARS,
+    DIFF_RESPONSE_MIN_CHARS,
+    DIFF_RESPONSE_TOTAL_MAX_CHARS,
+    normalizeDiffResponseMaxChars,
+    isBinaryContent,
+    stableDiffHeaders,
+    boundDiffOutput,
+    runPortableTextDiff,
+    safeTempExtension,
+    isAsciiPath,
+    createAsciiTempDirectory,
+    materializeRevision,
+    isNoDataError,
+    withWorkspaceBaseUnavailableDiagnostic,
+    boundTextDiffResult,
+    resolveDiffFileRevision,
+    isUnscopedDiffRevisionSpec,
+};
+
+export const diff = tool({
+    description: "Bounded non-GUI comparison. Require mode=file (one local file versus loaded base or revision), revisions (two historical selectors), or workspace (explicit pending paths or allPending=true). No implicit whole-workspace review.",
+    args: {
+        mode: tool.schema.enum(["file","revisions","workspace"]),
+        path: tool.schema.string().optional(),
+        revision: tool.schema.string().optional(),
+        leftRevision: tool.schema.string().optional(),
+        rightRevision: tool.schema.string().optional(),
+        paths: tool.schema.array(tool.schema.string()).optional(),
+        allPending: tool.schema.boolean().optional(),
+        includePrivate: tool.schema.boolean().optional(),
+        maxFiles: tool.schema.number().optional(),
+        maxChars: tool.schema.number().optional(),
+        format: outputFormatArg,
+        workdir: workdirArg,
+    },
+    execute: async args => assembleConsolidatedDiff(args),
+});

package/src/operations/merge.ts

@@ -0,0 +1,26 @@
+import { tool } from "../tool-definition";
+import { outputFormatArg } from "../presentation/results";
+import { workdirArg } from "./arguments";
+import { assembleWorkspaceMergeReceipt } from "./workspace-merge-receipt";
+import { presentWorkspaceMergeReceipt } from "../presentation/workspace-merge-results";
+export type MergeConflictStrategy = "auto" | "source" | "destination";
+export const merge = tool({
+ description:"Request one non-interactive workspace merge with an explicit strategy; command completion is not conflict resolution or checkin readiness.",
+ args:{
+ source:tool.schema.string().min(1).describe("Exact branch/changeset/label/shelveset source operand; not CLI options."),
+ strategy:tool.schema.enum(["auto","source","destination"]).optional().describe("Default auto/try; source/destination explicitly force contributor preference."),
+ cherrypicking:tool.schema.boolean().optional().describe("Request cherry-picking mode."),
+ forced:tool.schema.boolean().optional().describe("Request connected-branch-check override where CM supports it."),
+ preflight:tool.schema.boolean().optional().describe("Zero-command plan only, not conflict/readiness analysis."),
+ format:outputFormatArg,workdir:workdirArg},
+ async execute(args){const dto=await assembleWorkspaceMergeReceipt("merge",args);if(!dto.ok)throw new Error(presentWorkspaceMergeReceipt({...dto,data:{...dto.data,outputFormatRequested:"text"}}));return presentWorkspaceMergeReceipt(dto);}
+});
+export const finalizeMerge = tool({
+ description:"Request non-interactive merge finalization with an explicit contributor policy; not a guarantee of finalized metadata or preserved manual edits.",
+ args:{
+ source:tool.schema.string().min(1).describe("Exact original merge source operand; not CLI options."),
+ strategy:tool.schema.enum(["source","destination"]).optional().describe("Default destination; contributor preference is not a manual-edit preservation guarantee."),
+ preflight:tool.schema.boolean().optional().describe("Zero-command finalization plan only, not readiness analysis."),
+ format:outputFormatArg,workdir:workdirArg},
+ async execute(args){const dto=await assembleWorkspaceMergeReceipt("finalize-merge",args);if(!dto.ok)throw new Error(presentWorkspaceMergeReceipt({...dto,data:{...dto.data,outputFormatRequested:"text"}}));return presentWorkspaceMergeReceipt(dto);}
+});

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

@@ -0,0 +1,21 @@
+import {captureWorkspaceMergeCommand,emptyWorkspaceMergeAttempt} from "../execution/workspace-merge-command";
+import {safeBranchDeleteText} from "../domain/branch-delete-contract";
+export const validObjectDeleteText=safeBranchDeleteText;
+export type ObjectDeleteAction="shelveset-delete"|"code-review-delete";
+export type ObjectDeleteRequest={operands:string[];repository:string|null;workdir:string;preflight:boolean;format:"text"|"json"};
+export type ObjectDeleteData={requested:ObjectDeleteRequest|null;intendedArgv:string[];attempt:ReturnType<typeof emptyWorkspaceMergeAttempt>;capture:Awaited<ReturnType<typeof captureWorkspaceMergeCommand>>["capture"]|null;observedDeletedObjects:null;observedRepositoryIdentity:null;scope:"requested-only";rollback:"not-proven";effect:"not-attempted"|"not-proven"|"uncertain"};
+export type ObjectDeleteReceipt={schemaVersion:1;action:ObjectDeleteAction;provenance:{source:"plastic";producer:"@aefree/pi-plastic";contentTrust:"external"};completeness:{capture:"complete"|"incomplete"|"unknown";projection:true};data:ObjectDeleteData}&({ok:true;outcome:"preflight"|"command-completed"}|{ok:false;outcome:"failed"|"uncertain";error:{code:"invalid_request"|"launch_failed"|"aborted"|"uncertain"|"producer_failed";message:string}});
+export const objectDeletePrefix=(a:ObjectDeleteAction)=>a==="shelveset-delete"?["shelveset","delete"]:["codereview","-d"];
+export const objectDeleteArgv=(a:ObjectDeleteAction,r:ObjectDeleteRequest)=>[...objectDeletePrefix(a),...r.operands,...(r.repository===null?[]:[`--repository=${r.repository}`])];
+export function validObjectDeleteOperands(a:ObjectDeleteAction,v:unknown):v is string[]{if(!Array.isArray(v)||v.length<1||v.length>(a==="shelveset-delete"?1:256))return false;let bytes=0;for(let i=0;i<v.length;i++){const s=v[i];if(!safeBranchDeleteText(s)||s.trimStart().startsWith("-"))return false;bytes+=Buffer.byteLength(s,"utf8");if(bytes>32768)return false;}return true;}
+export function emptyObjectDeleteData(action:ObjectDeleteAction):ObjectDeleteData{return {requested:null,intendedArgv:objectDeletePrefix(action),attempt:emptyWorkspaceMergeAttempt(),capture:null,observedDeletedObjects:null,observedRepositoryIdentity:null,scope:"requested-only",rollback:"not-proven",effect:"not-attempted"};}
+function header(action:ObjectDeleteAction,data:ObjectDeleteData){return {schemaVersion:1 as const,action,provenance:{source:"plastic" as const,producer:"@aefree/pi-plastic" as const,contentTrust:"external" as const},completeness:{capture:data.capture?data.capture.complete?"complete" as const:"incomplete" as const:"unknown" as const,projection:true as const},data};}
+export function objectDeleteFailure(action:ObjectDeleteAction,data:ObjectDeleteData,code:Extract<ObjectDeleteReceipt,{ok:false}>["error"]["code"],message:string):ObjectDeleteReceipt{return {...header(action,data),ok:false,outcome:data.effect==="uncertain"?"uncertain":"failed",error:{code,message}};}
+export async function assembleObjectDeleteReceipt(action:ObjectDeleteAction,args:unknown):Promise<ObjectDeleteReceipt>{const data=emptyObjectDeleteData(action);let entered=false;try{
+ if(!args||typeof args!=="object"||Array.isArray(args)||Object.keys(args).some(k=>!(action==="shelveset-delete"?["shelveset","preflight","format","workdir"]:["ids","repository","preflight","format","workdir"]).includes(k)))return objectDeleteFailure(action,data,"invalid_request","Use only declared bounded object-delete controls.");
+ const i={...args} as Record<string,unknown>,operands=action==="shelveset-delete"?[i.shelveset]:Array.isArray(i.ids)&&i.ids.length<=256?Array.from(i.ids):i.ids,cwd=i.workdir===undefined?process.cwd():i.workdir,repository=i.repository===undefined?null:i.repository,preview=i.preflight===undefined?false:i.preflight,format=i.format===undefined?"text":i.format;
+ if(!validObjectDeleteOperands(action,operands)||!safeBranchDeleteText(cwd)||repository!==null&&!safeBranchDeleteText(repository)||Object.hasOwn(i,"repository")&&i.repository===null||typeof preview!=="boolean"||!["text","json"].includes(format as string))return objectDeleteFailure(action,data,"invalid_request","Use bounded exact operands, repository text, strict preview boolean and text/json. Options/stdin are rejected.");
+ const r:ObjectDeleteRequest={operands:[...operands],repository:repository as string|null,workdir:cwd,preflight:preview,format:format as "text"|"json"};if(Buffer.byteLength(JSON.stringify(r),"utf8")>32768)return objectDeleteFailure(action,data,"invalid_request","Request exceeds aggregate byte budget.");data.requested=r;data.intendedArgv=objectDeleteArgv(action,r);
+ if(preview)return {...header(action,data),ok:true,outcome:"preflight"};entered=true;const o=await captureWorkspaceMergeCommand([...data.intendedArgv],cwd);data.attempt=o.attempt;data.capture=o.capture;if(o.capture.complete&&!o.failed&&o.attempt.state==="started"&&o.attempt.exitCode===0){data.effect="not-proven";return {...header(action,data),ok:true,outcome:"command-completed"};}data.effect=["started","unknown"].includes(data.attempt.state)?"uncertain":"not-attempted";return objectDeleteFailure(action,data,o.attempt.aborted?"aborted":data.effect==="uncertain"?"uncertain":"launch_failed","Object deletion completion is not proven; inspect earlier possible effects before deciding whether to retry.");
+ }catch{if(entered){data.attempt={...emptyWorkspaceMergeAttempt(),state:"unknown"};data.capture=null;data.effect="uncertain";}return objectDeleteFailure(action,data,"producer_failed","Object deletion observation failed; no rollback or safe retry is proven.");}}
+export function presentObjectDeleteReceipt(dto:ObjectDeleteReceipt):string{if(dto.data.requested?.format==="json")return JSON.stringify(dto);if(!dto.ok)return `${dto.action} ${dto.outcome}: ${dto.error.message} Effects: ${dto.data.effect}.`;if(dto.outcome==="preflight")return `${dto.action} command-only preview (not executed): ${JSON.stringify(dto.data.intendedArgv)}. No existence/readiness analysis.`;return `${dto.action} command completed for ${dto.data.requested!.operands.length} requested operands. Deleted identities, repository scope and rollback remain unverified.`;}