@aefree/pi-plastic 0.7.6 → 0.8.1

package/src/pi/arguments.ts

@@ -0,0 +1,298 @@
+import type { PlasticExportName } from "./tool-registry";
+
+type ToolConfig = {
+  prepareArguments?: (args: unknown) => Record<string, unknown>;
+};
+
+export const TOOL_CONFIG: Partial<Record<PlasticExportName, ToolConfig>> = {
+  status: {
+    prepareArguments(args) {
+      const input = normalizeOutputFormatAlias(normalizeArgs(args));
+      normalizeWorkdirAliases(input);
+      assignAlias(input, "includeRevId", ["include_rev_id"]);
+      assignAlias(input, "machineReadable", ["machine_readable", "machine"]);
+      assignAlias(input, "maxItems", ["max_items"]);
+      assignAlias(input, "includeRaw", ["include_raw"]);
+      return input;
+    },
+  },
+  update: {
+    prepareArguments(args) {
+      const input = normalizeArgs(args);
+      normalizeWorkdirAliases(input);
+      return input;
+    },
+  },
+  add: {
+    prepareArguments(args) {
+      const input = normalizeArgs(args);
+      normalizeWorkdirAliases(input);
+      promoteSinglePath(input);
+      assignAlias(input, "paths", ["items"]);
+      return input;
+    },
+  },
+  checkin: {
+    prepareArguments(args) {
+      const input = normalizeOutputFormatAlias(normalizeArgs(args));
+      normalizeWorkdirAliases(input);
+      assignAlias(input, "message", ["comment", "comments"]);
+      promoteSinglePath(input);
+      assignAlias(input, "paths", ["items", "files"]);
+      assignAlias(input, "applyChanged", ["apply_changed"]);
+      assignAlias(input, "includePrivate", ["include_private"]);
+      assignAlias(input, "includeAll", ["include_all"]);
+      assignAlias(input, "updateAfter", ["update_after"]);
+      return input;
+    },
+  },
+  undo: {
+    prepareArguments(args) {
+      const input = normalizeArgs(args);
+      normalizeWorkdirAliases(input);
+      promoteSinglePath(input);
+      assignAlias(input, "paths", ["items"]);
+      // Consumed aliases must not become unsupported extra options in the selected producer.
+      for (const key of ["cwd", "workingDirectory", "working_directory", "path", "file", "items"]) delete input[key];
+      return input;
+    },
+  },
+  resolveDeleteChangeConflict: {
+    prepareArguments(args) {
+      const input = normalizeOutputFormatAlias(normalizeArgs(args));
+      normalizeWorkdirAliases(input);
+      promoteSinglePath(input);
+      assignAlias(input, "paths", ["items", "files"]);
+      assignAlias(input, "keepOnDisk", ["keep_on_disk", "keepOnDisk", "nodisk"]);
+      for (const key of ["cwd", "workingDirectory", "working_directory", "path", "file", "items", "files", "keep_on_disk", "nodisk"]) delete input[key];
+      return input;
+    },
+  },
+  diff: {
+    prepareArguments(args) {
+      const input=normalizeOutputFormatAlias(normalizeArgs(args));
+      normalizeWorkdirAliases(input);
+      return input;
+    },
+  },
+  patch: {
+    prepareArguments(args) {
+      const input = normalizeOutputFormatAlias(normalizeArgs(args));
+      normalizeWorkdirAliases(input);
+      assignAlias(input, "output", ["output_file", "outputFile"]);
+      assignAlias(input, "toolPath", ["tool_path", "tool"]);
+      for (const key of ["cwd", "workingDirectory", "working_directory", "output_file", "outputFile", "tool_path", "tool"]) delete input[key];
+      return input;
+    },
+  },
+  branchCreate: {
+    prepareArguments(args) {
+      const input = normalizeArgs(args);
+      normalizeWorkdirAliases(input);
+      assignAlias(input, "commentsFile", ["comments_file"]);
+      return input;
+    },
+  },
+  switchBranch: {
+    prepareArguments(args) {
+      const input = normalizeOutputFormatAlias(normalizeArgs(args));
+      normalizeWorkdirAliases(input);
+      assignAlias(input, "pendingChanges", ["pending_changes"]);
+      return input;
+    },
+  },
+  merge: {
+    prepareArguments(args) {
+      const input = normalizeOutputFormatAlias(normalizeArgs(args));
+      normalizeWorkdirAliases(input);
+      assignAlias(input, "cherrypicking", ["cherry_picking", "cherryPicking"]);
+      for (const key of ["cwd", "workingDirectory", "working_directory", "cherry_picking", "cherryPicking"]) delete input[key];
+      return input;
+    },
+  },
+  mergeBranches: {
+    prepareArguments(args) {
+      return normalizeOutputFormatAlias(normalizeArgs(args));
+    },
+  },
+  mergeToBranch: {
+    prepareArguments(args) {
+      const input = normalizeOutputFormatAlias(normalizeArgs(args));
+      normalizeWorkdirAliases(input);
+      assignAlias(input, "source", ["sourceBranch", "source_branch", "branch"]);
+      assignAlias(input, "target", ["targetBranch", "target_branch", "destination", "destinationBranch", "destination_branch"]);
+      assignAlias(input, "cardRef", ["card", "cardCode", "card_code", "codecksCard", "codecks_card"]);
+      assignAlias(input, "updateTarget", ["update_target", "update"]);
+      assignAlias(input, "includePrivate", ["include_private"]);
+      for (const key of ["cwd", "workingDirectory", "working_directory", "sourceBranch", "source_branch", "branch", "targetBranch", "target_branch", "destination", "destinationBranch", "destination_branch", "card", "cardCode", "card_code", "codecksCard", "codecks_card", "update_target", "update", "include_private"]) delete input[key];
+      return input;
+    },
+  },
+  finalizeMerge: {
+    prepareArguments(args) {
+      const input = normalizeOutputFormatAlias(normalizeArgs(args));
+      normalizeWorkdirAliases(input);
+      assignAlias(input, "source", ["mergeSource", "merge_source"]);
+      for (const key of ["cwd", "workingDirectory", "working_directory", "mergeSource", "merge_source"]) delete input[key];
+      return input;
+    },
+  },
+  currentBranch: {
+    prepareArguments(args) {
+      const input = normalizeOutputFormatAlias(normalizeArgs(args));
+      normalizeWorkdirAliases(input);
+      return input;
+    },
+  },
+  branchList: {
+    prepareArguments(args) {
+      const input = normalizeArgs(args);
+      normalizeWorkdirAliases(input);
+      assignAlias(input, "nameLike", ["name_like"]);
+      assignAlias(input, "includeHidden", ["include_hidden"]);
+      assignAlias(input, "orderBy", ["order_by"]);
+      return input;
+    },
+  },
+  branchExists: {
+    prepareArguments(args) {
+      const input = normalizeArgs(args);
+      normalizeWorkdirAliases(input);
+      return input;
+    },
+  },
+  branchDelete: {
+    prepareArguments(args) {
+      const input = normalizeOutputFormatAlias(normalizeArgs(args));
+      normalizeWorkdirAliases(input);
+      assignAlias(input, "deleteChangesets", ["delete_changesets"]);
+      for (const key of ["cwd", "workingDirectory", "working_directory", "delete_changesets"]) delete input[key];
+      return input;
+    },
+  },
+  shelvesetCreate: {
+    prepareArguments(args) {
+      const input = normalizeArgs(args);
+      normalizeWorkdirAliases(input);
+      promoteSinglePath(input);
+      assignAlias(input, "paths", ["items"]);
+      assignAlias(input, "commentsFile", ["comments_file"]);
+      assignAlias(input, "summaryFormat", ["summary_format"]);
+      for (const key of ["cwd","workingDirectory","working_directory","path","file","items","comments_file","summary_format"]) delete input[key];
+      return input;
+    },
+  },
+  shelvesetApply: {
+    prepareArguments(args) {
+      const input = normalizeArgs(args);
+      normalizeWorkdirAliases(input);
+      assignAlias(input, "changePaths", ["change_paths"]);
+      assignAlias(input, "dontCheckout", ["dont_checkout"]);
+      assignAlias(input, "comparisonMethod", ["comparison_method"]);
+      for (const key of ["cwd","workingDirectory","working_directory","change_paths","dont_checkout","comparison_method"]) delete input[key];
+      return input;
+    },
+  },
+  shelvesetDelete: {
+    prepareArguments(args) {
+      const input = normalizeOutputFormatAlias(normalizeArgs(args));
+      normalizeWorkdirAliases(input);
+      for (const key of ["cwd","workingDirectory","working_directory"]) delete input[key];
+      return input;
+    },
+  },
+  shelvesetList: {
+    prepareArguments(args) {
+      const input = normalizeArgs(args);
+      normalizeWorkdirAliases(input);
+      assignAlias(input, "commentLike", ["comment_like"]);
+      assignAlias(input, "dateFrom", ["date_from"]);
+      assignAlias(input, "dateFormat", ["date_format"]);
+      return input;
+    },
+  },
+  codeReviewCreate: {
+    prepareArguments(args) {
+      const input = normalizeArgs(args);
+      normalizeWorkdirAliases(input);
+      for (const key of ["cwd","workingDirectory","working_directory"]) delete input[key];
+      return input;
+    },
+  },
+  codeReviewUpdate: {
+    prepareArguments(args) {
+      const input = normalizeArgs(args);
+      normalizeWorkdirAliases(input);
+      assignAlias(input, "reviewId", ["review_id"]);
+      if (input.reviewId !== undefined && input.id === undefined) input.id = input.reviewId;
+      for (const key of ["cwd","workingDirectory","working_directory","reviewId","review_id"]) delete input[key];
+      return input;
+    },
+  },
+  codeReviewDelete: {
+    prepareArguments(args) {
+      const input = normalizeOutputFormatAlias(normalizeArgs(args));
+      normalizeWorkdirAliases(input);
+      if (input.id !== undefined && input.ids === undefined) input.ids = [String(input.id)];
+      assignAlias(input, "ids", ["review_ids"]);
+      for (const key of ["cwd","workingDirectory","working_directory","id","review_ids"]) delete input[key];
+      return input;
+    },
+  },
+  codeReviewFind: {
+    prepareArguments(args) {
+      const input = normalizeOutputFormatAlias(normalizeArgs(args));
+      normalizeWorkdirAliases(input);
+      assignAlias(input, "targetType", ["target_type"]);
+      assignAlias(input, "titleLike", ["title_like"]);
+      assignAlias(input, "orderBy", ["order_by"]);
+      assignAlias(input, "dateFormat", ["date_format"]);
+      assignAlias(input, "output", ["output_format", "response_format"]);
+      return input;
+    },
+  },
+  workspaceList: {
+    prepareArguments(args) {
+      const input = normalizeOutputFormatAlias(normalizeArgs(args));
+      normalizeWorkdirAliases(input);
+      assignAlias(input, "output", ["output_format", "response_format"]);
+      return input;
+    },
+  },
+};
+
+export function normalizeArgs(args: unknown): Record<string, unknown> {
+  return args && typeof args === "object" ? { ...(args as Record<string, unknown>) } : {};
+}
+
+function assignAlias(target: Record<string, unknown>, key: string, aliases: string[]): void {
+  if (target[key] !== undefined) return;
+  for (const alias of aliases) {
+    if (target[alias] !== undefined) {
+      target[key] = target[alias];
+      return;
+    }
+  }
+}
+
+function normalizeWorkdirAliases(input: Record<string, unknown>): void {
+  assignAlias(input, "workdir", ["cwd", "workingDirectory", "working_directory"]);
+}
+
+function normalizeOutputFormatAlias(input: Record<string, unknown>): Record<string, unknown> {
+  if (typeof input.format === "string" && input.format.trim().toLowerCase() === "markdown") {
+    input.format = "text";
+  }
+  if (typeof input.output === "string" && input.output.trim().toLowerCase() === "markdown") {
+    input.output = "text";
+  }
+  return input;
+}
+
+function promoteSinglePath(input: Record<string, unknown>): void {
+  if (input.paths !== undefined) return;
+  const singlePath = input.path ?? input.file;
+  if (typeof singlePath === "string" && singlePath.trim().length > 0) {
+    input.paths = [singlePath];
+  }
+}

package/src/pi/branch-create-output.ts

@@ -0,0 +1,83 @@
+import { Type, type TProperties } from "typebox";
+import { Check } from "typebox/value";
+import { assembleBranchCreateReceipt, presentBranchCreateReceipt, safeBranchCreateText, type BranchCreateReceipt, type BranchCreateAttempt, type BranchCreateCapture } from "../operations/branch-create";
+const object = <P extends TProperties>(p: P) => Type.Object(p, { additionalProperties: false });
+const enumeration = <const V extends readonly string[]>(v: V) => Type.Unsafe<V[number]>({ anyOf: v.map(value => ({ type: "string", const: value })) });
+const str = (max = 4096) => Type.String({ maxLength: max });
+const uint = (max = Number.MAX_SAFE_INTEGER) => Type.Integer({ minimum: 0, maximum: max });
+const nullable = <T extends ReturnType<typeof Type.Object> | ReturnType<typeof Type.String> | ReturnType<typeof Type.Array>>(s: T) => Type.Union([s, Type.Null()]);
+const attempt = object({ state: enumeration(["not-attempted", "not-started", "started", "unknown"]), terminal: enumeration(["not-observed", "observed"]), exitCode: Type.Union([uint(2147483647), Type.Null()]), aborted: Type.Boolean(), timedOut: Type.Boolean() });
+const capture = object({ stdoutBytes: uint(), stderrBytes: uint(), stdoutRetainedBytes: uint(65536), stderrRetainedBytes: uint(16384), truncated: Type.Boolean(), complete: Type.Boolean(), validUtf8: Type.Boolean() });
+const argv = Type.Array(str(8192), { maxItems: 8, minItems: 1 });
+const data = {
+    requested: nullable(object({ branch: str(), parent: nullable(str()), changeset: nullable(str()), label: nullable(str()), comment: nullable(str()), commentsFile: nullable(str()), allowRootBranch: Type.Boolean() })),
+    resolvedTarget: nullable(str()), parentResolution: object({ basis: enumeration(["not-required", "explicit", "status", "unresolved"]), observedBranch: nullable(str()), repositoryVerification: Type.Literal("unverified") }),
+    parentCommands: Type.Array(object({ argv, attempt, capture }), { maxItems: 2 }),
+    command: nullable(argv), attempt, capture: nullable(capture), observedCreatedIdentity: Type.Null(), repositoryVerification: Type.Literal("unverified"), workspaceSwitch: Type.Literal("not-requested"),
+};
+const header = { schemaVersion: Type.Literal(1), action: Type.Literal("branch-create"), provenance: object({ source: Type.Literal("plastic"), producer: Type.Literal("@aefree/pi-plastic"), contentTrust: Type.Literal("external") }), completeness: object({ capture: enumeration(["complete", "incomplete", "unknown"]), projection: Type.Literal(true) }) };
+const error = object({ code: enumeration(["invalid_request", "unsupported_source", "ambiguous_qualifier", "parent_unresolved", "launch_failed", "aborted", "uncertain", "producer_failed"]), stage: enumeration(["input", "source", "parent", "create", "producer"]), message: str(256) });
+export const branchCreateOutputSchema = Type.Unsafe<BranchCreateReceipt>(Type.Union([
+    object({ ...header, ok: Type.Literal(true), outcome: Type.Literal("command-completed"), data: object({ ...data, effect: Type.Literal("not-proven") }) }),
+    object({ ...header, ok: Type.Literal(false), outcome: enumeration(["failed", "unsupported"]), error, data: object({ ...data, effect: Type.Literal("not-attempted") }) }),
+    object({ ...header, ok: Type.Literal(false), outcome: Type.Literal("uncertain"), error, data: object({ ...data, effect: Type.Literal("uncertain") }) }),
+]));
+const validAttempt = (a: BranchCreateAttempt) => !(a.exitCode !== null && a.terminal !== "observed") && !(a.state === "not-attempted" && (a.terminal !== "not-observed" || a.exitCode !== null || a.timedOut)) && !(a.state === "not-started" && a.exitCode !== null);
+const validCapture = (c: BranchCreateCapture, a: BranchCreateAttempt) => c.stdoutRetainedBytes <= c.stdoutBytes && c.stderrRetainedBytes <= c.stderrBytes && (!c.complete || c.validUtf8 && !c.truncated && c.stdoutBytes === c.stdoutRetainedBytes && c.stderrBytes === c.stderrRetainedBytes && a.state === "started" && a.terminal === "observed" && a.exitCode !== null && !a.aborted && !a.timedOut);
+export function validateBranchCreateOutput(value: unknown): value is BranchCreateReceipt {
+    if (!Check(branchCreateOutputSchema, value) || Buffer.byteLength(JSON.stringify(value), "utf8") > 131072) return false;
+    const dto = value as BranchCreateReceipt, d = dto.data, a = d.attempt, p = d.parentResolution, r = d.requested;
+    if (!validAttempt(a) || d.capture && !validCapture(d.capture, a)) return false;
+    if (!dto.ok && !safeBranchCreateText(dto.error.message)) return false;
+    if (r && (!r.branch.trim() || Object.values(r).some(v => typeof v === "string" && !safeBranchCreateText(v)) || r.changeset && r.label || r.comment && r.commentsFile || r.comment !== null && !r.comment.trim())) return false;
+    if (d.resolvedTarget !== null && (!safeBranchCreateText(d.resolvedTarget) || !d.resolvedTarget.trim())) return false;
+    if (p.observedBranch !== null && (!safeBranchCreateText(p.observedBranch) || !/^\/(?:[^/@\\]+)(?:\/[^/@\\]+)*$/u.test(p.observedBranch) || /[?\uFFFD]/u.test(p.observedBranch))) return false;
+    if ((p.basis === "status") !== (p.observedBranch !== null)) return false;
+    for (let i = 0; i < d.parentCommands.length; i++) {
+        const c = d.parentCommands[i]!;
+        if (JSON.stringify(c.argv) !== JSON.stringify(i === 0 ? ["status"] : ["status", "--compact"]) || !validAttempt(c.attempt) || !validCapture(c.capture, c.attempt)) return false;
+    }
+    if (p.basis === "status" && (d.parentCommands.length !== 1 || !d.parentCommands[0]!.capture.complete || d.parentCommands[0]!.capture.stderrBytes || d.parentCommands[0]!.attempt.exitCode !== 0)) return false;
+    if (["explicit", "not-required"].includes(p.basis) && d.parentCommands.length) return false;
+    const norm = (s: string) => s.trim().replace(/^br:/i, "").split("@")[0]!.replace(/\\/g, "/");
+    if (r) {
+        const relative = !norm(r.branch).startsWith("/");
+        if (!relative && p.basis !== "not-required" || relative && p.basis === "explicit" && r.parent === null || relative && p.basis === "status" && r.parent !== null) return false;
+        if (d.command && relative && (r.branch.includes("@") || r.parent?.includes("@"))) return false;
+    }
+    if (d.command) {
+        if (!r || !d.resolvedTarget || Buffer.byteLength(JSON.stringify(d.command), "utf8") > 65536 || !d.command.every(s => !/[\u0000-\u001f\u007f-\u009f]|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u.test(s))) return false;
+        let expectedTarget = r.branch.trim();
+        if (!norm(r.branch).startsWith("/")) {
+            const parent = p.basis === "status" ? p.observedBranch : r.parent;
+            if (!parent || !["status", "explicit"].includes(p.basis)) return false;
+            const normalizedParent = norm(parent).replace(/\/$/, "");
+            if (!normalizedParent.startsWith("/") || normalizedParent === "/") return false;
+            expectedTarget = normalizedParent + "/" + norm(r.branch);
+        } else if (norm(r.branch).split("/").filter(Boolean).length === 1 && !r.allowRootBranch) return false;
+        if (d.resolvedTarget !== expectedTarget) return false;
+        const expected = ["branch", "create", expectedTarget];
+        if (r.changeset) expected.push(`--changeset=${r.changeset}`);
+        if (r.label) expected.push(`--label=${r.label}`);
+        if (r.comment) expected.push(`-c=${r.comment}`);
+        if (r.commentsFile) expected.push(`-commentsfile=${r.commentsFile}`);
+        if (JSON.stringify(expected) !== JSON.stringify(d.command)) return false;
+    } else if (d.resolvedTarget !== null || !["not-attempted", "unknown"].includes(a.state) || d.capture) return false;
+    if (dto.outcome === "command-completed" && (!d.command || !d.capture?.complete || d.capture.stderrBytes || a.state !== "started" || a.terminal !== "observed" || a.exitCode !== 0 || a.aborted || a.timedOut)) return false;
+    if (dto.outcome === "uncertain" && !["started", "unknown"].includes(a.state)) return false;
+    if (["failed", "unsupported"].includes(dto.outcome) && !["not-attempted", "not-started"].includes(a.state)) return false;
+    const lastCapture = d.capture ?? d.parentCommands.at(-1)?.capture;
+    if (dto.completeness.capture !== (lastCapture ? lastCapture.complete ? "complete" : "incomplete" : "unknown")) return false;
+    return true;
+}
+export async function executeBranchCreateOutput(args: unknown) {
+    let dto = await assembleBranchCreateReceipt(args);
+    const valid: boolean = validateBranchCreateOutput(dto);
+    if (!valid) {
+        const mayHaveStarted = !["not-attempted", "not-started"].includes(dto.data.attempt.state);
+        const safe = await assembleBranchCreateReceipt({});
+        dto = { ...safe, ok: false, outcome: mayHaveStarted ? "uncertain" : "failed", data: { ...safe.data, attempt: { ...safe.data.attempt, state: mayHaveStarted ? "unknown" : "not-attempted" }, effect: mayHaveStarted ? "uncertain" : "not-attempted" }, error: { code: "producer_failed", stage: "producer", message: "Branch creation receipt could not be validated; do not retry automatically." } } as BranchCreateReceipt;
+        if (!validateBranchCreateOutput(dto)) throw new Error("Safe branch creation receipt could not be constructed.");
+    }
+    return { content: [{ type: "text" as const, text: presentBranchCreateReceipt(dto) }], details: {}, structuredContent: dto, isError: !dto.ok };
+}

package/src/pi/branch-delete-output.ts

@@ -0,0 +1,46 @@
+import { Type } from "typebox";
+import { Check } from "typebox/value";
+import { assembleBranchDeleteReceipt, branchDeleteArgv, branchDeleteFailure, emptyBranchDeleteData, presentBranchDeleteReceipt, safeBranchDeleteText, validBranchDeleteOperand, type BranchDeleteReceipt } from "../operations/branch-delete-receipt";
+const obj=(p:Record<string,any>)=>Type.Object(p,{additionalProperties:false}),enm=(v:string[])=>Type.Union(v.map(x=>Type.Literal(x))),nil=(s:any)=>Type.Union([s,Type.Null()]),uint=(max=Number.MAX_SAFE_INTEGER)=>Type.Integer({minimum:0,maximum:max}),text=Type.String({minLength:1,maxLength:4096});
+const attempt=obj({state:enm(["not-attempted","not-started","started","unknown"]),terminal:enm(["not-observed","observed"]),exitCode:nil(uint(2147483647)),aborted:Type.Boolean(),timedOut:Type.Boolean()});
+const capture=obj({stdoutBytes:uint(),stderrBytes:uint(),stdoutRetainedBytes:uint(65536),stderrRetainedBytes:uint(16384),truncated:Type.Boolean(),complete:Type.Boolean(),validUtf8:Type.Boolean()});
+const data={intendedArgv:Type.Array(text,{minItems:2,maxItems:4}),requestedBranch:nil(text),workingDirectory:nil(text),deleteChangesetsRequested:nil(Type.Boolean()),previewRequested:nil(Type.Boolean()),outputFormatRequested:nil(enm(["text","json"])),attempt,capture:nil(capture),observedDeletedBranch:Type.Null(),observedDeletedChangesets:Type.Null(),observedRepositoryIdentity:Type.Null(),observedWorkspaceIdentity:Type.Null(),verification:Type.Literal("unverified"),rollback:Type.Literal("not-proven")};
+const header={schemaVersion:Type.Literal(1),action:Type.Literal("branch-delete"),provenance:obj({source:Type.Literal("plastic"),producer:Type.Literal("@aefree/pi-plastic"),contentTrust:Type.Literal("external")}),completeness:obj({capture:enm(["complete","incomplete","unknown"]),projection:Type.Literal(true)})};
+const error=obj({code:enm(["invalid_request","launch_failed","aborted","uncertain","producer_failed"]),message:Type.String({minLength:1,maxLength:256})});
+export const branchDeleteOutputSchema=Type.Unsafe<BranchDeleteReceipt>(Type.Union([
+ obj({...header,ok:Type.Literal(true),outcome:Type.Literal("preflight"),data:obj({...data,effect:Type.Literal("not-attempted")})}),
+ obj({...header,ok:Type.Literal(true),outcome:Type.Literal("command-completed"),data:obj({...data,effect:Type.Literal("not-proven")})}),
+ obj({...header,ok:Type.Literal(false),outcome:Type.Literal("failed"),data:obj({...data,effect:Type.Literal("not-attempted")}),error}),
+ obj({...header,ok:Type.Literal(false),outcome:Type.Literal("uncertain"),data:obj({...data,effect:Type.Literal("uncertain")}),error})
+]));
+export function validateBranchDeleteOutput(v:unknown):v is BranchDeleteReceipt {
+ if(!Check(branchDeleteOutputSchema,v)||Buffer.byteLength(JSON.stringify(v),"utf8")>131072)return false;
+ const dto=v as BranchDeleteReceipt,d=dto.data,a=d.attempt,c=d.capture;
+ if(d.requestedBranch===null){
+  if(JSON.stringify(d.intendedArgv)!==JSON.stringify(["branch","delete"])||[d.workingDirectory,d.deleteChangesetsRequested,d.previewRequested,d.outputFormatRequested].some(x=>x!==null)||c||a.terminal!=="not-observed"||a.exitCode!==null||a.aborted||a.timedOut||!["not-attempted","unknown"].includes(a.state))return false;
+ }else{
+  if(!validBranchDeleteOperand(d.requestedBranch)||!safeBranchDeleteText(d.workingDirectory)||typeof d.deleteChangesetsRequested!=="boolean"||typeof d.previewRequested!=="boolean"||d.outputFormatRequested===null||JSON.stringify(d.intendedArgv)!==JSON.stringify(branchDeleteArgv(d.requestedBranch,d.deleteChangesetsRequested)))return false;
+ }
+ if(a.exitCode!==null&&a.terminal!=="observed"||["not-attempted","not-started"].includes(a.state)&&(a.terminal!=="not-observed"||a.exitCode!==null)||a.state==="not-attempted"&&a.timedOut)return false;
+ if(c){
+  if(d.requestedBranch===null||c.stdoutRetainedBytes>c.stdoutBytes||c.stderrRetainedBytes>c.stderrBytes)return false;
+  if(c.complete&&(!c.validUtf8||c.truncated||c.stdoutBytes!==c.stdoutRetainedBytes||c.stderrBytes!==c.stderrRetainedBytes||a.state!=="started"||a.terminal!=="observed"||a.exitCode===null||a.aborted||a.timedOut))return false;
+  if(a.state==="not-attempted"&&(!a.aborted||c.stdoutBytes||c.stderrBytes||c.validUtf8||c.complete))return false;
+ }
+ if(dto.completeness.capture!==(c?c.complete?"complete":"incomplete":"unknown"))return false;
+ if(d.previewRequested===true&&(!dto.ok||dto.outcome!=="preflight"||d.requestedBranch===null||c||a.state!=="not-attempted"||a.terminal!=="not-observed"||a.exitCode!==null||a.aborted||a.timedOut))return false;
+ if(dto.ok&&dto.outcome==="preflight"&&(d.previewRequested!==true||d.requestedBranch===null))return false;
+ if(dto.ok&&dto.outcome==="command-completed"&&(d.previewRequested!==false||d.requestedBranch===null||!c?.complete||a.state!=="started"||a.exitCode!==0))return false;
+ if(!dto.ok){
+  if(!safeBranchDeleteText(dto.error.message))return false;
+  if(dto.outcome==="uncertain"&&!["started","unknown"].includes(a.state)||dto.outcome==="failed"&&!["not-attempted","not-started"].includes(a.state))return false;
+  if(dto.error.code==="invalid_request"&&(d.requestedBranch!==null||c||a.state!=="not-attempted"||a.aborted))return false;
+  if(dto.error.code==="aborted"&&!a.aborted||dto.error.code==="launch_failed"&&!["not-attempted","not-started"].includes(a.state))return false;
+ }
+ return true;
+}
+export async function executeBranchDeleteOutput(args:unknown) {
+ let dto=await assembleBranchDeleteReceipt(args);const valid:boolean=validateBranchDeleteOutput(dto);
+ if(!valid){const possible=["started","unknown"].includes(dto.data.attempt.state),d=emptyBranchDeleteData();if(possible){d.attempt.state="unknown";d.effect="uncertain";}dto=branchDeleteFailure(d,"producer_failed","Branch-delete receipt validation failed; effects remain possible, no automatic retry.");if(!validateBranchDeleteOutput(dto))throw Error("Safe branch-delete receipt unavailable.");}
+ return {content:[{type:"text" as const,text:presentBranchDeleteReceipt(dto)}],details:{},structuredContent:dto,isError:!dto.ok};
+}

package/src/pi/branch-list-output.ts

@@ -0,0 +1,59 @@
+import { Type, type Static, type TSchema } from "typebox";
+import { Check } from "typebox/value";
+import { assembleBranchListObservation, presentBranchListObservation, branchListPayload, BranchListError, validBranchListIdentity, validBranchQueryString, type BranchListArgs, BRANCH_LIST_MAX_BYTES } from "../operations/branch-list";
+import { getActiveAbortSignal } from "../execution/context";
+import { BranchListCommandError } from "../execution/branch-list-command";
+
+const object = <T extends Record<string, TSchema>>(fields: T) => Type.Object(fields, { additionalProperties: false });
+const nullable = <T extends TSchema>(schema: T) => Type.Union([schema, Type.Null()]);
+const integer = (maximum = Number.MAX_SAFE_INTEGER) => Type.Integer({ minimum: 0, maximum });
+const queryString = nullable(Type.String({ maxLength: 4096, pattern: "^[^\\u0000-\\u001f\\u007f-\\u009f]*$" }));
+const identity = Type.Intersect([
+    Type.String({ minLength: 1, maxLength: 4096, pattern: process.platform === "win32" ? "^[^\\u0000-\\u001f\\u007f-\\u009f\\uFFFD?]+$" : "^[^\\u0000-\\u001f\\u007f-\\u009f\\uFFFD]+$" }),
+    Type.String({ pattern: "^/[^/@\\\\]+(?:/[^/@\\\\]+)*$" }),
+]);
+const query = object({ nameLike: queryString, parent: queryString, owner: queryString, includeHidden: Type.Boolean(), orderBy: nullable(Type.Union([Type.Literal("date"), Type.Literal("branchname")])), descending: Type.Boolean(), limit: nullable(Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER })) });
+const limits = object({ maxItems: Type.Integer({ minimum: 1, maximum: 500 }), identityCodeUnits: Type.Literal(4096), compactUtf8Bytes: Type.Literal(131072) });
+const provenance = { source: "plastic", producer: "@aefree/pi-plastic", contentTrust: "external" } as const;
+const common = { schemaVersion: Type.Literal(1), action: Type.Literal("branch-list"), provenance: object({ source: Type.Literal("plastic"), producer: Type.Literal("@aefree/pi-plastic"), contentTrust: Type.Literal("external") }) };
+const dataCommon = { scope: Type.Literal("workspace_repository"), qualifierVerified: Type.Literal(false), query, limits };
+const errorCode = Type.Union([Type.Literal("command_failed"), Type.Literal("aborted"), Type.Literal("capture_incomplete"), Type.Literal("malformed_output"), Type.Literal("invalid_identity"), Type.Literal("unsupported_query"), Type.Literal("invalid_producer_data"), Type.Literal("output_overflow")]);
+export const branchListOutputSchema = Type.Union([
+    object({ ...common, ok: Type.Literal(true), completeness: object({ read: Type.Literal("complete"), capture: Type.Literal("complete"), projection: Type.Boolean() }), data: object({ ...dataCommon, mode: Type.Literal("names"), basis: Type.Literal("find_branch_name_utf8"), rows: Type.Array(object({ branch: identity }), { maxItems: 500 }), countBasis: Type.Literal("observed_query_rows"), counts: object({ observed: integer(20000), returned: integer(500), omitted: integer(20000), excluded: Type.Literal(0) }) }) }),
+    object({ ...common, ok: Type.Literal(true), completeness: object({ read: Type.Literal("unknown"), capture: Type.Literal("unknown"), projection: Type.Literal(false) }), data: object({ ...dataCommon, mode: Type.Literal("native"), basis: Type.Literal("find_branch_native"), rows: Type.Null(), countBasis: Type.Literal("unavailable"), counts: Type.Null() }) }),
+    object({ ...common, ok: Type.Literal(false), completeness: object({ read: Type.Literal("incomplete"), capture: Type.Literal("unknown"), projection: Type.Literal(false) }), error: object({ code: errorCode, message: Type.String({ minLength: 1, maxLength: 256 }) }) }),
+]);
+export type BranchListOutput = Static<typeof branchListOutputSchema>;
+export type BranchListErrorCode = Extract<BranchListOutput, { ok: false }>["error"]["code"];
+const failure = (code: BranchListErrorCode): BranchListOutput => ({ schemaVersion: 1, action: "branch-list", provenance, ok: false, completeness: { read: "incomplete", capture: "unknown", projection: false }, error: { code, message: `Branch list read failed (${code}); no reusable rows are available.` } });
+export function validateBranchListOutput(value: unknown): BranchListOutput {
+    if (!Check(branchListOutputSchema, value)) return failure("invalid_producer_data");
+    const dto = value as BranchListOutput;
+    if (dto.ok) {
+        if ([dto.data.query.nameLike, dto.data.query.parent, dto.data.query.owner].some(value => value !== null && !validBranchQueryString(value))) return failure("invalid_producer_data");
+        if (dto.data.mode === "names") {
+            const { counts, rows, limits, query } = dto.data;
+            if (query.includeHidden || rows.some(row => !validBranchListIdentity(row.branch)) || new Set(rows.map(row => row.branch)).size !== rows.length
+                || counts.returned !== rows.length || counts.observed !== counts.returned + counts.omitted
+                || counts.returned !== Math.min(counts.observed, limits.maxItems)
+                || (query.limit !== null && counts.observed > query.limit)
+                || dto.completeness.projection !== (counts.omitted === 0)) return failure("invalid_producer_data");
+        }
+    }
+    if (Buffer.byteLength(JSON.stringify(dto), "utf8") > BRANCH_LIST_MAX_BYTES) return failure("output_overflow");
+    return dto;
+}
+export async function executeBranchListOutput(args: BranchListArgs) {
+    let dto: BranchListOutput;
+    let rawResult: string | undefined;
+    try {
+        const observation = await assembleBranchListObservation(args, true);
+        if (getActiveAbortSignal()?.aborted) throw new BranchListCommandError("aborted");
+        dto = validateBranchListOutput(branchListPayload(observation));
+        if (dto.ok) rawResult = args.format === "json" ? JSON.stringify(dto) : presentBranchListObservation(observation);
+    } catch (error) {
+        dto = failure(error instanceof BranchListError || error instanceof BranchListCommandError ? error.code : "invalid_producer_data");
+    }
+    dto = validateBranchListOutput(dto);
+    return { content: [{ type: "text" as const, text: dto.ok ? rawResult! : dto.error.message }], structuredContent: dto, isError: !dto.ok, details: { exportName: "branchList", rawResult: dto.ok ? rawResult : undefined, ...(args.workdir ? { workdir: args.workdir } : {}) } };
+}

package/src/pi/branch-output.ts

@@ -0,0 +1,63 @@
+import { Type, type Static, type TSchema } from "typebox";
+import { Check } from "typebox/value";
+import { assembleCurrentBranchObservation, assembleBranchExistsObservation, presentCurrentBranchObservation, presentBranchExistsObservation, BranchReadError, validBranchIdentity, type BranchReadObservation } from "../operations/branch-reads";
+
+export const BRANCH_OUTPUT_MAX_BYTES = 16384;
+const object = <T extends Record<string, TSchema>>(fields: T) => Type.Object(fields, { additionalProperties: false });
+const identity = Type.String({ minLength: 1, maxLength: 4096, pattern: process.platform === "win32" ? "^[^\\u0000-\\u001f\\u007f-\\u009f\\uFFFD?]+$" : "^[^\\u0000-\\u001f\\u007f-\\u009f\\uFFFD]+$" });
+const observedPath = Type.Intersect([identity, Type.String({ pattern: "^/[^/@\\\\]+(?:/[^/@\\\\]+)*$" })]);
+const provenance = { source: "plastic", producer: "@aefree/pi-plastic", contentTrust: "external" } as const;
+const provenanceSchema = object({ source: Type.Literal("plastic"), producer: Type.Literal("@aefree/pi-plastic"), contentTrust: Type.Literal("external") });
+const errorSchema = object({ code: Type.Union([Type.Literal("command_failed"), Type.Literal("aborted"), Type.Literal("capture_incomplete"), Type.Literal("invalid_identity"), Type.Literal("malformed_output"), Type.Literal("invalid_producer_data"), Type.Literal("output_overflow")]), message: Type.String({ minLength: 1, maxLength: 256 }) });
+const completeness = (success: boolean) => object({ read: Type.Literal(success ? "complete" : "incomplete"), capture: Type.Literal(success ? "complete" : "unknown"), projection: Type.Literal(success) });
+const common = <A extends string>(action: A) => ({ schemaVersion: Type.Literal(1), action: Type.Literal(action), provenance: provenanceSchema });
+export const currentBranchOutputSchema = Type.Union([
+    object({ ...common("current-branch"), ok: Type.Literal(true), completeness: completeness(true), data: object({ branch: observedPath, basis: Type.Union([Type.Literal("status"), Type.Literal("compact_status"), Type.Literal("changeset_lookup")]), scope: Type.Literal("workspace") }) }),
+    object({ ...common("current-branch"), ok: Type.Literal(false), completeness: completeness(false), error: errorSchema }),
+]);
+export const branchExistsOutputSchema = Type.Union([
+    object({ ...common("branch-exists"), ok: Type.Literal(true), completeness: completeness(true), data: object({ requestedBranch: identity, comparisonBranch: identity, scope: Type.Literal("workspace_repository"), qualifierVerified: Type.Optional(Type.Literal(false)), exists: Type.Boolean() }) }),
+    object({ ...common("branch-exists"), ok: Type.Literal(false), completeness: completeness(false), error: errorSchema }),
+]);
+export type CurrentBranchOutput = Static<typeof currentBranchOutputSchema>;
+export type BranchExistsOutput = Static<typeof branchExistsOutputSchema>;
+export type BranchOutput = CurrentBranchOutput | BranchExistsOutput;
+type Action = BranchOutput["action"];
+const failure = (action: Action, code: Extract<BranchOutput, { ok: false }>["error"]["code"], message: string): BranchOutput => ({ schemaVersion: 1, action, provenance, ok: false, completeness: { read: "incomplete", capture: "unknown", projection: false }, error: { code, message } });
+export function validateBranchOutput(action: Action, value: unknown): BranchOutput {
+    if (!Check(action === "current-branch" ? currentBranchOutputSchema : branchExistsOutputSchema, value)) return failure(action, "invalid_producer_data", "Branch producer data did not match the output contract.");
+    const dto = value as BranchOutput;
+    if (dto.ok) {
+        const identities = dto.action === "current-branch" ? [dto.data.branch] : [dto.data.requestedBranch, dto.data.comparisonBranch];
+        if (identities.some(identity => !validBranchIdentity(identity))) return failure(action, "invalid_producer_data", "Branch producer identity was invalid or lossy.");
+    }
+    if (Buffer.byteLength(JSON.stringify(value), "utf8") > BRANCH_OUTPUT_MAX_BYTES) return failure(action, "output_overflow", "Branch output exceeded the compact UTF-8 byte limit.");
+    return value as BranchOutput;
+}
+export function projectBranchOutput(observation: BranchReadObservation): BranchOutput {
+    const { action, ...data } = observation;
+    return validateBranchOutput(action, { schemaVersion: 1, action, provenance, ok: true, completeness: { read: "complete", capture: "complete", projection: true }, data });
+}
+export async function executeBranchOutput(exportName: "currentBranch" | "branchExists", args: { branch?: string; format?: "text" | "json"; workdir?: string }) {
+    const action = exportName === "currentBranch" ? "current-branch" : "branch-exists";
+    let dto: BranchOutput;
+    let rawResult: string | undefined;
+    try {
+        if (exportName === "currentBranch") {
+            const observation = await assembleCurrentBranchObservation(args);
+            dto = projectBranchOutput(observation);
+            if (dto.ok) rawResult = await presentCurrentBranchObservation(observation, args);
+        } else {
+            if (typeof args.branch !== "string") throw new BranchReadError("invalid_identity");
+            const observation = await assembleBranchExistsObservation({ ...args, branch: args.branch });
+            dto = projectBranchOutput(observation);
+            if (dto.ok) rawResult = presentBranchExistsObservation(observation);
+        }
+    } catch (error) {
+        dto = failure(action, error instanceof BranchReadError ? error.code : "invalid_producer_data", error instanceof BranchReadError ? error.message : "Branch producer failed to produce valid data.");
+    }
+    // Validate even failures immediately before return.
+    dto = validateBranchOutput(action, dto);
+    return { content: [{ type: "text" as const, text: !dto.ok ? dto.error.message : dto.action === "current-branch" ? dto.data.branch : `${dto.data.exists} (workspace repository path comparison${dto.data.qualifierVerified === false ? "; requested repository qualifier NOT verified" : ""}).` }], structuredContent: dto, isError: !dto.ok,
+        details: { exportName, rawResult, ...(args.workdir ? { workdir: args.workdir } : {}) } };
+}

package/src/pi/capability-diagnostics.ts

@@ -0,0 +1,23 @@
+import { getPatchBackendCapabilityWarning } from "../operations/patch";
+
+export type CapabilityDiagnosticContext = {
+  hasUI?: boolean;
+  ui?: { notify?: (message: string, level: "warning") => void };
+};
+
+type PatchCapabilityWarningGetter = () => Promise<string | undefined>;
+
+export const __plasticCapabilityDiagnosticInternals = {
+  createPatchCapabilityWarningNotifier(getWarning: PatchCapabilityWarningGetter = () => getPatchBackendCapabilityWarning()) {
+    let emitted = false;
+    return async (ctx: CapabilityDiagnosticContext): Promise<void> => {
+      if (emitted || !ctx.hasUI || typeof ctx.ui?.notify !== "function") return;
+      const warning = await getWarning();
+      if (!warning) return;
+      emitted = true;
+      ctx.ui.notify(warning, "warning");
+    };
+  },
+};
+
+export const notifyPatchCapabilityWarning = __plasticCapabilityDiagnosticInternals.createPatchCapabilityWarningNotifier();