@aefree/pi-plastic 0.4.0

package/tests/pi-tool-harness.ts

@@ -0,0 +1,116 @@
+import { fileURLToPath } from "node:url";
+
+export type ToolSourceInfo = {
+  path: string;
+  source: string;
+  scope: string;
+  origin: string;
+  baseDir?: string;
+};
+
+export type RegisteredTool = {
+  name: string;
+  label?: string;
+  description?: string;
+  promptSnippet?: string;
+  promptGuidelines?: string[];
+  sourceInfo?: ToolSourceInfo;
+  parameters?: unknown;
+  constrainedSampling?: false | {
+    type: "json_schema";
+    strict: "prefer" | "require";
+  } | {
+    type: "grammar";
+    variants: {
+      openai_lark?: string;
+      openai_regex?: string;
+    };
+  };
+  prepareArguments?: (args: unknown) => Record<string, unknown>;
+  execute: (...args: any[]) => Promise<any> | any;
+};
+
+type SessionStartHandler = (event: unknown, ctx: { sessionManager: { getBranch: () => unknown[] } }) => Promise<void> | void;
+
+const DEFAULT_EXTENSION_SOURCE: ToolSourceInfo = {
+  path: fileURLToPath(new URL("../index.ts", import.meta.url)),
+  source: "extension",
+  scope: "project",
+  origin: "package",
+};
+
+export class PiToolHarness {
+  readonly registry = new Map<string, RegisteredTool>();
+  readonly setActiveToolsCalls: string[][] = [];
+  private readonly sessionStartHandlers: SessionStartHandler[] = [];
+  private readonly sourceInfoAvailable: boolean;
+  private readonly extensionSourceInfo: ToolSourceInfo;
+  private activeTools: string[];
+  private branchEntries: unknown[];
+
+  constructor(options: {
+    activeTools?: string[];
+    branchEntries?: unknown[];
+    foreignTools?: RegisteredTool[];
+    sourceInfoAvailable?: boolean;
+    extensionSourceInfo?: ToolSourceInfo;
+  } = {}) {
+    this.activeTools = [...(options.activeTools ?? [])];
+    this.branchEntries = [...(options.branchEntries ?? [])];
+    // Default to Pi 0.82 behavior; individual compatibility tests explicitly
+    // opt out to model older runtimes without canonical sourceInfo.
+    this.sourceInfoAvailable = options.sourceInfoAvailable ?? true;
+    this.extensionSourceInfo = options.extensionSourceInfo ?? DEFAULT_EXTENSION_SOURCE;
+    for (const tool of options.foreignTools ?? []) this.registry.set(tool.name, { ...tool });
+  }
+
+  readonly api = {
+    registerTool: (tool: RegisteredTool) => {
+      // Pi keeps the first effective definition for a colliding extension name.
+      if (!this.registry.has(tool.name)) {
+        this.registry.set(tool.name, this.sourceInfoAvailable ? { ...tool, sourceInfo: this.extensionSourceInfo } : { ...tool });
+      }
+    },
+    on: (event: string, handler: SessionStartHandler) => {
+      if (event === "session_start") this.sessionStartHandlers.push(handler);
+    },
+    getActiveTools: () => [...this.activeTools],
+    getAllTools: () => [...this.registry.values()],
+    setActiveTools: (names: string[]) => {
+      this.activeTools = [...new Set(names)];
+      this.setActiveToolsCalls.push([...this.activeTools]);
+    },
+  };
+
+  async load(modulePath = "../index.ts"): Promise<void> {
+    const extensionModule = await import(modulePath);
+    const extension = extensionModule.default as ((pi: any) => void) | undefined;
+    if (typeof extension !== "function") throw new Error(`Extension module '${modulePath}' has no default function export.`);
+    extension(this.api);
+  }
+
+  async startSession(branchEntries = this.branchEntries): Promise<void> {
+    this.branchEntries = [...branchEntries];
+    const ctx = { sessionManager: { getBranch: () => [...this.branchEntries] } };
+    for (const handler of this.sessionStartHandlers) await handler({ reason: "startup" }, ctx);
+  }
+
+  getActiveTools(): string[] {
+    return [...this.activeTools];
+  }
+}
+
+export async function loadRegisteredTools(modulePath = "../index.ts"): Promise<Map<string, RegisteredTool>> {
+  const harness = new PiToolHarness();
+  await harness.load(modulePath);
+  return harness.registry;
+}
+
+export async function invokeRegisteredTool(name: string, args: Record<string, unknown>, cwd = process.cwd(), modulePath = "../index.ts"): Promise<string> {
+  const tools = await loadRegisteredTools(modulePath);
+  const tool = tools.get(name);
+  if (!tool) throw new Error(`Tool '${name}' is not registered.`);
+  const result = await tool.execute("test-tool-call", args, undefined, undefined, { cwd });
+  const textParts = Array.isArray(result?.content) ? result.content.filter((entry: any) => entry?.type === "text") : [];
+  return textParts.map((entry: any) => String(entry.text ?? "")).join("\n");
+}

package/tests/plastic-branch-create-live.test.ts

@@ -0,0 +1,78 @@
+import assert from "node:assert/strict";
+import { invokeRegisteredTool } from "./pi-tool-harness.ts";
+
+type ToolEnvelope = {
+  ok?: boolean;
+  data?: Record<string, unknown>;
+};
+
+const parseToolEnvelope = (text: string): ToolEnvelope => {
+  const fencedJson = text.match(/```json\s*([\s\S]*?)\s*```/);
+  assert(fencedJson, "Expected a structured JSON tool result.");
+  return JSON.parse(fencedJson[1]) as ToolEnvelope;
+};
+
+const workspace = process.env.PI_PLASTIC_TEST_WORKSPACE?.trim();
+const mutationAllowed = process.env.PI_PLASTIC_ALLOW_MUTATION_TESTS?.trim().toLowerCase() === "true";
+
+if (!workspace || !mutationAllowed) {
+  console.log("SKIP: set PI_PLASTIC_TEST_WORKSPACE and PI_PLASTIC_ALLOW_MUTATION_TESTS=true to run branch mutation tests");
+  process.exit(0);
+}
+
+const status = parseToolEnvelope(await invokeRegisteredTool("plastic_status", { short: true, format: "json" }, workspace));
+assert.equal(status.ok, true, "Expected Plastic status to succeed.");
+const summary = status.data?.summary as Record<string, unknown> | undefined;
+const mergeState = status.data?.mergeState as Record<string, unknown> | undefined;
+assert.equal(summary?.totalPending, 0, "Live branch tests require a clean workspace.");
+assert.equal(mergeState?.hasMergeInProgress, false, "Live branch tests require no merge in progress.");
+
+const currentResult = parseToolEnvelope(await invokeRegisteredTool("plastic_currentBranch", { format: "json" }, workspace));
+const loadedBranch = currentResult.data?.branch;
+assert.equal(typeof loadedBranch, "string", "Expected a loaded Plastic branch.");
+
+const suffix = `${process.pid}-${Date.now().toString(36)}`;
+const parent = `${loadedBranch}/pi-live-parent-${suffix}`;
+const childLeaf = `child-${suffix}`;
+const child = `${parent}/${childLeaf}`;
+const blockedRoot = `/pi-live-root-${suffix}`;
+
+const exists = async (branch: string): Promise<boolean> =>
+  (await invokeRegisteredTool("plastic_branchExists", { branch }, workspace)).trim() === "true";
+
+assert.equal(await exists(parent), false, `Temporary parent already exists: ${parent}`);
+assert.equal(await exists(child), false, `Temporary child already exists: ${child}`);
+assert.equal(await exists(blockedRoot), false, `Temporary root already exists: ${blockedRoot}`);
+
+try {
+  await invokeRegisteredTool("plastic_branchCreate", { branch: parent, comment: "pi-plastic live parent test" }, workspace);
+  assert.equal(await exists(parent), true, "Expected full hierarchical branch creation to succeed.");
+
+  await invokeRegisteredTool("plastic_branchCreate", {
+    branch: childLeaf,
+    parent,
+    comment: "pi-plastic explicit-parent live test",
+  }, workspace);
+  assert.equal(await exists(child), true, "Expected creation beneath an explicit non-loaded parent to succeed.");
+
+  let rootGuarded = false;
+  try {
+    const output = await invokeRegisteredTool("plastic_branchCreate", { branch: blockedRoot }, workspace);
+    rootGuarded = /Refusing to create top-level branch/.test(output);
+  } catch (error) {
+    rootGuarded = /Refusing to create top-level branch/.test(error instanceof Error ? error.message : String(error));
+  }
+  assert.equal(rootGuarded, true, "Expected top-level creation to be rejected without allowRootBranch.");
+  assert.equal(await exists(blockedRoot), false, "Rejected top-level branch must not be created.");
+
+  const branchAfter = parseToolEnvelope(await invokeRegisteredTool("plastic_currentBranch", { format: "json" }, workspace));
+  assert.equal(branchAfter.data?.branch, loadedBranch, "Branch creation must not switch the workspace.");
+} finally {
+  if (await exists(child)) await invokeRegisteredTool("plastic_branchDelete", { branch: child }, workspace);
+  if (await exists(parent)) await invokeRegisteredTool("plastic_branchDelete", { branch: parent }, workspace);
+}
+
+assert.equal(await exists(child), false, "Temporary child branch cleanup failed.");
+assert.equal(await exists(parent), false, "Temporary parent branch cleanup failed.");
+assert.equal(await exists(blockedRoot), false, "Top-level guard cleanup invariant failed.");
+console.log("PASS: live hierarchical branch creation, explicit-parent behavior, top-level guard, and cleanup");

package/tests/plastic-branch-query.test.ts

@@ -0,0 +1,26 @@
+import assert from "node:assert/strict";
+import { __plasticBranchInternals } from "../src/plastic-core.ts";
+
+const { getBranchLeafName, resolveBranchCreationTarget } = __plasticBranchInternals;
+
+assert.equal(getBranchLeafName("/main/feature/test"), "test");
+assert.equal(getBranchLeafName("br:/main/feature/test"), "test");
+assert.equal(getBranchLeafName("br:/main/feature/test@repo@server"), "test");
+assert.equal(getBranchLeafName("test"), "test");
+
+assert.equal(resolveBranchCreationTarget("foo", "/main"), "/main/foo");
+assert.equal(resolveBranchCreationTarget("feature/foo", "/main"), "/main/feature/foo");
+assert.equal(resolveBranchCreationTarget("foo", "/release"), "/release/foo");
+assert.equal(resolveBranchCreationTarget("/release/foo"), "/release/foo");
+assert.equal(resolveBranchCreationTarget("br:/release/foo@repo@server"), "br:/release/foo@repo@server");
+assert.equal(resolveBranchCreationTarget("/foo", undefined, true), "/foo");
+assert.throws(
+  () => resolveBranchCreationTarget("/foo"),
+  /Refusing to create top-level branch \/foo.*allowRootBranch=true/,
+);
+assert.throws(
+  () => resolveBranchCreationTarget("foo"),
+  /relative branch name requires a parent branch/,
+);
+
+console.log("PASS: Plastic branch query normalization tests passed");

package/tests/plastic-branch-status.test.ts

@@ -0,0 +1,241 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import { createPlasticBranchStatusExtension } from "../extensions/plastic-branch-status.ts";
+
+type Handler = (event: any, ctx: any) => Promise<void> | void;
+type FakeTimer = { callback: () => void; delay: number; cleared: boolean };
+
+class FooterHarness {
+  handlers = new Map<string, Handler[]>();
+  statuses = new Map<string, string>();
+  statusCalls: Array<[string, string | undefined]> = [];
+  setFooterCalls = 0;
+  readonly ctx = {
+    cwd: "/workspace/nested/project",
+    hasUI: true,
+    ui: {
+      theme: { fg: (color: string, text: string) => `<${color}>${text}</${color}>` },
+      setStatus: (key: string, value: string | undefined) => {
+        this.statusCalls.push([key, value]);
+        if (value === undefined) this.statuses.delete(key);
+        else this.statuses.set(key, value);
+      },
+      setFooter: () => { this.setFooterCalls++; },
+    },
+  };
+  readonly api = {
+    on: (event: string, handler: Handler) => {
+      const handlers = this.handlers.get(event) ?? [];
+      handlers.push(handler);
+      this.handlers.set(event, handlers);
+    },
+    exec: async () => ({ stdout: "", stderr: "", code: 0, killed: false }),
+  };
+
+  async emit(event: string, payload: any = {}): Promise<void> {
+    for (const handler of this.handlers.get(event) ?? []) await handler(payload, this.ctx);
+  }
+}
+
+const workspace = (root: string) => ({
+  kind: "found" as const,
+  value: { root, plasticDir: `${root}/.plastic`, markerPath: `${root}/.plastic/plastic.workspace` },
+});
+
+const timers: FakeTimer[] = [];
+const schedule = (callback: () => void, delay: number): any => {
+  const timer = { callback, delay, cleared: false };
+  timers.push(timer);
+  return timer;
+};
+const clear = (timer: any): void => { timer.cleared = true; };
+const runTimers = async (delay: number): Promise<void> => {
+  const pending = timers.filter((timer) => !timer.cleared && timer.delay === delay);
+  for (const timer of pending) {
+    timer.cleared = true;
+    timer.callback();
+  }
+  await new Promise((resolve) => setImmediate(resolve));
+};
+
+{
+  timers.length = 0;
+  const harness = new FooterHarness();
+  harness.statuses.set("foreign-status", "keep me");
+  let confirmation = "/main/from-cm@repo@server\n";
+  let confirmCount = 0;
+  let watcherClosed = 0;
+  let watcherChange: (() => void) | undefined;
+  let watcherError: (() => void) | undefined;
+
+  createPlasticBranchStatusExtension({
+    discoverWorkspace: async (cwd) => cwd.startsWith("/sibling") ? workspace("/sibling") : workspace("/workspace"),
+    readSelector: async () => "repository repo@server\n  path /\n    smartbranch /main/from-selector\n",
+    watchDirectory: (_path, onChange, onError) => {
+      watcherChange = onChange;
+      watcherError = onError;
+      return { close: () => { watcherClosed++; } };
+    },
+    confirmBranch: async () => { confirmCount++; return confirmation; },
+    setTimeout: schedule,
+    clearTimeout: clear,
+    platform: "linux",
+  })(harness.api as any);
+
+  await harness.emit("session_start", { reason: "startup" });
+  assert.match(harness.statuses.get("plastic-branch") ?? "", /\/main\/from-cm/);
+  assert.equal(harness.statuses.get("foreign-status"), "keep me");
+  assert.equal(harness.setFooterCalls, 0);
+  assert.equal(confirmCount, 1);
+
+  confirmation = "/main/after-selector-replacement@repo@server\n";
+  watcherChange?.();
+  watcherChange?.();
+  await runTimers(150);
+  assert.equal(confirmCount, 2, "coalesced watcher events should run one refresh");
+  assert.match(harness.statuses.get("plastic-branch") ?? "", /after-selector-replacement/);
+  assert.ok(watcherClosed >= 1, "workspace watcher should be rebound after a directory event");
+
+  await harness.emit("tool_result", { toolCallId: "same", toolName: "plastic_switchBranch", input: { workdir: "." }, isError: false });
+  await harness.emit("tool_execution_end", { toolCallId: "same", toolName: "plastic_switchBranch", isError: false });
+  await runTimers(150);
+  assert.equal(confirmCount, 3, "same-workspace Plastic tools should refresh");
+
+  await harness.emit("tool_result", { toolCallId: "sibling", toolName: "plastic_status", input: { workdir: "/sibling" }, isError: false });
+  await harness.emit("tool_execution_end", { toolCallId: "sibling", toolName: "plastic_status", isError: false });
+  await runTimers(150);
+  assert.equal(confirmCount, 3, "sibling-workspace tools must not refresh this footer");
+
+  await harness.emit("tool_result", { toolCallId: "sibling-alias", toolName: "plastic_status", input: { cwd: "/sibling", workdir: "/sibling" }, isError: false });
+  await harness.emit("tool_execution_end", { toolCallId: "sibling-alias", toolName: "plastic_status", isError: false });
+  await runTimers(150);
+  assert.equal(confirmCount, 3, "normalized effective workdir should control sibling filtering");
+
+  watcherError?.();
+  await runTimers(150);
+  assert.equal(confirmCount, 4, "watcher errors should trigger bounded revalidation");
+
+  await harness.emit("session_shutdown", { reason: "reload" });
+  assert.equal(harness.statuses.has("plastic-branch"), false);
+  assert.equal(harness.statuses.get("foreign-status"), "keep me");
+}
+
+{
+  timers.length = 0;
+  const harness = new FooterHarness();
+  createPlasticBranchStatusExtension({
+    discoverWorkspace: async () => workspace("/workspace"),
+    readSelector: async () => "smartbranch /main/selector-only\n",
+    watchDirectory: () => ({ close() {} }),
+    confirmBranch: async () => { throw new Error("cm unavailable"); },
+    setTimeout: schedule,
+    clearTimeout: clear,
+    platform: "linux",
+  })(harness.api as any);
+  await harness.emit("session_start");
+  assert.match(harness.statuses.get("plastic-branch") ?? "", /selector-only/, "selector fallback should survive cm failure");
+}
+
+{
+  timers.length = 0;
+  const harness = new FooterHarness();
+  let aborted = false;
+  createPlasticBranchStatusExtension({
+    discoverWorkspace: async () => workspace("/workspace"),
+    readSelector: async () => "smartbranch \n",
+    watchDirectory: () => ({ close() {} }),
+    confirmBranch: async (_cwd, signal) => new Promise((_resolve, reject) => {
+      signal.addEventListener("abort", () => { aborted = true; reject(new Error("aborted")); }, { once: true });
+    }),
+    setTimeout: schedule,
+    clearTimeout: clear,
+    platform: "win32",
+  })(harness.api as any);
+  const startup = harness.emit("session_start");
+  await new Promise((resolve) => setImmediate(resolve));
+  assert.match(harness.statuses.get("plastic-branch") ?? "", /unavailable/);
+  await harness.emit("session_shutdown", { reason: "quit" });
+  await startup;
+  assert.equal(aborted, true, "shutdown should abort in-flight cm confirmation");
+  assert.equal(harness.statuses.has("plastic-branch"), false);
+}
+
+{
+  timers.length = 0;
+  const harness = new FooterHarness();
+  let markerPresent = true;
+  const watched: Array<{ path: string; change: () => void; closed: boolean }> = [];
+  createPlasticBranchStatusExtension({
+    discoverWorkspace: async () => markerPresent ? workspace("/workspace") : { kind: "not_found" },
+    readSelector: async () => "smartbranch /main/recreated\n",
+    watchDirectory: (path, onChange) => {
+      const handle = { path, change: onChange, closed: false };
+      watched.push(handle);
+      return { close: () => { handle.closed = true; } };
+    },
+    confirmBranch: async () => "/main/recreated@repo@server\n",
+    setTimeout: schedule,
+    clearTimeout: clear,
+    platform: "linux",
+  })(harness.api as any);
+
+  await harness.emit("session_start");
+  markerPresent = false;
+  watched.find((entry) => entry.path.endsWith("/.plastic") && !entry.closed)?.change();
+  await runTimers(150);
+  assert.equal(harness.statuses.has("plastic-branch"), false);
+  const recoveryWatcher = watched.find((entry) => entry.path === "/workspace" && !entry.closed);
+  assert.ok(recoveryWatcher, "workspace root should remain watched while .plastic is temporarily absent");
+
+  markerPresent = true;
+  recoveryWatcher?.change();
+  await runTimers(150);
+  assert.match(harness.statuses.get("plastic-branch") ?? "", /recreated/);
+  assert.ok(watched.some((entry) => entry.path.endsWith("/.plastic") && !entry.closed), "recreated .plastic directory should be rebound");
+  await harness.emit("session_shutdown");
+  assert.ok(watched.every((entry) => entry.closed), "all primary and recovery watchers should close on shutdown");
+}
+
+{
+  timers.length = 0;
+  const harness = new FooterHarness();
+  let innerPresent = true;
+  const watched: Array<{ path: string; change: () => void; closed: boolean }> = [];
+  createPlasticBranchStatusExtension({
+    discoverWorkspace: async () => innerPresent ? workspace("/workspace/inner") : workspace("/workspace"),
+    readSelector: async (path) => path.includes("/inner/") ? "smartbranch /main/inner\n" : "smartbranch /main/outer\n",
+    watchDirectory: (path, onChange) => {
+      const handle = { path, change: onChange, closed: false };
+      watched.push(handle);
+      return { close: () => { handle.closed = true; } };
+    },
+    confirmBranch: async (cwd) => cwd.endsWith("/inner") ? "/main/inner@repo@server\n" : "/main/outer@repo@server\n",
+    setTimeout: schedule,
+    clearTimeout: clear,
+    platform: "linux",
+  })(harness.api as any);
+
+  await harness.emit("session_start");
+  innerPresent = false;
+  watched.find((entry) => entry.path === "/workspace/inner/.plastic" && !entry.closed)?.change();
+  await runTimers(150);
+  assert.match(harness.statuses.get("plastic-branch") ?? "", /\/main\/outer/);
+  const nestedRecovery = watched.find((entry) => entry.path === "/workspace/inner" && !entry.closed);
+  assert.ok(nestedRecovery, "former nested workspace root should remain watched during outer fallback");
+
+  innerPresent = true;
+  nestedRecovery?.change();
+  await runTimers(150);
+  assert.match(harness.statuses.get("plastic-branch") ?? "", /\/main\/inner/);
+  assert.ok(watched.some((entry) => entry.path === "/workspace/inner/.plastic" && !entry.closed));
+  assert.equal(watched.some((entry) => entry.path === "/workspace/inner" && !entry.closed), false);
+  await harness.emit("session_shutdown");
+  assert.ok(watched.every((entry) => entry.closed));
+}
+
+{
+  const source = await readFile(new URL("../extensions/plastic-branch-status.ts", import.meta.url), "utf8");
+  assert.doesNotMatch(source, /\.setFooter\s*\(/, "additive branch extension must never replace Pi's footer");
+}
+
+console.log("PASS: Plastic branch footer lifecycle and composition tests passed");