@aefree/pi-plastic 0.4.0

package/tests/plastic-checkin-path-resolution.ts

@@ -0,0 +1,219 @@
+import { __plasticCheckinInternals, __plasticSwitchInternals } from "../src/plastic-core.ts";
+
+const assert = (condition: boolean, message: string): void =>
+{
+    if (!condition)
+    {
+        throw new Error(message);
+    }
+};
+
+const normalizePath = (pathValue: string): string => pathValue.replace(/\\/g, "/").replace(/^[A-Za-z]:/, "");
+const pathMatches = (actualPath: string, expectedPath: string): boolean =>
+{
+    const actual = normalizePath(actualPath);
+    const expected = normalizePath(expectedPath);
+    return actual === expected || actual.endsWith(`/${expected}`);
+};
+
+const main = (): void =>
+{
+    const cwd = "/repo/ws";
+    const machineOutput = [
+        "STATUS 123 Normandie/Repo server",
+        "CH /repo/ws/Assets/Gameplay/Movement.cs False NO_MERGES",
+        "LD /repo/ws/Assets/Gameplay/FakeModifierService.cs False NO_MERGES",
+        "MV /repo/ws/Assets/Gameplay/MockModifierService.cs False NO_MERGES",
+        "CH /repo/ws/ProjectSettings/ProjectSettings.asset False NO_MERGES",
+    ].join("\n");
+
+    const pendingItems = __plasticCheckinInternals.parseMachineReadablePendingItems(machineOutput, cwd);
+    assert(pendingItems.length === 4, "Expected parser to return four pending items.");
+    assert(pendingItems.some((item) => item.kind === "deleted"), "Expected at least one deleted pending item.");
+    assert(pendingItems.some((item) => item.kind === "moved"), "Expected at least one moved pending item.");
+    assert(__plasticCheckinInternals.inferPendingItemKind("CO+RP") === "changed", "Expected CO+RP to classify as changed.");
+
+    const pendingSummary = __plasticCheckinInternals.summarizePendingItems(pendingItems, cwd);
+    assert(pendingSummary.totalPending === 4, "Expected pending summary total count to match parsed items.");
+    assert(pendingSummary.tracked === 4, "Expected tracked count to equal total when no private items exist.");
+    assert(pendingSummary.private === 0, "Expected no private items in initial sample summary.");
+
+    const changedOnly = __plasticCheckinInternals.resolveCheckinPaths([
+        "Assets/Gameplay/Movement.cs",
+    ], pendingItems, cwd);
+    assert(changedOnly.includedPaths.length === 1, "Expected one included path for changed file scope.");
+    assert(pathMatches(changedOnly.includedPaths[0], "Assets/Gameplay/Movement.cs"), "Expected changed file path to be preserved.");
+    assert(changedOnly.shouldApplyChanged === false, "Expected changed-only scope to avoid auto --applychanged.");
+
+    const deletedOnly = __plasticCheckinInternals.resolveCheckinPaths([
+        "Assets/Gameplay/FakeModifierService.cs",
+    ], pendingItems, cwd);
+    assert(deletedOnly.includedPaths.length === 1, "Expected one included path for deleted file scope.");
+    assert(pathMatches(deletedOnly.includedPaths[0], "Assets/Gameplay/FakeModifierService.cs"), "Expected deleted-file scope to preserve the requested path before fallback retry.");
+    assert(deletedOnly.shouldApplyChanged, "Expected deleted-file scope to enable --applychanged.");
+    assert(deletedOnly.fallbackPaths.length === 1 && pathMatches(deletedOnly.fallbackPaths[0], "Assets/Gameplay"),
+           "Expected deleted-file fallback scope to target the parent directory.");
+
+    const directoryScope = __plasticCheckinInternals.resolveCheckinPaths([
+        "Assets/Gameplay",
+    ], pendingItems, cwd);
+    assert(directoryScope.includedPaths.length === 1, "Expected one included path for directory scope.");
+    assert(pathMatches(directoryScope.includedPaths[0], "Assets/Gameplay"), "Expected directory scope to remain stable.");
+    assert(directoryScope.shouldApplyChanged, "Expected directory scope with deleted/moved items to enable --applychanged.");
+
+    const noMatch = __plasticCheckinInternals.resolveCheckinPaths([
+        "Assets/UI/Nope.cs",
+    ], pendingItems, cwd);
+    assert(noMatch.includedPaths.length === 0, "Expected no included paths for unmatched scope.");
+    assert(noMatch.excludedPaths.length === 1, "Expected one excluded path for unmatched scope.");
+    assert(noMatch.excludedPaths[0].reason === "no_pending_changes", "Expected unmatched scope reason to be no_pending_changes.");
+
+    const windowsCwd = "C:/Workspaces/GameProject/ws3";
+    const windowsMachineOutput = [
+        "STATUS 1147 ExampleRepo/game-unity example@server",
+        "CH c:/Workspaces/GameProject/ws3/game-unity/Assets/Game/code/Runtime/Paths.cs False NO_MERGES",
+        "CH c:/Workspaces/GameProject/ws3/game-unity/Assets/Game/code/Editor/Validation/MapGraphValidationBatchTools.cs False NO_MERGES",
+    ].join("\n");
+    const windowsPendingItems = __plasticCheckinInternals.parseMachineReadablePendingItems(windowsMachineOutput, windowsCwd);
+    assert(windowsPendingItems.length === 2, "Expected Windows parser sample to return two pending items.");
+
+    const windowsRelativeScope = __plasticCheckinInternals.resolveCheckinPaths([
+        "game-unity/Assets/Game/code/Runtime/Paths.cs",
+    ], windowsPendingItems, windowsCwd);
+    assert(windowsRelativeScope.includedPaths.length === 1, "Expected Windows relative scope to match pending file despite drive-letter case mismatch.");
+    assert(pathMatches(windowsRelativeScope.includedPaths[0], "game-unity/Assets/Game/code/Runtime/Paths.cs"), "Expected Windows relative scope to keep workspace-relative command path.");
+
+    const windowsAbsoluteScope = __plasticCheckinInternals.resolveCheckinPaths([
+        "C:/Workspaces/GameProject/ws3/game-unity/Assets/Game/code/Runtime/Paths.cs",
+    ], windowsPendingItems, windowsCwd);
+    assert(windowsAbsoluteScope.includedPaths.length === 1, "Expected Windows absolute scope to match pending file despite drive-letter case mismatch.");
+    assert(pathMatches(windowsAbsoluteScope.includedPaths[0], "game-unity/Assets/Game/code/Runtime/Paths.cs"), "Expected Windows absolute scope to collapse back to workspace-relative command path.");
+
+    const windowsDirectoryScope = __plasticCheckinInternals.resolveCheckinPaths([
+        "GAME-UNITY/Assets/Game/code/Editor",
+    ], windowsPendingItems, windowsCwd);
+    assert(windowsDirectoryScope.includedPaths.length === 1, "Expected Windows directory scope to match pending children despite path case differences.");
+    assert(pathMatches(windowsDirectoryScope.includedPaths[0], "GAME-UNITY/Assets/Game/code/Editor"), "Expected Windows directory scope to preserve the requested command path casing.");
+
+    const windowsDuplicateScope = __plasticCheckinInternals.resolveCheckinPaths([
+        "GAME-UNITY/Assets/Game/code/Runtime/Paths.cs",
+        "game-unity/Assets/Game/code/Runtime/Paths.cs",
+    ], windowsPendingItems, windowsCwd);
+    assert(windowsDuplicateScope.includedPaths.length === 1, "Expected Windows duplicate scopes that differ only by case to dedupe to one command path.");
+
+    assert(__plasticCheckinInternals.isSameFilesystemDevice(100, 100), "Expected Darwin case probing to remain on the target filesystem device.");
+    assert(!__plasticCheckinInternals.isSameFilesystemDevice(100, 200), "Expected Darwin case probing to stop before crossing a mount-device boundary.");
+
+    const comparisonPath = "/Volumes/Workspace/Assets/Player.cs";
+    const darwinInsensitiveKey = __plasticCheckinInternals.toPathComparisonKeyFromAbsolutePath(comparisonPath, {
+        platform: "darwin",
+        isDarwinCaseInsensitiveVolume: () => true,
+    });
+    const darwinSensitiveKey = __plasticCheckinInternals.toPathComparisonKeyFromAbsolutePath(comparisonPath, {
+        platform: "darwin",
+        isDarwinCaseInsensitiveVolume: () => false,
+    });
+    assert(darwinInsensitiveKey === comparisonPath.toLowerCase(), "Expected a detected case-insensitive Darwin volume to normalize comparison keys.");
+    assert(darwinSensitiveKey === comparisonPath, "Expected a case-sensitive APFS volume to preserve comparison-key casing.");
+    assert(__plasticCheckinInternals.toPathComparisonKeyFromAbsolutePath("C:/Workspace/Assets/Player.cs", {
+        platform: "darwin",
+        isDarwinCaseInsensitiveVolume: () => false,
+    }) === "c:/workspace/assets/player.cs", "Expected Windows drive paths to remain case-insensitive on every host platform.");
+
+    const gameplayScope = pendingItems.find((item) => item.workspacePath.endsWith("Movement.cs"))?.normalizedPath.replace(/\/Movement\.cs$/, "") ?? "";
+    const scopedPendingItems = __plasticCheckinInternals.filterPendingItemsByScope(
+        pendingItems,
+        gameplayScope.length > 0 ? [gameplayScope] : [],
+    );
+    assert(scopedPendingItems.length === 3, "Expected scope-filter helper to return only pending items under the requested path.");
+
+    const fallbackPaths = __plasticCheckinInternals.buildFallbackScopePaths([
+        "/repo/ws/Assets/Gameplay/Movement.cs",
+        "/repo/ws/Assets/Gameplay/FakeModifierService.cs",
+    ], cwd);
+    assert(fallbackPaths.length === 1 && pathMatches(fallbackPaths[0], "Assets/Gameplay"), "Expected fallback paths to collapse to the common parent scope.");
+
+    const normalizedDiffRevision = __plasticCheckinInternals.normalizeDiffFileRevisionSpec(
+        "Assets/Gameplay/Movement.cs",
+        "cs:947",
+    );
+    assert(normalizedDiffRevision === "Assets/Gameplay/Movement.cs#cs:947", "Expected diff-file revision shorthand to be expanded with path scope.");
+
+    const numericDiffRevision = __plasticCheckinInternals.normalizeDiffFileRevisionSpec(
+        "Assets/Gameplay/Movement.cs",
+        "947",
+    );
+    assert(numericDiffRevision === "Assets/Gameplay/Movement.cs#cs:947", "Expected numeric diff-file revision shorthand to normalize to cs: selector.");
+
+    const scopedRevision = __plasticCheckinInternals.normalizeDiffFileRevisionSpec(
+        "Assets/Gameplay/Movement.cs",
+        "Assets/Gameplay/Movement.cs#cs:947",
+    );
+    assert(scopedRevision === "Assets/Gameplay/Movement.cs#cs:947", "Expected already scoped revision to remain unchanged.");
+
+    assert(__plasticCheckinInternals.isUnscopedDiffRevisionSpec("cs:947"), "Expected cs selector without file scope to be detected as unscoped.");
+    assert(__plasticCheckinInternals.isUnscopedDiffRevisionSpec("947"), "Expected numeric selector without file scope to be detected as unscoped.");
+    assert(!__plasticCheckinInternals.isUnscopedDiffRevisionSpec("Assets/Gameplay/Movement.cs#cs:947"), "Expected file-qualified selector not to be treated as unscoped.");
+
+    assert(__plasticCheckinInternals.isGitUnknownOptionLabelError("error: unknown option `label'"), "Expected backtick-style git unknown-option error to be detected.");
+    assert(__plasticCheckinInternals.isGitUnknownOptionLabelError("error: unknown option 'label'"), "Expected single-quote-style git unknown-option error to be detected.");
+    assert(!__plasticCheckinInternals.isGitUnknownOptionLabelError("fatal: unrelated error"), "Expected unrelated git errors not to match label-option detector.");
+
+    assert(__plasticCheckinInternals.isRevisionNotFoundError("The specified revision was not found foo#cs:1"), "Expected revision-not-found detector to match Plastic cat errors.");
+    assert(!__plasticCheckinInternals.isRevisionNotFoundError("fatal: unrelated error"), "Expected unrelated errors not to match revision-not-found detector.");
+
+    const branchSelectorFromRevision = __plasticCheckinInternals.extractBranchSelectorFromRevision("Assets/Gameplay/Movement.cs#br:/dev/task-123");
+    assert(branchSelectorFromRevision === "br:/dev/task-123", "Expected branch selector extraction from file-qualified revision.");
+    assert(__plasticCheckinInternals.extractBranchSelectorFromRevision("Assets/Gameplay/Movement.cs#cs:947") === null, "Expected no branch selector extraction for non-branch revisions.");
+
+    const branchName = __plasticCheckinInternals.extractBranchNameFromSelector("br:/dev/task-123@Repo@server");
+    assert(branchName === "/dev/task-123", "Expected branch selector repository suffix to be removed.");
+    assert(__plasticCheckinInternals.extractBranchNameFromSelector("br:") === null, "Expected invalid branch selector to return null branch name.");
+
+    assert(__plasticSwitchInternals.normalizeBranchSpecForComparison("br:/dev/task-123@Repo@server") === "/dev/task-123", "Expected switch branch normalization to remove br: prefix and repository suffix.");
+    assert(__plasticSwitchInternals.isSameBranchSpec("/dev/task-123", "br:/dev/task-123@Repo@server"), "Expected branch comparison helper to treat equivalent branch specs as equal.");
+    assert(!__plasticSwitchInternals.isSameBranchSpec("/dev/task-123", "/dev/task-124"), "Expected branch comparison helper to detect different branches.");
+
+    const machineOutputWithPrivate = [
+        "STATUS 123 Normandie/Repo server",
+        "PR /repo/ws/todos/059-ready.md False NO_MERGES",
+        "PR /repo/ws/.env.local False NO_MERGES",
+        "PR /repo/ws/src/id_rsa False NO_MERGES",
+    ].join("\n");
+    const pendingItemsWithPrivate = __plasticCheckinInternals.parseMachineReadablePendingItems(machineOutputWithPrivate, cwd);
+    const privateSummary = __plasticCheckinInternals.summarizePendingItems(pendingItemsWithPrivate, cwd);
+    assert(privateSummary.private === 3, "Expected private summary to count private pending items.");
+    assert(privateSummary.tracked === 0, "Expected tracked count to be zero for private-only sample.");
+    assert(privateSummary.privatePaths.some((path) => pathMatches(path, "todos/059-ready.md")), "Expected summary private paths to include the expected markdown file.");
+
+    const privateOnlyProfile = __plasticSwitchInternals.buildSwitchPendingProfile(privateSummary);
+    assert(privateOnlyProfile.hasPrivateOnlyPendingChanges, "Expected switch pending profile to classify private-only pending state.");
+    assert(__plasticSwitchInternals.canSwitchDirectWithPrivateOnlyPending("bring", false, privateOnlyProfile), "Expected private-only bring policy to allow direct unattended switch.");
+    assert(__plasticSwitchInternals.canSwitchDirectWithPrivateOnlyPending("shelve", false, privateOnlyProfile), "Expected private-only shelve policy to allow direct unattended switch.");
+    assert(__plasticSwitchInternals.canSwitchDirectWithPrivateOnlyPending("cancel", true, privateOnlyProfile), "Expected defaulted cancel policy to allow direct private-only switch.");
+    assert(!__plasticSwitchInternals.canSwitchDirectWithPrivateOnlyPending("cancel", false, privateOnlyProfile), "Expected explicit cancel policy to keep private-only switch blocked.");
+
+    assert(__plasticCheckinInternals.getSensitivePrivatePathReason(".env.local") === "sensitive_path:dotenv", "Expected dotenv path to be blocked as sensitive.");
+    assert(__plasticCheckinInternals.getSensitivePrivatePathReason("src/id_rsa") === "sensitive_path:ssh-key", "Expected SSH key path to be blocked as sensitive.");
+    assert(__plasticCheckinInternals.getSensitivePrivatePathReason("todos/059-ready.md") === null, "Expected normal markdown path not to be blocked as sensitive.");
+
+    const autoAddSelection = __plasticCheckinInternals.selectPrivatePathsForAutoAdd(pendingItemsWithPrivate, [], cwd);
+    assert(autoAddSelection.candidatePaths.length === 1, "Expected one safe private auto-add candidate.");
+    assert(pathMatches(autoAddSelection.candidatePaths[0], "todos/059-ready.md"), "Expected private auto-add candidate to keep relative file path.");
+    assert(autoAddSelection.blockedPaths.length === 2, "Expected two sensitive private paths to be blocked from auto-add.");
+
+    const trackedPendingProfile = __plasticSwitchInternals.buildSwitchPendingProfile(pendingSummary);
+    assert(__plasticSwitchInternals.isSwitchBringBlockedForUnattended("bring", trackedPendingProfile), "Expected bring policy to be blocked when tracked pending changes exist.");
+    assert(!__plasticSwitchInternals.isSwitchBringBlockedForUnattended("bring", privateOnlyProfile), "Expected bring policy not to be blocked for private-only pending changes.");
+
+    const legacyPendingSummary = __plasticSwitchInternals.toLegacyPendingSummary(privateSummary);
+    assert(legacyPendingSummary.totalPending === privateSummary.totalPending, "Expected legacy pending summary total count to match detailed summary.");
+    assert(legacyPendingSummary.other >= privateSummary.private, "Expected legacy pending summary to account for private items in other count.");
+
+    assert(__plasticCheckinInternals.isNoChangesWorkspaceCheckinError("Error: There are no changes in the workspace c:/repo/ws"), "Expected no-changes detector to match workspace no-changes errors.");
+    assert(!__plasticCheckinInternals.isNoChangesWorkspaceCheckinError("Error: path is not changed in current workspace"), "Expected no-changes detector not to match path-scope errors.");
+
+    console.log("PASS: plastic checkin path resolution tests passed");
+};
+
+main();

package/tests/plastic-constrained-sampling.test.ts

@@ -0,0 +1,77 @@
+import assert from "node:assert/strict";
+import { loadRegisteredTools } from "./pi-tool-harness.ts";
+
+type JsonSchema = {
+  type?: string;
+  properties?: Record<string, JsonSchema>;
+  required?: string[];
+  additionalProperties?: boolean | JsonSchema;
+  items?: JsonSchema;
+  anyOf?: JsonSchema[];
+};
+
+const collectOpenAiStrictIssues = (schema: JsonSchema, path = "$", issues: string[] = []): string[] => {
+  if (schema.type === "object") {
+    if (schema.additionalProperties !== false) {
+      issues.push(`${path} must set additionalProperties to false`);
+    }
+
+    const propertyNames = Object.keys(schema.properties ?? {});
+    const required = new Set(schema.required ?? []);
+    for (const propertyName of propertyNames) {
+      if (!required.has(propertyName)) {
+        issues.push(`${path}.${propertyName} is optional`);
+      }
+      collectOpenAiStrictIssues(schema.properties![propertyName], `${path}.${propertyName}`, issues);
+    }
+  }
+
+  if (schema.items) {
+    collectOpenAiStrictIssues(schema.items, `${path}[]`, issues);
+  }
+  for (const [index, variant] of (schema.anyOf ?? []).entries()) {
+    collectOpenAiStrictIssues(variant, `${path}.anyOf[${index}]`, issues);
+  }
+
+  return issues;
+};
+
+const main = async (): Promise<void> => {
+  const tools = await loadRegisteredTools();
+  const report = [...tools.values()].map((tool) => {
+    const schema = tool.parameters as JsonSchema;
+    return {
+      name: tool.name,
+      issues: collectOpenAiStrictIssues(schema),
+      constrainedSampling: tool.constrainedSampling,
+    };
+  });
+
+  assert(report.length > 0, "Expected registered Plastic tools to audit.");
+
+  const optedIn = report.filter((entry) => entry.constrainedSampling !== undefined && entry.constrainedSampling !== false);
+  for (const entry of optedIn) {
+    if (entry.constrainedSampling && entry.constrainedSampling.type === "json_schema") {
+      assert.deepEqual(entry.issues, [], `${entry.name} must be OpenAI strict-schema compatible before opting in`);
+    }
+  }
+
+  // Pi 0.82 forwards a strict tool's schema without normalizing it. Every current
+  // Plastic schema has optional fields (at minimum workdir), and TypeBox objects
+  // currently allow unspecified additional properties. Enabling strict sampling
+  // would therefore make direct OpenAI requests fail or require a breaking public
+  // argument-schema redesign.
+  assert.equal(optedIn.length, 0, "No Plastic tool should opt in until its ordinary public schema is strict-compatible.");
+  assert.equal(report.filter((entry) => entry.issues.length === 0).length, 0, "The current catalog should be classified as blocked, not strict-ready.");
+
+  for (const pilotName of ["plastic_status", "plastic_branchExists", "plastic_branchCreate"]) {
+    const pilot = report.find((entry) => entry.name === pilotName);
+    assert(pilot, `Missing pilot tool ${pilotName}`);
+    assert(pilot.issues.some((issue) => issue.includes("additionalProperties")), `${pilotName} should report its closed-object blocker`);
+    assert(pilot.issues.some((issue) => issue.endsWith("workdir is optional")), `${pilotName} should report its optional workdir blocker`);
+  }
+
+  console.log(`PASS: audited ${report.length} Plastic schemas; 0 are currently OpenAI strict-ready`);
+};
+
+void main();

package/tests/plastic-diff-workflow.test.ts

@@ -0,0 +1,86 @@
+import assert from "node:assert/strict";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { __plasticDiffInternals, __plasticProcessInternals } from "../src/plastic-core.ts";
+
+const root = await mkdtemp(join(tmpdir(), "pi-plastic-diff-"));
+
+try {
+    const { resolveDiffFileRevision, isUnscopedDiffRevisionSpec, runPortableTextDiff, DIFF_OUTPUT_MAX_CHARS, safeTempExtension } = __plasticDiffInternals;
+
+    assert.deepEqual(
+        resolveDiffFileRevision("Assets/Scene.unity"),
+        { supplied: null, kind: "workspace-base", resolved: "Assets/Scene.unity" },
+        "omitting revision should select the workspace-base path",
+    );
+    assert.deepEqual(
+        resolveDiffFileRevision("Assets/Scene.unity", "42"),
+        { supplied: "42", kind: "changeset", resolved: "Assets/Scene.unity#cs:42" },
+        "a number must be a changeset selector, not an item revision",
+    );
+    assert.equal(resolveDiffFileRevision("Assets/Scene.unity", "br:/dev/diff").kind, "branch");
+    assert.equal(resolveDiffFileRevision("Assets/Scene.unity", "revid:123").kind, "global-revision");
+    assert.throws(() => resolveDiffFileRevision("Assets/Scene.unity", "base"), /Unsupported revision 'base'/);
+    assert.throws(() => resolveDiffFileRevision("Assets/Scene.unity", "cs:head"), /Unsupported revision 'cs:head'/);
+    assert.throws(() => resolveDiffFileRevision("Assets/Scene.unity", "cs:br:\/main"), /Unsupported revision/);
+    assert.equal(isUnscopedDiffRevisionSpec("base"), true);
+    assert.equal(isUnscopedDiffRevisionSpec("head"), true);
+    assert.equal(isUnscopedDiffRevisionSpec("cs:42"), true);
+    assert.equal(isUnscopedDiffRevisionSpec("42"), true);
+    assert.equal(isUnscopedDiffRevisionSpec("rev:"), true);
+    assert.equal(isUnscopedDiffRevisionSpec("arbitrary"), true);
+    assert.equal(isUnscopedDiffRevisionSpec("Assets/Scene.unity#cs:42"), false);
+    assert.equal(isUnscopedDiffRevisionSpec("Assets/Scene.unity#br:/main"), false);
+    assert.equal(isUnscopedDiffRevisionSpec("revid:123"), false);
+    assert.equal(safeTempExtension("Assets/My Scene.unity"), ".unity");
+    assert.equal(safeTempExtension("revid:99"), ".tmp");
+    assert.equal(__plasticProcessInternals.resolveDiffExecutable({ PI_PLASTIC_DIFF_EXECUTABLE: "D:/tools/diff.exe" }), "D:/tools/diff.exe");
+
+    const left = join(root, "Unity Scene ünicode.unity");
+    const right = join(root, "Unity Scene ünicode copy.unity");
+    await writeFile(left, "%YAML 1.1\n--- !u!1 &1\nGameObject:\n  m_Name: Before\n", "utf8");
+    await writeFile(right, "%YAML 1.1\n--- !u!1 &1\nGameObject:\n  m_Name: After\n", "utf8");
+    const yamlResult = await runPortableTextDiff(left, right, root, "Assets/Scene.unity (Plastic base)", "Assets/Scene.unity (workspace)");
+    assert.equal(yamlResult.backend, "diff");
+    assert.equal(yamlResult.changed, true);
+    assert.equal(yamlResult.binary, false, "Unity YAML must be treated as text based on bytes, not extension/attributes");
+    assert.match(yamlResult.output, /^--- Assets\/Scene\.unity \(Plastic base\)\n\+\+\+ Assets\/Scene\.unity \(workspace\)/);
+    assert.doesNotMatch(yamlResult.output, new RegExp(root.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")), "temporary/local paths must not appear in normalized headers");
+
+    const sameResult = await runPortableTextDiff(left, left, root, "left", "right");
+    assert.equal(sameResult.changed, false);
+    assert.equal(sameResult.binary, false);
+
+    const binaryLeft = join(root, "fixture.asset");
+    const binaryRight = join(root, "fixture-copy.asset");
+    await writeFile(binaryLeft, Buffer.from([0, 1, 2, 3]));
+    await writeFile(binaryRight, Buffer.from([0, 1, 4, 3]));
+    const binaryResult = await runPortableTextDiff(binaryLeft, binaryRight, root, "base", "workspace");
+    assert.equal(binaryResult.changed, true);
+    assert.equal(binaryResult.binary, true);
+    assert.equal(binaryResult.output, "");
+
+    const invalidUtf8Left = join(root, "invalid-utf8-left.asset");
+    const invalidUtf8Right = join(root, "invalid-utf8-right.asset");
+    await writeFile(invalidUtf8Left, Buffer.from([0xff, 0x81, 0x41]));
+    await writeFile(invalidUtf8Right, Buffer.from([0xff, 0x81, 0x42]));
+    const invalidUtf8Result = await runPortableTextDiff(invalidUtf8Left, invalidUtf8Right, root, "base", "workspace");
+    assert.equal(invalidUtf8Result.changed, true);
+    assert.equal(invalidUtf8Result.binary, true, "non-UTF-8 bytes must be reported as binary instead of replacement-decoded text");
+    assert.equal(invalidUtf8Result.output, "");
+
+    const largeLeft = join(root, "large-left.txt");
+    const largeRight = join(root, "large-right.txt");
+    await writeFile(largeLeft, `${"before\n".repeat(12_000)}`, "utf8");
+    await writeFile(largeRight, `${"after\n".repeat(12_000)}`, "utf8");
+    const largeResult = await runPortableTextDiff(largeLeft, largeRight, root, "large base", "large workspace");
+    assert.equal(largeResult.changed, true);
+    assert.equal(largeResult.truncated, true);
+    assert.ok(largeResult.totalChars > DIFF_OUTPUT_MAX_CHARS);
+    assert.match(largeResult.output, /Diff output truncated/);
+
+    console.log("PASS: plastic diff workflow tests passed");
+} finally {
+    await rm(root, { recursive: true, force: true });
+}

package/tests/plastic-dynamic-tool-loading.test.ts

@@ -0,0 +1,224 @@
+import assert from "node:assert/strict";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { PiToolHarness, type RegisteredTool, type ToolSourceInfo } from "./pi-tool-harness.ts";
+import {
+  BALANCED_ACTIVE_PLASTIC_TOOL_NAMES,
+  PLASTIC_SEARCH_CATALOG,
+  PLASTIC_TOOL_LOADING_MODE_ENV,
+  PLASTIC_TOOL_NAMES,
+  PLASTIC_TOOL_SEARCH_NAME,
+  searchPlasticTools,
+} from "../src/plastic-tool-loading.ts";
+
+const publicToolNames = [...PLASTIC_TOOL_NAMES];
+const foreignSource: ToolSourceInfo = { path: "/extensions/foreign.ts", source: "extension", scope: "project", origin: "package" };
+
+async function withMode<T>(mode: string | undefined, action: () => Promise<T>): Promise<T> {
+  const previous = process.env[PLASTIC_TOOL_LOADING_MODE_ENV];
+  if (mode === undefined) delete process.env[PLASTIC_TOOL_LOADING_MODE_ENV];
+  else process.env[PLASTIC_TOOL_LOADING_MODE_ENV] = mode;
+  try {
+    return await action();
+  } finally {
+    if (previous === undefined) delete process.env[PLASTIC_TOOL_LOADING_MODE_ENV];
+    else process.env[PLASTIC_TOOL_LOADING_MODE_ENV] = previous;
+  }
+}
+
+async function loadHarness(activeTools: string[], branchEntries: unknown[] = [], options: ConstructorParameters<typeof PiToolHarness>[0] = {}): Promise<PiToolHarness> {
+  const harness = new PiToolHarness({ activeTools, branchEntries, ...options });
+  await harness.load();
+  await harness.startSession();
+  return harness;
+}
+
+async function main(): Promise<void> {
+  await withMode(undefined, async () => {
+    const harness = await loadHarness(["read", "foreign_tool", ...publicToolNames]);
+    assert.equal(harness.registry.size, 29, "all 28 public Plastic tools plus the loader should be registered");
+    assert(harness.registry.has(PLASTIC_TOOL_SEARCH_NAME));
+    assert.deepEqual(new Set(harness.getActiveTools()), new Set(["read", "foreign_tool", PLASTIC_TOOL_SEARCH_NAME, ...BALANCED_ACTIVE_PLASTIC_TOOL_NAMES]));
+  });
+
+  await withMode("loader-only", async () => {
+    const harness = await loadHarness(["read", "foreign_tool", ...publicToolNames]);
+    assert.deepEqual(new Set(harness.getActiveTools()), new Set(["read", "foreign_tool", PLASTIC_TOOL_SEARCH_NAME]));
+  });
+
+  await withMode("all-active", async () => {
+    const harness = await loadHarness(["read", "foreign_tool", ...publicToolNames]);
+    assert.deepEqual(new Set(harness.getActiveTools()), new Set(["read", "foreign_tool", ...publicToolNames]), "all-active should expose all 28 current Plastic tools without the new loader");
+  });
+
+  await withMode("balanced", async () => {
+    const extensionPath = fileURLToPath(new URL("../index.ts", import.meta.url));
+    const relativeSource: ToolSourceInfo = {
+      path: "./index.ts",
+      source: "local",
+      scope: "project",
+      origin: "cli",
+      baseDir: dirname(extensionPath),
+    };
+    const harness = await loadHarness(["read", ...publicToolNames], [], { extensionSourceInfo: relativeSource });
+    assert.deepEqual(new Set(harness.getActiveTools()), new Set(["read", PLASTIC_TOOL_SEARCH_NAME, ...BALANCED_ACTIVE_PLASTIC_TOOL_NAMES]), "relative configured extension paths should resolve to the package-owned source");
+    const result = await harness.registry.get(PLASTIC_TOOL_SEARCH_NAME)!.execute("loader", { toolNames: ["plastic_branchList"] });
+    assert.deepEqual(result.details.added, ["plastic_branchList"], "relative-path provenance should still allow deferred activation");
+  });
+
+  assert.deepEqual(searchPlasticTools({ toolNames: ["plastic_branchDelete"] }).map((match) => match.name), ["plastic_branchDelete"], "exact public names should select one known tool");
+  assert(searchPlasticTools({ query: "shelveset" }).every((match) => match.name.includes("shelveset")), "keyword search should find the requested capability");
+  assert.equal(searchPlasticTools({ query: "branch", limit: 99 }).length, 4, "search results should have a hard upper bound");
+  assert.deepEqual(searchPlasticTools({ query: "branch", limit: 3 }).map((match) => match.name), ["plastic_branchList", "plastic_branchExists", "plastic_currentBranch"], "ambiguous branch searches should prioritize inspection and query tools when multiple results are requested");
+  assert.deepEqual(searchPlasticTools({ query: "list available branches" }).map((match) => match.name), ["plastic_branchList"], "multi-term branch discovery should not activate unrelated list tools");
+  assert.deepEqual(searchPlasticTools({ query: "list branches in a specified workspace read-only", limit: 1 }).map((match) => match.name), ["plastic_branchList"], "the first capability domain should outrank incidental workspace context");
+  assert.deepEqual(searchPlasticTools({ query: "find existing code reviews" }).map((match) => match.name), ["plastic_codeReviewFind"], "contextual review discovery should select the smallest sufficient query tool");
+  assert.deepEqual(searchPlasticTools({ query: "what changed" }).map((match) => match.name), ["plastic_status"], "changed-file questions should route to status rather than GUI-capable diff commands");
+  const diffMatches = searchPlasticTools({ query: "diff" }).map((match) => match.name);
+  assert(!diffMatches.includes("plastic_diff"), "the disabled compatibility diff alias must never be executable through search");
+  assert.deepEqual(diffMatches.slice(0, 2), ["plastic_diffFile", "plastic_diffRevisions"], "generic diff searches should prefer the common workspace-file route before advanced revision comparison");
+  assert.deepEqual(searchPlasticTools({ query: "workspace diff" }).map((match) => match.name), ["plastic_diffFile"], "workspace diff intent should select the file diff tool");
+  assert.deepEqual(searchPlasticTools({ query: "compare revisions" }).map((match) => match.name), ["plastic_diffRevisions"], "explicit revision comparison should select the advanced tool");
+  assert.deepEqual(searchPlasticTools({ toolNames: ["plastic_diff"] }).map((match) => match.name), [], "the disabled diff alias must not be exactly selectable");
+  assert.deepEqual(searchPlasticTools({ toolNames: ["plastic_workspaceCreate"] }).map((match) => match.name), [], "workspace creation must not be discoverable until paired cleanup is available");
+  assert.deepEqual(searchPlasticTools({ toolNames: ["foreign_tool"] }).map((match) => match.name), [], "unknown names must not be selectable");
+  assert.equal(searchPlasticTools({ toolNames: ["plastic_branchDelete", "plastic_branchCreate", "plastic_branchList", "plastic_currentBranch"] }).length, 4, "up to four exact names should all be selected when no limit is supplied");
+
+  await withMode("loader-only", async () => {
+    const harness = await loadHarness(["read", "foreign_tool"]);
+    const loader = harness.registry.get(PLASTIC_TOOL_SEARCH_NAME)!;
+
+    const browseCallsBefore = harness.setActiveToolsCalls.length;
+    for (const query of [undefined, "Unity Version Control", "version control", "UVCS", "VCS"]) {
+      const browse = await loader.execute("loader", query === undefined ? {} : { query });
+      assert.equal(browse.details.browse, true, `${String(query)} should provide a browse response`);
+      assert.match(browse.content[0].text, /Browse Plastic capabilities/, "browse output should give concise recovery categories");
+    }
+    assert.equal(harness.setActiveToolsCalls.length, browseCallsBefore, "browse and recovery responses must not activate tools");
+
+    const setCallsBefore = harness.setActiveToolsCalls.length;
+    const result = await loader.execute("loader", { toolNames: ["plastic_branchDelete", "plastic_branchCreate", "plastic_branchList", "plastic_currentBranch"] });
+    assert.equal(result.details.added.length, 4, "all requested exact tools should activate by default");
+    assert(harness.getActiveTools().includes("read") && harness.getActiveTools().includes("foreign_tool"), "activation must preserve foreign tools");
+    assert.equal(harness.setActiveToolsCalls.length, setCallsBefore + 1, "new matches should be activated once");
+    assert.match(result.content[0].text, /Confirm the full branch path/, "loader results should return selected safety guidance");
+
+    const repeatCallsBefore = harness.setActiveToolsCalls.length;
+    const repeat = await loader.execute("loader", { toolNames: ["plastic_branchDelete"] });
+    assert.deepEqual(repeat.details.alreadyActive, ["plastic_branchDelete"]);
+    assert.equal(harness.setActiveToolsCalls.length, repeatCallsBefore, "already-active matches must not replace the active set");
+
+    const noMatchCallsBefore = harness.setActiveToolsCalls.length;
+    const noMatch = await loader.execute("loader", { toolNames: ["unknown_tool"] });
+    assert.deepEqual(noMatch.details.matches, []);
+    assert.deepEqual(noMatch.details.unknownToolNames, ["unknown_tool"]);
+    assert.match(noMatch.content[0].text, /unknown_tool/, "unknown exact requests must be reported clearly");
+    assert.equal(harness.setActiveToolsCalls.length, noMatchCallsBefore, "no-match searches must not change active tools");
+
+    const disabledDiff = await loader.execute("loader", { toolNames: ["plastic_diff"] });
+    assert.deepEqual(disabledDiff.details.matches, []);
+    assert.deepEqual(disabledDiff.details.unavailableToolNames, ["plastic_diff"], "the compatibility diff alias must be reported as unavailable rather than activated");
+  });
+
+  await withMode("loader-only", async () => {
+    const activeBranch = [
+      { type: "message", message: { role: "toolResult", addedToolNames: ["plastic_diff", "plastic_merge", "plastic_branchList", "foreign_tool", "removed_tool"] } },
+    ];
+    const harness = await loadHarness(["read", "foreign_tool", ...publicToolNames], activeBranch);
+    assert(harness.getActiveTools().includes("plastic_diff"), "the disabled compatibility diff alias should remain restorable from active history");
+    assert(harness.getActiveTools().includes("plastic_merge") && harness.getActiveTools().includes("plastic_branchList"), "valid active-branch loader additions should be restored");
+    assert(!harness.getActiveTools().includes("removed_tool"), "unknown historical names must not be restored");
+    assert(harness.getActiveTools().includes("foreign_tool"), "foreign active tools must survive restoration");
+  });
+
+  await withMode("loader-only", async () => {
+    const foreignBranchCreate: RegisteredTool = {
+      name: "plastic_branchCreate",
+      label: "Foreign branch create",
+      description: "Foreign collision",
+      sourceInfo: foreignSource,
+      execute: () => ({}),
+    };
+    const harness = await loadHarness(["read", "plastic_branchCreate"], [], { sourceInfoAvailable: true, foreignTools: [foreignBranchCreate] });
+    assert(harness.getActiveTools().includes("plastic_branchCreate"), "sourceInfo ownership must preserve a name-colliding foreign active tool");
+
+    const loader = harness.registry.get(PLASTIC_TOOL_SEARCH_NAME)!;
+    const callsBefore = harness.setActiveToolsCalls.length;
+    const collision = await loader.execute("loader", { toolNames: ["plastic_branchCreate", "plastic_branchList"] });
+    assert.deepEqual(collision.details.added, ["plastic_branchList"], "only the same-source effective tool may be activated");
+    assert.deepEqual(collision.details.unavailableToolNames, ["plastic_branchCreate"], "foreign collisions should be reported as unavailable from this extension");
+    assert.equal(harness.setActiveToolsCalls.length, callsBefore + 1);
+
+    const restoredHarness = await loadHarness(["read"], [
+      { type: "message", message: { role: "toolResult", addedToolNames: ["plastic_branchCreate", "plastic_branchList"] } },
+    ], { sourceInfoAvailable: true, foreignTools: [foreignBranchCreate] });
+    assert(!restoredHarness.getActiveTools().includes("plastic_branchCreate"), "foreign same-name tools must not be restored from this loader's history");
+    assert(restoredHarness.getActiveTools().includes("plastic_branchList"), "same-source historical loader additions should still restore");
+  });
+
+  await withMode("loader-only", async () => {
+    const compatibilityHarness = await loadHarness(["read", ...publicToolNames], [], { sourceInfoAvailable: false });
+    assert.deepEqual(
+      compatibilityHarness.getActiveTools(),
+      ["read", ...publicToolNames],
+      "without sourceInfo, loader-only mode must preserve the active legacy set exactly",
+    );
+    assert.equal(compatibilityHarness.setActiveToolsCalls.length, 0, "unproven loader ownership must not rewrite the active set");
+
+    const foreignBranchCreate: RegisteredTool = {
+      name: "plastic_branchCreate",
+      label: "Foreign branch create without provenance",
+      description: "Foreign collision",
+      sourceInfo: foreignSource,
+      execute: () => ({}),
+    };
+    const initiallyActive = ["read", "foreign_tool", PLASTIC_TOOL_SEARCH_NAME, "plastic_status", "plastic_branchCreate"];
+    const harness = await loadHarness(initiallyActive, [], { sourceInfoAvailable: false, foreignTools: [foreignBranchCreate] });
+    assert.deepEqual(harness.getActiveTools(), initiallyActive, "without sourceInfo, startup must preserve every active Plastic-named tool");
+    assert.equal(harness.setActiveToolsCalls.length, 0, "without sourceInfo, startup must not defer or otherwise rewrite the active set when the loader is already active");
+
+    const loader = harness.registry.get(PLASTIC_TOOL_SEARCH_NAME)!;
+    const collision = await loader.execute("loader", { toolNames: ["plastic_branchCreate", "plastic_branchList"] });
+    assert.deepEqual(collision.details.matches, ["plastic_branchCreate"], "without provenance, the loader may report only already-active known matches");
+    assert.deepEqual(collision.details.added, [], "without provenance, the loader must not activate inactive Plastic names");
+    assert.deepEqual(collision.details.unavailableToolNames, ["plastic_branchList"]);
+    assert.deepEqual(harness.getActiveTools(), initiallyActive, "a foreign colliding plastic_* tool must not cause deactivation or activation without sourceInfo");
+    assert.equal(harness.setActiveToolsCalls.length, 0, "a no-sourceInfo loader request must not change the active set");
+  });
+
+  for (const mode of ["loader-only", "all-active"] as const) await withMode(mode, async () => {
+    const foreignLoader: RegisteredTool = {
+      name: PLASTIC_TOOL_SEARCH_NAME,
+      label: "Foreign Plastic loader",
+      description: "Foreign collision",
+      sourceInfo: foreignSource,
+      execute: () => ({}),
+    };
+    const foreignBranchList: RegisteredTool = {
+      name: "plastic_branchList",
+      label: "Foreign branch list",
+      description: "Foreign collision from the same source as the foreign loader",
+      sourceInfo: foreignSource,
+      execute: () => ({}),
+    };
+    const active = ["read", PLASTIC_TOOL_SEARCH_NAME, "plastic_branchList", "plastic_status"];
+    const harness = await loadHarness(active, [], { sourceInfoAvailable: true, foreignTools: [foreignLoader, foreignBranchList] });
+    assert.deepEqual(harness.getActiveTools(), active, `${mode} must preserve an active foreign loader and same-source Plastic collision`);
+    assert.equal(harness.setActiveToolsCalls.length, 0, `${mode} must not rewrite tools when this extension does not own the effective loader`);
+  });
+
+  await withMode("loader-only", async () => {
+    const harness = await loadHarness(["read"]);
+    for (const name of PLASTIC_SEARCH_CATALOG.map((entry) => entry.name)) {
+      const tool = harness.registry.get(name)!;
+      assert.equal(tool.promptSnippet, undefined, `${name} should not rebuild the prompt after deferred activation`);
+      assert.equal(tool.promptGuidelines, undefined, `${name} should not add deferred prompt guidance`);
+    }
+    assert(harness.registry.get(PLASTIC_TOOL_SEARCH_NAME)?.promptSnippet, "the always-active loader should explain discovery");
+    assert(harness.registry.get(PLASTIC_TOOL_SEARCH_NAME)?.promptGuidelines?.length, "the always-active loader should retain universal safety guidance");
+  });
+
+  console.log("PASS: plastic dynamic tool loading test succeeded");
+}
+
+void main();