create-ailk 0.10.0 → 0.11.0

package/templates/apps/mcp/__tests__/lib/commerce-claim.test.ts

@@ -1,17 +1,25 @@
 /**
- * Tests for the boot-memoised commerce claim (#5971 spec D2).
+ * Tests for the boot-memoised commerce claim (#5971 spec D2) and the held
+ * licence-feature set resolved from the same read (#7136 spec D3).
  *
- * Idiom: `__tests__/lib/require-paid-tier.test.ts` — `checkLicense()` is
- * injected, never called for real, so no suite reaches a licence server
- * (NFR-6). Every arm that cannot POSITIVELY establish the claim must resolve
- * to `"unclaimed"` (NFR-3, fail closed).
+ * Idiom: the `checkLicense` option — `checkLicense()` is injected, never
+ * called for real, so no suite reaches a licence server (NFR-6). Every arm
+ * that cannot POSITIVELY establish the claim must resolve to `"unclaimed"`
+ * and an empty feature set (NFR-3, fail closed).
  */
 
 import {
+  MCP_CLAIM_MAX_MISSED_REREADS,
+  MCP_CLAIM_REFRESH_MS,
   initMcpCommerceClaim,
   mcpCommerceClaim,
+  mcpFeatureGateOverride,
+  mcpHeldFeatures,
   resetMcpCommerceClaim,
+  startMcpClaimRefresh,
   __setMcpCommerceClaimForTest,
+  __setMcpFeatureGateForTest,
+  __setMcpHeldFeaturesForTest,
 } from "../../src/lib/commerce-claim.js";
 
 /**
@@ -109,3 +117,415 @@ describe("mcpCommerceClaim — fail-closed initial state", () => {
     expect(mcpCommerceClaim()).toBe("claimed");
   });
 });
+
+describe("mcpHeldFeatures — the deployment's feature set, from the same read (#7136)", () => {
+  const FEATURES = ["scheduling", "flows-deliverables", "commerce"] as const;
+
+  it("one checkLicense() call resolves both the commerce claim and the features", async () => {
+    const fake = jest.fn(resolving({ tier: "pro", features: [...FEATURES] }));
+
+    await initMcpCommerceClaim({ checkLicense: fake });
+
+    expect(fake).toHaveBeenCalledTimes(1);
+    expect([...mcpHeldFeatures()].sort()).toEqual([...FEATURES].sort());
+    expect(mcpCommerceClaim()).toBe("claimed");
+  });
+
+  it("is empty before any init", () => {
+    expect(mcpHeldFeatures().size).toBe(0);
+  });
+
+  it("is empty when the licence is revoked, even carrying the features", async () => {
+    await initMcpCommerceClaim({
+      checkLicense: resolving({
+        tier: "pro",
+        features: [...FEATURES],
+        revoked: true,
+      }),
+    });
+
+    expect(mcpHeldFeatures().size).toBe(0);
+  });
+
+  it("is empty — never throws — when checkLicense() rejects", async () => {
+    await initMcpCommerceClaim({
+      checkLicense: resolving({ tier: "pro", features: [...FEATURES] }),
+    });
+    await initMcpCommerceClaim({ checkLicense: rejecting() });
+
+    expect(mcpHeldFeatures().size).toBe(0);
+  });
+
+  it("reset empties a populated set and clears the mode override", async () => {
+    await initMcpCommerceClaim({
+      checkLicense: resolving({ tier: "pro", features: [...FEATURES] }),
+    });
+    __setMcpFeatureGateForTest("refuse");
+    expect(mcpFeatureGateOverride()).toBe("refuse");
+
+    resetMcpCommerceClaim();
+
+    expect(mcpHeldFeatures().size).toBe(0);
+    expect(mcpFeatureGateOverride()).toBeUndefined();
+  });
+});
+
+/** A licence reader whose promise never settles — the "one read in flight"
+ * probe (#7156 AC-1). */
+function neverResolving(): CheckLicenseSeam {
+  return () => new Promise<LicenseShape>(() => {});
+}
+
+/** A licence reader the test resolves on its own schedule — the "a stale
+ * read is discarded" probe (#7156 AC-1). */
+function deferred(): {
+  reader: CheckLicenseSeam;
+  resolve: (result: Partial<LicenseShape>) => void;
+} {
+  let resolveFn!: (value: LicenseShape) => void;
+  const promise = new Promise<LicenseShape>((resolve) => {
+    resolveFn = resolve;
+  });
+  return {
+    reader: () => promise,
+    resolve: (result) => resolveFn(result as LicenseShape),
+  };
+}
+
+describe("startMcpClaimRefresh — bounded re-read (#7156 AC-1)", () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+  });
+
+  afterEach(() => {
+    resetMcpCommerceClaim();
+    jest.useRealTimers();
+  });
+
+  it("the bound is a 5-minute constant", () => {
+    expect(MCP_CLAIM_REFRESH_MS).toBe(300_000);
+  });
+
+  it("re-reads in both directions once the bound elapses", async () => {
+    await initMcpCommerceClaim({
+      checkLicense: resolving({
+        tier: "pro",
+        features: ["scheduling", "commerce"],
+      }),
+    });
+
+    let current: Partial<LicenseShape> = {
+      tier: "pro",
+      features: ["scheduling", "commerce"],
+    };
+    const fake = jest.fn<CheckLicenseSeam>(() =>
+      Promise.resolve(current as LicenseShape),
+    );
+    startMcpClaimRefresh({ checkLicense: fake });
+
+    current = { tier: "free", features: [] };
+
+    await jest.advanceTimersByTimeAsync(MCP_CLAIM_REFRESH_MS - 1);
+    expect(fake).not.toHaveBeenCalled();
+    expect([...mcpHeldFeatures()].sort()).toEqual(
+      ["commerce", "scheduling"].sort(),
+    );
+
+    await jest.advanceTimersByTimeAsync(1);
+    expect(fake).toHaveBeenCalledTimes(1);
+    expect(mcpHeldFeatures().size).toBe(0);
+    expect(mcpCommerceClaim()).toBe("unclaimed");
+
+    current = { tier: "pro", features: ["scheduling", "commerce"] };
+    await jest.advanceTimersByTimeAsync(MCP_CLAIM_REFRESH_MS);
+    expect([...mcpHeldFeatures()].sort()).toEqual(
+      ["commerce", "scheduling"].sort(),
+    );
+    expect(mcpCommerceClaim()).toBe("claimed");
+  });
+
+  it("fails closed on a re-read that reports revoked", async () => {
+    await initMcpCommerceClaim({
+      checkLicense: resolving({ tier: "pro", features: ["commerce"] }),
+    });
+    startMcpClaimRefresh({
+      checkLicense: resolving({
+        tier: "pro",
+        features: ["commerce"],
+        revoked: true,
+      }),
+    });
+
+    await jest.advanceTimersByTimeAsync(MCP_CLAIM_REFRESH_MS);
+
+    expect(mcpHeldFeatures().size).toBe(0);
+    expect(mcpCommerceClaim()).toBe("unclaimed");
+  });
+
+  it("fails closed on a re-read that rejects, without throwing", async () => {
+    await initMcpCommerceClaim({
+      checkLicense: resolving({ tier: "pro", features: ["commerce"] }),
+    });
+    startMcpClaimRefresh({ checkLicense: rejecting() });
+
+    await jest.advanceTimersByTimeAsync(MCP_CLAIM_REFRESH_MS);
+
+    expect(mcpHeldFeatures().size).toBe(0);
+    expect(mcpCommerceClaim()).toBe("unclaimed");
+  });
+
+  it("is single-flight — a read that never settles is called once across multiple intervals", async () => {
+    const fake = jest.fn(neverResolving());
+    startMcpClaimRefresh({ checkLicense: fake });
+
+    await jest.advanceTimersByTimeAsync(MCP_CLAIM_REFRESH_MS * 3);
+
+    expect(fake).toHaveBeenCalledTimes(1);
+  });
+
+  it("starting the loop twice replaces the first — only one loop runs", async () => {
+    const fake = jest.fn(resolving({ tier: "free", features: [] }));
+    startMcpClaimRefresh({ checkLicense: fake });
+    startMcpClaimRefresh({ checkLicense: fake });
+
+    await jest.advanceTimersByTimeAsync(MCP_CLAIM_REFRESH_MS);
+
+    expect(fake).toHaveBeenCalledTimes(1);
+  });
+
+  it("resetMcpCommerceClaim() stops the loop", async () => {
+    const fake = jest.fn(resolving({ tier: "free", features: [] }));
+    startMcpClaimRefresh({ checkLicense: fake });
+
+    resetMcpCommerceClaim();
+
+    await jest.advanceTimersByTimeAsync(MCP_CLAIM_REFRESH_MS * 2);
+
+    expect(fake).not.toHaveBeenCalled();
+  });
+
+  it("a stale read is discarded after a reset and a fresh boot", async () => {
+    const held = deferred();
+    startMcpClaimRefresh({ checkLicense: held.reader });
+
+    await jest.advanceTimersByTimeAsync(MCP_CLAIM_REFRESH_MS);
+
+    resetMcpCommerceClaim();
+    await initMcpCommerceClaim({
+      checkLicense: resolving({ tier: "pro", features: ["scheduling"] }),
+    });
+
+    held.resolve({ tier: "pro", features: ["scheduling", "commerce"] });
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect([...mcpHeldFeatures()]).toEqual(["scheduling"]);
+    expect(mcpCommerceClaim()).toBe("unclaimed");
+  });
+
+  it("no stuck in-flight flag survives a reset — a fresh loop re-reads on its first interval", async () => {
+    const never = jest.fn(neverResolving());
+    startMcpClaimRefresh({ checkLicense: never });
+    await jest.advanceTimersByTimeAsync(MCP_CLAIM_REFRESH_MS);
+    resetMcpCommerceClaim();
+
+    const fake = jest.fn(resolving({ tier: "pro", features: ["commerce"] }));
+    startMcpClaimRefresh({ checkLicense: fake });
+    await jest.advanceTimersByTimeAsync(MCP_CLAIM_REFRESH_MS);
+
+    expect(fake).toHaveBeenCalledTimes(1);
+    expect(mcpCommerceClaim()).toBe("claimed");
+  });
+
+  it("never holds a process open — the timer is unref'd", () => {
+    const setIntervalSpy = jest.spyOn(global, "setInterval");
+    startMcpClaimRefresh({
+      checkLicense: resolving({ tier: "free", features: [] }),
+    });
+
+    const timer = setIntervalSpy.mock.results[0]?.value as {
+      hasRef(): boolean;
+    };
+    expect(timer.hasRef()).toBe(false);
+
+    setIntervalSpy.mockRestore();
+  });
+});
+
+describe("startMcpClaimRefresh — staleness ceiling (#7315 AC-3, L1)", () => {
+  const BOTH_PLUS_COMMERCE = [
+    "scheduling",
+    "flows-deliverables",
+    "commerce",
+  ] as const;
+
+  beforeEach(() => {
+    jest.useFakeTimers();
+  });
+
+  afterEach(() => {
+    resetMcpCommerceClaim();
+    jest.useRealTimers();
+  });
+
+  it("is a 3-interval constant", () => {
+    expect(MCP_CLAIM_MAX_MISSED_REREADS).toBe(3);
+  });
+
+  it("fires at the fourth interval — falls back to no claim, starts a fresh read, and an abandoned read cannot write once recovery has happened", async () => {
+    await initMcpCommerceClaim({
+      checkLicense: resolving({
+        tier: "pro",
+        features: [...BOTH_PLUS_COMMERCE],
+      }),
+    });
+
+    let resolveFirst!: (value: LicenseShape) => void;
+    let resolveSecond!: (value: LicenseShape) => void;
+    const first = new Promise<LicenseShape>((resolve) => {
+      resolveFirst = resolve;
+    });
+    const second = new Promise<LicenseShape>((resolve) => {
+      resolveSecond = resolve;
+    });
+    const fake = jest
+      .fn<CheckLicenseSeam>()
+      .mockReturnValueOnce(first)
+      .mockReturnValueOnce(second);
+    startMcpClaimRefresh({ checkLicense: fake });
+
+    // Interval 1 starts the (never-settling, for now) read; intervals 2 and
+    // 3 are misses 1 and 2 — the ceiling has not fired yet.
+    await jest.advanceTimersByTimeAsync(3 * MCP_CLAIM_REFRESH_MS);
+    expect(fake).toHaveBeenCalledTimes(1);
+    expect([...mcpHeldFeatures()].sort()).toEqual(
+      [...BOTH_PLUS_COMMERCE].sort(),
+    );
+    expect(mcpCommerceClaim()).toBe("claimed");
+
+    // Interval 4 — the third miss reaches the ceiling: fall back to no
+    // claim and start a fresh (second) read on the same tick.
+    await jest.advanceTimersByTimeAsync(MCP_CLAIM_REFRESH_MS);
+    expect(mcpHeldFeatures().size).toBe(0);
+    expect(mcpCommerceClaim()).toBe("unclaimed");
+    expect(fake).toHaveBeenCalledTimes(2);
+
+    // Recovery — the fresh read finishing restores the claim.
+    resolveSecond({
+      tier: "pro",
+      features: [...BOTH_PLUS_COMMERCE],
+    } as LicenseShape);
+    await Promise.resolve();
+    await Promise.resolve();
+    expect([...mcpHeldFeatures()].sort()).toEqual(
+      [...BOTH_PLUS_COMMERCE].sort(),
+    );
+    expect(mcpCommerceClaim()).toBe("claimed");
+
+    // The read the ceiling abandoned resolving afterwards must not write —
+    // it is no longer the most recently started read.
+    resolveFirst({ tier: "pro", features: [] } as LicenseShape);
+    await Promise.resolve();
+    await Promise.resolve();
+    expect([...mcpHeldFeatures()].sort()).toEqual(
+      [...BOTH_PLUS_COMMERCE].sort(),
+    );
+    expect(mcpCommerceClaim()).toBe("claimed");
+  });
+
+  it("resets the missed count when a read finishes, so a merely slow store never reaches the ceiling", async () => {
+    await initMcpCommerceClaim({
+      checkLicense: resolving({
+        tier: "pro",
+        features: [...BOTH_PLUS_COMMERCE],
+      }),
+    });
+
+    const fake = jest.fn<CheckLicenseSeam>(
+      () =>
+        new Promise<LicenseShape>((resolve) => {
+          setTimeout(
+            () =>
+              resolve({
+                tier: "pro",
+                features: [...BOTH_PLUS_COMMERCE],
+              } as LicenseShape),
+            1.5 * MCP_CLAIM_REFRESH_MS,
+          );
+        }),
+    );
+    startMcpClaimRefresh({ checkLicense: fake });
+
+    for (let i = 0; i < 8; i++) {
+      await jest.advanceTimersByTimeAsync(MCP_CLAIM_REFRESH_MS);
+      expect([...mcpHeldFeatures()].sort()).toEqual(
+        [...BOTH_PLUS_COMMERCE].sort(),
+      );
+      expect(mcpCommerceClaim()).toBe("claimed");
+    }
+  });
+
+  it("the existing single-flight probe stays true at N = 3 (#7156)", async () => {
+    const fake = jest.fn(neverResolving());
+    startMcpClaimRefresh({ checkLicense: fake });
+
+    await jest.advanceTimersByTimeAsync(MCP_CLAIM_REFRESH_MS * 3);
+
+    expect(fake).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("test-only writers throw outside a test run (#7156 AC-3, L2)", () => {
+  const ORIGINAL_NODE_ENV = process.env["NODE_ENV"];
+
+  afterEach(() => {
+    process.env["NODE_ENV"] = "test";
+    resetMcpCommerceClaim();
+    if (ORIGINAL_NODE_ENV === undefined) {
+      delete process.env["NODE_ENV"];
+    } else {
+      process.env["NODE_ENV"] = ORIGINAL_NODE_ENV;
+    }
+  });
+
+  async function establishNonInitialState(): Promise<void> {
+    await initMcpCommerceClaim({
+      checkLicense: resolving({
+        tier: "pro",
+        features: ["scheduling", "commerce"],
+      }),
+    });
+    __setMcpFeatureGateForTest("refuse");
+  }
+
+  it.each(["production", undefined] as const)(
+    "throws without changing state when NODE_ENV is %p",
+    async (nodeEnv) => {
+      await establishNonInitialState();
+      const preClaim = mcpCommerceClaim();
+      const preFeatures = new Set(mcpHeldFeatures());
+      const preGate = mcpFeatureGateOverride();
+
+      if (nodeEnv === undefined) {
+        delete process.env["NODE_ENV"];
+      } else {
+        process.env["NODE_ENV"] = nodeEnv;
+      }
+
+      expect(() => __setMcpCommerceClaimForTest("unclaimed")).toThrow(
+        /__setMcpCommerceClaimForTest/,
+      );
+      expect(() => __setMcpHeldFeaturesForTest([])).toThrow(
+        /__setMcpHeldFeaturesForTest/,
+      );
+      expect(() => __setMcpFeatureGateForTest("warn")).toThrow(
+        /__setMcpFeatureGateForTest/,
+      );
+      expect(() => resetMcpCommerceClaim()).toThrow(/resetMcpCommerceClaim/);
+
+      expect(mcpCommerceClaim()).toBe(preClaim);
+      expect(mcpHeldFeatures()).toEqual(preFeatures);
+      expect(mcpFeatureGateOverride()).toBe(preGate);
+    },
+  );
+});

package/templates/apps/mcp/__tests__/module-exclusion.test.ts

@@ -12,10 +12,21 @@
  * Reverting the `shouldRegister` module filter in `../src/server.ts` (while
  * leaving the `OSS_DISABLED_TOOLS` check alone) makes this test fail RED —
  * see #5088 S1 verification notes.
+ *
+ * #7136: the module filter stays independent of the licence-feature gate —
+ * the matrix below also runs in refuse mode with every feature held. The
+ * catalog enumerations pin `featureGate: "warn"`, so they list every
+ * module-tagged tool whichever way `MCP_FEATURE_GATE_MODE` is set and can
+ * never iterate nothing.
  */
 
 import { getMcpToolRegistrations } from "@working-theory/metadata";
 
+import {
+  __setMcpFeatureGateForTest,
+  __setMcpHeldFeaturesForTest,
+  resetMcpCommerceClaim,
+} from "../src/lib/commerce-claim.js";
 import { createMcpServer, listRegisteredTools } from "../src/server.js";
 
 // `content-write` left this list in #5853: its three tools (create_page /
@@ -26,6 +37,11 @@ import { createMcpServer, listRegisteredTools } from "../src/server.js";
 // (D8), which this MCP-side matrix has never covered.
 const PAID_MODULES = ["scheduling", "signal-collectors"] as const;
 
+/** Every module-tagged tool in the catalog, whatever the gate mode. */
+function catalogRegistrations() {
+  return getMcpToolRegistrations({ featureGate: "warn" });
+}
+
 function withEnabledModules<T>(enabled: string, fn: () => T): T {
   const prior = process.env.AILK_ENABLED_MODULES;
   process.env.AILK_ENABLED_MODULES = enabled;
@@ -50,10 +66,11 @@ describe("MCP tool registration — module exclusion (S1, #5088)", () => {
     // the catalog without a matching entry here would silently go
     // unverified.
     const taggedModules = new Set(
-      getMcpToolRegistrations()
+      catalogRegistrations()
         .map((reg) => reg.module)
         .filter((m): m is string => Boolean(m)),
     );
+    expect(taggedModules.size).toBeGreaterThan(0);
     for (const m of taggedModules) {
       expect(PAID_MODULES).toContain(m);
     }
@@ -65,7 +82,7 @@ describe("MCP tool registration — module exclusion (S1, #5088)", () => {
       const enabledModules = PAID_MODULES.filter((m) => m !== excluded).join(
         ",",
       );
-      const excludedToolNames = getMcpToolRegistrations()
+      const excludedToolNames = catalogRegistrations()
         .filter((reg) => reg.module === excluded)
         .map((reg) => reg.name);
       // Sanity check the fixture: every module this test parametrizes over
@@ -101,11 +118,58 @@ describe("MCP tool registration — module exclusion (S1, #5088)", () => {
         listRegisteredTools().map((t) => t.name),
       ),
     );
-    const taggedNames = getMcpToolRegistrations()
+    const taggedNames = catalogRegistrations()
       .filter((reg) => reg.module)
       .map((reg) => reg.name);
+    expect(taggedNames.length).toBeGreaterThan(0);
     for (const name of taggedNames) {
       expect(registeredNames).toContain(name);
     }
   });
 });
+
+describe("module exclusion is independent of the licence-feature gate (#7136)", () => {
+  beforeEach(() => {
+    __setMcpFeatureGateForTest("refuse");
+    __setMcpHeldFeaturesForTest(["scheduling", "flows-deliverables"]);
+  });
+
+  afterEach(() => {
+    resetMcpCommerceClaim();
+    delete process.env.AILK_ENABLED_MODULES;
+  });
+
+  it.each(PAID_MODULES)(
+    "refuse mode, every feature held: excluding '%s' still registers none of its tools",
+    (excluded) => {
+      const enabledModules = PAID_MODULES.filter((m) => m !== excluded).join(
+        ",",
+      );
+      const excludedToolNames = catalogRegistrations()
+        .filter((reg) => reg.module === excluded)
+        .map((reg) => reg.name);
+      expect(excludedToolNames.length).toBeGreaterThan(0);
+
+      const registeredNames = withEnabledModules(enabledModules, () =>
+        listRegisteredTools().map((t) => t.name),
+      );
+      for (const name of excludedToolNames) {
+        expect(registeredNames).not.toContain(name);
+      }
+    },
+  );
+
+  it("refuse mode, every feature held, both modules enabled: all five register", () => {
+    const featureTools = catalogRegistrations()
+      .filter((reg) => reg.feature)
+      .map((reg) => reg.name);
+    expect(featureTools).toHaveLength(5);
+
+    const registeredNames = withEnabledModules(PAID_MODULES.join(","), () =>
+      listRegisteredTools().map((t) => t.name),
+    );
+    for (const name of featureTools) {
+      expect(registeredNames).toContain(name);
+    }
+  });
+});