@hellcoder/companion 0.96.0

package/server/prompt-manager.test.ts

@@ -0,0 +1,211 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+let tempDir: string;
+let promptManager: typeof import("./prompt-manager.js");
+
+const mockHomedir = vi.hoisted(() => {
+  let dir = "";
+  return {
+    get: () => dir,
+    set: (d: string) => {
+      dir = d;
+    },
+  };
+});
+
+vi.mock("node:os", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:os")>();
+  return {
+    ...actual,
+    homedir: () => mockHomedir.get(),
+  };
+});
+
+beforeEach(async () => {
+  tempDir = mkdtempSync(join(tmpdir(), "prompt-test-"));
+  mockHomedir.set(tempDir);
+  vi.resetModules();
+  promptManager = await import("./prompt-manager.js");
+});
+
+afterEach(() => {
+  rmSync(tempDir, { recursive: true, force: true });
+});
+
+describe("createPrompt", () => {
+  it("creates a global prompt", () => {
+    // Validates global prompts persist without project path coupling.
+    const prompt = promptManager.createPrompt("Review PR", "Review this PR and summarize risks", "global");
+    expect(prompt.scope).toBe("global");
+    expect(prompt.projectPath).toBeUndefined();
+    expect(prompt.projectPaths).toBeUndefined();
+    expect(prompt.id).toBeTruthy();
+  });
+
+  it("creates a project prompt with normalized path", () => {
+    // Validates project scope stores a normalized project root for later cwd matching.
+    const prompt = promptManager.createPrompt("Plan", "Plan this feature", "project", "/tmp/my-repo/");
+    expect(prompt.scope).toBe("project");
+    expect(prompt.projectPath).toBe("/tmp/my-repo");
+    expect(prompt.projectPaths).toEqual(["/tmp/my-repo"]);
+  });
+
+  it("creates a project prompt with multiple projectPaths", () => {
+    // Validates multi-folder targeting stores all paths normalized and deduplicated.
+    const prompt = promptManager.createPrompt(
+      "Multi",
+      "Multi-project prompt",
+      "project",
+      undefined,
+      ["/tmp/repo-a/", "/tmp/repo-b", "/tmp/repo-a/"],
+    );
+    expect(prompt.scope).toBe("project");
+    expect(prompt.projectPaths).toEqual(["/tmp/repo-a", "/tmp/repo-b"]);
+    // projectPath is set to the first path for backward compatibility
+    expect(prompt.projectPath).toBe("/tmp/repo-a");
+  });
+
+  it("merges projectPaths and legacy projectPath without duplicates", () => {
+    // When both projectPaths and projectPath are provided, they should be merged and deduped.
+    const prompt = promptManager.createPrompt(
+      "Merge",
+      "Merged",
+      "project",
+      "/tmp/repo-a",
+      ["/tmp/repo-b", "/tmp/repo-a"],
+    );
+    expect(prompt.projectPaths).toEqual(["/tmp/repo-b", "/tmp/repo-a"]);
+  });
+
+  it("rejects project prompts without a project path", () => {
+    expect(() => promptManager.createPrompt("Plan", "x", "project")).toThrow(
+      "Project path is required for project prompts",
+    );
+  });
+
+  it("rejects project prompts with empty projectPaths array", () => {
+    // An empty array is not valid for project scope.
+    expect(() => promptManager.createPrompt("Plan", "x", "project", undefined, [])).toThrow(
+      "Project path is required for project prompts",
+    );
+  });
+});
+
+describe("listPrompts", () => {
+  it("returns global + matching project prompts for cwd", () => {
+    // Verifies cwd filtering includes global prompts and only project prompts in the same repo subtree.
+    const global = promptManager.createPrompt("Global", "Global text", "global");
+    const project = promptManager.createPrompt("Project", "Project text", "project", "/tmp/repo");
+    promptManager.createPrompt("Other", "Other text", "project", "/tmp/other");
+
+    const prompts = promptManager.listPrompts({ cwd: "/tmp/repo/packages/ui" });
+    expect(prompts.map((p) => p.id)).toContain(global.id);
+    expect(prompts.map((p) => p.id)).toContain(project.id);
+    expect(prompts.map((p) => p.name)).not.toContain("Other");
+  });
+
+  it("matches cwd against any of the projectPaths", () => {
+    // A prompt with multiple projectPaths should be visible in any of those directories.
+    const multi = promptManager.createPrompt(
+      "Multi-target",
+      "Visible in both repos",
+      "project",
+      undefined,
+      ["/tmp/repo-a", "/tmp/repo-b"],
+    );
+
+    const inA = promptManager.listPrompts({ cwd: "/tmp/repo-a/src" });
+    expect(inA.map((p) => p.id)).toContain(multi.id);
+
+    const inB = promptManager.listPrompts({ cwd: "/tmp/repo-b" });
+    expect(inB.map((p) => p.id)).toContain(multi.id);
+
+    const inC = promptManager.listPrompts({ cwd: "/tmp/repo-c" });
+    expect(inC.map((p) => p.id)).not.toContain(multi.id);
+  });
+
+  it("reads legacy prompts with only projectPath (no projectPaths)", () => {
+    // Simulates loading a prompts.json that was created before projectPaths existed.
+    const companionDir = join(tempDir, ".companion");
+    mkdirSync(companionDir, { recursive: true });
+    writeFileSync(
+      join(companionDir, "prompts.json"),
+      JSON.stringify([
+        {
+          id: "legacy-1",
+          name: "Legacy",
+          content: "Legacy prompt",
+          scope: "project",
+          projectPath: "/tmp/legacy-repo",
+          createdAt: 1,
+          updatedAt: 2,
+        },
+      ]),
+    );
+
+    // Re-import to pick up the written file
+    const prompts = promptManager.listPrompts({ cwd: "/tmp/legacy-repo/src" });
+    expect(prompts.map((p) => p.id)).toContain("legacy-1");
+  });
+});
+
+describe("updatePrompt", () => {
+  it("updates a prompt name/content", () => {
+    // Ensures edits update mutable fields while preserving prompt identity.
+    const prompt = promptManager.createPrompt("Old", "Old content", "global");
+    const updated = promptManager.updatePrompt(prompt.id, { name: "New", content: "New content" });
+    expect(updated).not.toBeNull();
+    expect(updated!.name).toBe("New");
+    expect(updated!.content).toBe("New content");
+  });
+
+  it("changes scope from global to project with projectPaths", () => {
+    // Validates that update can change scope and set project paths.
+    const prompt = promptManager.createPrompt("Was global", "Some content", "global");
+    const updated = promptManager.updatePrompt(prompt.id, {
+      scope: "project",
+      projectPaths: ["/tmp/repo-x"],
+    });
+    expect(updated!.scope).toBe("project");
+    expect(updated!.projectPaths).toEqual(["/tmp/repo-x"]);
+    expect(updated!.projectPath).toBe("/tmp/repo-x");
+  });
+
+  it("changes scope from project to global and clears paths", () => {
+    // Validates that switching to global removes projectPaths.
+    const prompt = promptManager.createPrompt("Was project", "Content", "project", "/tmp/repo");
+    const updated = promptManager.updatePrompt(prompt.id, { scope: "global" });
+    expect(updated!.scope).toBe("global");
+    expect(updated!.projectPaths).toBeUndefined();
+    expect(updated!.projectPath).toBeUndefined();
+  });
+
+  it("rejects switching to project scope without paths", () => {
+    // Project scope without paths should fail validation.
+    const prompt = promptManager.createPrompt("Global", "Content", "global");
+    expect(() => promptManager.updatePrompt(prompt.id, { scope: "project" })).toThrow(
+      "Project path is required for project prompts",
+    );
+  });
+
+  it("updates projectPaths on an existing project prompt", () => {
+    // Validates that projectPaths can be updated independently.
+    const prompt = promptManager.createPrompt("Project", "Content", "project", "/tmp/repo-a");
+    const updated = promptManager.updatePrompt(prompt.id, {
+      projectPaths: ["/tmp/repo-b", "/tmp/repo-c"],
+    });
+    expect(updated!.projectPaths).toEqual(["/tmp/repo-b", "/tmp/repo-c"]);
+    expect(updated!.projectPath).toBe("/tmp/repo-b");
+  });
+});
+
+describe("deletePrompt", () => {
+  it("deletes a prompt", () => {
+    // Ensures a deleted prompt is no longer retrievable.
+    const prompt = promptManager.createPrompt("Delete me", "tmp", "global");
+    expect(promptManager.deletePrompt(prompt.id)).toBe(true);
+    expect(promptManager.getPrompt(prompt.id)).toBeNull();
+  });
+});

package/server/prompt-manager.ts

@@ -0,0 +1,211 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { COMPANION_HOME } from "./paths.js";
+
+export type PromptScope = "global" | "project";
+
+export interface SavedPrompt {
+  id: string;
+  name: string;
+  content: string;
+  scope: PromptScope;
+  projectPath?: string;
+  projectPaths?: string[];
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface PromptUpdateFields {
+  name?: string;
+  content?: string;
+  scope?: PromptScope;
+  projectPaths?: string[];
+}
+
+const PROMPTS_FILE = join(COMPANION_HOME, "prompts.json");
+
+function ensureDir(): void {
+  mkdirSync(COMPANION_HOME, { recursive: true });
+}
+
+function normalizePath(path: string): string {
+  return resolve(path).replace(/[\\/]+$/, "");
+}
+
+function loadPrompts(): SavedPrompt[] {
+  ensureDir();
+  if (!existsSync(PROMPTS_FILE)) return [];
+  try {
+    const raw = readFileSync(PROMPTS_FILE, "utf-8");
+    const parsed = JSON.parse(raw) as unknown;
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter((p): p is SavedPrompt => {
+      if (!p || typeof p !== "object") return false;
+      const candidate = p as Partial<SavedPrompt>;
+      return (
+        typeof candidate.id === "string"
+        && typeof candidate.name === "string"
+        && typeof candidate.content === "string"
+        && (candidate.scope === "global" || candidate.scope === "project")
+      );
+    });
+  } catch {
+    return [];
+  }
+}
+
+function savePrompts(prompts: SavedPrompt[]): void {
+  ensureDir();
+  writeFileSync(PROMPTS_FILE, JSON.stringify(prompts, null, 2), "utf-8");
+}
+
+function sortPrompts(prompts: SavedPrompt[]): SavedPrompt[] {
+  return [...prompts].sort((a, b) => b.updatedAt - a.updatedAt || a.name.localeCompare(b.name));
+}
+
+function visibleForCwd(prompt: SavedPrompt, cwd: string): boolean {
+  if (prompt.scope === "global") return true;
+  const paths = resolveProjectPaths(prompt);
+  if (paths.length === 0) return false;
+  const normalizedCwd = normalizePath(cwd);
+  return paths.some((p) => {
+    const normalizedProject = normalizePath(p);
+    return normalizedCwd === normalizedProject || normalizedCwd.startsWith(`${normalizedProject}/`);
+  });
+}
+
+/** Merges legacy projectPath and projectPaths into a single deduplicated list. */
+function resolveProjectPaths(prompt: SavedPrompt): string[] {
+  const paths: string[] = [];
+  if (prompt.projectPaths && prompt.projectPaths.length > 0) {
+    paths.push(...prompt.projectPaths);
+  }
+  if (prompt.projectPath && !paths.some((p) => normalizePath(p) === normalizePath(prompt.projectPath!))) {
+    paths.push(prompt.projectPath);
+  }
+  return paths;
+}
+
+export function listPrompts(opts?: { cwd?: string; scope?: "global" | "project" | "all" }): SavedPrompt[] {
+  const prompts = loadPrompts();
+  const scope = opts?.scope ?? "all";
+
+  const filteredByScope = prompts.filter((p) => {
+    if (scope === "all") return true;
+    return p.scope === scope;
+  });
+
+  if (!opts?.cwd) return sortPrompts(filteredByScope);
+
+  return sortPrompts(filteredByScope.filter((p) => visibleForCwd(p, opts.cwd!)));
+}
+
+export function getPrompt(id: string): SavedPrompt | null {
+  return loadPrompts().find((p) => p.id === id) ?? null;
+}
+
+export function createPrompt(
+  name: string,
+  content: string,
+  scope: PromptScope,
+  projectPath?: string,
+  projectPaths?: string[],
+): SavedPrompt {
+  const cleanName = name?.trim();
+  const cleanContent = content?.trim();
+  if (!cleanName) throw new Error("Prompt name is required");
+  if (!cleanContent) throw new Error("Prompt content is required");
+  if (scope !== "global" && scope !== "project") throw new Error("Invalid prompt scope");
+
+  // Merge projectPaths and legacy projectPath into a single deduplicated list
+  const mergedPaths = dedupeAndNormalizePaths(projectPaths, projectPath);
+  if (scope === "project" && mergedPaths.length === 0) {
+    throw new Error("Project path is required for project prompts");
+  }
+
+  const prompts = loadPrompts();
+  const now = Date.now();
+  const prompt: SavedPrompt = {
+    id: crypto.randomUUID(),
+    name: cleanName,
+    content: cleanContent,
+    scope,
+    projectPath: scope === "project" ? mergedPaths[0] : undefined,
+    projectPaths: scope === "project" ? mergedPaths : undefined,
+    createdAt: now,
+    updatedAt: now,
+  };
+  prompts.push(prompt);
+  savePrompts(prompts);
+  return prompt;
+}
+
+function dedupeAndNormalizePaths(paths?: string[], legacyPath?: string): string[] {
+  const seen = new Set<string>();
+  const result: string[] = [];
+  const all = [...(paths ?? []), ...(legacyPath?.trim() ? [legacyPath] : [])];
+  for (const p of all) {
+    const trimmed = p.trim();
+    if (!trimmed) continue;
+    const normalized = normalizePath(trimmed);
+    if (!seen.has(normalized)) {
+      seen.add(normalized);
+      result.push(normalized);
+    }
+  }
+  return result;
+}
+
+export function updatePrompt(id: string, updates: PromptUpdateFields): SavedPrompt | null {
+  const prompts = loadPrompts();
+  const index = prompts.findIndex((p) => p.id === id);
+  if (index < 0) return null;
+
+  if (updates.name !== undefined && !updates.name.trim()) {
+    throw new Error("Prompt name cannot be empty");
+  }
+  if (updates.content !== undefined && !updates.content.trim()) {
+    throw new Error("Prompt content cannot be empty");
+  }
+
+  const newScope = updates.scope ?? prompts[index].scope;
+  if (updates.scope !== undefined && updates.scope !== "global" && updates.scope !== "project") {
+    throw new Error("Invalid prompt scope");
+  }
+
+  let newProjectPaths = prompts[index].projectPaths;
+  let newProjectPath = prompts[index].projectPath;
+  if (updates.projectPaths !== undefined) {
+    const normalized = dedupeAndNormalizePaths(updates.projectPaths);
+    newProjectPaths = normalized.length > 0 ? normalized : undefined;
+    newProjectPath = normalized.length > 0 ? normalized[0] : undefined;
+  }
+  if (newScope === "project" && (!newProjectPaths || newProjectPaths.length === 0)) {
+    throw new Error("Project path is required for project prompts");
+  }
+  if (newScope === "global") {
+    newProjectPaths = undefined;
+    newProjectPath = undefined;
+  }
+
+  const updated: SavedPrompt = {
+    ...prompts[index],
+    name: updates.name !== undefined ? updates.name.trim() : prompts[index].name,
+    content: updates.content !== undefined ? updates.content.trim() : prompts[index].content,
+    scope: newScope,
+    projectPath: newProjectPath,
+    projectPaths: newProjectPaths,
+    updatedAt: Date.now(),
+  };
+  prompts[index] = updated;
+  savePrompts(prompts);
+  return updated;
+}
+
+export function deletePrompt(id: string): boolean {
+  const prompts = loadPrompts();
+  const next = prompts.filter((p) => p.id !== id);
+  if (next.length === prompts.length) return false;
+  savePrompts(next);
+  return true;
+}

package/server/protocol/claude-upstream/README.md

@@ -0,0 +1,19 @@
+# Claude Upstream Snapshot
+
+This folder contains an offline snapshot of the official Claude Agent SDK TypeScript
+surface used by the bridge compatibility tests.
+
+Source package:
+- `@anthropic-ai/claude-agent-sdk@0.2.41`
+- tarball: `https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk/-/claude-agent-sdk-0.2.41.tgz`
+
+Files:
+- `sdk.d.ts.txt` — copied from `package/sdk.d.ts` in the npm tarball
+
+Refresh command (example):
+```bash
+TARBALL=$(npm view @anthropic-ai/claude-agent-sdk dist.tarball)
+curl -fsSL "$TARBALL" -o /tmp/claude-agent-sdk.tgz
+tar -xzf /tmp/claude-agent-sdk.tgz -C /tmp package/sdk.d.ts
+cp /tmp/package/sdk.d.ts web/server/protocol/claude-upstream/sdk.d.ts.txt
+```