@aefree/pi-plastic 0.5.5 → 0.5.6

package/CHANGELOG.md

@@ -7,6 +7,12 @@ 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

package/README.md

@@ -143,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

@@ -656,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;
@@ -770,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.5",
+  "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-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-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;
@@ -1228,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,
@@ -1491,6 +1535,7 @@ export const __plasticProcessInternals = {
 export const __plasticPatchInternals = {
     buildPatchCommandArgs,
     resolvePatchToolPath,
+    getPatchBackendCapabilityWarning,
     qualifyPatchBranchSpec,
     resolvePatchBranchSpecs,
     createPatchOutputStaging,

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.