@aefree/pi-plastic 0.4.0 → 0.5.1

package/skills/using-plastic/references/troubleshooting.md

@@ -41,7 +41,9 @@ cm codereview -e <review-id> --reviewer="reviewer-name"
 - `cm diff` is blocked in Pi because it can launch GUI windows and hang the CLI.
 - Use text-only alternatives:
   - `plastic_status(machineReadable=true)` for changed paths/statuses.
-  - `plastic_diffFile(path="<workspace-path>")` for the common workspace-base comparison.
+  - `plastic_diffFile(path="<workspace-path>", maxChars=4000)` when one intentional file comparison is needed.
+  - `plastic_workspaceDiff(paths=["<workspace-path>"], maxChars=3000)` for an explicitly scoped pending review, or `allPending=true` for an intentional small whole-workspace review.
+  - Use `plastic_status` instead when only pending paths are needed; do not diff routinely.
   - `plastic_diffFile(path="<workspace-path>", revision="cs:<number>")` for an explicit supported revision.
   - `plastic_diffRevisions(leftRevision="<left-file-qualified-revspec>", rightRevision="<right-file-qualified-revspec>")` for two historical files.
 
@@ -95,12 +97,12 @@ plastic_resolveDeleteChangeConflict(paths=["<workspace-path>"], keepOnDisk=true)
 
 - Do not use `cm diff --summary`; this form is invalid.
 - Also avoid all other `cm diff` forms in Pi.
-- Use the same text-only alternatives listed above.
+- Use `plastic_status` unless change-boundary evidence is actually needed; then use the focused text-only alternatives above.
 
 ## Deleted Files Missing From Checkin
 
 - Run `cm status --all` and confirm deleted items are listed before checkin.
-- Use `plastic_checkin(preflight=true, paths=[...])` first; the tool can auto-rewrite moved/deleted file scopes to parent directories.
+- For a path-scoped checkin containing moved/deleted items, use `plastic_checkin(preflight=true, paths=[...])`; the tool can preview rewriting unstable file scopes to parent directories. Do not add preflight to unrelated routine checkins.
 - If a path-scoped checkin is rejected as "not changed", rerun with `applyChanged=true` and a parent-directory scope.
 - Re-run `cm status --all` just before checkin to validate scope.
 

package/skills/using-plastic/references/workspaces.md

@@ -1,33 +1,33 @@
-# Review Workspaces
-
-## Strategy
-
-- Use a separate review workspace for isolation.
-- Reuse `-review-1` by default (Unity workspaces are large).
-
-## Create or Reuse
-
-```bash
-main_workspace=$(basename "$PWD")
-review_workspace_name="${main_workspace}-review-1"
-review_workspace="../${review_workspace_name}"
-
-if [ -d "$review_workspace" ]; then
-  cd "$review_workspace"
-  cm switch --silent --noinput "$review_branch" || {
-    cm shelveset create --all -c="Auto-shelve before review switch"
-    cm switch --silent --noinput "$review_branch"
-  }
-else
-  repo_spec=$(cm status --wkconfig | grep "^Repository:" | cut -d: -f2- | xargs)
-  cm workspace create "$review_workspace_name" "$review_workspace" "$repo_spec"
-  cd "$review_workspace"
-  cm switch --silent --noinput "$review_branch"
-fi
-```
-
-Agent preference: use runtime `plastic_*` methods first for branch/status operations; keep shell commands as manual fallback.
-
-## Cleanup
-
-Only remove review workspaces when disk space is tight or requested.
+# Review Workspaces
+
+## Strategy
+
+- Use a separate review workspace for isolation.
+- Reuse `-review-1` by default (Unity workspaces are large).
+
+## Create or Reuse
+
+```bash
+main_workspace=$(basename "$PWD")
+review_workspace_name="${main_workspace}-review-1"
+review_workspace="../${review_workspace_name}"
+
+if [ -d "$review_workspace" ]; then
+  cd "$review_workspace"
+  cm switch --silent --noinput "$review_branch" || {
+    cm shelveset create --all -c="Auto-shelve before review switch"
+    cm switch --silent --noinput "$review_branch"
+  }
+else
+  repo_spec=$(cm status --wkconfig | grep "^Repository:" | cut -d: -f2- | xargs)
+  cm workspace create "$review_workspace_name" "$review_workspace" "$repo_spec"
+  cd "$review_workspace"
+  cm switch --silent --noinput "$review_branch"
+fi
+```
+
+Agent preference: use runtime `plastic_*` methods first for branch/status operations; keep shell commands as manual fallback.
+
+## Cleanup
+
+Only remove review workspaces when disk space is tight or requested.

package/src/file-discovery-filter-rendezvous.ts

@@ -0,0 +1,104 @@
+/**
+ * Narrow local adapter for the published capability-registry global protocol.
+ *
+ * Pi loads independently installed packages from separate module roots. Plastic
+ * therefore registers its optional file-discovery filter through the stable
+ * global capability key instead of importing a sibling package contract.
+ */
+const ROOT_PROTOCOL = "@aefree/pi-capability-registry/root";
+const ROOT_PROTOCOL_VERSION = 1;
+export const PLASTIC_FILE_DISCOVERY_FILTER_REGISTRY_KEY_V1 = "@aefree/pi-file-discovery/filters/v1" as const;
+
+type FilterOwner = Readonly<{ packageName: string; packageRoot: string }>;
+type FilterRecord = Readonly<{ contractVersion: 1; id: string; kind: "file-discovery-filter"; owner: FilterOwner; evaluate: (...args: never[]) => unknown }>;
+export type PlasticFileDiscoveryRegistrationToken = Readonly<{ registryKey: string; contractVersion: 1; scope: object; ownerKey: string; id: string; nonce: number }>;
+type StoredRecord = Readonly<{ nonce: number; record: FilterRecord }>;
+type ScopedState = { sequence: number; records: Map<string, StoredRecord> };
+type VersionState = { version: 1; scopes: WeakMap<object, ScopedState> };
+type RegistryRoot = { protocol: string; protocolVersion: number; registryKey: string; versions: Map<unknown, unknown> };
+
+export type PlasticFileDiscoveryFilterRegistryV1 = Readonly<{
+  register(scope: object, filter: FilterRecord): PlasticFileDiscoveryRegistrationToken;
+  unregister(token: PlasticFileDiscoveryRegistrationToken | undefined): boolean;
+}>;
+
+/** Create Plastic's view of the shared file-discovery v1 capability registry. */
+export function createPlasticFileDiscoveryFilterRegistryV1(): PlasticFileDiscoveryFilterRegistryV1 {
+  const registryKey = PLASTIC_FILE_DISCOVERY_FILTER_REGISTRY_KEY_V1;
+  const globalRecord = globalThis as typeof globalThis & Record<symbol, unknown>;
+  const symbol = Symbol.for(registryKey);
+  let candidate = globalRecord[symbol];
+  if (candidate === undefined) {
+    candidate = { protocol: ROOT_PROTOCOL, protocolVersion: ROOT_PROTOCOL_VERSION, registryKey, versions: new Map() } satisfies RegistryRoot;
+    globalRecord[symbol] = candidate;
+  }
+  const root = assertRoot(candidate, registryKey);
+  let versionCandidate = root.versions.get(1);
+  if (versionCandidate === undefined) {
+    versionCandidate = { version: 1, scopes: new WeakMap<object, ScopedState>() } satisfies VersionState;
+    root.versions.set(1, versionCandidate);
+  }
+  const version = assertVersionState(versionCandidate, registryKey);
+
+  return Object.freeze({
+    register(scope, filter) {
+      assertScope(scope);
+      assertFilter(filter);
+      let scoped = version.scopes.get(scope);
+      if (scoped === undefined) {
+        scoped = { sequence: 0, records: new Map() };
+        version.scopes.set(scope, scoped);
+      } else {
+        assertScopedState(scoped, registryKey);
+      }
+      const ownerKey = `${filter.owner.packageName}\0${filter.owner.packageRoot}\0${filter.id}`;
+      for (const current of scoped.records.values()) {
+        if (current.record.id === filter.id && ownerKeyFor(current.record) !== ownerKey) {
+          throw new TypeError(`Provider id '${filter.id}' conflicts in file-discovery registry '${registryKey}'.`);
+        }
+      }
+      const nonce = scoped.sequence + 1;
+      scoped.records.set(ownerKey, Object.freeze({ nonce, record: filter }));
+      scoped.sequence = nonce;
+      return Object.freeze({ registryKey, contractVersion: 1, scope, ownerKey, id: filter.id, nonce });
+    },
+    unregister(token) {
+      if (!token || token.registryKey !== registryKey || token.contractVersion !== 1) return false;
+      const scoped = version.scopes.get(token.scope);
+      if (scoped === undefined) return false;
+      assertScopedState(scoped, registryKey);
+      const current = scoped.records.get(token.ownerKey);
+      if (current === undefined || current.nonce !== token.nonce || current.record.id !== token.id) return false;
+      scoped.records.delete(token.ownerKey);
+      return true;
+    },
+  });
+}
+
+function assertRoot(value: unknown, registryKey: string): RegistryRoot {
+  if (value === null || typeof value !== "object") throw incompatible(registryKey);
+  const root = value as Partial<RegistryRoot>;
+  if (root.protocol !== ROOT_PROTOCOL || root.protocolVersion !== ROOT_PROTOCOL_VERSION || root.registryKey !== registryKey || !(root.versions instanceof Map)) throw incompatible(registryKey);
+  return root as RegistryRoot;
+}
+function assertVersionState(value: unknown, registryKey: string): VersionState {
+  if (value === null || typeof value !== "object") throw incompatible(registryKey);
+  const state = value as Partial<VersionState>;
+  if (state.version !== 1 || !(state.scopes instanceof WeakMap)) throw incompatible(registryKey);
+  return state as VersionState;
+}
+function assertScopedState(value: unknown, registryKey: string): asserts value is ScopedState {
+  if (value === null || typeof value !== "object") throw incompatible(registryKey);
+  const state = value as Partial<ScopedState>;
+  if (!Number.isSafeInteger(state.sequence) || (state.sequence ?? -1) < 0 || !(state.records instanceof Map)) throw incompatible(registryKey);
+}
+function assertScope(scope: unknown): asserts scope is object {
+  if ((typeof scope !== "object" && typeof scope !== "function") || scope === null) throw new TypeError("File-discovery registration requires a session scope object.");
+}
+function assertFilter(value: unknown): asserts value is FilterRecord {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) throw new TypeError("Plastic attempted an invalid file-discovery filter registration.");
+  const filter = value as Partial<FilterRecord>;
+  if (filter.contractVersion !== 1 || filter.kind !== "file-discovery-filter" || typeof filter.id !== "string" || !filter.id || typeof filter.evaluate !== "function" || filter.owner === null || typeof filter.owner !== "object" || typeof filter.owner.packageName !== "string" || !filter.owner.packageName || typeof filter.owner.packageRoot !== "string" || !filter.owner.packageRoot) throw new TypeError("Plastic attempted an invalid file-discovery filter registration.");
+}
+function ownerKeyFor(record: FilterRecord): string { return `${record.owner.packageName}\0${record.owner.packageRoot}\0${record.id}`; }
+function incompatible(registryKey: string): TypeError { return new TypeError(`@aefree/pi-file-discovery advertises an incompatible capability-registry contract for '${registryKey}'.`); }

package/src/{repository-search-provider.ts → file-discovery-filter.ts}

@@ -2,23 +2,26 @@ import { access, readFile, realpath, stat } from "node:fs/promises";
 import { constants as fsConstants } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-// Structural copies of the narrow public v1 contract keep the policy module loadable
+// Structural copies of the narrow public v1 contract keep the filter module loadable
 // when the optional registry package is absent. The installed registry validates the
-// record when registration is available.
-type RepoSearchOwnerV1 = Readonly<{ packageName: string; packageVersion: string; packageRoot: string; registeredBy: string }>;
-type RepoSearchExecutionContextV1 = Readonly<{ cwd: string; requestId?: string; signal: AbortSignal }>;
-type RepositoryPolicyRequestV1 = Readonly<{ workspaceRoot: string; roots: readonly string[]; includeHidden: boolean; options?: Readonly<Record<string, unknown>>; signal: AbortSignal }>;
-type RepositoryPolicyResultV1 =
+// record when registration is available; unavailable or malformed filter data
+// degrades to generic discovery rather than interrupting file discovery.
+type FileDiscoveryOwnerV1 = Readonly<{ packageName: string; packageVersion: string; packageRoot: string; registeredBy: string }>;
+type FileDiscoveryExecutionContextV1 = Readonly<{ cwd: string; requestId?: string; signal: AbortSignal }>;
+type FileDiscoveryFilterRequestV1 = Readonly<{ workspaceRoot: string; roots: readonly string[]; includeHidden: boolean; signal: AbortSignal }>;
+type FileDiscoveryAppliedRootV1 = Readonly<{ root: string; filterDecision: "applied" | "bypassed"; decisionCode: string; filterBoundary?: string; excludeGlobs?: readonly string[]; ignoreFiles?: readonly string[]; disclosures: readonly string[] }>;
+type FileDiscoveryFilterResultV1 =
   | Readonly<{ outcome: "not_applicable" }>
-  | Readonly<{ outcome: "applied"; roots: readonly Readonly<{ root: string; policyOwnedRoot?: string; excludeGlobs?: readonly string[]; ignoreFiles?: readonly string[]; disclosures: readonly string[] }>[] }>
+  | Readonly<{ outcome: "applied"; roots: readonly FileDiscoveryAppliedRootV1[] }>
   | Readonly<{ outcome: "unavailable" | "error"; code: string; retryable: boolean }>;
-type RepositoryPolicyV1 = Readonly<{ contractVersion: 1; id: string; kind: "repository-search-policy"; owner: RepoSearchOwnerV1; evaluate(context: RepoSearchExecutionContextV1, request: RepositoryPolicyRequestV1): Promise<RepositoryPolicyResultV1> }>;
+type FileDiscoveryFilterV1 = Readonly<{ contractVersion: 1; id: string; kind: "file-discovery-filter"; owner: FileDiscoveryOwnerV1; evaluate(context: FileDiscoveryExecutionContextV1, request: FileDiscoveryFilterRequestV1): Promise<FileDiscoveryFilterResultV1> }>;
 import { discoverPlasticWorkspace } from "./plastic-workspace.ts";
 
-export const PLASTIC_REPOSITORY_SEARCH_POLICY_ID = "plastic.ignore-files" as const;
+export const PLASTIC_FILE_DISCOVERY_FILTER_ID = "plastic.ignore-files" as const;
+export const PLASTIC_IGNORE_FILES_APPLIED_CODE = "plastic_ignore_files_applied" as const;
 
-/** Resolve this physical package copy's identity for repository-search registration. */
-export async function loadPlasticOwnerV1(moduleUrl: string = import.meta.url): Promise<RepoSearchOwnerV1> {
+/** Resolve this physical package copy's identity for file-discovery registration. */
+export async function loadPlasticOwnerV1(moduleUrl: string = import.meta.url): Promise<FileDiscoveryOwnerV1> {
   const registeredBy = fileURLToPath(moduleUrl);
   const packageRoot = await realpath(fileURLToPath(new URL("../", moduleUrl)));
   const manifest = JSON.parse(await readFile(join(packageRoot, "package.json"), "utf8")) as { name?: unknown; version?: unknown };
@@ -26,13 +29,13 @@ export async function loadPlasticOwnerV1(moduleUrl: string = import.meta.url): P
   return Object.freeze({ packageName: "@aefree/pi-plastic", packageVersion: manifest.version, packageRoot, registeredBy });
 }
 
-/** Independent executable policy for bounded Plastic ignore/cloaking discovery. */
-export function createPlasticRepositorySearchPolicyV1(owner: RepoSearchOwnerV1): RepositoryPolicyV1 {
+/** Advisory filter that supplies bounded Plastic ignore/cloaking data to file discovery. */
+export function createPlasticFileDiscoveryFilterV1(owner: FileDiscoveryOwnerV1): FileDiscoveryFilterV1 {
   return Object.freeze({
-    contractVersion: 1, id: PLASTIC_REPOSITORY_SEARCH_POLICY_ID, kind: "repository-search-policy", owner,
-    async evaluate(context: RepoSearchExecutionContextV1, request: RepositoryPolicyRequestV1): Promise<RepositoryPolicyResultV1> {
+    contractVersion: 1, id: PLASTIC_FILE_DISCOVERY_FILTER_ID, kind: "file-discovery-filter", owner,
+    async evaluate(context: FileDiscoveryExecutionContextV1, request: FileDiscoveryFilterRequestV1): Promise<FileDiscoveryFilterResultV1> {
       throwIfAborted(context.signal);
-      const roots = [] as { root: string; policyOwnedRoot: string; ignoreFiles: string[]; disclosures: string[] }[];
+      const roots: FileDiscoveryAppliedRootV1[] = [];
       for (const root of request.roots) {
         throwIfAborted(context.signal);
         const workspace = await discoverPlasticWorkspace(root);
@@ -42,7 +45,8 @@ export function createPlasticRepositorySearchPolicyV1(owner: RepoSearchOwnerV1):
         const canonicalWorkspace = await realpath(workspace.value.root).catch(() => undefined);
         if (!canonicalRoot || !canonicalWorkspace || !isWithin(canonicalWorkspace, canonicalRoot)) return { outcome: "error", code: "plastic_workspace_boundary_invalid", retryable: false };
         const ignoreFiles = await discoverIgnoreFiles(canonicalWorkspace, canonicalRoot, context.signal);
-        roots.push({ root: canonicalRoot, policyOwnedRoot: canonicalWorkspace, ignoreFiles, disclosures: [ignoreFiles.length ? `Plastic ignore policy applied (${ignoreFiles.length} file${ignoreFiles.length === 1 ? "" : "s"}).` : "Plastic workspace detected; no readable ignore.conf or cloaked.conf found."] });
+        if (ignoreFiles.length === 0) continue;
+        roots.push({ root: canonicalRoot, filterDecision: "applied", decisionCode: PLASTIC_IGNORE_FILES_APPLIED_CODE, filterBoundary: canonicalWorkspace, ignoreFiles, disclosures: [`Plastic ignore filter applied (${ignoreFiles.length} readable file${ignoreFiles.length === 1 ? "" : "s"}).`] });
       }
       return roots.length ? { outcome: "applied", roots } : { outcome: "not_applicable" };
     },