create-ailk 0.10.0 → 0.11.1

package/templates/apps/mcp/__tests__/catalog-drift.test.ts

@@ -13,6 +13,10 @@
  *     `start_purchase` visible, so comparing a claimed server against an
  *     unclaimed catalog (or vice versa) would compare unlike surfaces and
  *     report drift that isn't there — or, worse, miss drift that is.
+ *   - …and under every licence-feature state × gate mode (#7136): 2 commerce
+ *     states × {warn, refuse} × 4 held-feature sets = 16. In refuse mode a
+ *     feature's tools are in both surfaces iff the feature is held; in warn
+ *     mode all five are in both.
  *
  * What this does NOT assert:
  *   - inputSchema equality — the server registers Zod schemas; the catalog
@@ -21,14 +25,35 @@
  */
 
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { getMcpToolCatalog } from "@working-theory/metadata";
+import {
+  getMcpToolCatalog,
+  type McpCatalogOptions,
+  type McpToolCatalogEntry,
+} from "@working-theory/metadata";
 
 import {
+  MCP_CLAIM_REFRESH_MS,
   __setMcpCommerceClaimForTest,
+  __setMcpFeatureGateForTest,
+  __setMcpHeldFeaturesForTest,
+  initMcpCommerceClaim,
   resetMcpCommerceClaim,
+  startMcpClaimRefresh,
   type McpCommerceClaim,
 } from "../src/lib/commerce-claim.js";
-import { createMcpServer } from "../src/server.js";
+import { createMcpServer, listRegisteredTools } from "../src/server.js";
+
+/** The injected licence reader — same seam `commerce-claim.test.ts` types. */
+type CheckLicenseSeam = NonNullable<
+  NonNullable<Parameters<typeof initMcpCommerceClaim>[0]>["checkLicense"]
+>;
+
+type LicenseShape = Awaited<ReturnType<CheckLicenseSeam>>;
+
+/** A licence reader that resolves to the given (partial) result. */
+function resolving(result: Partial<LicenseShape>): CheckLicenseSeam {
+  return () => Promise.resolve(result as LicenseShape);
+}
 
 interface RegisteredTool {
   description?: string;
@@ -47,29 +72,70 @@ const PAID_MODULES = "scheduling,content-write,signal-collectors";
  * @modelcontextprotocol/sdk ^1.29.0 — if the SDK renames the field, change it
  * here once rather than at each call site.
  */
-function registeredToolsOf(
-  server: McpServer,
-): Record<string, RegisteredTool> {
+function registeredToolsOf(server: McpServer): Record<string, RegisteredTool> {
   return (
     // eslint-disable-next-line no-restricted-syntax -- #506/#507: the SDK exposes no public accessor; the double assertion is confined to this one helper
-    server as unknown as { _registeredTools: Record<string, RegisteredTool> }
-  )._registeredTools;
+    (server as unknown as { _registeredTools: Record<string, RegisteredTool> })
+      ._registeredTools
+  );
 }
 
+type GateMode = NonNullable<McpCatalogOptions["featureGate"]>;
+
+type McpFeature = NonNullable<McpToolCatalogEntry["feature"]>;
+
+/** The five licence-feature tools, by the feature that entitles them. */
+const FEATURE_TOOLS: Record<McpFeature, readonly string[]> = {
+  scheduling: ["list_availability", "get_event_meta", "create_booking"],
+  "flows-deliverables": ["get_flow", "submit_flow_step"],
+};
+
+const HELD_SETS: readonly (readonly McpFeature[])[] = [
+  [],
+  ["scheduling"],
+  ["flows-deliverables"],
+  ["scheduling", "flows-deliverables"],
+];
+
+/** Every claim state: commerce × gate mode × held features (16). */
+const CLAIM_STATES = (["unclaimed", "claimed"] as const).flatMap((claim) =>
+  (["warn", "refuse"] as const).flatMap((mode) =>
+    HELD_SETS.map(
+      (held) =>
+        [claim, mode, held] as [
+          McpCommerceClaim,
+          GateMode,
+          readonly McpFeature[],
+        ],
+    ),
+  ),
+);
+
 /** The catalog options a given claim state implies — the same mapping
  * `server.ts` applies internally, so both surfaces are read like for like. */
-function catalogOptionsFor(claim: McpCommerceClaim) {
-  return { addons: { commerce: claim === "claimed" } };
+function catalogOptionsFor(
+  claim: McpCommerceClaim,
+  mode: GateMode,
+  held: readonly McpFeature[],
+): McpCatalogOptions {
+  return {
+    addons: { commerce: claim === "claimed" },
+    features: held,
+    featureGate: mode,
+  };
 }
 
-describe.each<McpCommerceClaim>(["unclaimed", "claimed"])(
-  "MCP catalog ↔ server drift — commerce claim %s",
-  (claim) => {
+describe.each(CLAIM_STATES)(
+  "MCP catalog ↔ server drift — commerce %s, mode %s, held %j",
+  (claim, mode, held) => {
     const priorEnabledModules = process.env.AILK_ENABLED_MODULES;
+    const options = catalogOptionsFor(claim, mode, held);
 
     beforeEach(() => {
       process.env.AILK_ENABLED_MODULES = PAID_MODULES;
       __setMcpCommerceClaimForTest(claim);
+      __setMcpFeatureGateForTest(mode);
+      __setMcpHeldFeaturesForTest(held);
     });
 
     afterEach(() => {
@@ -87,7 +153,7 @@ describe.each<McpCommerceClaim>(["unclaimed", "claimed"])(
     it("registered tool names equal catalog tool names", () => {
       const registered = registeredToolsOf(createMcpServer());
       const registeredNames = Object.keys(registered).sort();
-      const catalogNames = getMcpToolCatalog(catalogOptionsFor(claim))
+      const catalogNames = getMcpToolCatalog(options)
         .map((t) => t.name)
         .sort();
       expect(registeredNames).toEqual(catalogNames);
@@ -95,7 +161,7 @@ describe.each<McpCommerceClaim>(["unclaimed", "claimed"])(
 
     it("registered tool descriptions equal catalog descriptions", () => {
       const registered = registeredToolsOf(createMcpServer());
-      for (const entry of getMcpToolCatalog(catalogOptionsFor(claim))) {
+      for (const entry of getMcpToolCatalog(options)) {
         expect(registered[entry.name]).toBeDefined();
         expect(registered[entry.name]!.description).toBe(entry.description);
       }
@@ -107,10 +173,87 @@ describe.each<McpCommerceClaim>(["unclaimed", "claimed"])(
 
       expect("start_purchase" in registered).toBe(expected);
       expect(
-        getMcpToolCatalog(catalogOptionsFor(claim)).some(
-          (t) => t.name === "start_purchase",
-        ),
+        getMcpToolCatalog(options).some((t) => t.name === "start_purchase"),
       ).toBe(expected);
     });
+
+    it("each feature's tools appear in both surfaces exactly when the gate lets them", () => {
+      const registered = registeredToolsOf(createMcpServer());
+      const catalogNames = getMcpToolCatalog(options).map((t) => t.name);
+
+      for (const [feature, tools] of Object.entries(FEATURE_TOOLS)) {
+        const expected =
+          mode === "warn" || held.includes(feature as McpFeature);
+        for (const name of tools) {
+          expect(name in registered).toBe(expected);
+          expect(catalogNames.includes(name)).toBe(expected);
+        }
+      }
+    });
   },
 );
+
+describe("MCP catalog ↔ server agreement after a bounded re-read (#7156 AC-1)", () => {
+  const priorEnabledModules = process.env.AILK_ENABLED_MODULES;
+
+  beforeEach(() => {
+    process.env.AILK_ENABLED_MODULES = PAID_MODULES;
+    jest.useFakeTimers();
+  });
+
+  afterEach(() => {
+    resetMcpCommerceClaim();
+    jest.useRealTimers();
+    if (priorEnabledModules === undefined) {
+      delete process.env.AILK_ENABLED_MODULES;
+    } else {
+      process.env.AILK_ENABLED_MODULES = priorEnabledModules;
+    }
+  });
+
+  it("a new server and listRegisteredTools() match the catalog once the re-read resolves", async () => {
+    __setMcpFeatureGateForTest("refuse");
+    await initMcpCommerceClaim({
+      checkLicense: resolving({
+        tier: "pro",
+        features: ["scheduling", "flows-deliverables", "commerce"],
+      }),
+    });
+
+    const bootOptions: McpCatalogOptions = {
+      addons: { commerce: true },
+      features: ["scheduling", "flows-deliverables"],
+      featureGate: "refuse",
+    };
+    const bootNames = Object.keys(registeredToolsOf(createMcpServer())).sort();
+    expect(bootNames).toEqual(
+      getMcpToolCatalog(bootOptions)
+        .map((t) => t.name)
+        .sort(),
+    );
+    expect(bootNames).toHaveLength(20);
+
+    startMcpClaimRefresh({ checkLicense: resolving({ features: [] }) });
+    await jest.advanceTimersByTimeAsync(MCP_CLAIM_REFRESH_MS);
+
+    const refreshedOptions: McpCatalogOptions = {
+      addons: { commerce: false },
+      features: [],
+      featureGate: "refuse",
+    };
+    const catalogNames = getMcpToolCatalog(refreshedOptions)
+      .map((t) => t.name)
+      .sort();
+    expect(catalogNames).toHaveLength(14);
+
+    const serverNames = Object.keys(
+      registeredToolsOf(createMcpServer()),
+    ).sort();
+    expect(serverNames).toEqual(catalogNames);
+
+    const listedNames = listRegisteredTools()
+      .map((t) => t.name)
+      .sort();
+    expect(listedNames).toEqual(catalogNames);
+  });
+});

package/templates/apps/mcp/__tests__/index.test.ts

@@ -1,5 +1,6 @@
 /**
- * Structural ordering guard for apps/mcp's bootstrap (#5876 spec D4, AC-3).
+ * Structural ordering guard for apps/mcp's bootstrap (#5876 spec D4, AC-3;
+ * #7156 AC-1, AC-2).
  *
  * `apps/mcp/src/index.ts` has real side effects at import time (starts a
  * transport, opens a stdio/HTTP listener) — it cannot safely be imported by
@@ -8,6 +9,9 @@
  */
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
+import vm from "node:vm";
+
+import * as ts from "typescript";
 
 describe("apps/mcp/src/index.ts — bootstrap ordering", () => {
   const src = readFileSync(resolve(__dirname, "../src/index.ts"), "utf-8");
@@ -37,3 +41,116 @@ describe("apps/mcp/src/index.ts — bootstrap ordering", () => {
     expect(initIdx).toBeLessThan(catchIdx);
   });
 });
+
+describe("apps/mcp/src/index.ts — the claim refresh loop starts in production (#7156 AC-1)", () => {
+  const src = readFileSync(resolve(__dirname, "../src/index.ts"), "utf-8");
+
+  it("starts after the boot read and before the transport branch", () => {
+    const initIdx = src.indexOf("await initMcpCommerceClaim()");
+    const callMatches = [...src.matchAll(/^startMcpClaimRefresh\(\);$/gm)];
+    const transportBranchIdx = src.indexOf('if (transport === "http")');
+
+    expect(initIdx).toBeGreaterThan(-1);
+    expect(callMatches).toHaveLength(1);
+    expect(transportBranchIdx).toBeGreaterThan(-1);
+
+    const callIdx = callMatches[0]!.index!;
+    expect(initIdx).toBeLessThan(callIdx);
+    expect(callIdx).toBeLessThan(transportBranchIdx);
+  });
+});
+
+describe("apps/mcp/src/index.ts — the boot warning cannot stop the server (#7156 AC-2, D2)", () => {
+  const src = readFileSync(resolve(__dirname, "../src/index.ts"), "utf-8");
+
+  /**
+   * The exact behavioural slice AC-2 specifies: from the last `try {` before
+   * the `reportUnlicensedProTools();` call statement, up to `const transport
+   * =`. Transpiled and run in a fresh vm context so a real throw from the
+   * stubbed function proves the guard, not a mock of the guard itself.
+   */
+  function guardedSlice(): string {
+    const callMatches = [
+      ...src.matchAll(/^\s*reportUnlicensedProTools\(\);$/gm),
+    ];
+    expect(callMatches).toHaveLength(1);
+    const callIdx = callMatches[0]!.index!;
+    const tryIdx = src.lastIndexOf("try {", callIdx);
+    const transportIdx = src.indexOf("const transport =");
+
+    expect(tryIdx).toBeGreaterThan(-1);
+    expect(transportIdx).toBeGreaterThan(callIdx);
+
+    const slice = src.slice(tryIdx, transportIdx);
+    // The extracted try block must be the one that immediately wraps the
+    // call, not an earlier try{}/await pair (code review, #7156): the two
+    // other try blocks in this file each await a boot call, so a regressed
+    // boundary would carry "await" into the slice. Asserting that here
+    // turns a boundary regression into a clear failure instead of an opaque
+    // vm ReferenceError from the un-injected awaited function.
+    expect(slice).not.toContain("await");
+
+    return slice;
+  }
+
+  function runGuardedSlice(
+    reportUnlicensedProTools: () => unknown,
+    errorSpy: jest.Mock,
+  ): void {
+    const slice = guardedSlice();
+    const { outputText } = ts.transpileModule(slice, {
+      compilerOptions: {
+        module: ts.ModuleKind.CommonJS,
+        target: ts.ScriptTarget.ES2020,
+      },
+    });
+    vm.runInNewContext(outputText, {
+      reportUnlicensedProTools,
+      console: { error: errorSpy },
+    });
+  }
+
+  it("a throw is logged to stderr and does not escape", () => {
+    const errorSpy = jest.fn();
+
+    expect(() =>
+      runGuardedSlice(() => {
+        throw new Error("boom");
+      }, errorSpy),
+    ).not.toThrow();
+
+    expect(errorSpy).toHaveBeenCalledTimes(1);
+    const call = errorSpy.mock.calls[0]!;
+    expect(String(call[0])).toContain("reportUnlicensedProTools");
+    const lastArg = call[call.length - 1];
+    expect(lastArg).toBeInstanceOf(Error);
+    expect((lastArg as Error).message).toBe("boom");
+  });
+
+  it("a successful call is not logged", () => {
+    const errorSpy = jest.fn();
+    const report = jest.fn(() => []);
+
+    runGuardedSlice(report, errorSpy);
+
+    expect(report).toHaveBeenCalledTimes(1);
+    expect(errorSpy).not.toHaveBeenCalled();
+  });
+
+  it("the call statement occurs exactly once, before the transport branch", () => {
+    const callMatches = [
+      ...src.matchAll(/^\s*reportUnlicensedProTools\(\);$/gm),
+    ];
+    const transportBranchIdx = src.indexOf('if (transport === "http")');
+
+    expect(callMatches).toHaveLength(1);
+    expect(callMatches[0]!.index!).toBeLessThan(transportBranchIdx);
+  });
+
+  it("logs to stderr only — the guarded slice never writes stdout", () => {
+    const slice = guardedSlice();
+
+    expect(slice).toContain("console.error");
+    expect(slice).not.toContain("console.log");
+  });
+});