@aefree/pi-plastic 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -5,6 +5,30 @@ 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.
 
+## [0.5.1] - 2026-08-05
+
+### Changed
+
+- Clarified that preflight is situational rather than routine and that status, focused tests, and direct reads should precede intentional diff output.
+- Reduced agent-facing diff defaults, added caller-controlled body bounds and complete JSON response bounds, required selected paths or explicit `allPending=true` for workspace diffs (including direct-call guards), and limited generic diff discovery to one focused tool.
+
+## [0.5.0] - 2026-08-05
+
+### Added
+
+- Added dynamically loadable `plastic_workspaceDiff` for bounded pending review: one machine-readable status pass, per-file text/binary/unavailable outcomes, selected-path and private-file policy, and intentional file/output limits.
+
+### Changed
+
+- Kept GNU/POSIX `diff` as the only text-diff backend, improved `PI_PLASTIC_DIFF_EXECUTABLE`/bare-PATH diagnostics (including Windows-like missing-diff guidance), and removed unused Git diff fallback code.
+- Made workspace `plastic_diffFile` use machine-readable pending status for private/new, added, changed, moved, and deleted comparisons; status revision IDs materialize safe bases and `--nodata` base failures now explain recovery.
+- Updated diff routing guidance: changed listing uses `plastic_status`, one file uses `plastic_diffFile`, pending review uses `plastic_workspaceDiff`, and explicit historical pairs use `plastic_diffRevisions`.
+
+- Replaced the optional `@aefree/pi-repo-search` integration with `@aefree/pi-file-discovery`. Plastic ignore/cloak data is now an advisory file-discovery filter: only roots with readable ignore/cloak files emit `filterDecision: "applied"` records with a nearest-workspace `filterBoundary`; no-op roots are omitted and unavailable or malformed filter data degrades to generic discovery as routine execution hygiene.
+- Register the optional Plastic filter through the package-qualified global capability-registry rendezvous instead of importing `pi-file-discovery` from Plastic's separate module root. Registration remains session-scoped, transactional, and safe against stale shutdown tokens.
+- Excluded development-only tests and behavioral evals from published npm artifacts.
+- Publish verified GitHub releases to npm through resumable OIDC trusted-publishing automation, and canonicalized the package repository URL for GitHub identity matching.
+
 ## [0.4.0] - 2026-08-01
 
 ### Added

package/README.md

@@ -8,9 +8,9 @@ When Pi starts inside a Plastic workspace, this package adds a themed `Plastic <
 
 The extension owns only the `plastic-branch` status key. It does not replace Pi's footer or suppress Pi's Git branch display, so Git and Plastic information can appear together in nested workspaces. If the Plastic marker exists but neither the selector nor `cm` yields a branch, the footer shows `Plastic branch unavailable`. Non-Plastic directories show no Plastic status.
 
-## Repository-search policy
+## File-discovery filter
 
-When `@aefree/pi-repo-search` is also installed, Pi session startup registers the independent `plastic.ignore-files` repository-search policy. The marker-based policy discovers readable `ignore.conf` and `cloaked.conf` only from the nearest Plastic workspace to each requested root, then adds them as ripgrep ignore files without replacing native ripgrep/Git-ignore behavior. The integration is optional: without `pi-repo-search`, all Plastic tools and skills still load and only this policy registration is omitted. It does not register workflow guidance or perform Plastic CLI readiness checks; owning `plastic_*` tools validate their own workspace and CLI requirements.
+When `@aefree/pi-file-discovery` is also loaded, Pi session startup registers the independent advisory `plastic.ignore-files` file-discovery filter through the package-qualified capability-registry rendezvous key. The packages may have separate module roots; Plastic does not import file-discovery from its own root. It discovers readable `ignore.conf` and `cloaked.conf` only from the nearest Plastic workspace to each requested root, then supplies them as ripgrep ignore files without replacing native ripgrep/Git-ignore behavior. A root is emitted only when it has at least one readable ignore/cloak file; each emitted root declares `filterDecision: "applied"`, decision code `plastic_ignore_files_applied`, and that workspace as its `filterBoundary`. No-op Plastic roots are omitted from mixed requests, and a request with no effective ignore/cloak records is `not_applicable`. The integration is optional: without `pi-file-discovery`, all Plastic tools and skills still load and no filter registry is created. Missing, malformed, or unavailable Plastic filter data degrades to generic discovery; `pi-file-discovery` owns that execution hygiene and disclosure behavior. It does not register workflow guidance or perform Plastic CLI readiness checks; owning `plastic_*` tools validate their own workspace and CLI requirements.
 
 
 ## Mutation execution
@@ -32,6 +32,7 @@ Removing the approval layer does not relax Plastic safety guards. Command allowl
 - `plastic_patch`
 - `plastic_diffRevisions`
 - `plastic_diffFile`
+- `plastic_workspaceDiff`
 - `plastic_branchCreate`
 - `plastic_switchBranch`
 - `plastic_merge`
@@ -53,7 +54,7 @@ Removing the approval layer does not relax Plastic safety guards. Command allowl
 
 ## Dynamic tool loading
 
-The package exposes 28 public `plastic_*` tools. `plastic_workspaceCreate` is intentionally not registered or discoverable until the package provides a paired, safe workspace-cleanup capability. `plastic_tool_search` is a package-owned loader that searches the explicit Plastic capability catalog, reports bounded matches and safety guidance, and additively enables selected tools for the next model request.
+The package exposes 29 public `plastic_*` tools. `plastic_workspaceCreate` is intentionally not registered or discoverable until the package provides a paired, safe workspace-cleanup capability. `plastic_tool_search` is a package-owned loader that searches the explicit Plastic capability catalog, reports bounded matches and safety guidance, and additively enables selected tools for the next model request.
 
 The default **balanced** session set keeps `plastic_tool_search`, `plastic_status`, and `plastic_currentBranch` active. The other Plastic tools remain registered but inactive until selected; built-in and other-extension tools are not removed. Previous loader additions on the active session branch are restored on startup, resume, fork, and reload.
 
@@ -62,7 +63,7 @@ For controlled comparisons, set `PI_PLASTIC_TOOL_LOADING_MODE` before starting P
 ```bash
 PI_PLASTIC_TOOL_LOADING_MODE=balanced    # default production candidate
 PI_PLASTIC_TOOL_LOADING_MODE=loader-only # maximum initial schema reduction
-PI_PLASTIC_TOOL_LOADING_MODE=all-active  # all 28 currently exposed tools; loader omitted
+PI_PLASTIC_TOOL_LOADING_MODE=all-active  # all 29 currently exposed tools; loader omitted
 ```
 
 Pi 0.82 and newer use canonical `sourceInfo` provenance to identify this package's effective tools before deferring, restoring, or activating them. If canonical provenance or ownership of the effective loader cannot be proven, `pi-plastic` fails safe: it preserves the complete current active set exactly, does not defer, remove, or activate any `plastic_*` name, and an effective package loader can only report known tools that are already active rather than activating inactive names. On sourceInfo-capable Pi instances, providers without native deferred definitions still receive the complete current active set after a loader call. Reload or restart Pi after source edits; source files are not watched automatically.
@@ -70,7 +71,8 @@ Pi 0.82 and newer use canonical `sourceInfo` provenance to identify this package
 ## Safety behavior
 
 - `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_diffFile` or `plastic_diffRevisions` for text-only file diffs.
+- `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.
+- 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.
 - Bash safety rails block `cm diff` and unsafe interactive `cm merge --merge` usage.
 - Merge tooling surfaces Plastic `FILE_CONFLICT` records and merge-state metadata from `cm status`.
@@ -129,9 +131,9 @@ pi install -l <path-to-pi-plastic>
 - Node.js 22.19.0 or newer
 - 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 compatible `diff` executable available on `PATH`, or `PI_PLASTIC_DIFF_EXECUTABLE` set to its full executable path, for text-only diff and patch tools
+- GNU/POSIX-compatible `diff` available on `PATH`, or `PI_PLASTIC_DIFF_EXECUTABLE` set to its full executable path (including paths containing spaces), for text-only diff and patch tools. Pi does not discover Git Bash paths automatically.
 - A configured Plastic workspace for workspace-scoped operations
-- `@aefree/pi-repo-search` is an optional peer. When installed, it receives the Plastic ignore/cloak policy; when absent, `pi-plastic` loads without repository-search integration. The tarball does not embed linked sibling workspaces or `node_modules` paths.
+- `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.
 
 ## Testing
 

package/extensions/bash-cm-diff-guard.ts

@@ -6,7 +6,7 @@ import {
 } from "./shared/bash-command-guards";
 
 const BLOCK_MESSAGE =
-  "`cm diff` is blocked in Pi because it can launch a GUI window and hang CLI automation. Use `plastic_status` to list changed paths, `plastic_diffFile` for a file diff, or `plastic_diffRevisions` for two explicit revisions.";
+  "`cm diff` is blocked in Pi because it can launch a GUI window and hang CLI automation. Use `plastic_status` when only changed paths are needed. Do not diff routinely; when change-boundary evidence is necessary, use a focused `plastic_diffFile`, explicitly scoped `plastic_workspaceDiff`, or `plastic_diffRevisions`.";
 
 const DIRECT_CM_DIFF = /^(?:[A-Za-z_][A-Za-z0-9_]*=\S+\s+)*(?:(?:"[^"]*[\\/]cm(?:\.exe)?"|'[^']*[\\/]cm(?:\.exe)?')|(?:[^"'\s]*[\\/])?cm(?:\.exe)?)\s+diff(?:\s|$)/i;
 
@@ -24,6 +24,7 @@ function commandRunsCmDiff(command: string): boolean {
 }
 
 export const __bashCmDiffGuardInternals = {
+  blockMessage: BLOCK_MESSAGE,
   segmentRunsCmDiff,
   commandRunsCmDiff,
   stripAssignments,

package/extensions/file-discovery-filter.ts

@@ -0,0 +1,67 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createPlasticFileDiscoveryFilterV1, loadPlasticOwnerV1 } from "../src/file-discovery-filter.ts";
+import {
+  createPlasticFileDiscoveryFilterRegistryV1,
+  type PlasticFileDiscoveryRegistrationToken,
+} from "../src/file-discovery-filter-rendezvous.ts";
+
+type ScopeRegistration = Readonly<{ token: PlasticFileDiscoveryRegistrationToken }>;
+type ScopeLifecycle = { generation: number; active: boolean };
+
+function hasFileDiscoveryTool(pi: Pick<ExtensionAPI, "getActiveTools">): boolean {
+  return pi.getActiveTools?.().includes("discover_candidate_files") ?? false;
+}
+
+/**
+ * Session-scoped optional Plastic file-discovery filter registration.
+ *
+ * Independently loaded packages rendezvous through the published global
+ * capability-registry protocol. No import is attempted from Plastic's module
+ * root, so an absent file-discovery package leaves Plastic unchanged.
+ */
+export function createPlasticFileDiscoveryFilterExtension(): (pi: ExtensionAPI) => void {
+  return (pi) => {
+    const registrations = new WeakMap<object, ScopeRegistration>();
+    const lifecycles = new WeakMap<object, ScopeLifecycle>();
+
+    pi.on("session_start", async (_event, ctx) => {
+      if (!hasFileDiscoveryTool(pi)) return;
+      const scope = ctx.sessionManager;
+      const previous = lifecycles.get(scope);
+      const lifecycle = { generation: (previous?.generation ?? 0) + 1, active: true };
+      lifecycles.set(scope, lifecycle);
+
+      const owner = await loadPlasticOwnerV1(import.meta.url);
+      // Do not revive a scope whose shutdown occurred while owner discovery was pending.
+      if (lifecycles.get(scope) !== lifecycle || !lifecycle.active) return;
+      const registry = createPlasticFileDiscoveryFilterRegistryV1();
+      const token = registry.register(scope, createPlasticFileDiscoveryFilterV1(owner));
+      // Registration succeeds before the prior token is retired, preserving a valid
+      // record if construction or validation fails. Nonces make stale retirement safe.
+      const current = registrations.get(scope);
+      if (lifecycles.get(scope) !== lifecycle || !lifecycle.active) {
+        registry.unregister(token);
+        return;
+      }
+      registrations.set(scope, Object.freeze({ token }));
+      if (current !== undefined) registry.unregister(current.token);
+    });
+    pi.on("session_shutdown", (_event, ctx) => {
+      const scope = ctx.sessionManager;
+      const lifecycle = lifecycles.get(scope);
+      if (lifecycle !== undefined) {
+        lifecycle.active = false;
+        lifecycle.generation += 1;
+      }
+      const current = registrations.get(scope);
+      if (current === undefined) return;
+      createPlasticFileDiscoveryFilterRegistryV1().unregister(current.token);
+      // A stale shutdown must not erase a replacement registration.
+      if (registrations.get(scope) === current) registrations.delete(scope);
+    });
+  };
+}
+
+export default function registerPlasticFileDiscoveryFilters(pi: ExtensionAPI): void {
+  createPlasticFileDiscoveryFilterExtension()(pi);
+}

package/index.ts

@@ -64,6 +64,7 @@ const PLASTIC_EXPORTS = [
   "patch",
   "diffRevisions",
   "diffFile",
+  "workspaceDiff",
   "branchCreate",
   "switchBranch",
   "merge",
@@ -171,6 +172,7 @@ const TOOL_CONFIG: Partial<Record<PlasticExportName, ToolConfig>> = {
       normalizeWorkdirAliases(input);
       assignAlias(input, "leftRevision", ["left_revision"]);
       assignAlias(input, "rightRevision", ["right_revision"]);
+      assignAlias(input, "maxChars", ["max_chars"]);
       return input;
     },
   },
@@ -178,6 +180,20 @@ const TOOL_CONFIG: Partial<Record<PlasticExportName, ToolConfig>> = {
     prepareArguments(args) {
       const input = normalizeArgs(args);
       normalizeWorkdirAliases(input);
+      assignAlias(input, "maxChars", ["max_chars"]);
+      return input;
+    },
+  },
+  workspaceDiff: {
+    prepareArguments(args) {
+      const input = normalizeOutputFormatAlias(normalizeArgs(args));
+      normalizeWorkdirAliases(input);
+      promoteSinglePath(input);
+      assignAlias(input, "paths", ["items", "files"]);
+      assignAlias(input, "allPending", ["all_pending"]);
+      assignAlias(input, "includePrivate", ["include_private"]);
+      assignAlias(input, "maxFiles", ["max_files"]);
+      assignAlias(input, "maxChars", ["max_chars"]);
       return input;
     },
   },
@@ -696,12 +712,12 @@ export default function plasticTools(pi: ExtensionAPI) {
     description: "Search and enable Plastic SCM / Unity Version Control tools for workspace status and sync, changes and checkins, text-only diffs and patches, branches and merges, shelvesets, code reviews, and workspaces.",
     promptSnippet: "Use plastic_tool_search to find and enable Plastic SCM capabilities that are not active.",
     promptGuidelines: [
-      "Use plastic_tool_search before a Plastic SCM action when an appropriate plastic_* tool is not active. Inspect exact targets and use each tool's preflight and safety options before mutations.",
+      "Use plastic_tool_search before a Plastic SCM action when an appropriate plastic_* tool is not active. Inspect exact mutation targets. Do not preflight routinely: use preflight for ambiguous or broad scope, moved/deleted path rewriting, compound operations, or an explicit preview request.",
     ],
     parameters: Type.Object({
       query: Type.Optional(Type.String({ description: "Capability or workflow to search for." })),
       toolNames: Type.Optional(Type.Array(Type.String({ description: "Exact public Plastic tool name." }), { maxItems: 4, description: "Optional exact tool names to enable." })),
-      limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 4, description: "Maximum matching tools to enable. Defaults to the single best keyword match, except generic diff loads both safe text-only alternatives; exact toolNames requests may enable up to four." })),
+      limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 4, description: "Maximum matching tools to enable. Defaults to the single best keyword match; exact toolNames requests may enable up to four." })),
     }),
     async execute(_toolCallId, params) {
       if (isPlasticToolBrowseRequest(params)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aefree/pi-plastic",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "type": "module",
   "engines": {
     "node": ">=22.19.0"
@@ -17,8 +17,6 @@
     "src/",
     "references/",
     "skills/",
-    "evals/tool-loading/",
-    "tests/",
     "CHANGELOG.md",
     "CONTRIBUTING.md",
     "LICENSE",
@@ -31,24 +29,25 @@
       "./extensions/plastic-branch-status.ts",
       "./extensions/bash-cm-diff-guard.ts",
       "./extensions/bash-cm-merge-guard.ts",
-      "./extensions/repository-search-provider.ts"
+      "./extensions/file-discovery-filter.ts"
     ],
     "skills": [
       "./skills"
     ]
   },
   "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-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/repository-search-provider.test.ts && npx --yes tsx tests/repository-search-provider-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-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: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"
   },
   "devDependencies": {
+    "@aefree/pi-file-discovery": "^0.1.1",
     "@earendil-works/pi-coding-agent": "0.83.0",
     "typebox": "^1.3.8"
   },
   "peerDependencies": {
-    "@aefree/pi-repo-search": "^0.1.0",
+    "@aefree/pi-file-discovery": "^0.1.0",
     "@earendil-works/pi-coding-agent": "*",
     "typebox": "*"
   },
@@ -56,14 +55,14 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+ssh://git@github.com/aefreedman/pi-plastic.git"
+    "url": "git+https://github.com/aefreedman/pi-plastic.git"
   },
   "bugs": {
     "url": "https://github.com/aefreedman/pi-plastic/issues"
   },
   "homepage": "https://github.com/aefreedman/pi-plastic#readme",
   "peerDependenciesMeta": {
-    "@aefree/pi-repo-search": {
+    "@aefree/pi-file-discovery": {
       "optional": true
     },
     "@earendil-works/pi-coding-agent": {