@blackbelt-technology/pi-agent-dashboard 0.5.1 → 0.5.2

package/packages/shared/src/__tests__/binary-lookup-resolveJiti.test.ts

@@ -0,0 +1,228 @@
+/**
+ * Tests for `ToolResolver.resolveJiti` — ported from the prior
+ * `resolve-jiti.test.ts`. Exercises every anchor in the resolution
+ * chain (managed-pi upstream/legacy, system-pi, anchor walk-up,
+ * argv fallback, all-miss) plus the URL-shape invariants
+ * (`file://` URL output, Windows drive-letter wrapping, upstream
+ * jiti chosen before legacy fork).
+ *
+ * Test seams (`_pathExists`, `_realpath`, `_whichPi`, `_argv1`,
+ * `_managedDir`, `resolver`) keep the test pure — no fs / process
+ * mutation, no managed-dir on disk.
+ */
+import { describe, it, expect } from "vitest";
+import path from "node:path";
+import { ToolResolver, MANAGED_PI_PACKAGES, JITI_PACKAGES } from "../platform/binary-lookup.js";
+
+const MANAGED_DIR = "/fake/.pi-dashboard";
+
+function makeResolver(installed: Record<string, string>) {
+  return (spec: string): string => {
+    if (spec in installed) return installed[spec]!;
+    throw new Error(`Cannot find module '${spec}'`);
+  };
+}
+
+describe("MANAGED_PI_PACKAGES + JITI_PACKAGES contract", () => {
+  it("upstream pi pkg first, legacy fork fallback", () => {
+    expect(MANAGED_PI_PACKAGES).toEqual([
+      "@earendil-works/pi-coding-agent",
+      "@mariozechner/pi-coding-agent",
+    ]);
+  });
+
+  it("upstream jiti first, legacy fork fallback", () => {
+    expect(JITI_PACKAGES).toEqual(["jiti", "@mariozechner/jiti"]);
+  });
+});
+
+describe("ToolResolver.resolveJiti — managed pi", () => {
+  it("hits upstream managed pi (@earendil-works) when only it is present", () => {
+    const upstreamPkgJson = path.join(
+      MANAGED_DIR, "node_modules", "@earendil-works", "pi-coding-agent", "package.json",
+    );
+    const jitiPkgJson = "/managed/upstream/node_modules/jiti/package.json";
+    const url = new ToolResolver().resolveJiti({
+      _managedDir: MANAGED_DIR,
+      _pathExists: (p) => p === upstreamPkgJson || p === path.join(path.dirname(jitiPkgJson), "lib", "jiti-register.mjs"),
+      _whichPi: () => null,
+      _argv1: undefined,
+      resolver: makeResolver({ "jiti/package.json": jitiPkgJson }),
+    });
+    expect(url).not.toBeNull();
+    expect(url!.startsWith("file://")).toBe(true);
+    expect(url!).toMatch(/\/jiti\/lib\/jiti-register\.mjs$/);
+    expect(url!).not.toContain("@mariozechner");
+  });
+
+  it("falls through to legacy managed pi (@mariozechner) when upstream is absent", () => {
+    const legacyPkgJson = path.join(
+      MANAGED_DIR, "node_modules", "@mariozechner", "pi-coding-agent", "package.json",
+    );
+    const jitiPkgJson = "/managed/legacy/node_modules/@mariozechner/jiti/package.json";
+    const url = new ToolResolver().resolveJiti({
+      _managedDir: MANAGED_DIR,
+      _pathExists: (p) =>
+        p === legacyPkgJson ||
+        p === path.join(path.dirname(jitiPkgJson), "lib", "jiti-register.mjs"),
+      _whichPi: () => null,
+      _argv1: undefined,
+      resolver: makeResolver({
+        "@mariozechner/jiti/package.json": jitiPkgJson,
+      }),
+    });
+    expect(url).not.toBeNull();
+    expect(url!).toContain("@mariozechner/jiti");
+  });
+
+  it("prefers upstream pi over legacy when BOTH managed pkgs are present", () => {
+    const upstream = path.join(MANAGED_DIR, "node_modules", "@earendil-works", "pi-coding-agent", "package.json");
+    const legacy = path.join(MANAGED_DIR, "node_modules", "@mariozechner", "pi-coding-agent", "package.json");
+    const upstreamJiti = "/managed/upstream/jiti/package.json";
+    const legacyJiti = "/managed/legacy/@mariozechner/jiti/package.json";
+    const calls: string[] = [];
+    const resolver = (spec: string): string => {
+      calls.push(spec);
+      if (spec === "jiti/package.json") return upstreamJiti;
+      if (spec === "@mariozechner/jiti/package.json") return legacyJiti;
+      throw new Error(`nope ${spec}`);
+    };
+    const url = new ToolResolver().resolveJiti({
+      _managedDir: MANAGED_DIR,
+      _pathExists: (p) =>
+        p === upstream || p === legacy ||
+        p === path.join(path.dirname(upstreamJiti), "lib", "jiti-register.mjs"),
+      _whichPi: () => null,
+      _argv1: undefined,
+      resolver,
+    });
+    expect(url!).toMatch(/\/jiti\/lib\/jiti-register\.mjs$/);
+    expect(url!).not.toContain("@mariozechner");
+    // Upstream pi anchor produced upstream jiti — legacy pi anchor never tried.
+    expect(calls).toEqual(["jiti/package.json"]);
+  });
+});
+
+describe("ToolResolver.resolveJiti — system pi", () => {
+  it("uses which(\"pi\") when managed pi absent", () => {
+    const piBin = "/usr/local/bin/pi";
+    const piReal = "/usr/local/lib/node_modules/@earendil-works/pi-coding-agent/dist/cli.js";
+    const jitiPkgJson = "/usr/local/lib/node_modules/jiti/package.json";
+    const url = new ToolResolver().resolveJiti({
+      _managedDir: MANAGED_DIR,
+      _pathExists: (p) => p === path.join(path.dirname(jitiPkgJson), "lib", "jiti-register.mjs"),
+      _whichPi: () => piBin,
+      _realpath: (p) => (p === piBin ? piReal : p),
+      _argv1: undefined,
+      resolver: makeResolver({ "jiti/package.json": jitiPkgJson }),
+    });
+    expect(url!.startsWith("file://")).toBe(true);
+    expect(url!).toMatch(/\/jiti\/lib\/jiti-register\.mjs$/);
+  });
+
+  it("realpaths a symlinked pi binary before resolving", () => {
+    const piSymlink = "/usr/local/bin/pi";
+    const piTarget = "/opt/pi/dist/cli.js";
+    const jitiPkgJson = "/opt/pi/node_modules/jiti/package.json";
+    let realpathArg: string | null = null;
+    const url = new ToolResolver().resolveJiti({
+      _managedDir: MANAGED_DIR,
+      // Managed-pi miss; only the symlinked register file exists.
+      _pathExists: (p) => p === path.join(path.dirname(jitiPkgJson), "lib", "jiti-register.mjs"),
+      _whichPi: () => piSymlink,
+      _realpath: (p) => { realpathArg = p; return piTarget; },
+      _argv1: undefined,
+      resolver: makeResolver({ "jiti/package.json": jitiPkgJson }),
+    });
+    expect(realpathArg).toBe(piSymlink);
+    expect(url).not.toBeNull();
+  });
+});
+
+describe("ToolResolver.resolveJiti — anchor walk-up + argv fallback", () => {
+  it("uses caller-supplied anchor when prior layers miss", () => {
+    const anchor = "/custom/cli/path.js";
+    const jitiPkgJson = "/custom/node_modules/jiti/package.json";
+    const url = new ToolResolver().resolveJiti({
+      anchor,
+      _managedDir: MANAGED_DIR,
+      _pathExists: (p) => p === anchor || p === path.join(path.dirname(jitiPkgJson), "lib", "jiti-register.mjs"),
+      _whichPi: () => null,
+      _argv1: undefined,
+      resolver: makeResolver({ "jiti/package.json": jitiPkgJson }),
+    });
+    expect(url).not.toBeNull();
+    expect(url!).toMatch(/\/jiti\/lib\/jiti-register\.mjs$/);
+  });
+
+  it("returns null when caller-supplied anchor does not exist on disk", () => {
+    const url = new ToolResolver().resolveJiti({
+      anchor: "/missing/path.js",
+      _managedDir: MANAGED_DIR,
+      _pathExists: () => false,
+      _whichPi: () => null,
+      _argv1: undefined,
+      resolver: () => "/whatever/jiti/package.json",
+    });
+    expect(url).toBeNull();
+  });
+
+  it("falls back to process.argv[1] (test seam) when all earlier anchors miss", () => {
+    const argv = "/runtime/argv1/cli.js";
+    const jitiPkgJson = "/runtime/node_modules/jiti/package.json";
+    const url = new ToolResolver().resolveJiti({
+      _managedDir: MANAGED_DIR,
+      _pathExists: () => true,
+      _whichPi: () => null,
+      _realpath: (p) => p,
+      _argv1: argv,
+      resolver: makeResolver({ "jiti/package.json": jitiPkgJson }),
+    });
+    expect(url).not.toBeNull();
+  });
+
+  it("returns null when every anchor misses", () => {
+    const url = new ToolResolver().resolveJiti({
+      _managedDir: MANAGED_DIR,
+      _pathExists: () => false,
+      _whichPi: () => null,
+      _argv1: undefined,
+      resolver: () => { throw new Error("nope"); },
+    });
+    expect(url).toBeNull();
+  });
+});
+
+describe("ToolResolver.resolveJiti — URL contract", () => {
+  it("returns a file:// URL parseable by new URL()", () => {
+    const url = new ToolResolver().resolveJiti({
+      _managedDir: MANAGED_DIR,
+      _pathExists: () => true,
+      _whichPi: () => null,
+      _argv1: "/runtime/argv1/cli.js",
+      _realpath: (p) => p,
+      resolver: makeResolver({ "jiti/package.json": "/r/node_modules/jiti/package.json" }),
+    });
+    expect(url!.startsWith("file://")).toBe(true);
+    expect(() => new URL(url!)).not.toThrow();
+    expect(url!.endsWith("/lib/jiti-register.mjs")).toBe(true);
+  });
+
+  it("URL-wraps Windows drive-letter pkg.json paths (regression for ERR_UNSUPPORTED_ESM_URL_SCHEME)", () => {
+    const winPkgJson = "B:\\Dev\\Nodejs\\global\\node_modules\\@mariozechner\\jiti\\package.json";
+    const url = new ToolResolver().resolveJiti({
+      _managedDir: MANAGED_DIR,
+      _pathExists: () => true,
+      _whichPi: () => null,
+      _argv1: "C:\\runtime\\cli.js",
+      _realpath: (p) => p,
+      resolver: makeResolver({ "@mariozechner/jiti/package.json": winPkgJson }),
+    });
+    expect(url).not.toBeNull();
+    expect(url!.startsWith("file:///")).toBe(true);
+    expect(() => new URL(url!)).not.toThrow();
+    expect(new URL(url!).protocol).toBe("file:");
+    expect(url!.toLowerCase()).toContain("/b:/");
+    expect(url!.endsWith("/lib/jiti-register.mjs")).toBe(true);
+  });
+});

package/packages/shared/src/__tests__/config-openspec.test.ts

@@ -104,3 +104,77 @@ describe("loadConfig — openspec poll block", () => {
     expect(second.openspec).toEqual(first.openspec);
   });
 });
+
+describe("loadConfig — openspec.enabled (auto-hide-empty-session-subcards)", () => {
+  let testDir: string;
+  let configFile: string;
+  let origHome: string;
+
+  beforeEach(() => {
+    testDir = path.join(
+      os.tmpdir(),
+      `test-config-openspec-enabled-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+    );
+    fs.mkdirSync(path.join(testDir, ".pi", "dashboard"), { recursive: true });
+    configFile = path.join(testDir, ".pi", "dashboard", "config.json");
+    origHome = process.env.HOME!;
+    process.env.HOME = testDir;
+  });
+
+  afterEach(() => {
+    process.env.HOME = origHome;
+    if (fs.existsSync(testDir)) fs.rmSync(testDir, { recursive: true });
+  });
+
+  it("defaults to true when openspec block is absent", () => {
+    fs.writeFileSync(configFile, JSON.stringify({ port: 8000 }));
+    expect(loadConfig().openspec.enabled).toBe(true);
+  });
+
+  it("defaults to true when openspec block has other fields but no `enabled`", () => {
+    fs.writeFileSync(
+      configFile,
+      JSON.stringify({ openspec: { pollIntervalSeconds: 60 } }),
+    );
+    expect(loadConfig().openspec.enabled).toBe(true);
+  });
+
+  it("preserves explicit `false`", () => {
+    fs.writeFileSync(
+      configFile,
+      JSON.stringify({ openspec: { enabled: false } }),
+    );
+    const cfg = loadConfig();
+    expect(cfg.openspec.enabled).toBe(false);
+    // sibling fields keep their defaults
+    expect(cfg.openspec.pollIntervalSeconds).toBe(30);
+  });
+
+  it("preserves explicit `true`", () => {
+    fs.writeFileSync(
+      configFile,
+      JSON.stringify({ openspec: { enabled: true } }),
+    );
+    expect(loadConfig().openspec.enabled).toBe(true);
+  });
+
+  it("falls back to default true on non-boolean", () => {
+    fs.writeFileSync(
+      configFile,
+      JSON.stringify({ openspec: { enabled: "yes" } }),
+    );
+    expect(loadConfig().openspec.enabled).toBe(true);
+  });
+
+  it("round-trips through load → stringify → load", () => {
+    fs.writeFileSync(
+      configFile,
+      JSON.stringify({ openspec: { enabled: false, pollIntervalSeconds: 90 } }),
+    );
+    const first = loadConfig();
+    fs.writeFileSync(configFile, JSON.stringify(first));
+    const second = loadConfig();
+    expect(second.openspec.enabled).toBe(false);
+    expect(second.openspec.pollIntervalSeconds).toBe(90);
+  });
+});

package/packages/shared/src/__tests__/model-proxy-config.test.ts

@@ -0,0 +1,146 @@
+import { describe, it, expect } from "vitest";
+import {
+  parseModelProxyConfig,
+  DEFAULT_MODEL_PROXY,
+  type ModelProxyConfig,
+} from "../config.js";
+
+describe("parseModelProxyConfig", () => {
+  it("returns defaults when input is missing", () => {
+    expect(parseModelProxyConfig(undefined)).toEqual(DEFAULT_MODEL_PROXY);
+    expect(parseModelProxyConfig(null)).toEqual(DEFAULT_MODEL_PROXY);
+    expect(parseModelProxyConfig("string")).toEqual(DEFAULT_MODEL_PROXY);
+  });
+
+  it("returns defaults when input is empty object", () => {
+    const result = parseModelProxyConfig({});
+    expect(result.enabled).toBe(true);
+    expect(result.maxConcurrentStreams).toBe(16);
+    expect(result.perKeyConcurrentStreams).toBe(4);
+    expect(result.logRequests).toBe(false);
+    expect(result.apiKeys).toEqual([]);
+  });
+
+  it("preserves valid enabled flag", () => {
+    expect(parseModelProxyConfig({ enabled: false }).enabled).toBe(false);
+    expect(parseModelProxyConfig({ enabled: true }).enabled).toBe(true);
+  });
+
+  it("clamps maxConcurrentStreams to [1, 256]", () => {
+    expect(parseModelProxyConfig({ maxConcurrentStreams: 0 }).maxConcurrentStreams).toBe(1);
+    expect(parseModelProxyConfig({ maxConcurrentStreams: -5 }).maxConcurrentStreams).toBe(1);
+    expect(parseModelProxyConfig({ maxConcurrentStreams: 500 }).maxConcurrentStreams).toBe(256);
+    expect(parseModelProxyConfig({ maxConcurrentStreams: 32 }).maxConcurrentStreams).toBe(32);
+    // Non-number falls back to default
+    expect(parseModelProxyConfig({ maxConcurrentStreams: "ten" }).maxConcurrentStreams).toBe(16);
+  });
+
+  it("clamps perKeyConcurrentStreams to [1, 64]", () => {
+    expect(parseModelProxyConfig({ perKeyConcurrentStreams: 0 }).perKeyConcurrentStreams).toBe(1);
+    expect(parseModelProxyConfig({ perKeyConcurrentStreams: 100 }).perKeyConcurrentStreams).toBe(64);
+    expect(parseModelProxyConfig({ perKeyConcurrentStreams: 8 }).perKeyConcurrentStreams).toBe(8);
+  });
+
+  it("accepts arbitrary string keys in perProviderCaps", () => {
+    const result = parseModelProxyConfig({
+      perProviderCaps: { anthropic: 5, google: 10, "custom-provider": 2 },
+    });
+    expect(result.perProviderCaps).toEqual({ anthropic: 5, google: 10, "custom-provider": 2 });
+  });
+
+  it("filters invalid perProviderCaps entries", () => {
+    const result = parseModelProxyConfig({
+      perProviderCaps: { valid: 5, bad: "nope", zero: 0, negative: -1 },
+    });
+    expect(result.perProviderCaps).toEqual({ valid: 5 });
+  });
+
+  it("clamps perProviderCaps values to max 256", () => {
+    const result = parseModelProxyConfig({
+      perProviderCaps: { huge: 999 },
+    });
+    expect(result.perProviderCaps).toEqual({ huge: 256 });
+  });
+
+  it("omits perProviderCaps when not an object", () => {
+    expect(parseModelProxyConfig({ perProviderCaps: "bad" }).perProviderCaps).toBeUndefined();
+    expect(parseModelProxyConfig({ perProviderCaps: [1] }).perProviderCaps).toBeUndefined();
+  });
+
+  it("validates apiKeys entries — rejects missing hash", () => {
+    const result = parseModelProxyConfig({
+      apiKeys: [
+        { id: "a", label: "test", createdAt: 1000 }, // missing hash
+        { id: "b", label: "ok", hash: "abc123", createdAt: 2000 },
+      ],
+    });
+    expect(result.apiKeys).toHaveLength(1);
+    expect(result.apiKeys[0].id).toBe("b");
+  });
+
+  it("validates apiKeys entries — rejects missing id/label/createdAt", () => {
+    const result = parseModelProxyConfig({
+      apiKeys: [
+        { label: "no-id", hash: "h", createdAt: 1 },
+        { id: "no-label", hash: "h", createdAt: 1 },
+        { id: "no-time", label: "x", hash: "h" },
+      ],
+    });
+    expect(result.apiKeys).toHaveLength(0);
+  });
+
+  it("preserves optional apiKey fields", () => {
+    const result = parseModelProxyConfig({
+      apiKeys: [
+        {
+          id: "k1",
+          label: "full",
+          hash: "sha",
+          createdAt: 1000,
+          createdBy: "alice@x",
+          scopes: ["all"],
+          lastUsedAt: 2000,
+          expiresAt: 9999,
+          revokedAt: 3000,
+        },
+      ],
+    });
+    expect(result.apiKeys[0]).toEqual({
+      id: "k1",
+      label: "full",
+      hash: "sha",
+      createdAt: 1000,
+      createdBy: "alice@x",
+      scopes: ["all"],
+      lastUsedAt: 2000,
+      expiresAt: 9999,
+      revokedAt: 3000,
+    });
+  });
+
+  it("filters non-string scopes in apiKeys", () => {
+    const result = parseModelProxyConfig({
+      apiKeys: [
+        { id: "k1", label: "t", hash: "h", createdAt: 1, scopes: ["chat", 42, null, "messages"] },
+      ],
+    });
+    expect(result.apiKeys[0].scopes).toEqual(["chat", "messages"]);
+  });
+
+  it("validates secondPort range [1024, 65535]", () => {
+    expect(parseModelProxyConfig({ secondPort: 9876 }).secondPort).toBe(9876);
+    expect(parseModelProxyConfig({ secondPort: 80 }).secondPort).toBeUndefined();
+    expect(parseModelProxyConfig({ secondPort: 70000 }).secondPort).toBeUndefined();
+    expect(parseModelProxyConfig({ secondPort: "bad" }).secondPort).toBeUndefined();
+  });
+
+  it("preserves defaultModel string", () => {
+    expect(parseModelProxyConfig({ defaultModel: "gpt-4" }).defaultModel).toBe("gpt-4");
+    expect(parseModelProxyConfig({ defaultModel: 42 }).defaultModel).toBeUndefined();
+  });
+
+  it("preserves logRequests boolean", () => {
+    expect(parseModelProxyConfig({ logRequests: true }).logRequests).toBe(true);
+    expect(parseModelProxyConfig({ logRequests: "yes" }).logRequests).toBe(false); // falls back
+  });
+});

package/packages/shared/src/__tests__/no-raw-node-import.test.ts

@@ -20,10 +20,12 @@ import url from "node:url";
 /** Files allowed to reference --import / --loader with raw identifiers. */
 const ALLOWLIST: readonly string[] = [
   "packages/shared/src/platform/node-spawn.ts",
-  // resolve-jiti.ts returns a file:// URL to callers; it does not itself
-  // build a `["--import", X, Y]` argv. Allowlisted as the documented
-  // source of loader URLs referenced in server spawn call sites.
-  "packages/shared/src/resolve-jiti.ts",
+  // server-launcher.ts is the single shared spawn primitive for the
+  // dashboard server (Bridge / Standalone CLI / Electron). It mentions
+  // "--import" in commentary; argv construction itself is delegated to
+  // node-spawn.ts via `spawnNodeScript` / `buildNodeImportArgvParts`.
+  // See change: unify-server-launch-ts-loader.
+  "packages/shared/src/server-launcher.ts",
 ];
 
 /** Per-line opt-out for intentional usages (e.g. comment examples). */
@@ -49,7 +51,7 @@ const IMPORT_ARGV_RE =
   /["']--(?:import|loader)["']\s*,\s*([^,\]]+?)\s*,\s*([^,\]]+?)(?:\s*,|\s*\])/g;
 
 const URL_LOOKING_RE =
-  /^(?:["']file:|toFileUrl\s*\(|pathToFileURL\s*\([^)]*\)\s*\.href|resolveJitiImport\s*\(|resolveJitiFromAnchor\s*\()/;
+  /^(?:["']file:|toFileUrl\s*\(|pathToFileURL\s*\([^)]*\)\s*\.href)/;
 
 /** Recursively walk a directory, yielding .ts / .tsx files. */
 async function* walk(dir: string): AsyncGenerator<string> {

package/packages/shared/src/__tests__/node-spawn.test.ts

@@ -180,6 +180,57 @@ describe("spawnNodeScript", () => {
   });
 });
 
+describe("buildNodeImportArgvParts", () => {
+  // Pure helper shared by spawnNodeScript and restart-helper.ts so the
+  // `--import` argv shape lives in exactly one place.
+  it("POSIX + jiti: entry passed RAW (jiti rejects file:// URL entries)", async () => {
+    const { buildNodeImportArgvParts } = await import("../platform/node-spawn.js");
+    const parts = buildNodeImportArgvParts({
+      loader: "/usr/lib/jiti/lib/jiti-register.mjs",
+      entry: "/srv/cli.ts",
+      args: ["start", "--port", "8000"],
+      platform: "linux",
+    });
+    expect(parts[0]).toBe("--import");
+    expect(parts[1]).toMatch(/^file:\/\//);
+    expect(parts[2]).toBe("/srv/cli.ts"); // RAW
+    expect(parts.slice(3)).toEqual(["start", "--port", "8000"]);
+  });
+
+  it("Windows + jiti: entry URL-wrapped", async () => {
+    const { buildNodeImportArgvParts } = await import("../platform/node-spawn.js");
+    const parts = buildNodeImportArgvParts({
+      loader: "B:\\Dev\\jiti\\lib\\jiti-register.mjs",
+      entry: "B:\\srv\\cli.ts",
+      args: ["start"],
+      platform: "win32",
+    });
+    expect(parts[1]).toBe("file:///B:/Dev/jiti/lib/jiti-register.mjs");
+    expect(parts[2]).toBe("file:///B:/srv/cli.ts");
+  });
+
+  it("tsx loader: entry RAW on any platform", async () => {
+    const { buildNodeImportArgvParts } = await import("../platform/node-spawn.js");
+    const parts = buildNodeImportArgvParts({
+      loader: "/x/tsx/dist/esm/index.mjs",
+      entry: "C:\\srv\\cli.ts",
+      args: [],
+      platform: "win32",
+    });
+    expect(parts[2]).toBe("C:\\srv\\cli.ts"); // RAW (tsx rejects file:// entries)
+  });
+
+  it("omits args when none supplied", async () => {
+    const { buildNodeImportArgvParts } = await import("../platform/node-spawn.js");
+    const parts = buildNodeImportArgvParts({
+      loader: "/x/jiti/lib/jiti-register.mjs",
+      entry: "/srv/cli.ts",
+      platform: "linux",
+    });
+    expect(parts).toEqual(["--import", `file://${"/x/jiti/lib/jiti-register.mjs"}`, "/srv/cli.ts"]);
+  });
+});
+
 describe("shouldUrlWrapEntry", () => {
   it("returns false for tsx loader on any platform", () => {
     const tsxLoader = "file:///home/u/node_modules/tsx/dist/esm/index.mjs";

package/packages/shared/src/__tests__/openspec-groups-types.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Type-level tests for OpenSpec change-grouping shared types.
+ *
+ * Asserts:
+ *   - `OpenSpecGroup` shape compiles.
+ *   - `OpenSpecChange.groupId?: string | null` is optional.
+ *   - `OpenSpecGroupsFile` shape compiles.
+ *   - `OPENSPEC_GROUPS_SCHEMA_VERSION` is the literal `1`.
+ *   - `BrowserOpenSpecGroupsUpdateMessage` is a member of `ServerToBrowserMessage`
+ *     (otherwise esbuild would dead-code-eliminate the consumer switch arm).
+ *   - REST request/response shapes for the five `/api/openspec/groups*` routes compile.
+ *
+ * See change: add-openspec-change-grouping (tasks 1.1–1.7).
+ */
+import { describe, it, expect } from "vitest";
+import type {
+  OpenSpecGroup,
+  OpenSpecChange,
+  OpenSpecGroupsFile,
+} from "../types.js";
+import { OPENSPEC_GROUPS_SCHEMA_VERSION } from "../types.js";
+import type {
+  ServerToBrowserMessage,
+  BrowserOpenSpecGroupsUpdateMessage,
+} from "../browser-protocol.js";
+import type {
+  GetOpenSpecGroupsResponse,
+  CreateOpenSpecGroupRequest,
+  CreateOpenSpecGroupResponse,
+  UpdateOpenSpecGroupRequest,
+  UpdateOpenSpecGroupResponse,
+  DeleteOpenSpecGroupResponse,
+  SetOpenSpecGroupAssignmentRequest,
+  SetOpenSpecGroupAssignmentResponse,
+} from "../rest-api.js";
+
+// Type-level assertion: if the type does NOT extend the union, this will fail to compile.
+type AssertExtends<T, U> = T extends U ? true : never;
+
+// 1.5 — broadcast variant lives in the union.
+type _GroupsUpdateInBrowserUnion = AssertExtends<
+  BrowserOpenSpecGroupsUpdateMessage,
+  ServerToBrowserMessage
+>;
+
+// 1.1 — group shape.
+type _GroupShape = AssertExtends<
+  { id: string; name: string; color?: string; order: number },
+  OpenSpecGroup
+>;
+
+// 1.2 — `groupId?` is optional on `OpenSpecChange`.
+type _ChangeGroupIdOptional = AssertExtends<
+  { name: string; status: "in-progress"; completedTasks: 0; totalTasks: 0; artifacts: [] },
+  OpenSpecChange
+>;
+// And it accepts a string when present.
+type _ChangeWithGroupId = AssertExtends<
+  {
+    name: string;
+    status: "in-progress";
+    completedTasks: 0;
+    totalTasks: 0;
+    artifacts: [];
+    groupId: "ui";
+  },
+  OpenSpecChange
+>;
+
+// 1.4 — file shape.
+type _FileShape = AssertExtends<
+  {
+    schemaVersion: 1;
+    groups: OpenSpecGroup[];
+    assignments: Record<string, string>;
+  },
+  OpenSpecGroupsFile
+>;
+
+// 1.6 — REST shapes (compile-time only).
+const _getResp: GetOpenSpecGroupsResponse = {
+  success: true,
+  data: { schemaVersion: 1, groups: [], assignments: {} },
+};
+const _createReq: CreateOpenSpecGroupRequest = { name: "UI", color: "#3b82f6" };
+const _createResp: CreateOpenSpecGroupResponse = {
+  success: true,
+  data: { id: "ui", name: "UI", color: "#3b82f6", order: 0 },
+};
+const _updateReq: UpdateOpenSpecGroupRequest = { name: "Frontend" };
+const _updateResp: UpdateOpenSpecGroupResponse = {
+  success: true,
+  data: { id: "ui", name: "Frontend", order: 0 },
+};
+const _deleteResp: DeleteOpenSpecGroupResponse = { success: true };
+const _putReq: SetOpenSpecGroupAssignmentRequest = { changeName: "add-foo", groupId: "ui" };
+const _putReqNull: SetOpenSpecGroupAssignmentRequest = { changeName: "add-foo", groupId: null };
+const _putResp: SetOpenSpecGroupAssignmentResponse = { success: true };
+
+// Suppress unused-locals for compile-time-only declarations.
+void _getResp;
+void _createReq;
+void _createResp;
+void _updateReq;
+void _updateResp;
+void _deleteResp;
+void _putReq;
+void _putReqNull;
+void _putResp;
+
+describe("OpenSpec change-grouping shared types", () => {
+  it("OPENSPEC_GROUPS_SCHEMA_VERSION is the literal 1", () => {
+    expect(OPENSPEC_GROUPS_SCHEMA_VERSION).toBe(1);
+  });
+
+  it("openspec_groups_update is reachable in a runtime switch over ServerToBrowserMessage", () => {
+    // Runtime check that the discriminant survives type-narrowing — mirrors
+    // the prompt-message regression guard in browser-protocol-types.test.ts.
+    const sample: ServerToBrowserMessage = {
+      type: "openspec_groups_update",
+      cwd: "/tmp/foo",
+      groups: [],
+      assignments: {},
+    };
+    let hit = false;
+    switch (sample.type) {
+      case "openspec_groups_update":
+        hit = true;
+        break;
+      default:
+        break;
+    }
+    expect(hit).toBe(true);
+  });
+});