@komarspn/pi-permission-system 16.0.2

package/test/helpers/make-fake-pi.ts

@@ -0,0 +1,100 @@
+/**
+ * `makeFakePi()` — a composition-root test harness.
+ *
+ * Lets a test run the real `piPermissionSystemExtension(pi)` factory and then
+ * introspect and drive the result. Unlike the per-handler unit fixtures in
+ * `handler-fixtures.ts` (which inject collaborators), this harness exercises the
+ * factory itself — the wiring layer where registration completeness, shared-
+ * instance contracts, teardown, and event ordering live.
+ *
+ * It provides:
+ * - `events` — a real `createEventBus()` so cross-extension pub/sub and RPC
+ *   behave as in production (tests can inject a shared bus to model parent/child
+ *   instances).
+ * - `handlers` — every `pi.on(event, handler)` registration, keyed by event
+ *   name, so a test can assert completeness and fire handlers.
+ * - `commands` — every `pi.registerCommand(name, …)` registration.
+ * - `fire(event, input, ctx)` — drive a registered handler; resolves to its
+ *   (possibly async) result.
+ *
+ * The harness object is cast to `ExtensionAPI` at the call to the factory; the
+ * `FakePi` interface itself stays narrow (ISP — only what the factory touches).
+ */
+import { createEventBus, type EventBus } from "@earendil-works/pi-coding-agent";
+import { vi } from "vitest";
+
+/** A handler recorded by `pi.on(...)`, kept generic over event/result shapes. */
+export type RecordedHandler = (event: unknown, ctx: unknown) => unknown;
+
+export interface FakePi {
+  /** Real event bus so cross-extension pub/sub and RPC behave as in production. */
+  events: EventBus;
+  /** Every `pi.on(event, handler)` registration, keyed by event name. */
+  handlers: Map<string, RecordedHandler>;
+  /** Every `pi.registerCommand(name, …)` registration, keyed by command name. */
+  commands: Map<string, unknown>;
+  /**
+   * Drive a registered handler; resolves to its (possibly async) result.
+   *
+   * Throws if no handler is registered for `event` so a typo in a test surfaces
+   * loudly instead of silently resolving to `undefined`.
+   */
+  fire(event: string, input?: unknown, ctx?: unknown): Promise<unknown>;
+  /** Minimal tool registry — returns the configured tool names. */
+  getAllTools(): { name: string }[];
+  /** Active tool names (`pi.getActiveTools()` shape — bare strings). */
+  getActiveTools(): string[];
+  setActiveTools(names: string[]): void;
+}
+
+export interface MakeFakePiOptions {
+  /** Inject a shared bus to model parent/child instances; defaults to a fresh bus. */
+  events?: EventBus;
+  /** Tool names returned by `getAllTools()`; defaults to a small set. */
+  toolNames?: readonly string[];
+}
+
+const DEFAULT_TOOL_NAMES = ["read", "write", "edit", "bash", "ls", "grep"];
+
+/**
+ * Build a fake `ExtensionAPI` for composition-root tests.
+ *
+ * The returned object is structurally a `FakePi`; pass it to the factory as
+ * `piPermissionSystemExtension(pi as unknown as ExtensionAPI)`.
+ */
+export function makeFakePi(options: MakeFakePiOptions = {}): FakePi {
+  const events = options.events ?? createEventBus();
+  const toolNames = options.toolNames ?? DEFAULT_TOOL_NAMES;
+  const handlers = new Map<string, RecordedHandler>();
+  const commands = new Map<string, unknown>();
+
+  return {
+    events,
+    handlers,
+    commands,
+    fire(event, input, ctx): Promise<unknown> {
+      const handler = handlers.get(event);
+      if (!handler) {
+        throw new Error(`No handler registered for event "${event}"`);
+      }
+      return Promise.resolve(handler(input, ctx));
+    },
+    getAllTools(): { name: string }[] {
+      return toolNames.map((name) => ({ name }));
+    },
+    getActiveTools(): string[] {
+      return [...toolNames];
+    },
+    setActiveTools: vi.fn(),
+    // ── ExtensionAPI methods the factory touches (recorded) ────────────────
+    on(event: string, handler: RecordedHandler): void {
+      handlers.set(event, handler);
+    },
+    registerCommand(name: string, optionsArg: unknown): void {
+      commands.set(name, optionsArg);
+    },
+    // ── ExtensionAPI methods present for the cast but unused by the factory ─
+    registerProvider: vi.fn(),
+    exec: vi.fn(),
+  } as FakePi & Record<string, unknown>;
+}

package/test/helpers/manager-harness.ts

@@ -0,0 +1,112 @@
+/**
+ * Filesystem-backed PermissionManager harness for integration tests.
+ *
+ * Writes a real config file and agents directory to a temp directory so
+ * PermissionManager can load them without mocking the file system.
+ */
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { PermissionManager } from "#src/permission-manager";
+import type { ScopeConfig } from "#src/types";
+
+export type CreateManagerOptions = {
+  mcpServerNames?: readonly string[];
+};
+
+export type CreateManagerWithProjectOptions = CreateManagerOptions & {
+  projectConfig?: ScopeConfig;
+  projectAgentFiles?: Record<string, string>;
+};
+
+export function createManager(
+  config: ScopeConfig,
+  agentFiles: Record<string, string> = {},
+  options: CreateManagerOptions = {},
+) {
+  const baseDir = mkdtempSync(join(tmpdir(), "pi-permission-system-test-"));
+  const globalConfigPath = join(baseDir, "pi-permissions.jsonc");
+  const agentsDir = join(baseDir, "agents");
+
+  mkdirSync(agentsDir, { recursive: true });
+  writeFileSync(
+    globalConfigPath,
+    `${JSON.stringify(config, null, 2)}\n`,
+    "utf8",
+  );
+
+  for (const [name, content] of Object.entries(agentFiles)) {
+    writeFileSync(join(agentsDir, `${name}.md`), content, "utf8");
+  }
+
+  const manager = new PermissionManager({
+    globalConfigPath,
+    agentsDir,
+    mcpServerNames: options.mcpServerNames,
+  });
+
+  return {
+    manager,
+    globalConfigPath,
+    cleanup: (): void => {
+      rmSync(baseDir, { recursive: true, force: true });
+    },
+  };
+}
+
+export function createManagerWithProject(
+  config: ScopeConfig,
+  agentFiles: Record<string, string> = {},
+  options: CreateManagerWithProjectOptions = {},
+) {
+  const baseDir = mkdtempSync(
+    join(tmpdir(), "pi-permission-system-proj-test-"),
+  );
+  const globalConfigPath = join(baseDir, "pi-permissions.jsonc");
+  const agentsDir = join(baseDir, "agents");
+  const projectRoot = join(baseDir, "project");
+  const projectGlobalConfigPath = join(projectRoot, "pi-permissions.jsonc");
+  const projectAgentsDir = join(projectRoot, "agents");
+
+  mkdirSync(agentsDir, { recursive: true });
+  mkdirSync(projectAgentsDir, { recursive: true });
+
+  writeFileSync(
+    globalConfigPath,
+    `${JSON.stringify(config, null, 2)}\n`,
+    "utf8",
+  );
+  if (options.projectConfig) {
+    writeFileSync(
+      projectGlobalConfigPath,
+      `${JSON.stringify(options.projectConfig, null, 2)}\n`,
+      "utf8",
+    );
+  }
+
+  for (const [name, content] of Object.entries(agentFiles)) {
+    writeFileSync(join(agentsDir, `${name}.md`), content, "utf8");
+  }
+
+  for (const [name, content] of Object.entries(
+    options.projectAgentFiles ?? {},
+  )) {
+    writeFileSync(join(projectAgentsDir, `${name}.md`), content, "utf8");
+  }
+
+  const manager = new PermissionManager({
+    globalConfigPath,
+    agentsDir,
+    projectGlobalConfigPath,
+    projectAgentsDir,
+    mcpServerNames: options.mcpServerNames,
+  });
+
+  return {
+    manager,
+    cleanup: (): void => {
+      rmSync(baseDir, { recursive: true, force: true });
+    },
+  };
+}

package/test/helpers/session-fixtures.ts

@@ -0,0 +1,204 @@
+/**
+ * Shared real-instance test fixtures for PermissionSession and
+ * PermissionResolver.
+ *
+ * Use these instead of hand-rolling per-file mock intersection types.
+ * Build a real PermissionSession from small per-collaborator fakes so tests
+ * assert against actual behavior rather than mock contracts.
+ *
+ * Note: tests that exercise `resolveAgentName` must mock `active-agent` in
+ * their own file (the vi.hoisted / vi.mock pattern from permission-session.test.ts)
+ * since that mock is module-scoped.
+ */
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { vi } from "vitest";
+
+import type { SessionConfigStore } from "#src/config-store";
+import { DEFAULT_EXTENSION_CONFIG } from "#src/extension-config";
+import type { ExtensionPaths } from "#src/extension-paths";
+import type { ForwardingController } from "#src/forwarding-manager";
+import type { ScopedPermissionManager } from "#src/permission-manager";
+import { PermissionResolver } from "#src/permission-resolver";
+import { PermissionSession } from "#src/permission-session";
+import type { PromptingGatewayLifecycle } from "#src/prompting-gateway";
+import type { Ruleset } from "#src/rule";
+import type { SessionLogger } from "#src/session-logger";
+import { SessionRules } from "#src/session-rules";
+import type { PermissionCheckResult, PermissionState } from "#src/types";
+
+// ── Per-collaborator fake factories ────────────────────────────────────────
+
+export function makePaths(
+  overrides: Partial<ExtensionPaths> = {},
+): ExtensionPaths {
+  return {
+    agentDir: "/test/agent",
+    sessionsDir: "/test/agent/sessions",
+    subagentSessionsDir: "/test/agent/subagent-sessions",
+    forwardingDir: "/test/agent/sessions/permission-forwarding",
+    globalLogsDir: "/test/agent/logs",
+    piInfrastructureDirs: ["/test/agent", "/test/agent/git"],
+    ...overrides,
+  };
+}
+
+export function makeLogger(): SessionLogger {
+  return {
+    debug: vi.fn(),
+    review: vi.fn(),
+    warn: vi.fn(),
+  };
+}
+
+export function makeConfigStore(
+  overrides: Partial<SessionConfigStore> = {},
+): SessionConfigStore {
+  return {
+    current:
+      overrides.current ??
+      vi
+        .fn<() => typeof DEFAULT_EXTENSION_CONFIG>()
+        .mockReturnValue({ ...DEFAULT_EXTENSION_CONFIG }),
+    refresh: overrides.refresh ?? vi.fn<(ctx?: ExtensionContext) => void>(),
+    logResolvedPaths: overrides.logResolvedPaths ?? vi.fn<() => void>(),
+  };
+}
+
+export function makeGateway(): PromptingGatewayLifecycle {
+  return {
+    activate: vi.fn<PromptingGatewayLifecycle["activate"]>(),
+    deactivate: vi.fn<PromptingGatewayLifecycle["deactivate"]>(),
+  };
+}
+
+export function makeForwarding(): ForwardingController {
+  return {
+    start: vi.fn(),
+    stop: vi.fn(),
+  };
+}
+
+/**
+ * Fake `ScopedPermissionManager` with vi.fn() stubs.
+ *
+ * Return type is intentionally unannotated so callers retain full `vi.fn()`
+ * mock access (`mock.calls`, `toHaveBeenCalledWith`, `mockReturnValue`, etc.).
+ */
+export function makeFakePermissionManager() {
+  return {
+    configureForCwd: vi.fn<(cwd: string | undefined | null) => void>(),
+    checkPermission: vi
+      .fn<
+        (
+          toolName: string,
+          input: unknown,
+          agentName?: string,
+          sessionRules?: Ruleset,
+        ) => PermissionCheckResult
+      >()
+      .mockReturnValue({
+        state: "allow",
+        toolName: "read",
+        source: "tool",
+        origin: "builtin",
+      }),
+    checkPathPolicy: vi
+      .fn<
+        (
+          values: readonly string[],
+          agentName?: string,
+          sessionRules?: Ruleset,
+        ) => PermissionCheckResult
+      >()
+      .mockReturnValue({
+        state: "allow",
+        toolName: "path",
+        source: "special",
+        origin: "builtin",
+      }),
+    getToolPermission: vi
+      .fn<(toolName: string, agentName?: string) => PermissionState>()
+      .mockReturnValue("allow"),
+    getConfigIssues: vi.fn((): string[] => []),
+  };
+}
+
+// ── Real-instance factories ────────────────────────────────────────────────
+
+/**
+ * Build a real PermissionSession from per-collaborator fakes.
+ *
+ * Returns the session and every collaborator so callers can destructure only
+ * what they need and assert against collaborator spies directly.
+ * The `permissionManager` is a `makeFakePermissionManager()` result unless
+ * the caller passes an explicit `ScopedPermissionManager`.
+ */
+export function makeRealSession(overrides?: {
+  paths?: Partial<ExtensionPaths>;
+  logger?: SessionLogger;
+  forwarding?: ForwardingController;
+  permissionManager?: ScopedPermissionManager;
+  sessionRules?: SessionRules;
+  configStore?: SessionConfigStore;
+  gateway?: PromptingGatewayLifecycle;
+}): {
+  session: PermissionSession;
+  paths: ExtensionPaths;
+  logger: SessionLogger;
+  forwarding: ForwardingController;
+  permissionManager: ReturnType<typeof makeFakePermissionManager>;
+  sessionRules: SessionRules;
+  configStore: SessionConfigStore;
+  gateway: PromptingGatewayLifecycle;
+} {
+  const paths = makePaths(overrides?.paths);
+  const logger = overrides?.logger ?? makeLogger();
+  const forwarding = overrides?.forwarding ?? makeForwarding();
+  const permissionManager =
+    (overrides?.permissionManager as
+      | ReturnType<typeof makeFakePermissionManager>
+      | undefined) ?? makeFakePermissionManager();
+  const sessionRules = overrides?.sessionRules ?? new SessionRules();
+  const configStore = overrides?.configStore ?? makeConfigStore();
+  const gateway = overrides?.gateway ?? makeGateway();
+  const session = new PermissionSession(
+    paths,
+    forwarding,
+    permissionManager,
+    sessionRules,
+    configStore,
+    gateway,
+  );
+  return {
+    session,
+    paths,
+    logger,
+    forwarding,
+    permissionManager,
+    sessionRules,
+    configStore,
+    gateway,
+  };
+}
+
+/**
+ * Build a real PermissionResolver from a fake manager and a SessionRules
+ * instance.
+ *
+ * When called with no arguments, creates a fresh fake manager and fresh
+ * SessionRules.  Pass shared instances to connect the resolver to the same
+ * manager/rules used by a real session.
+ */
+export function makeRealResolver(
+  manager?: ReturnType<typeof makeFakePermissionManager>,
+  sessionRules?: SessionRules,
+): {
+  resolver: PermissionResolver;
+  manager: ReturnType<typeof makeFakePermissionManager>;
+  sessionRules: SessionRules;
+} {
+  const resolvedManager = manager ?? makeFakePermissionManager();
+  const resolvedRules = sessionRules ?? new SessionRules();
+  const resolver = new PermissionResolver(resolvedManager, resolvedRules);
+  return { resolver, manager: resolvedManager, sessionRules: resolvedRules };
+}