@aefree/pi-plastic 0.4.0

package/src/plastic-tool-loading.ts

@@ -0,0 +1,234 @@
+import { resolve } from "node:path";
+
+export const PLASTIC_TOOL_LOADING_MODE_ENV = "PI_PLASTIC_TOOL_LOADING_MODE";
+export const PLASTIC_TOOL_SEARCH_NAME = "plastic_tool_search";
+export const BALANCED_ACTIVE_PLASTIC_TOOL_NAMES = ["plastic_status", "plastic_currentBranch"] as const;
+export const MAX_PLASTIC_TOOL_SEARCH_RESULTS = 4;
+
+export type PlasticToolLoadingMode = "balanced" | "loader-only" | "all-active";
+
+export type PlasticSearchCatalogEntry = {
+  name: string;
+  aliases: readonly string[];
+  tags: readonly string[];
+  guidance: readonly string[];
+};
+
+/**
+ * Package-owned executable capability vocabulary. `plastic_diff` deliberately
+ * remains outside this catalog: it is registered for compatibility, but is a
+ * disabled alias rather than a safe executable diff capability.
+ */
+export const PLASTIC_SEARCH_CATALOG: readonly PlasticSearchCatalogEntry[] = [
+  { name: "plastic_status", aliases: ["status", "pending changes", "working changes", "what changed", "changed files", "list changes"], tags: ["workspace", "inspect", "changes"], guidance: ["Use machineReadable=true to list changed, added, moved, deleted, and private paths without invoking GUI-capable cm diff."] },
+  { name: "plastic_update", aliases: ["update", "sync", "pull latest"], tags: ["workspace", "synchronize", "safe"], guidance: ["Review pending changes before updating a workspace."] },
+  { name: "plastic_add", aliases: ["add files", "track files", "add item"], tags: ["workspace", "changes", "mutation"], guidance: ["Confirm the intended paths before adding them to source control."] },
+  { name: "plastic_checkin", aliases: ["checkin", "check in", "commit changes"], tags: ["changes", "mutation", "changeset"], guidance: ["Inspect the selected paths and checkin message before creating a changeset."] },
+  { name: "plastic_undo", aliases: ["undo changes", "revert changes", "discard changes"], tags: ["changes", "mutation", "destructive"], guidance: ["Confirm the exact paths before discarding pending changes."] },
+  { name: "plastic_resolveDeleteChangeConflict", aliases: ["resolve delete conflict", "deleted conflict"], tags: ["merge", "conflict", "resolution"], guidance: ["Inspect the conflict and choose whether files should remain on disk before resolving it."] },
+  { name: "plastic_patch", aliases: ["patch", "generate patch", "review patch"], tags: ["diff", "patch", "export"], guidance: ["Inspect generated patches before sharing because they can include source, paths, or secrets."] },
+  { name: "plastic_diffFile", aliases: ["diff", "diff file", "file diff", "workspace diff", "compare file"], tags: ["diff", "file", "workspace", "inspect"], guidance: ["For the common workspace diff, pass path and omit revision; use a documented changeset, branch, label, file-qualified, or global revision only when needed."] },
+  { name: "plastic_diffRevisions", aliases: ["diff revisions", "compare revisions", "revision diff"], tags: ["diff", "revision", "inspect"], guidance: ["Use this only for two explicit file-qualified revision specifications."] },
+  { name: "plastic_branchCreate", aliases: ["create branch", "new branch"], tags: ["branch", "mutation", "workflow"], guidance: ["Create normal work branches beneath an intended parent, which may differ from the loaded branch. Use allowRootBranch only for intentional top-level branches."] },
+  { name: "plastic_switchBranch", aliases: ["switch branch", "checkout branch", "change branch"], tags: ["branch", "workspace", "mutation"], guidance: ["Check pending changes and choose how to handle them before switching branches."] },
+  { name: "plastic_merge", aliases: ["merge branch", "merge changes"], tags: ["merge", "conflict", "workflow"], guidance: ["Inspect merge state and resolve conflicts before checkin."] },
+  { name: "plastic_mergeToBranch", aliases: ["merge to branch", "close branch", "merge closeout"], tags: ["merge", "branch", "closeout"], guidance: ["Confirm source and target branches before the non-interactive merge closeout flow."] },
+  { name: "plastic_finalizeMerge", aliases: ["finalize merge", "complete merge", "resolve merge"], tags: ["merge", "conflict", "finalize"], guidance: ["Use after reviewed manual conflict resolution when Plastic still needs merge metadata finalized."] },
+  { name: "plastic_currentBranch", aliases: ["current branch", "which branch", "branch name"], tags: ["branch", "workspace", "inspect"], guidance: ["Inspect the current branch before branch, merge, or checkin operations."] },
+  { name: "plastic_branchList", aliases: ["list branches", "find branch", "branches"], tags: ["branch", "inspect", "query"], guidance: ["Use the returned full branch paths when selecting a branch for another operation."] },
+  { name: "plastic_branchExists", aliases: ["branch exists", "check branch", "verify branch"], tags: ["branch", "inspect", "query"], guidance: ["Verify the full branch path before creating, switching, merging, or deleting."] },
+  { name: "plastic_branchDelete", aliases: ["delete branch", "remove branch"], tags: ["branch", "mutation", "destructive"], guidance: ["Confirm the full branch path and whether its changesets may be deleted before deleting it."] },
+  { name: "plastic_shelvesetCreate", aliases: ["create shelveset", "shelve changes", "stash changes"], tags: ["shelveset", "changes", "mutation"], guidance: ["Inspect selected pending changes and shelveset comments before shelving."] },
+  { name: "plastic_shelvesetApply", aliases: ["apply shelveset", "unshelve", "restore shelveset"], tags: ["shelveset", "changes", "mutation"], guidance: ["Check the target workspace and pending changes before applying a shelveset."] },
+  { name: "plastic_shelvesetDelete", aliases: ["delete shelveset", "remove shelveset"], tags: ["shelveset", "mutation", "destructive"], guidance: ["Confirm the shelveset identifier before deleting it."] },
+  { name: "plastic_shelvesetList", aliases: ["list shelvesets", "find shelveset", "shelvesets"], tags: ["shelveset", "inspect", "query"], guidance: ["Inspect shelveset ownership and comments before applying or deleting one."] },
+  { name: "plastic_codeReviewCreate", aliases: ["create code review", "new review"], tags: ["review", "code review", "mutation"], guidance: ["Confirm review targets, title, and reviewers before creating a code review."] },
+  { name: "plastic_codeReviewUpdate", aliases: ["update code review", "edit review"], tags: ["review", "code review", "mutation"], guidance: ["Confirm the review ID and requested fields before updating a code review."] },
+  { name: "plastic_codeReviewDelete", aliases: ["delete code review", "remove review"], tags: ["review", "code review", "mutation", "destructive"], guidance: ["Confirm review IDs before deleting code reviews."] },
+  { name: "plastic_codeReviewFind", aliases: ["find code review", "list reviews", "search reviews"], tags: ["review", "code review", "inspect", "query"], guidance: ["Use filters to identify the intended review before changing or deleting it."] },
+  { name: "plastic_workspaceList", aliases: ["list workspaces", "find workspace", "workspaces"], tags: ["workspace", "inspect", "query"], guidance: ["Inspect workspace paths and repository identity before using a workspace in a mutation."] },
+] as const;
+
+export const PLASTIC_COMPATIBILITY_TOOL_NAMES = ["plastic_diff"] as const;
+export const PLASTIC_SEARCHABLE_TOOL_NAMES = new Set(PLASTIC_SEARCH_CATALOG.map((entry) => entry.name));
+export const PLASTIC_TOOL_NAMES = new Set([...PLASTIC_SEARCHABLE_TOOL_NAMES, ...PLASTIC_COMPATIBILITY_TOOL_NAMES]);
+
+export type ToolSourceInfo = {
+  path: string;
+  source: string;
+  scope: string;
+  origin: string;
+  baseDir?: string;
+};
+
+export type PlasticToolInfo = { name?: unknown; sourceInfo?: unknown };
+export type PlasticToolOwnership = { ownedToolNames: Set<string>; usesSourceInfo: boolean };
+
+export function getPlasticToolLoadingMode(value = process.env[PLASTIC_TOOL_LOADING_MODE_ENV]): PlasticToolLoadingMode {
+  switch (value?.trim().toLowerCase()) {
+    case "all-active": return "all-active";
+    case "loader-only": return "loader-only";
+    default: return "balanced";
+  }
+}
+
+export function getInitiallyInactivePlasticTools(mode: PlasticToolLoadingMode): Set<string> {
+  if (mode === "all-active") return new Set();
+  if (mode === "loader-only") return new Set(PLASTIC_TOOL_NAMES);
+  return new Set([...PLASTIC_TOOL_NAMES].filter((name) => !BALANCED_ACTIVE_PLASTIC_TOOL_NAMES.includes(name as typeof BALANCED_ACTIVE_PLASTIC_TOOL_NAMES[number])));
+}
+
+function asSourceInfo(value: unknown): ToolSourceInfo | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  const candidate = value as Partial<ToolSourceInfo>;
+  return typeof candidate.path === "string" && typeof candidate.source === "string" && typeof candidate.scope === "string" && typeof candidate.origin === "string"
+    ? candidate as ToolSourceInfo
+    : undefined;
+}
+
+function normalizeSourcePath(value: string): string {
+  const normalized = value.replaceAll("\\", "/").replace(/\/$/, "");
+  return /^[a-z]:\//i.test(normalized) ? normalized.toLowerCase() : normalized;
+}
+
+function resolveSourcePath(sourceInfo: ToolSourceInfo): string {
+  return normalizeSourcePath(resolve(sourceInfo.baseDir ?? process.cwd(), sourceInfo.path));
+}
+
+function hasSourcePath(tool: PlasticToolInfo, expectedSourcePath: string): boolean {
+  const sourceInfo = asSourceInfo(tool.sourceInfo);
+  return Boolean(sourceInfo && resolveSourcePath(sourceInfo) === normalizeSourcePath(resolve(expectedSourcePath)));
+}
+
+/**
+ * Pi 0.82 exposes effective tool provenance. Compare effective definitions to
+ * this module's own import path, so even a foreign first-registration-wins
+ * collision on the public loader name cannot become an ownership anchor.
+ * Without that proof, callers preserve the active set unchanged.
+ */
+export function getEffectivePlasticToolOwnership(allTools: readonly PlasticToolInfo[], expectedSourcePath: string): PlasticToolOwnership {
+  const effectiveLoader = allTools.find((tool) => tool.name === PLASTIC_TOOL_SEARCH_NAME);
+  if (!effectiveLoader || !hasSourcePath(effectiveLoader, expectedSourcePath)) {
+    return { ownedToolNames: new Set(), usesSourceInfo: false };
+  }
+
+  return {
+    ownedToolNames: new Set(allTools
+      .filter((tool) => typeof tool.name === "string" && PLASTIC_TOOL_NAMES.has(tool.name))
+      .filter((tool) => hasSourcePath(tool, expectedSourcePath))
+      .map((tool) => tool.name as string)),
+    usesSourceInfo: true,
+  };
+}
+
+export type PlasticToolSearchInput = { query?: unknown; toolNames?: unknown; limit?: unknown };
+export type PlasticToolSearchMatch = PlasticSearchCatalogEntry & { description?: string; score: number };
+
+const SEARCH_STOP_WORDS = new Set(["a", "an", "available", "existing", "for", "my", "of", "the", "this", "to"]);
+const SEARCH_DOMAIN_TERMS = new Set(["branch", "changeset", "diff", "merge", "patch", "review", "shelveset", "workspace"]);
+const MUTATION_INTENT_TERMS = new Set(["add", "apply", "checkin", "create", "delete", "discard", "edit", "finalize", "merge", "remove", "resolve", "switch", "undo", "update"]);
+
+function normalizeSearchToken(token: string): string {
+  if (token.length > 4 && /(?:ch|sh|x|z)es$/.test(token)) return token.slice(0, -2);
+  if (token.length > 3 && token.endsWith("s") && !token.endsWith("ss")) return token.slice(0, -1);
+  return token;
+}
+
+function tokenize(value: string): string[] {
+  return [...new Set(value.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean).map(normalizeSearchToken).filter((token) => !SEARCH_STOP_WORDS.has(token)))];
+}
+
+function exactRequestedNames(value: unknown): Set<string> {
+  if (!Array.isArray(value)) return new Set();
+  return new Set(value.filter((name): name is string => typeof name === "string").map((name) => name.trim().toLowerCase()).filter(Boolean));
+}
+
+export function getUnknownExactPlasticToolNames(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  const knownNames = new Set([...PLASTIC_TOOL_NAMES].map((name) => name.toLowerCase()));
+  return [...new Set(value.filter((name): name is string => typeof name === "string" && name.trim().length > 0)
+    .map((name) => name.trim())
+    .filter((name) => !knownNames.has(name.toLowerCase())))];
+}
+
+function normalizeLimit(value: unknown, requestedNames: ReadonlySet<string>): number {
+  if (typeof value === "number" && Number.isInteger(value)) return Math.max(1, Math.min(MAX_PLASTIC_TOOL_SEARCH_RESULTS, value));
+  return requestedNames.size > 0 ? MAX_PLASTIC_TOOL_SEARCH_RESULTS : 1;
+}
+
+function safetyPriority(entry: PlasticSearchCatalogEntry): number {
+  if (entry.tags.includes("query")) return 0;
+  if (entry.tags.includes("inspect")) return 1;
+  if (entry.tags.includes("mutation")) return 3;
+  return 2;
+}
+
+/** Search the executable catalog with deterministic scoring and safe bare-domain ordering. */
+export function searchPlasticTools(input: PlasticToolSearchInput, descriptions: ReadonlyMap<string, string> = new Map()): PlasticToolSearchMatch[] {
+  const requestedNames = exactRequestedNames(input.toolNames);
+  const terms = typeof input.query === "string" ? tokenize(input.query) : [];
+  const normalizedLimit = normalizeLimit(input.limit, requestedNames);
+  const limit = input.limit === undefined && requestedNames.size === 0 && terms.length === 1 && terms[0] === "diff" ? 2 : normalizedLimit;
+  const domainTerms = terms.filter((term) => SEARCH_DOMAIN_TERMS.has(term));
+  const primaryDomainTerm = domainTerms[0];
+  const mutationIntent = terms.some((term) => MUTATION_INTENT_TERMS.has(term));
+  const preferReadOnly = domainTerms.length > 0 && !mutationIntent;
+
+  return PLASTIC_SEARCH_CATALOG.map((entry, index) => {
+    const description = descriptions.get(entry.name);
+    const nameTokens = new Set(tokenize(entry.name));
+    const aliases = entry.aliases.map(tokenize);
+    const tags = entry.tags.map(tokenize);
+    const descriptionTokens = new Set(tokenize(description ?? ""));
+    const exact = requestedNames.has(entry.name.toLowerCase());
+    let score = exact ? 1000 : 0;
+    let matchedTerms = 0;
+    for (const term of terms) {
+      const nameMatch = nameTokens.has(term);
+      const aliasMatch = aliases.some((alias) => alias.includes(term));
+      const tagMatch = tags.some((tag) => tag.includes(term));
+      const descriptionMatch = descriptionTokens.has(term);
+      if (nameMatch || aliasMatch || tagMatch || descriptionMatch) matchedTerms += 1;
+      if (nameMatch) score += 8;
+      if (aliasMatch) score += 6;
+      if (tagMatch) score += 4;
+      if (descriptionMatch) score += 1;
+    }
+    const domainMatches = primaryDomainTerm && (nameTokens.has(primaryDomainTerm) || aliases.some((alias) => alias.includes(primaryDomainTerm)) || tags.some((tag) => tag.includes(primaryDomainTerm)) || descriptionTokens.has(primaryDomainTerm)) ? 1 : 0;
+    return { ...entry, description, score, matchedTerms, domainMatches, index, exact };
+  })
+    .filter((entry) => entry.exact || entry.score > 0)
+    .filter((entry) => entry.exact || domainTerms.length === 0 || entry.domainMatches > 0)
+    .filter((entry, _index, entries) => {
+      if (entry.exact || terms.length <= 1) return true;
+      const bestCoverage = Math.max(...entries.map((candidate) => candidate.matchedTerms));
+      return entry.matchedTerms === bestCoverage;
+    })
+    .filter((entry) => entry.exact || !preferReadOnly || !entry.tags.includes("mutation"))
+    .sort((left, right) => right.score - left.score || (preferReadOnly ? safetyPriority(left) - safetyPriority(right) : 0) || left.index - right.index)
+    .slice(0, limit)
+    .map(({ matchedTerms: _matchedTerms, domainMatches: _domainMatches, index: _index, exact: _exact, ...entry }) => entry);
+}
+
+const BROAD_PRODUCT_QUERIES = new Set(["plastic", "plastic scm", "unity version control", "version control", "uvcs", "vcs"]);
+
+/** Empty and product-level requests are discovery prompts, never activation requests. */
+export function isPlasticToolBrowseRequest(input: PlasticToolSearchInput): boolean {
+  if (exactRequestedNames(input.toolNames).size > 0) return false;
+  const query = typeof input.query === "string" ? input.query.trim().toLowerCase().replace(/\s+/g, " ") : "";
+  return query.length === 0 || BROAD_PRODUCT_QUERIES.has(query);
+}
+
+export const PLASTIC_TOOL_BROWSE_TEXT = "Browse Plastic capabilities without activating tools: workspace status/sync; changes and checkins; text-only diffs and patches; branches and merges; shelvesets; code reviews; and workspaces. Examples: ‘pending changes’, ‘diff file’, ‘list branches’, or ‘find code reviews’.";
+
+export function getRestoredPlasticToolNames(branchEntries: readonly unknown[], effectiveToolNames: ReadonlySet<string> = PLASTIC_TOOL_NAMES): string[] {
+  const restored = new Set<string>();
+  for (const entry of branchEntries) {
+    const candidate = entry as { type?: unknown; message?: { role?: unknown; addedToolNames?: unknown } };
+    if (candidate.type !== "message" || candidate.message?.role !== "toolResult" || !Array.isArray(candidate.message.addedToolNames)) continue;
+    for (const name of candidate.message.addedToolNames) {
+      if (typeof name === "string" && effectiveToolNames.has(name)) restored.add(name);
+    }
+  }
+  return [...PLASTIC_COMPATIBILITY_TOOL_NAMES, ...PLASTIC_SEARCH_CATALOG.map((entry) => entry.name)].filter((name) => restored.has(name));
+}

package/src/plastic-workspace.ts

@@ -0,0 +1,176 @@
+import { promises as fs } from "node:fs";
+import { dirname, join, parse, resolve } from "node:path";
+
+export type Found<T> = { kind: "found"; value: T };
+export type ParseOutcome<T> = Found<T> | { kind: "not_found" } | { kind: "malformed"; reason: string };
+export type WorkspaceDiscoveryOutcome =
+  | Found<{ root: string; plasticDir: string; markerPath: string }>
+  | { kind: "not_found" }
+  | { kind: "unavailable"; reason: string };
+
+export type PlasticSelector = {
+  branch: string;
+  repository?: string;
+};
+
+export type PlasticStatusBranch = {
+  branch?: string;
+  changesetId?: string;
+};
+
+type WorkspaceFileSystem = {
+  realpath(path: string): Promise<string>;
+  stat(path: string): Promise<{ isFile(): boolean }>;
+};
+
+const defaultWorkspaceFileSystem: WorkspaceFileSystem = {
+  realpath: (path) => fs.realpath(path),
+  stat: (path) => fs.stat(path),
+};
+
+const isMissingPathError = (error: unknown): boolean =>
+  error instanceof Error && ["ENOENT", "ENOTDIR"].includes((error as NodeJS.ErrnoException).code ?? "");
+
+/** Find the nearest enclosing Plastic workspace using only the documented marker. */
+export async function discoverPlasticWorkspace(
+  cwd: string,
+  fileSystem: WorkspaceFileSystem = defaultWorkspaceFileSystem,
+): Promise<WorkspaceDiscoveryOutcome> {
+  let current: string;
+  try {
+    current = await fileSystem.realpath(resolve(cwd));
+  } catch (error) {
+    return {
+      kind: "unavailable",
+      reason: error instanceof Error ? error.message : String(error),
+    };
+  }
+
+  while (true) {
+    const plasticDir = join(current, ".plastic");
+    const markerPath = join(plasticDir, "plastic.workspace");
+    try {
+      if ((await fileSystem.stat(markerPath)).isFile()) {
+        return { kind: "found", value: { root: current, plasticDir, markerPath } };
+      }
+    } catch (error) {
+      if (!isMissingPathError(error)) {
+        return {
+          kind: "unavailable",
+          reason: error instanceof Error ? error.message : String(error),
+        };
+      }
+    }
+
+    const parent = dirname(current);
+    if (parent === current || current === parse(current).root) return { kind: "not_found" };
+    current = parent;
+  }
+}
+
+const parseSelectorValue = (line: string, key: string): string | undefined => {
+  const match = line.match(new RegExp(`^\\s*${key}\\s+(.*?)\\s*$`, "i"));
+  if (!match) return undefined;
+  const value = match[1].replace(/^(["'])(.*)\1$/, "$2").trim();
+  return value;
+};
+
+/** Parse the local selector without treating it as proof that a workspace exists. */
+export function parsePlasticSelector(content: string): ParseOutcome<PlasticSelector> {
+  let repository: string | undefined;
+  let branch: string | undefined;
+  let sawBranchKey = false;
+
+  for (const line of content.split(/\r?\n/)) {
+    if (/^\s*(?:#|$)/.test(line)) continue;
+    if (/^\s*repository(?:\s|$)/i.test(line)) repository = parseSelectorValue(line, "repository");
+    if (/^\s*smartbranch(?:\s|$)/i.test(line)) {
+      sawBranchKey = true;
+      branch = parseSelectorValue(line, "smartbranch");
+    }
+  }
+
+  if (!sawBranchKey) return { kind: "not_found" };
+  if (!branch || /[\u0000-\u001f\u007f]/.test(branch)) {
+    return { kind: "malformed", reason: "Selector smartbranch is blank or contains control characters." };
+  }
+
+  return {
+    kind: "found",
+    value: { branch, ...(repository ? { repository } : {}) },
+  };
+}
+
+const nonEmptyLines = (output: string): string[] => output.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+
+const normalizeStatusBranch = (branch: string): string =>
+  branch.trim().replace(/^br:/i, "").replace(/@[^@\s)]+(?:@[^@\s)]+)*$/, "");
+
+/** Parse normal or compact `cm status` output into an unqualified branch path. */
+export function parsePlasticStatusBranch(output: string): ParseOutcome<PlasticStatusBranch> {
+  const lines = nonEmptyLines(output);
+  if (lines.length === 0) return { kind: "not_found" };
+
+  const workspaceMatch = lines[0].match(/^([^@\s]+)@/);
+  if (workspaceMatch) return { kind: "found", value: { branch: normalizeStatusBranch(workspaceMatch[1]) } };
+
+  for (const line of lines) {
+    const branchSpec = line.match(/\bbr:[^\s)]+/i);
+    if (branchSpec) return { kind: "found", value: { branch: normalizeStatusBranch(branchSpec[0]) } };
+
+    const branchLine = line.match(/^branch\s*[:=]\s*(.+)$/i);
+    if (branchLine?.[1]?.trim()) return { kind: "found", value: { branch: normalizeStatusBranch(branchLine[1]) } };
+  }
+
+  const changeset = output.match(/\bcs:(\d+)/i);
+  if (changeset) return { kind: "found", value: { changesetId: changeset[1] } };
+
+  return { kind: "malformed", reason: "Status output contains no recognized branch or changeset." };
+}
+
+const isCombining = (codePoint: number): boolean =>
+  (codePoint >= 0x0300 && codePoint <= 0x036f)
+  || (codePoint >= 0x1ab0 && codePoint <= 0x1aff)
+  || (codePoint >= 0x1dc0 && codePoint <= 0x1dff)
+  || (codePoint >= 0xfe20 && codePoint <= 0xfe2f);
+
+const isWide = (codePoint: number): boolean =>
+  codePoint >= 0x1100 && (
+    codePoint <= 0x115f || codePoint === 0x2329 || codePoint === 0x232a
+    || (codePoint >= 0x2e80 && codePoint <= 0xa4cf && codePoint !== 0x303f)
+    || (codePoint >= 0xac00 && codePoint <= 0xd7a3)
+    || (codePoint >= 0xf900 && codePoint <= 0xfaff)
+    || (codePoint >= 0xfe10 && codePoint <= 0xfe19)
+    || (codePoint >= 0xfe30 && codePoint <= 0xfe6f)
+    || (codePoint >= 0xff00 && codePoint <= 0xff60)
+    || (codePoint >= 0xffe0 && codePoint <= 0xffe6)
+    || (codePoint >= 0x1f300 && codePoint <= 0x1faff)
+  );
+
+export function sanitizePlasticBranch(branch: string, maxColumns = 80): string {
+  const clean = branch.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ").replace(/\s+/g, " ").trim();
+  if (maxColumns <= 0) return "";
+
+  let width = 0;
+  let result = "";
+  let truncated = false;
+  for (const character of clean) {
+    const codePoint = character.codePointAt(0) ?? 0;
+    const characterWidth = isCombining(codePoint) ? 0 : isWide(codePoint) ? 2 : 1;
+    if (width + characterWidth > maxColumns) {
+      truncated = true;
+      break;
+    }
+    result += character;
+    width += characterWidth;
+  }
+
+  if (!truncated) return result;
+  while (result && width > maxColumns - 1) {
+    const character = Array.from(result).pop()!;
+    result = Array.from(result).slice(0, -1).join("");
+    const codePoint = character.codePointAt(0) ?? 0;
+    width -= isCombining(codePoint) ? 0 : isWide(codePoint) ? 2 : 1;
+  }
+  return `${result}…`;
+}

package/src/repository-search-provider.ts

@@ -0,0 +1,64 @@
+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
+// 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 =
+  | 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: "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> }>;
+import { discoverPlasticWorkspace } from "./plastic-workspace.ts";
+
+export const PLASTIC_REPOSITORY_SEARCH_POLICY_ID = "plastic.ignore-files" as const;
+
+/** Resolve this physical package copy's identity for repository-search registration. */
+export async function loadPlasticOwnerV1(moduleUrl: string = import.meta.url): Promise<RepoSearchOwnerV1> {
+  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 };
+  if (manifest.name !== "@aefree/pi-plastic" || typeof manifest.version !== "string" || manifest.version.trim() === "") throw new Error(`Invalid @aefree/pi-plastic package identity at ${packageRoot}.`);
+  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 {
+  return Object.freeze({
+    contractVersion: 1, id: PLASTIC_REPOSITORY_SEARCH_POLICY_ID, kind: "repository-search-policy", owner,
+    async evaluate(context: RepoSearchExecutionContextV1, request: RepositoryPolicyRequestV1): Promise<RepositoryPolicyResultV1> {
+      throwIfAborted(context.signal);
+      const roots = [] as { root: string; policyOwnedRoot: string; ignoreFiles: string[]; disclosures: string[] }[];
+      for (const root of request.roots) {
+        throwIfAborted(context.signal);
+        const workspace = await discoverPlasticWorkspace(root);
+        if (workspace.kind === "unavailable") return { outcome: "unavailable", code: "plastic_workspace_unavailable", retryable: true };
+        if (workspace.kind !== "found") continue;
+        const canonicalRoot = await realpath(root).catch(() => undefined);
+        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."] });
+      }
+      return roots.length ? { outcome: "applied", roots } : { outcome: "not_applicable" };
+    },
+  });
+}
+
+async function discoverIgnoreFiles(workspaceRoot: string, root: string, signal: AbortSignal): Promise<string[]> {
+  const stats = await stat(root); let current = stats.isDirectory() ? root : dirname(root); const directories: string[] = [];
+  while (true) { directories.push(current); if (samePath(current, workspaceRoot)) break; const parent = dirname(current); if (parent === current || !isWithin(workspaceRoot, parent)) break; current = parent; }
+  directories.reverse(); const files: string[] = [];
+  for (const directory of directories) for (const name of ["ignore.conf", "cloaked.conf"]) {
+    throwIfAborted(signal); const candidate = join(directory, name);
+    try { if ((await stat(candidate)).isFile()) { await access(candidate, fsConstants.R_OK); files.push(candidate); } } catch (error) { const code = (error as NodeJS.ErrnoException).code; if (code !== "ENOENT" && code !== "ENOTDIR") throw error; }
+  }
+  return files;
+}
+function isWithin(root: string, target: string): boolean { const normalizedRoot = root.replaceAll("\\", "/").replace(/\/$/, ""); const normalizedTarget = target.replaceAll("\\", "/"); return normalizedTarget === normalizedRoot || normalizedTarget.startsWith(`${normalizedRoot}/`); }
+function samePath(a: string, b: string): boolean { return process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b; }
+function throwIfAborted(signal: AbortSignal): void { if (signal.aborted) { const error = new Error("Operation cancelled."); error.name = "AbortError"; throw error; } }

package/tests/bash-cm-diff-guard-validation.ts

@@ -0,0 +1,55 @@
+import { __bashCmDiffGuardInternals } from "../extensions/bash-cm-diff-guard.ts";
+
+const assert = (condition: boolean, message: string): void =>
+{
+    if (!condition)
+    {
+        throw new Error(message);
+    }
+};
+
+const expectBlocked = (command: string): void =>
+{
+    assert(
+        __bashCmDiffGuardInternals.commandRunsCmDiff(command),
+        `Expected command to be blocked: ${command}`,
+    );
+};
+
+const expectAllowed = (command: string): void =>
+{
+    assert(
+        !__bashCmDiffGuardInternals.commandRunsCmDiff(command),
+        `Expected command to be allowed: ${command}`,
+    );
+};
+
+const main = (): void =>
+{
+    expectBlocked("cm diff cs:123");
+    expectBlocked("env FOO=bar cm diff cs:123");
+    expectBlocked("command cm diff cs:123");
+    expectBlocked("sudo cm diff cs:123");
+    expectBlocked("time cm diff cs:123");
+    expectBlocked("nice -n 5 cm diff cs:123");
+    expectBlocked("zsh -lc \"cm diff cs:123\"");
+    expectBlocked("zsh -c \"cm diff cs:123\"");
+    expectBlocked("zsh -lc \"command cm diff cs:123\"");
+    expectBlocked("bash -lc \"env FOO=bar cm diff cs:123\"");
+    expectBlocked("cmd /c \"cm diff cs:123\"");
+    expectBlocked("cmd /c cm diff cs:123");
+    expectBlocked("pwsh -command \"cm diff cs:123\"");
+    expectBlocked("powershell -command cm diff cs:123");
+    expectBlocked("\"C:\\Program Files\\PlasticSCM5\\client\\cm.exe\" diff cs:123");
+    expectBlocked("cm status & cm diff cs:123");
+    expectBlocked("cm status\ncm diff cs:123");
+
+    expectAllowed("cm status");
+    expectAllowed("cm merge br:/main");
+    expectAllowed("git diff --stat");
+    expectAllowed("zsh -lc \"cm status\"");
+
+    console.log("PASS: bash cm diff guard validation succeeded");
+};
+
+main();

package/tests/fixtures/plastic.selector

@@ -0,0 +1,3 @@
+repository sanitized-repository@sanitized-server
+  path /
+    smartbranch /main/feature/footer

package/tests/fixtures/status-compact.txt

@@ -0,0 +1 @@
+Workspace status for cs:42@br:/main/feature/footer@sanitized-repository@sanitized-server

package/tests/fixtures/status-normal.txt

@@ -0,0 +1 @@
+/main/feature/footer@sanitized-repository@sanitized-server (cs:42 - head)

package/tests/packed-copy-owner-conflict.test.ts

@@ -0,0 +1,28 @@
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { spawnSync } from "node:child_process";
+import { createPlasticRepositorySearchPolicyV1, loadPlasticOwnerV1 } from "../src/repository-search-provider.ts";
+
+const temp = await mkdtemp(path.join(tmpdir(), "pi-plastic-packed-copies-"));
+try {
+  const npmCli = process.env.npm_execpath ?? (process.platform === "win32" ? path.join(process.env.APPDATA!, "npm", "node_modules", "npm", "bin", "npm-cli.js") : "/usr/lib/node_modules/npm/bin/npm-cli.js");
+  const packed = spawnSync(process.execPath, [npmCli, "pack", "--json", "--pack-destination", temp], { cwd: path.join(import.meta.dirname, ".."), encoding: "utf8", shell: false });
+  assert.equal(packed.status, 0, packed.stderr);
+  const filename = JSON.parse(packed.stdout)[0].filename as string;
+  const first = path.join(temp, "first"); const second = path.join(temp, "second");
+  await mkdir(first); await mkdir(second);
+  for (const destination of [first, second]) {
+    const extracted = spawnSync("tar", ["-xf", filename, "-C", path.basename(destination), "package/package.json", "package/extensions/repository-search-provider.ts"], { cwd: temp, encoding: "utf8", shell: false });
+    assert.equal(extracted.status, 0, extracted.stderr);
+  }
+  const entry = (root: string) => pathToFileURL(path.join(root, "package", "extensions", "repository-search-provider.ts")).href;
+  const ownerOne = await loadPlasticOwnerV1(entry(first));
+  const ownerTwo = await loadPlasticOwnerV1(entry(second));
+  assert.notEqual(ownerOne.packageRoot, ownerTwo.packageRoot);
+  assert.equal(ownerOne.packageVersion, ownerTwo.packageVersion);
+  assert.equal(createPlasticRepositorySearchPolicyV1(ownerOne).id, createPlasticRepositorySearchPolicyV1(ownerTwo).id);
+} finally { await rm(temp, { recursive: true, force: true }); }
+console.log("PASS: two packed physical pi-plastic copies retain distinct owner roots");