@aefree/pi-plastic 0.5.4 → 0.5.6

package/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project follows semantic versioning for public package releases.
 
+## Unreleased
+
+## [0.5.6] - 2026-08-27
+
+### Fixed
+
+- Warn once per interactive Pi runtime when a configured `PI_PLASTIC_PATCH_EXECUTABLE` cannot launch or Windows lacks its required patch backend setting. Warnings redact configured paths; `plastic_patch` retains its existing tool-time validation.
+
+## [0.5.5] - 2026-08-14
+
+### Changed
+
+- Made `plastic_status(machineReadable=true, format="json")` return compact parsed pending-item records, aggregate counts, and bounded-item metadata, with package-owned field separation and revision IDs. It returns at most 100 items by default (configurable up to 500); raw, unbounded Plastic output is omitted by default and available with `includeRaw=true` only for diagnostics.
+
 ## [0.5.4] - 2026-08-13
 
 ### Fixed

package/README.md

@@ -74,6 +74,7 @@ The Bash guards run only in Pi processes that actually load this package. A proj
 
 - `plastic_branchCreate` supports an explicit parent branch independent of the loaded workspace branch, defaults relative names to the current branch when no parent is supplied, and rejects top-level paths unless `allowRootBranch=true` is explicit.
 - `plastic_diff` remains a disabled alias by design. Use `plastic_status` for changed-path listing; do not diff as routine post-edit validation or checkin preflight. When change-boundary evidence is needed, use `plastic_diffFile` for one exact file, `plastic_workspaceDiff` with selected paths or explicit `allPending=true`, or `plastic_diffRevisions` for an explicit historical pair. Diff responses use small defaults and caller-controlled `maxChars` bounds. Historical and workspace bytes are copied to ASCII-safe package-owned paths before the backend runs, while normalized headers retain the logical Unicode labels.
+- `plastic_status(machineReadable=true, format="json")` returns parsed `items`, aggregate `summary`, and `itemCount` (`total`, `returned`, `omitted`) rather than requiring agents to parse Plastic rows. It returns at most 100 items by default; set `maxItems` (up to 500) when more are intentional. `includeRaw=true` adds the original unbounded Plastic output for diagnostics, so omit it for normal agent use to conserve context tokens.
 - Preflight is not routine confirmation. Use it for ambiguous or broad mutation scope, moved/deleted path rewriting, compound operations, or explicit preview requests; otherwise rely on exact targets and the tools' runtime guards.
 - `plastic_patch` generates review patches with `cm patch`, including `clean` and `integration` filters for branch review workflows. It does not expose patch apply. Unqualified `br:/...` selectors are qualified only with the current workspace selector's exact repository; otherwise pass `br:/<branch>@<repository>@<server>`.
 - Bash safety rails block `cm diff` and unsafe interactive `cm merge --merge` usage.
@@ -142,7 +143,7 @@ Project-local installation protects only Pi processes that load those project se
 - Pi 0.82.0 or newer; the current development and eval baseline is Pi 0.83
 - Plastic SCM / Unity Version Control CLI (`cm`) available on `PATH`, or `PI_PLASTIC_CM_EXECUTABLE` set to its full executable path
 - A GNU/POSIX-compatible text `diff` available on `PATH`, or `PI_PLASTIC_DIFF_EXECUTABLE` set to its full executable path (including paths containing spaces), for text-only diff tools. Pi invokes that resolved executable as-is and does not discover Git Bash paths automatically. On macOS, bare `diff` is PATH-dependent: it may be GNU Diffutils (often installed as `diff` ahead of system paths) or Apple’s BSD `/usr/bin/diff`; the package does not substitute one for the other. Configure the intended text executable explicitly when that distinction matters.
-- Patch generation has a separate executable policy: `toolPath` is the one-call highest-priority override, followed by `PI_PLASTIC_PATCH_EXECUTABLE`. On Windows, set one to a verified patch-capable non-GUI executable such as Git's `diff.exe`; the package deliberately does not reuse `PI_PLASTIC_DIFF_EXECUTABLE`/GnuWin32 as a patch default. macOS validation with Plastic 11 found that Apple BSD `/usr/bin/diff` supports text-only diffs but rejects the `--binary` argument supplied by `cm patch`; configure a verified GNU Diffutils-compatible executable explicitly for `plastic_patch`. The non-Windows fallback to `PI_PLASTIC_DIFF_EXECUTABLE` or bare `diff` remains only for environments whose resolved executable satisfies that patch contract.
+- Patch generation has a separate executable policy: `toolPath` is the one-call highest-priority override, followed by `PI_PLASTIC_PATCH_EXECUTABLE`. On Windows, set one to a verified patch-capable non-GUI executable such as Git's `diff.exe`; the package deliberately does not reuse `PI_PLASTIC_DIFF_EXECUTABLE`/GnuWin32 as a patch default. macOS validation with Plastic 11 found that Apple BSD `/usr/bin/diff` supports text-only diffs but rejects the `--binary` argument supplied by `cm patch`; configure a verified GNU Diffutils-compatible executable explicitly for `plastic_patch`. The non-Windows fallback to `PI_PLASTIC_DIFF_EXECUTABLE` or bare `diff` remains only for environments whose resolved executable satisfies that patch contract. In an interactive Pi session, an invalid configured patch override or missing Windows patch setting produces one package capability warning per Pi runtime; the warning omits configured paths, and `plastic_patch` retains its tool-time validation.
 - A configured Plastic workspace for workspace-scoped operations. Text diffs require an ASCII-safe temporary directory; if the configured backend cannot accept Unicode paths, set `TEMP` and `TMP` to a writable ASCII-only location.
 - `pi-file-discovery` is an optional independently loaded integration. When its `discover_candidate_files` tool is active, it receives the advisory Plastic ignore/cloak filter through the shared global capability protocol; when absent, `pi-plastic` loads without file-discovery filtering. The tarball does not embed linked sibling workspaces or `node_modules` paths.
 

package/index.ts

@@ -94,6 +94,8 @@ const TOOL_CONFIG: Partial<Record<PlasticExportName, ToolConfig>> = {
       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;
     },
   },
@@ -654,6 +656,28 @@ function metadataDescription(node: CoreSchemaNode): string {
   return node.metadata?.description ?? "Allowed values.";
 }
 
+type CapabilityDiagnosticContext = {
+  hasUI?: boolean;
+  ui?: { notify?: (message: string, level: "warning") => void };
+};
+
+type PatchCapabilityWarningGetter = () => Promise<string | undefined>;
+
+export const __plasticCapabilityDiagnosticInternals = {
+  createPatchCapabilityWarningNotifier(getWarning: PatchCapabilityWarningGetter = () => core.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");
+    };
+  },
+};
+
+const notifyPatchCapabilityWarning = __plasticCapabilityDiagnosticInternals.createPatchCapabilityWarningNotifier();
+
 function buildParameters(args: Record<string, unknown> | undefined): TSchema {
   if (!args || Object.keys(args).length === 0) {
     return EMPTY_PARAMETERS;
@@ -768,7 +792,8 @@ export default function plasticTools(pi: ExtensionAPI) {
     },
   });
 
-  pi.on("session_start", (_event, ctx) => {
+  pi.on("session_start", async (_event, ctx) => {
+    await notifyPatchCapabilityWarning(ctx as CapabilityDiagnosticContext);
     const ownership = getEffectivePlasticToolOwnership(pi.getAllTools(), EXTENSION_SOURCE_PATH);
     const active = pi.getActiveTools();
     const mode = getPlasticToolLoadingMode();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aefree/pi-plastic",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "type": "module",
   "engines": {
     "node": ">=22.19.0"
@@ -18,8 +18,7 @@
     "skills/",
     "CHANGELOG.md",
     "LICENSE",
-    "README.md",
-    "SECURITY.md"
+    "README.md"
   ],
   "pi": {
     "extensions": [
@@ -34,7 +33,7 @@
     ]
   },
   "scripts": {
-    "test": "npx --yes tsx tests/plastic-tool-validation.ts && npx --yes tsx tests/plastic-checkin-path-resolution.ts && npx --yes tsx tests/plastic-diff-workflow.test.ts && npx --yes tsx tests/plastic-workspace-diff.test.ts && npx --yes tsx tests/plastic-process-lifecycle.test.ts && npx --yes tsx tests/plastic-patch-command.test.ts && npx --yes tsx tests/plastic-extension-registration.test.ts && npx --yes tsx tests/plastic-dynamic-tool-loading.test.ts && npx --yes tsx tests/plastic-tool-rendering.test.ts && npx --yes tsx tests/plastic-branch-query.test.ts && npx --yes tsx tests/plastic-workspace.test.ts && npx --yes tsx tests/plastic-mutation-execution.test.ts && npx --yes tsx tests/file-discovery-filter.test.ts && npx --yes tsx tests/file-discovery-filter-registration.test.ts && npx --yes tsx tests/packed-copy-owner-conflict.test.ts && npx --yes tsx tests/plastic-branch-status.test.ts && npx --yes tsx tests/plastic-constrained-sampling.test.ts && npx --yes tsx tests/bash-cm-diff-guard-validation.ts",
+    "test": "npx --yes tsx tests/plastic-tool-validation.ts && npx --yes tsx tests/plastic-status-machine-readable.test.ts && npx --yes tsx tests/plastic-checkin-path-resolution.ts && npx --yes tsx tests/plastic-diff-workflow.test.ts && npx --yes tsx tests/plastic-workspace-diff.test.ts && npx --yes tsx tests/plastic-process-lifecycle.test.ts && npx --yes tsx tests/plastic-patch-command.test.ts && npx --yes tsx tests/plastic-capability-diagnostics.test.ts && npx --yes tsx tests/plastic-extension-registration.test.ts && npx --yes tsx tests/plastic-dynamic-tool-loading.test.ts && npx --yes tsx tests/plastic-tool-rendering.test.ts && npx --yes tsx tests/plastic-branch-query.test.ts && npx --yes tsx tests/plastic-workspace.test.ts && npx --yes tsx tests/plastic-mutation-execution.test.ts && npx --yes tsx tests/file-discovery-filter.test.ts && npx --yes tsx tests/file-discovery-filter-registration.test.ts && npx --yes tsx tests/packed-copy-owner-conflict.test.ts && npx --yes tsx tests/plastic-branch-status.test.ts && npx --yes tsx tests/plastic-constrained-sampling.test.ts && npx --yes tsx tests/bash-cm-diff-guard-validation.ts",
     "test:live": "npx --yes tsx tests/plastic-live-smoke.test.ts",
     "test:live:branch-create": "npx --yes tsx tests/plastic-branch-create-live.test.ts",
     "eval:tool-loading": "npx --yes tsx evals/tool-loading/run-eval.ts"

package/skills/using-plastic/SKILL.md

@@ -22,7 +22,7 @@ Plastic merges are workspace- and branch-oriented, not Git fast-forwards: the me
 
 `plastic_workspaceDiff` requires selected paths or explicit `allPending=true`, runs status once, has small default file/per-file/combined-output bounds, and returns per-file outcomes without aborting when one file is unavailable. Selected private paths are included; whole-workspace private review additionally requires `includePrivate=true`. Keep `maxChars` small unless more output is intentional. Text-diff selection and patch-backend selection are distinct: text tools use `PI_PLASTIC_DIFF_EXECUTABLE` or bare PATH `diff`. On macOS, bare `diff` can resolve either to GNU Diffutils or Apple’s BSD `/usr/bin/diff`; Pi uses the resolved executable and does not auto-select `gdiff`.
 
-Use `plastic_patch` for review patch generation with `clean` and `integration` filters; it is generation-only and does not apply patches. `toolPath` is its highest-priority one-call patch-backend override, followed by `PI_PLASTIC_PATCH_EXECUTABLE`. On Windows, configure one to a verified patch-capable non-GUI executable such as Git's `diff.exe`: patch generation deliberately does not reuse `PI_PLASTIC_DIFF_EXECUTABLE`/GnuWin32. On macOS with Plastic 11, Apple BSD `/usr/bin/diff` works for text-only `plastic_diffFile` but rejects the `--binary` argument used by `cm patch`; set the patch-specific policy to a verified GNU Diffutils-compatible non-GUI executable. The non-Windows fallback to the text setting or bare `diff` is only valid when that executable accepts the local Plastic patch arguments. Unqualified `br:/...` patch selectors are qualified only from the current workspace's exact selector repository; otherwise pass `br:/<branch>@<repository>@<server>`. For a large patch, pass an intentional new `output` path: the package stages and atomically publishes it, never overwriting an existing path. Do not use `cm cat --raw`: it is unsupported for this workflow. Typed retrieval owns cleanup; the low-level byte-preserving fallback is `cm cat --file` only when a typed tool cannot represent the case. Plastic/server output may represent moves as moves or delete/add records, so inspect generated patches rather than assuming a move-aware encoding.
+Use `plastic_patch` for review patch generation with `clean` and `integration` filters; it is generation-only and does not apply patches. `toolPath` is its highest-priority one-call patch-backend override, followed by `PI_PLASTIC_PATCH_EXECUTABLE`. On Windows, configure one to a verified patch-capable non-GUI executable such as Git's `diff.exe`: patch generation deliberately does not reuse `PI_PLASTIC_DIFF_EXECUTABLE`/GnuWin32. On macOS with Plastic 11, Apple BSD `/usr/bin/diff` works for text-only `plastic_diffFile` but rejects the `--binary` argument used by `cm patch`; set the patch-specific policy to a verified GNU Diffutils-compatible non-GUI executable. The non-Windows fallback to the text setting or bare `diff` is only valid when that executable accepts the local Plastic patch arguments. Interactive Pi sessions issue one path-redacted package capability warning per runtime for an invalid configured patch override or missing Windows setting; fix `PI_PLASTIC_PATCH_EXECUTABLE` and retry, while headless sessions retain `plastic_patch` tool-time validation. Unqualified `br:/...` patch selectors are qualified only from the current workspace's exact selector repository; otherwise pass `br:/<branch>@<repository>@<server>`. For a large patch, pass an intentional new `output` path: the package stages and atomically publishes it, never overwriting an existing path. Do not use `cm cat --raw`: it is unsupported for this workflow. Typed retrieval owns cleanup; the low-level byte-preserving fallback is `cm cat --file` only when a typed tool cannot represent the case. Plastic/server output may represent moves as moves or delete/add records, so inspect generated patches rather than assuming a move-aware encoding.
 
 Prefer runtime `plastic_*` tools first. Keep `cm` shell commands as manual fallback.
 

package/src/plastic-core.ts

@@ -32,6 +32,7 @@ const getCmExecutable = (): string => resolveExecutable(process.env, "PI_PLASTIC
 // Keep the executable name configurable rather than assuming a .exe suffix or package-manager path.
 const getDiffExecutable = (): string => resolveExecutable(process.env, "PI_PLASTIC_DIFF_EXECUTABLE", "diff");
 const PLASTIC_PATCH_EXECUTABLE_ENV = "PI_PLASTIC_PATCH_EXECUTABLE";
+type PatchExecutableProbe = (command: string) => Promise<boolean>;
 // Plastic's server/backend determines whether a moved item is encoded as a
 // move or as delete/add records. Do not claim either without a live fixture.
 const PATCH_MOVE_REPRESENTATION = "backend-determined" as const;
@@ -326,6 +327,20 @@ type PendingItemSummary = {
     privatePaths: string[];
 };
 
+type MachineReadableStatusItem = {
+    statusCode: string;
+    kind: PendingItemKind;
+    path: string;
+    isDirectory: boolean;
+    revisionId?: string;
+    sourcePath?: string;
+};
+
+type MachineReadableStatusSummary = Omit<PendingItemSummary, "privatePaths">;
+
+const MACHINE_READABLE_STATUS_DEFAULT_MAX_ITEMS = 100;
+const MACHINE_READABLE_STATUS_MAX_ITEMS = 500;
+
 type PrivateAutoAddSelection = {
     candidatePaths: string[];
     blockedPaths: Array<{ path: string; reason: string }>;
@@ -685,6 +700,22 @@ const getMachineReadablePendingItems = async (workdir?: string): Promise<Pending
     return parseMachineReadablePendingItems(output, cwd);
 };
 
+const toMachineReadableStatusItems = (pendingItems: PendingItem[]): MachineReadableStatusItem[] =>
+    pendingItems.map((item) => ({
+        statusCode: item.statusCode,
+        kind: item.kind,
+        path: item.workspacePath,
+        isDirectory: item.isDirectory,
+        ...(item.revisionId ? { revisionId: item.revisionId } : {}),
+        ...(item.sourceWorkspacePath ? { sourcePath: item.sourceWorkspacePath } : {}),
+    }));
+
+const toMachineReadableStatusSummary = (pendingItems: PendingItem[], cwd: string): MachineReadableStatusSummary =>
+{
+    const { privatePaths: _privatePaths, ...summary } = summarizePendingItems(pendingItems, cwd);
+    return summary;
+};
+
 const summarizePendingItems = (pendingItems: PendingItem[], cwd?: string): PendingItemSummary =>
 {
     const summary: PendingItemSummary = {
@@ -1198,6 +1229,49 @@ const assertNonBlankPatchValue = (name: keyof PatchCommandArgs, value: string |
     }
 };
 
+const probePatchExecutable = async (command: string): Promise<boolean> =>
+{
+    try
+    {
+        // This establishes only that the configured executable can launch.
+        // `cm patch` remains the authoritative verifier for its --binary contract.
+        const result = await spawnAndCollect(command, ["--version"], process.cwd(), undefined, AbortSignal.timeout(3000), {
+            abortKillDelayMs: 100,
+            outputLimitChars: 1024,
+        });
+        return !result.aborted;
+    }
+    catch
+    {
+        return false;
+    }
+};
+
+export const getPatchBackendCapabilityWarning = async (
+    environment: ExecutableEnvironment = process.env,
+    platform: NodeJS.Platform = process.platform,
+    probe: PatchExecutableProbe = probePatchExecutable,
+): Promise<string | undefined> =>
+{
+    const configuredPatchExecutable = environment[PLASTIC_PATCH_EXECUTABLE_ENV]?.trim();
+    if (configuredPatchExecutable)
+    {
+        if (await probe(configuredPatchExecutable))
+        {
+            return undefined;
+        }
+
+        return "Pi Plastic capability warning: the configured PI_PLASTIC_PATCH_EXECUTABLE could not be launched. Set it to a verified patch-capable non-GUI diff executable, or remove the override to use this platform's documented fallback. The configured path is not shown for privacy.";
+    }
+
+    if (platform === "win32")
+    {
+        return "Pi Plastic capability warning: plastic_patch requires PI_PLASTIC_PATCH_EXECUTABLE on Windows. Set it to a verified patch-capable non-GUI diff executable (for example Git's diff.exe). PI_PLASTIC_DIFF_EXECUTABLE is only for text diffs.";
+    }
+
+    return undefined;
+};
+
 const resolvePatchToolPath = (
     toolPath?: string,
     environment: ExecutableEnvironment = process.env,
@@ -1461,6 +1535,7 @@ export const __plasticProcessInternals = {
 export const __plasticPatchInternals = {
     buildPatchCommandArgs,
     resolvePatchToolPath,
+    getPatchBackendCapabilityWarning,
     qualifyPatchBranchSpec,
     resolvePatchBranchSpecs,
     createPatchOutputStaging,
@@ -2375,7 +2450,9 @@ export const status = tool({
     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 machine-readable status output when supported."),
+        machineReadable: tool.schema.boolean().optional().describe("Return parsed, machine-readable pending status records when supported."),
+        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 unbounded raw machine-readable Plastic output in JSON diagnostics. Applies only when machineReadable=true."),
         short: tool.schema.boolean().optional().describe("Use short status output."),
         format: outputFormatArg,
     },
@@ -2396,15 +2473,32 @@ export const status = tool({
 
         if (args.machineReadable)
         {
-            cmdArgs.push("--machinereadable");
+            // 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 machineOutput = await runCmRaw(cmdArgs, args.workdir);
+            const cwd = args.workdir ?? process.cwd();
+            const pendingItems = parseMachineReadablePendingItems(machineOutput, cwd);
+            const maxItems = args.maxItems ?? MACHINE_READABLE_STATUS_DEFAULT_MAX_ITEMS;
+            const returnedItems = pendingItems.slice(0, maxItems);
             return toStructuredResult(
                 "status",
                 format,
                 machineOutput,
                 {
-                    rawOutput: 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,
             );

package/SECURITY.md

@@ -1,31 +0,0 @@
-# Security Policy
-
-## Supported versions
-
-Security fixes are provided for the latest tagged release. Upgrade to the newest release before reporting an issue that may already be fixed.
-
-## Reporting a vulnerability
-
-Do not open a public issue for a suspected vulnerability, credential exposure, or unsafe command-execution path.
-
-Use GitHub's private vulnerability reporting for this repository:
-
-<https://github.com/aefreedman/pi-plastic/security/advisories/new>
-
-Include:
-
-- the affected package version or commit;
-- the Pi, Node.js, Git, and Plastic CLI versions;
-- the operating system;
-- reproduction steps and expected versus observed behavior;
-- the affected tool or extension;
-- impact and any known mitigations;
-- whether credentials, repository content, or remote Plastic objects may have been exposed or changed.
-
-Avoid including real credentials or sensitive repository content. Use a disposable Plastic workspace when a reproduction requires mutation.
-
-You should receive an acknowledgement within seven days. Release timing depends on severity, reproducibility, and coordination needs.
-
-## Scope
-
-Security-sensitive areas include command construction, executable-path overrides, workspace/path targeting, destructive Plastic operations, provider payload capture, dynamic tool ownership, and package-install behavior. General support questions and ordinary bugs belong in the public issue tracker.