@aefree/pi-plastic 0.7.6 → 0.8.1

package/src/operations/removal-receipt.ts

@@ -0,0 +1,42 @@
+import { captureRemovalCommand, emptyRemovalAttempt } from "../execution/removal-command";
+import { REMOVAL_COMMAND, safeRemovalText, validRemovalOperands, type RemovalData, type RemovalError, type RemovalReceipt } from "../domain/removal-contract";
+export { REMOVAL_COMMAND, safeRemovalText, validRemovalOperands } from "../domain/removal-contract";
+export type { RemovalData, RemovalError, RemovalReceipt, RemovalAttempt, RemovalCapture } from "../domain/removal-contract";
+export { presentRemovalReceipt } from "../presentation/removal-results";
+export function emptyRemovalData(): RemovalData {
+    return { intendedArgv: [REMOVAL_COMMAND], requestedOperandCount: null, workingDirectory: null, keepOnDiskRequested: null, previewRequested: null, outputFormatRequested: null, resolutionIntent: "accept-source-deletion", attempt: emptyRemovalAttempt(), capture: null, observedWorkspaceIdentity: null, observedResolvedItems: null, observedResolution: null, observedPreservation: null, observedPendingState: null, verification: "unverified", effect: "not-attempted" };
+}
+function removalHeader(data: RemovalData) {
+    return { schemaVersion: 1 as const, action: "resolve-delete-change-conflict" as const, 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 removalFailure(data: RemovalData, code: RemovalError["code"], message: string): RemovalReceipt {
+    return { ...removalHeader(data), ok: false, outcome: data.effect === "uncertain" ? "uncertain" : "failed", error: { code, message } };
+}
+export async function assembleRemovalReceipt(args: unknown): Promise<RemovalReceipt> {
+    const data = emptyRemovalData(); let dispatched = false;
+    try {
+        if (!args || typeof args !== "object" || Array.isArray(args) || Object.keys(args).some(key => !["paths", "workdir", "keepOnDisk", "preflight", "format"].includes(key))) return removalFailure(data, "invalid_request", "Removal accepts paths, workdir, keepOnDisk, preflight and text/json format only.");
+        const input = args as Record<string, unknown>;
+        const cwd = input.workdir === undefined ? process.cwd() : input.workdir;
+        const keep = input.keepOnDisk === undefined ? true : input.keepOnDisk;
+        const preview = input.preflight === undefined ? false : input.preflight;
+        const format = input.format === undefined ? "text" : input.format;
+        const paths = Array.isArray(input.paths) && input.paths.length <= 256 ? Array.from(input.paths) : input.paths;
+        if (!safeRemovalText(cwd) || !validRemovalOperands(paths) || typeof keep !== "boolean" || typeof preview !== "boolean" || !["text", "json"].includes(format as string)) return removalFailure(data, "invalid_request", "Use bounded path operands, strict booleans and text/json format; flags, stdin and bare private/controlled modes are rejected.");
+        data.workingDirectory = cwd; data.intendedArgv = [REMOVAL_COMMAND, ...(keep ? ["--nodisk"] : []), ...paths]; data.requestedOperandCount = paths.length;
+        data.keepOnDiskRequested = keep; data.previewRequested = preview; data.outputFormatRequested = format as "text" | "json";
+        if (preview) return { ...removalHeader(data), ok: true, outcome: "preflight" };
+        dispatched = true;
+        const observation = await captureRemovalCommand([...data.intendedArgv], cwd);
+        data.attempt = observation.attempt; data.capture = observation.capture;
+        if (observation.capture.complete && !observation.failed && observation.attempt.state === "started" && observation.attempt.exitCode === 0) {
+            data.effect = "not-proven";
+            return { ...removalHeader(data), ok: true, outcome: "command-completed" };
+        }
+        data.effect = ["started", "unknown"].includes(data.attempt.state) ? "uncertain" : "not-attempted";
+        return removalFailure(data, data.attempt.aborted ? "aborted" : data.effect === "uncertain" ? "uncertain" : "launch_failed", data.effect === "uncertain" ? "Removal completion is not proven; partial removal or workspace/disk effects may exist." : "Removal did not establish a process start.");
+    } catch {
+        if (dispatched) { data.attempt = { ...emptyRemovalAttempt(), state: "unknown" }; data.capture = null; data.effect = "uncertain"; }
+        return removalFailure(data, "producer_failed", "Removal observation failed; no rollback or safe retry is proven.");
+    }
+}

package/src/operations/reviews.ts

@@ -0,0 +1,90 @@
+import { tool } from "../tool-definition";
+import { workdirArg } from "./arguments";
+import { assembleObjectWriteReceipt, presentObjectWriteReceipt } from "./object-write-receipt";
+import { outputFormatArg } from "../presentation/results";
+import { executeCodeReviewFind } from "./code-review-find";
+import { assembleObjectDeleteReceipt, presentObjectDeleteReceipt } from "./object-delete-receipt";
+
+export const codeReviewCreate = tool({
+    description: "Create a code review (cm codereview).",
+    args: {
+        target: tool.schema.string().min(1).describe("Review target spec (branch, changeset, or shelveset spec)."),
+        title: tool.schema.string().min(1).describe("Code review title."),
+        status: tool.schema.string().optional().describe("Initial review status."),
+        assignee: tool.schema.string().optional().describe("Initial review assignee."),
+        repository: tool.schema.string().optional().describe("Repository specification when no workspace is used."),
+        format: tool.schema.string().optional().describe("Format string for creation output."),
+        preflight: tool.schema.boolean().optional().describe("Command-only zero-CLI preview; no existence/conflict/state analysis."),
+        output: outputFormatArg,
+        workdir: workdirArg,
+    },
+    async execute(args) {
+        const dto = await assembleObjectWriteReceipt("code-review-create", Object.freeze({...args}));
+        const result = presentObjectWriteReceipt(dto);
+        if (!dto.ok) throw new Error(result);
+        return result;
+    },
+});
+
+export const codeReviewUpdate = tool({
+    description: "Update an existing code review (cm codereview -e).",
+    args: {
+        id: tool.schema.string().min(1).describe("Code review id or GUID."),
+        status: tool.schema.string().optional().describe("Updated review status."),
+        assignee: tool.schema.string().optional().describe("Updated review assignee."),
+        repository: tool.schema.string().optional().describe("Repository specification when no workspace is used."),
+        preflight: tool.schema.boolean().optional().describe("Command-only zero-CLI preview; no existence/conflict/state analysis."),
+        output: outputFormatArg,
+        workdir: workdirArg,
+    },
+    async execute(args) {
+        const dto = await assembleObjectWriteReceipt("code-review-update", Object.freeze({...args}));
+        const result = presentObjectWriteReceipt(dto);
+        if (!dto.ok) throw new Error(result);
+        return result;
+    },
+});
+
+export const codeReviewDelete = tool({
+    description: "Delete one or more code reviews (cm codereview -d).",
+    args: {
+        ids: tool.schema.array(tool.schema.string()).min(1).describe("Code review IDs or GUIDs to delete."),
+        repository: tool.schema.string().optional().describe("Repository specification when no workspace is used."),
+        preflight: tool.schema.boolean().optional().describe("Command-only zero-CLI preview; no existence/readiness analysis."),
+        format: outputFormatArg,
+        workdir: workdirArg,
+    },
+    async execute(args)
+    {
+        const request = Object.freeze({...args});
+        const dto = await assembleObjectDeleteReceipt("code-review-delete",request);
+        const result = presentObjectDeleteReceipt(dto);
+        if (!dto.ok && request.preflight !== true) throw new Error(result);
+        return result;
+    },
+});
+
+export const codeReviewFind = tool({
+    description: "Find code reviews with filters using cm find review.",
+    args: {
+        status: tool.schema.string().optional().describe("Filter by review status."),
+        assignee: tool.schema.string().optional().describe("Filter by review assignee."),
+        owner: tool.schema.string().optional().describe("Filter by review owner."),
+        target: tool.schema.string().optional().describe("Filter by review target branch/changeset spec."),
+        targetType: tool.schema.enum(["branch", "changeset"]).optional().describe("Filter by review target type."),
+        titleLike: tool.schema.string().optional().describe("Filter by title pattern (supports % wildcard)."),
+        source: tool.schema.enum(["native", "ids"]).optional().describe("Native output (default) or one canonical review-ID query."),
+        maxItems: tool.schema.number().int().min(1).max(500).optional().describe("Projected record cap (default 100); separate from CLI limit."),
+        limit: tool.schema.number().int().min(1).optional().describe("Maximum number of reviews to return."),
+        orderBy: tool.schema.enum(["date", "modifieddate", "status"]).optional().describe("Sort field for review queries."),
+        descending: tool.schema.boolean().optional().describe("Sort descending when true."),
+        format: tool.schema.string().optional().describe("Format string for query output."),
+        dateFormat: tool.schema.string().optional().describe("Date format for query output."),
+        output: outputFormatArg,
+        workdir: workdirArg,
+    },
+    async execute(args)
+    {
+        return executeCodeReviewFind(args);
+    },
+});

package/src/operations/server-merge.ts

@@ -0,0 +1,130 @@
+import { randomBytes } from "node:crypto";
+import { assertAbsoluteResolutionPath, inspectResolutionFile } from "../domain/server-merge-resolutions";
+import { getActiveAbortSignal } from "../execution/context";
+import { captureServerMergeCommand } from "../execution/server-merge-command";
+import { tool } from "../tool-definition";
+import { outputFormatArg, formatServerMergeResult } from "../presentation/results";
+import { parseServerMergeOutput } from "../domain/merge-output";
+import { emptyMergeAttempt, splitServerBranch, type MergeReceipt, type MergeReceiptData, type ServerMergeRequest } from "../domain/server-merge-contract";
+export { splitServerBranch };
+export type { MergeReceipt } from "../domain/server-merge-contract";
+export type QualifiedServerBranch = { raw: string; branch: string; repository: string; server: string };
+class ServerMergeInputError extends Error {}
+export const SERVER_MERGE_OUTPUT_LIMIT = 32768, SERVER_MERGE_HELP_TIMEOUT_MS = 3000, SERVER_MERGE_COMMAND_TIMEOUT_MS = 30000;
+export const serverMergeControlPattern = /[\u0000-\u001f\u007f-\u009f]|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+export const serverMergeCapabilityTokens = ["--to", "--merge", "--nointeractiveresolution", "--machinereadable", "--startlineseparator", "--endlineseparator", "--fieldseparator"];
+export function assertSafeServerMergeValue(name: string, value: string): string {
+    if (typeof value !== "string" || !value.trim() || value.length > 4096 || serverMergeControlPattern.test(value)) throw new ServerMergeInputError(`${name} must be non-empty, bounded and free of control/malformed characters.`);
+    return value.trim();
+}
+export function parseQualifiedServerBranch(name: string, value: string): QualifiedServerBranch {
+    const raw = assertSafeServerMergeValue(name, value), parts = splitServerBranch(raw);
+    if (!parts) throw new ServerMergeInputError(`${name} must use unambiguous fully qualified syntax 'br:/<branch>@<repository>@<server>'.`);
+    return { raw, ...parts };
+}
+export const createServerMergeSeparators = () => {
+    const n = randomBytes(16).toString("hex");
+    return { start: `__PI_PLASTIC_MERGE_START_${n}__`, end: `__PI_PLASTIC_MERGE_END_${n}__`, field: `__PI_PLASTIC_MERGE_FIELD_${n}__` };
+};
+export function validateServerMergeRequest(input: unknown): asserts input is ServerMergeRequest {
+    if (!input || typeof input !== "object" || Array.isArray(input)) throw new ServerMergeInputError("Merge input must be an object.");
+    const r = input as Record<string, unknown>;
+    if (Object.keys(r).some(k => !["source", "target", "message", "mode", "fileConflictsResolutionsFile", "unlistedConflictPolicy", "preflight", "format"].includes(k)) || r.preflight !== undefined && typeof r.preflight !== "boolean" || r.format !== undefined && r.format !== "text" && r.format !== "json" || r.mode !== undefined && r.mode !== "apply" && r.mode !== "analyze" || r.unlistedConflictPolicy !== undefined && r.unlistedConflictPolicy !== "source" && r.unlistedConflictPolicy !== "destination") throw new ServerMergeInputError("Merge input contains unsupported fields or options.");
+    if (r.mode === "analyze" && (r.message !== undefined || r.fileConflictsResolutionsFile !== undefined || r.unlistedConflictPolicy !== undefined)) throw new ServerMergeInputError("Analyze mode does not accept a message, resolutions file or conflict policy.");
+    if (r.fileConflictsResolutionsFile !== undefined) {
+        try { assertAbsoluteResolutionPath(r.fileConflictsResolutionsFile); }
+        catch { throw new ServerMergeInputError("fileConflictsResolutionsFile must be a bounded absolute local path."); }
+    }
+    const s = parseQualifiedServerBranch("source", r.source as string), t = parseQualifiedServerBranch("target", r.target as string);
+    if (r.mode !== "analyze") assertSafeServerMergeValue("message", r.message as string);
+    if (s.repository !== t.repository || s.server !== t.server) throw new ServerMergeInputError("source and target must identify the same exact repository and server.");
+    if (s.branch === t.branch) throw new ServerMergeInputError("source and target must identify different branches.");
+}
+export async function assembleServerMergeReceipt(input: unknown): Promise<MergeReceipt> {
+    const data: MergeReceiptData = { mode: "apply", resolutionsFile: null, unlistedConflictPolicy: null, requestedIdentity: null, command: null, capability: { state: "not-checked", missingTokens: [] }, attempt: emptyMergeAttempt(), capture: { help: null, merge: null }, parse: null, observedChangesets: [], conflictPaths: [], counts: { changesetsReturned: 0, changesetsOmitted: 0, conflictsReturned: 0, conflictsOmitted: 0 }, createdChangeset: null, effect: "not-attempted", serverAliasEquivalence: "unverified", mergeLinkIdentity: "unverified", xlinkEffects: "unverified", wouldRun: false, remoteAnalysis: "not-performed" };
+    const completeness: MergeReceipt["completeness"] = { capture: "unknown", projection: true };
+    const finish = (outcome: MergeReceipt["outcome"], stage: "input" | "help" | "merge" | "producer", code?: string, message = "The server merge evidence could not be verified."): MergeReceipt => {
+        data.effect = outcome === "completed" ? "changeset-created" : outcome === "no-op" ? "not-proven" : outcome === "conflict" || outcome === "uncertain" ? "uncertain" : "not-attempted";
+        const ok = ["preflight", "analyzed", "completed", "no-op"].includes(outcome);
+        const dto = { schemaVersion: 1, action: "merge-branches", provenance: { source: "plastic", producer: "@aefree/pi-plastic", contentTrust: "external" }, ok, outcome, completeness, data, ...(!ok ? { error: { code: code ?? outcome, stage, message } } : {}) } as MergeReceipt;
+        while (Buffer.byteLength(JSON.stringify(dto), "utf8") > 131072 && (data.conflictPaths.length || data.observedChangesets.length)) {
+            if (data.conflictPaths.length) { data.conflictPaths.pop(); data.counts.conflictsReturned--; data.counts.conflictsOmitted++; }
+            else { data.observedChangesets.pop(); data.counts.changesetsReturned--; data.counts.changesetsOmitted++; }
+            completeness.projection = false;
+        }
+        return dto;
+    };
+    let stage: "input" | "help" | "merge" = "input";
+    try {
+        validateServerMergeRequest(input);
+        const source = parseQualifiedServerBranch("source", input.source), target = parseQualifiedServerBranch("target", input.target);
+        data.mode = input.mode ?? "apply";
+        data.unlistedConflictPolicy = input.unlistedConflictPolicy ?? null;
+        if (input.fileConflictsResolutionsFile !== undefined) {
+            try { data.resolutionsFile = await inspectResolutionFile(input.fileConflictsResolutionsFile); }
+            catch (error) { throw new ServerMergeInputError(error instanceof Error && /^(Invalid resolution entry|Resolutions|Resolution)/.test(error.message) ? error.message : "Resolutions file or a result file is unavailable or invalid."); }
+        }
+        const seps = createServerMergeSeparators();
+        const command = ["merge", source.raw, `--to=${target.raw}`, ...(data.mode === "apply" ? ["--merge", `-c=${assertSafeServerMergeValue("message", input.message!)}`] : []), ...(data.resolutionsFile ? [`--fileconflictsresolutionsfile=${data.resolutionsFile.path}`] : []), ...(data.unlistedConflictPolicy ? [data.unlistedConflictPolicy === "source" ? "--keepsource" : "--keepdestination"] : []), "--nointeractiveresolution", "--machinereadable", `--startlineseparator=${seps.start}`, `--endlineseparator=${seps.end}`, `--fieldseparator=${seps.field}`];
+        data.requestedIdentity = { source: source.raw, target: target.raw, branch: target.branch, repository: target.repository, server: target.server }; data.command = ["cm", ...command]; data.wouldRun = true;
+        if (input.preflight) return finish("preflight", "input");
+        if (getActiveAbortSignal()?.aborted) { data.attempt.aborted = true; return finish("failed", "merge", "aborted"); }
+        stage = "help";
+        const help = await captureServerMergeCommand(["help", "merge"], SERVER_MERGE_HELP_TIMEOUT_MS); data.capture.help = help.capture;
+        if (!help.capture.complete || help.attempt.exitCode !== 0 || help.attempt.aborted || help.attempt.timedOut || help.capture.stderrBytes) { data.capability.state = "unavailable"; return finish("failed", "help", "capability_unavailable"); }
+        const requiredTokens = [...serverMergeCapabilityTokens, ...(data.resolutionsFile ? ["--fileconflictsresolutionsfile"] : []), ...(data.unlistedConflictPolicy ? [data.unlistedConflictPolicy === "source" ? "--keepsource" : "--keepdestination"] : [])];
+        data.capability.missingTokens = requiredTokens.filter(t => !help.stdout!.includes(t));
+        if (data.capability.missingTokens.length) { data.capability.state = "missing"; completeness.capture = "complete"; return finish("unsupported", "help", "unsupported"); }
+        data.capability.state = "advertised";
+        // Revalidate the JSON after help so edited instructions are not silently submitted.
+        // Result content is caller-owned; callers must keep all inputs immutable until cm exits.
+        if (data.resolutionsFile) {
+            try {
+                const current = await inspectResolutionFile(data.resolutionsFile.path);
+                if (current.sha256 !== data.resolutionsFile.sha256) throw new Error("changed");
+            } catch { return finish("failed", "input", "invalid_request", "Resolution inputs changed or became unavailable before merge dispatch."); }
+        }
+        stage = "merge";
+        const obs = await captureServerMergeCommand(command, SERVER_MERGE_COMMAND_TIMEOUT_MS); data.attempt = obs.attempt; data.capture.merge = obs.capture;
+        completeness.capture = obs.capture.complete ? "complete" : "incomplete";
+        if (obs.attempt.state === "not-attempted" || obs.attempt.state === "not-started") return finish("failed", "merge", obs.attempt.aborted ? "aborted" : "launch_failed");
+        const parsed = parseServerMergeOutput(obs.stdout ?? "", seps);
+        const paths = parsed.records.filter(r => r.operation === "FILE_CONFLICT" && r.fields.length === 6 && r.fields[1]!.length <= 4096 && !serverMergeControlPattern.test(r.fields[1]!)).map(r => r.fields[1]!);
+        data.parse = { records: parsed.records.length, malformed: parsed.malformed, unknownOperations: parsed.unknownOperations.length, changesetsObserved: parsed.changesets.length, conflictsObserved: paths.length };
+        // One aggregate evidence budget, not one budget per collection.
+        data.observedChangesets = parsed.changesets.slice(0, 100); data.conflictPaths = paths.slice(0, 100 - data.observedChangesets.length);
+        data.counts = { changesetsReturned: data.observedChangesets.length, changesetsOmitted: parsed.changesets.length - data.observedChangesets.length, conflictsReturned: data.conflictPaths.length, conflictsOmitted: paths.length - data.conflictPaths.length };
+        if (data.counts.changesetsOmitted || data.counts.conflictsOmitted) completeness.projection = false;
+        const matching = parsed.changesets.filter(c => c.branch === target.branch && c.repository === target.repository && c.mount === "/");
+        // Emitted server aliases are kept verbatim. Matching uses dispatch context,
+        // not an invented equivalence between requested and emitted server names.
+        const ambiguous = !obs.capture.complete || obs.failed || obs.attempt.aborted || obs.attempt.timedOut || obs.attempt.terminal !== "observed" || obs.attempt.exitCode === null || parsed.malformed || parsed.unknownOperations.length > 0 || parsed.changesets.length > 1 || parsed.changesets.length > 0 && matching.length !== 1 || parsed.hasConflict && parsed.changesets.length > 0 || parsed.isAlreadyConnected && (parsed.changesets.length > 0 || parsed.hasConflict);
+        if (data.mode === "analyze") {
+            if (!ambiguous && obs.attempt.exitCode === 0 && !obs.capture.stderrBytes && !parsed.changesets.length && parsed.records.length > 0) {
+                data.remoteAnalysis = "performed";
+                return finish("analyzed", "merge");
+            }
+            return finish("uncertain", "merge", "uncertain", "Server conflict analysis could not be verified; no applying command was requested.");
+        }
+        if (!ambiguous && obs.attempt.exitCode === 0 && !obs.capture.stderrBytes && matching.length === 1 && !parsed.hasConflict && !parsed.isAlreadyConnected) { data.createdChangeset = matching[0]!; return finish("completed", "merge"); }
+        if (!ambiguous && obs.attempt.exitCode === 0 && !obs.capture.stderrBytes && parsed.isAlreadyConnected && !parsed.changesets.length && !parsed.hasConflict) return finish("no-op", "merge");
+        if (!ambiguous && obs.attempt.exitCode !== 0 && parsed.hasConflict && !parsed.changesets.length) return finish("conflict", "merge", "conflict");
+        return finish("uncertain", "merge", "uncertain");
+    } catch (error) {
+        if (stage === "input") return finish("failed", "input", "invalid_request", error instanceof ServerMergeInputError ? error.message : "Invalid merge input.");
+        // Once merge collection is entered, an unexpected failure cannot prove nonstart.
+        if (stage === "merge") { if (data.attempt.state === "not-attempted") data.attempt.state = "unknown"; return finish("uncertain", "producer", "producer_failed"); }
+        data.capability.state = "unavailable"; return finish("failed", "help", "capability_unavailable");
+    }
+}
+export async function presentServerMergeReceipt(dto: MergeReceipt, format: "text" | "json" = "text"): Promise<string> {
+    const title = dto.outcome === "no-op" ? "No-op" : dto.outcome[0]!.toUpperCase() + dto.outcome.slice(1);
+    const text = dto.outcome === "preflight" ? `## Server Merge Preflight\n\n- Would run: yes\n- Remote analysis: not performed\n- Command argv: ${JSON.stringify(dto.data.command)}` : dto.outcome === "analyzed" ? `## Server Merge Analysis\n\n- Read-only: no applying merge requested\n- File conflicts observed: ${dto.data.parse?.conflictsObserved ?? "unknown"}\n${dto.data.conflictPaths.map(path => "- " + path).join("\n")}\n- Conflicts omitted: ${dto.data.counts.conflictsOmitted}\n- Point-in-time evidence only; no contributor content retrieved.` : `## Server Merge ${title}\n\n${dto.data.createdChangeset ? "- Created target changeset: cs:" + dto.data.createdChangeset.id + "\n" : ""}- Effect: ${dto.data.effect}\n- Server alias equivalence, merge-link identity and Xlink effects: unverified\n${dto.ok ? "" : "- Do not retry automatically; inspect server state if an attempt may have started."}`;
+    const rendered = await formatServerMergeResult(format, dto.outcome, text, dto.data);
+    return rendered.length <= 24000 ? rendered : JSON.stringify({ action: dto.action, outcome: dto.outcome, ok: dto.ok, note: "Presentation omitted; use the registered tool structuredContent for the bounded receipt." });
+}
+export const mergeBranches = tool({
+    description: "Inspect server merge conflicts with mode=analyze, then apply reviewed per-file JSON resolutions without a workspace or UI. Server aliases, merge links and Xlink effects remain unverified.",
+    args: { source: tool.schema.string().min(1).describe("Fully qualified source branch; branch/repository may not contain @; full server tail retained."), target: tool.schema.string().min(1).describe("Fully qualified distinct target in the same exact requested repository/server."), message: tool.schema.string().min(1).optional().describe("Required for apply; omit in analyze mode. Bounded nonempty comment, no editor fallback."), mode: tool.schema.enum(["apply", "analyze"]).optional().describe("Default apply creates a merge changeset. Analyze performs read-only remote conflict discovery without --merge; not command-only preflight."), fileConflictsResolutionsFile: tool.schema.string().min(1).optional().describe("Apply only: absolute existing UTF-8 JSON file with resolutions entries (exact conflict path plus keep or absolute readable resultFile). Inputs must remain immutable until completion."), unlistedConflictPolicy: tool.schema.enum(["source", "destination"]).optional().describe("Apply only: explicitly keep this contributor for conflicts absent from the JSON. Omit to retain noninteractive default behavior; never selected automatically."), preflight: tool.schema.boolean().optional().describe("Render intent only, zero commands; does not analyze remote conflicts."), format: outputFormatArg },
+    async execute(args) { const dto = await assembleServerMergeReceipt(args); if (!dto.ok && dto.error.stage === "input") throw new Error(dto.error.message); return presentServerMergeReceipt(dto, args.format); },
+});

package/src/operations/shelveset-list.ts

@@ -0,0 +1,90 @@
+import { cmWhereEquals, cmWhereLike, escapeCmWhereValue } from "../domain/branches";
+import { runCm } from "../execution/cm";
+import { spawnAndCollect, getCmExecutable } from "../execution/process";
+import { commandExecutionStorage, getActiveAbortSignal } from "../execution/context";
+import { runShelvesetListIdsCommand, ShelvesetListCommandError, SHELVESET_LIST_CAPTURE_LIMITS } from "../execution/shelveset-list-command";
+
+export type ShelvesetListArgs = { owner?: string; commentLike?: string; dateFrom?: string; limit?: number; format?: string; dateFormat?: string; source?: "native" | "ids"; output?: "text" | "json"; maxItems?: number; workdir?: string };
+export type ShelvesetListQuery = { owner: string | null; commentLike: string | null; dateFrom: string | null; limit: number | null };
+export class ShelvesetListError extends Error {
+    constructor(readonly code: "invalid_identity" | "malformed_output" | "unsupported_query" | "invalid_producer_data" | "output_overflow") { super(`Shelveset list read failed (${code}); no reusable rows are available.`); }
+}
+export const SHELVESET_LIST_MAX_BYTES = 131072;
+export const validShelvesetQueryString = (s: string) => s.length <= 4096 && !/[\u0000-\u001f\u007f-\u009f\uD800-\uDFFF]/u.test(s);
+export const validShelvesetTemplate = (s: string) => s.length <= 4096 && !/[\u0000\uD800-\uDFFF]/u.test(s);
+// Decimal strings retain exact integers beyond JavaScript's safe-number range.
+export const validShelvesetId = (s: string) => s.length <= 20 && /^(?:0|[1-9][0-9]*)$/.test(s);
+export function shelvesetListRequest(args: ShelvesetListArgs) {
+    for (const value of [args.owner, args.commentLike, args.dateFrom])
+        if (value !== undefined && (typeof value !== "string" || !validShelvesetQueryString(value))) throw new ShelvesetListError("invalid_identity");
+    for (const value of [args.format, args.dateFormat])
+        if (value !== undefined && (typeof value !== "string" || !validShelvesetTemplate(value))) throw new ShelvesetListError("invalid_producer_data");
+    if ((args.source !== undefined && args.source !== "native" && args.source !== "ids")
+        || (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 ShelvesetListError("invalid_producer_data");
+    const source = args.source ?? "native";
+    if (source === "ids" && (args.format || args.dateFormat)) throw new ShelvesetListError("unsupported_query");
+    return { source, maxItems: args.maxItems ?? 100, query: { owner: args.owner ?? null, commentLike: args.commentLike ?? null, dateFrom: args.dateFrom ?? null, limit: args.limit ?? null } };
+}
+export function shelvesetListCommand(args: ShelvesetListArgs): string[] {
+    const { source, query } = shelvesetListRequest(args);
+    const where: string[] = [];
+    if (query.owner) where.push(cmWhereEquals("owner", query.owner));
+    if (query.commentLike) where.push(cmWhereLike("comment", query.commentLike));
+    if (query.dateFrom) where.push(`date >= '${escapeCmWhereValue(query.dateFrom)}'`);
+    return ["find", "shelve", ...(where.length ? [`where ${where.join(" and ")}`] : []),
+        ...(query.limit ? [`limit ${query.limit}`] : []),
+        ...(source === "native" && args.format ? [`--format=${args.format}`] : []),
+        ...(source === "native" && args.dateFormat ? [`--dateformat=${args.dateFormat}`] : []),
+        "--nototal", ...(source === "ids" ? ["--format={shelveid}", "--encoding=utf-8"] : [])];
+}
+export function parseShelvesetListIds(bytes: Uint8Array): { ids: string[]; duplicateRecords: number } {
+    if (bytes.byteLength > SHELVESET_LIST_CAPTURE_LIMITS.stdoutBytes) throw new ShelvesetListCommandError("capture_incomplete");
+    if (bytes.some(byte => byte > 127)) throw new ShelvesetListError("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 > SHELVESET_LIST_CAPTURE_LIMITS.records) throw new ShelvesetListCommandError("capture_incomplete");
+    if (ids.some(id => !validShelvesetId(id))) throw new ShelvesetListError("invalid_identity");
+    return { ids, duplicateRecords: ids.length - new Set(ids).size };
+}
+export type ShelvesetListObservation = ReturnType<typeof shelvesetListRequest> & ({ source: "native"; rawResult: string } | { source: "ids"; ids: string[]; duplicateRecords: number });
+export async function assembleShelvesetListObservation(args: ShelvesetListArgs, typedNative = false): Promise<ShelvesetListObservation> {
+    const request = shelvesetListRequest(args), command = shelvesetListCommand(args);
+    if (request.source === "ids") {
+        const bytes = await runShelvesetListIdsCommand(command, args.workdir);
+        if (getActiveAbortSignal()?.aborted) throw new ShelvesetListCommandError("aborted");
+        const parsed = parseShelvesetListIds(bytes);
+        if (getActiveAbortSignal()?.aborted) throw new ShelvesetListCommandError("aborted");
+        return { ...request, source: "ids", ...parsed };
+    }
+    if (!typedNative) return { ...request, source: "native", rawResult: await runCm(command, args.workdir) };
+    const signal = getActiveAbortSignal();
+    if (signal?.aborted) throw new ShelvesetListCommandError("aborted");
+    let result;
+    try { result = await spawnAndCollect(getCmExecutable(), command, args.workdir ?? process.cwd(), undefined, signal, commandExecutionStorage.getStore()); }
+    catch { throw new ShelvesetListCommandError(signal?.aborted ? "aborted" : "command_failed"); }
+    if (result.aborted || signal?.aborted) throw new ShelvesetListCommandError("aborted");
+    if (result.timedOut || result.stdoutTruncated || result.stderrTruncated) throw new ShelvesetListCommandError("capture_incomplete");
+    if (result.exitCode !== 0) throw new ShelvesetListCommandError("command_failed");
+    return { ...request, source: "native", rawResult: [result.stdout, result.stderr].filter(Boolean).join("\n").trim() || "(no output)" };
+}
+export function shelvesetListPayload(observation: ShelvesetListObservation) {
+    const common = { schemaVersion: 1, action: "shelveset-list", 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: SHELVESET_LIST_MAX_BYTES } } as const;
+    const payload = observation.source === "native"
+        ? { ...common, completeness: { read: "unknown", capture: "unknown", projection: false }, data: { ...data, mode: "native", basis: "find_shelve_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_shelve_id_utf8", diagnostics: { duplicateRecords: observation.duplicateRecords }, rows: observation.ids.slice(0, observation.maxItems).map(id => ({ id, shelveset: `sh:${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") > SHELVESET_LIST_MAX_BYTES) throw new ShelvesetListError("output_overflow");
+    return payload;
+}
+export function presentShelvesetListObservation(observation: ShelvesetListObservation): string {
+    if (observation.source === "native") return observation.rawResult;
+    const ids = observation.ids.slice(0, observation.maxItems), omitted = observation.ids.length - ids.length;
+    return [...(ids.length ? ids.map(id => `sh:${id}`) : ["(no observed query rows)"]), ...(omitted ? [`(${omitted} observed query rows omitted from presentation.)`] : [])].join("\n");
+}
+export async function executeShelvesetList(args: ShelvesetListArgs): Promise<string> {
+    const observation = await assembleShelvesetListObservation(args);
+    return args.output === "json" ? JSON.stringify(shelvesetListPayload(observation)) : presentShelvesetListObservation(observation);
+}

package/src/operations/shelvesets.ts

@@ -0,0 +1,90 @@
+import { tool } from "../tool-definition";
+import { workdirArg } from "./arguments";
+import { assembleObjectWriteReceipt, presentObjectWriteReceipt } from "./object-write-receipt";
+import { executeShelvesetList } from "./shelveset-list";
+import { assembleObjectDeleteReceipt, presentObjectDeleteReceipt } from "./object-delete-receipt";
+import { outputFormatArg } from "../presentation/results";
+
+export const shelvesetCreate = tool({
+    description: "Create a shelveset (cm shelveset create).",
+    args: {
+        comment: tool.schema.string().optional().describe("Shelveset comment."),
+        commentsFile: tool.schema.string().optional().describe("File path containing shelveset comment."),
+        paths: tool.schema.array(tool.schema.string()).optional().describe("Optional item paths to shelve."),
+        all: tool.schema.boolean().optional().describe("Include changed, moved, and deleted items."),
+        dependencies: tool.schema.boolean().optional().describe("Include local change dependencies."),
+        summaryFormat: tool.schema.boolean().optional().describe("Print only created shelveset spec for automation."),
+        preflight: tool.schema.boolean().optional().describe("Command-only zero-CLI preview; no existence/conflict/state analysis."),
+        output: outputFormatArg,
+        workdir: workdirArg,
+    },
+    async execute(args) {
+        const dto = await assembleObjectWriteReceipt("shelveset-create", Object.freeze({...args}));
+        const result = presentObjectWriteReceipt(dto);
+        if (!dto.ok) throw new Error(result);
+        return result;
+    },
+});
+
+export const shelvesetApply = tool({
+    description: "Apply a shelveset (cm shelveset apply).",
+    args: {
+        shelveset: tool.schema.string().min(1).describe("Shelveset spec to apply (for example, sh:3)."),
+        changePaths: tool.schema.array(tool.schema.string()).optional().describe("Optional shelve server paths to apply."),
+        preview: tool.schema.boolean().optional().describe("Preview changes without applying them."),
+        dontCheckout: tool.schema.boolean().optional().describe("Keep applied changes as local modifications without checkout."),
+        comparisonMethod: tool.schema.enum([
+            "ignoreeol",
+            "ignorewhitespaces",
+            "ignoreeolandwhitespaces",
+            "recognizeall",
+        ]).optional().describe("Comparison method used when applying changes."),
+        preflight: tool.schema.boolean().optional().describe("Command-only zero-CLI preview; no existence/conflict/state analysis."),
+        output: outputFormatArg,
+        workdir: workdirArg,
+    },
+    async execute(args) {
+        const dto = await assembleObjectWriteReceipt("shelveset-apply", Object.freeze({...args}));
+        const result = presentObjectWriteReceipt(dto);
+        if (!dto.ok) throw new Error(result);
+        return result;
+    },
+});
+
+export const shelvesetDelete = tool({
+    description: "Delete a shelveset (cm shelveset delete).",
+    args: {
+        shelveset: tool.schema.string().min(1).describe("Shelveset spec to delete (for example, sh:3)."),
+        preflight: tool.schema.boolean().optional().describe("Command-only zero-CLI preview; no existence/readiness analysis."),
+        format: outputFormatArg,
+        workdir: workdirArg,
+    },
+    async execute(args)
+    {
+        const request = Object.freeze({...args});
+        const dto = await assembleObjectDeleteReceipt("shelveset-delete",request);
+        const result = presentObjectDeleteReceipt(dto);
+        if (!dto.ok && request.preflight !== true) throw new Error(result);
+        return result;
+    },
+});
+
+export const shelvesetList = tool({
+    description: "List shelvesets using cm find shelve.",
+    args: {
+        owner: tool.schema.string().optional().describe("Filter by shelveset owner."),
+        commentLike: tool.schema.string().optional().describe("Filter by shelveset comment pattern (supports % wildcard)."),
+        limit: tool.schema.number().int().min(1).optional().describe("Maximum number of shelvesets to return."),
+        dateFrom: tool.schema.string().optional().describe("Filter shelvesets created on or after this date/date constant."),
+        source: tool.schema.enum(["native", "ids"]).optional().describe("Native output (default) or one canonical shelveset-ID query."),
+        output: tool.schema.enum(["text", "json"]).optional().describe("Presentation only; does not change query source."),
+        maxItems: tool.schema.number().int().min(1).max(500).optional().describe("Projected record cap (default 100); separate from CLI limit."),
+        format: tool.schema.string().optional().describe("Format string for query output; conflicts with ids source."),
+        dateFormat: tool.schema.string().optional().describe("Date format for query output."),
+        workdir: workdirArg,
+    },
+    async execute(args)
+    {
+        return executeShelvesetList(args);
+    },
+});

package/src/operations/status.ts

@@ -0,0 +1,129 @@
+import { tool } from "../tool-definition";
+import { workdirArg } from "./arguments";
+import { MACHINE_READABLE_STATUS_MAX_ITEMS, MACHINE_READABLE_STATUS_DEFAULT_MAX_ITEMS, STATUS_FIELD_SEPARATOR, diagnoseMachineReadablePendingItems, toMachineReadableStatusItems, toMachineReadableStatusSummary, summarizeShortStatus } from "../domain/pending";
+import { outputFormatArg, toStructuredResult, formatStatusText } from "../presentation/results";
+import { runStatusCommand, StatusCommandError } from "../execution/status-command";
+import { getActiveAbortSignal } from "../execution/context";
+import { analyzeMergeStatusOutput } from "../domain/merge-output";
+import { parseStatusXml } from "../domain/status-xml";
+export { StatusXmlError } from "../domain/status-xml";
+import { runStatusXmlCommand } from "../execution/status-xml-command";
+
+export class StatusOptionError extends Error {
+    constructor() { super("Status source options are conflicting or unsupported. XML does not support short or base revision requests."); }
+}
+export const resolveStatusSource = (args: StatusObservationOptions): "text" | "machine" | "xml" => {
+    const source = args.source ?? (args.machineReadable ? "machine" : "text");
+    if (!["text", "machine", "xml"].includes(source) || (source === "machine" && args.machineReadable === false) || (source !== "machine" && args.machineReadable === true) || (source === "xml" && (args.short || args.includeRevId))) throw new StatusOptionError();
+    return source;
+};
+
+export type StatusObservationOptions = {
+    workdir?: string;
+    short?: boolean;
+    includeRevId?: boolean;
+    machineReadable?: boolean;
+    source?: "text" | "machine" | "xml";
+};
+
+// Internal observations precede presentation; no version lookup or rendered-text parsing.
+export const assembleStatusObservation = async (args: StatusObservationOptions) =>
+{
+    const source = resolveStatusSource(args);
+    if (source === "xml") {
+        const bytes = await runStatusXmlCommand(args.workdir);
+        if (getActiveAbortSignal()?.aborted) throw new StatusCommandError("aborted");
+        const parsed = parseStatusXml(bytes);
+        // Whole-document DOM parsing is synchronous; cancellation is checked at its boundaries.
+        if (getActiveAbortSignal()?.aborted) throw new StatusCommandError("aborted");
+        return { kind: "xml" as const, ...parsed, capture: "complete" as const, requestedShort: false as const };
+    }
+    const cmdArgs: string[] = ["status"];
+    if (args.short) cmdArgs.push("--short");
+    if (args.includeRevId) cmdArgs.push("--includeRevId");
+    if (source === "machine")
+    {
+        // Package-owned separators make paths with whitespace unambiguous, and
+        // revision IDs let agents safely identify the base of moved/deleted items.
+        if (!cmdArgs.includes("--includeRevId")) cmdArgs.push("--includeRevId");
+        cmdArgs.push("--machinereadable", `--fieldseparator=${STATUS_FIELD_SEPARATOR}`);
+        const { output, capture } = await runStatusCommand(cmdArgs, args.workdir, true);
+        const cwd = args.workdir ?? process.cwd();
+        return { kind: "machine" as const, output, capture, cwd, ...diagnoseMachineReadablePendingItems(output, cwd), requestedShort: args.short ?? false };
+    }
+    const primary = await runStatusCommand(cmdArgs, args.workdir);
+    const secondary = await runStatusCommand(["status", "--short"], args.workdir, true);
+    const output = primary.output;
+    const shortOutput = secondary.output;
+    return {
+        kind: "standard" as const,
+        capture: secondary.capture,
+        output,
+        shortOutput,
+        summary: summarizeShortStatus(shortOutput),
+        mergeState: analyzeMergeStatusOutput(output),
+        usedShortFlag: args.short ?? false,
+    };
+};
+export type StatusObservation = Awaited<ReturnType<typeof assembleStatusObservation>>;
+
+export const presentStatusObservation = async (observation: StatusObservation, args: { format?: "text" | "json"; maxItems?: number; includeRaw?: boolean; workdir?: string }) =>
+{
+        const format = args.format ?? "text";
+        if (observation.kind === "xml") {
+            const items = observation.items.slice(0, args.maxItems ?? MACHINE_READABLE_STATUS_DEFAULT_MAX_ITEMS);
+            const source = { transport: "status_xml", encoding: "utf-8", pathBasis: "absolute", scope: "workspace", baseRevisionAvailability: "unavailable" };
+            const warning = "Raw XML contains private workspace/repository/server metadata.";
+            const text = [`Status XML (synthesized; workspace scope; base revisions unavailable): ${observation.items.length} records.`, ...items.map(row => `${row.statusCode} ${row.sourcePath ? `${row.sourcePath} -> ` : ""}${row.path}${row.isDirectory ? " [directory]" : ""}`), ...(items.length < observation.items.length ? [`${observation.items.length - items.length} records omitted.`] : [])].join("\n");
+            if (format === "json") return JSON.stringify({ ok: true, action: "status", data: { mode: "xml", presentation: "synthesized", source, items, summary: observation.summary, itemCount: { parsed: observation.items.length, returned: items.length, omitted: observation.items.length - items.length }, ...(args.includeRaw ? { rawXml: observation.output, rawWarning: warning } : {}) } });
+            return args.includeRaw ? `${text}\n\n${warning}\nRaw status_xml (utf-8):\n${observation.output}` : text;
+        }
+        if (observation.kind === "machine")
+        {
+            const { output: machineOutput, pendingItems, cwd } = observation;
+            const maxItems = args.maxItems ?? MACHINE_READABLE_STATUS_DEFAULT_MAX_ITEMS;
+            const returnedItems = pendingItems.slice(0, maxItems);
+            return toStructuredResult(
+                "status",
+                format,
+                machineOutput,
+                {
+                    machineReadable: true,
+                    items: toMachineReadableStatusItems(returnedItems),
+                    itemCount: {
+                        total: pendingItems.length,
+                        returned: returnedItems.length,
+                        omitted: pendingItems.length - returnedItems.length,
+                    },
+                    summary: toMachineReadableStatusSummary(pendingItems, cwd),
+                    ...(args.includeRaw ? { rawOutput: machineOutput } : {}),
+                },
+                args.workdir,
+            );
+        }
+        const { output, shortOutput, summary, mergeState, usedShortFlag } = observation;
+        const textOutput = formatStatusText(output, mergeState);
+        return toStructuredResult(
+            "status", format, textOutput,
+            { rawOutput: output, shortOutput, summary, mergeState, usedShortFlag },
+            args.workdir,
+        );
+};
+
+export const status = tool({
+    description: "Show Plastic SCM workspace status (cm status).",
+    args: {
+        workdir: workdirArg,
+        includeRevId: tool.schema.boolean().optional().describe("Include revision IDs in the status output when supported."),
+        machineReadable: tool.schema.boolean().optional().describe("Return parsed, machine-readable pending status records when supported."),
+        source: tool.schema.enum(["text", "machine", "xml"]).optional().describe("Explicit status source; omitted preserves machineReadable. XML is UTF-8, workspace-scoped, absolute paths, no short/base revisions, with synthesized presentation."),
+        maxItems: tool.schema.number().int().min(1).max(MACHINE_READABLE_STATUS_MAX_ITEMS).optional().describe(`Maximum parsed items in machine-readable JSON (default ${MACHINE_READABLE_STATUS_DEFAULT_MAX_ITEMS}, maximum ${MACHINE_READABLE_STATUS_MAX_ITEMS}).`),
+        includeRaw: tool.schema.boolean().optional().describe("Include raw machine output in JSON diagnostics, or bounded XML with a private metadata warning. Never included in the compact native DTO."),
+        short: tool.schema.boolean().optional().describe("Use short status output."),
+        format: outputFormatArg,
+    },
+    async execute(args)
+    {
+        return presentStatusObservation(await assembleStatusObservation(args), args);
+    },
+});