@tdk-landscape/tdk-cli-core 1.3.45 → 1.3.48

package/cli/src/generator/__tests__/extension-fetch.test.ts

@@ -0,0 +1,220 @@
+// Covers the exact three scenarios demonstrated manually on the real CLI:
+//   1. no TDK_LICENSE_KEY set          -> free tier, zero network calls
+//   2. TDK_LICENSE_KEY set but invalid -> "no premium resources unlocked", free tier
+//   3. TDK_LICENSE_KEY set and valid   -> premium files applied over the stubs
+//
+// Only the network boundary (fetch) is mocked - tar extraction, the file
+// overlay, and the on-disk cache all run for real against temp directories,
+// so this exercises the same code path `tdk project` actually runs.
+
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, utimesSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+let projectRoot: string;
+let destDir: string;
+let fakeHome: string;
+let fixtureTarball: Buffer;
+
+function buildFixtureTarball(): Buffer {
+  const src = mkdtempSync(join(tmpdir(), "tdk-premium-fixture-"));
+  mkdirSync(join(src, "typescript"), { recursive: true });
+  writeFileSync(
+    join(src, "typescript", "playwright_config.star"),
+    "# REAL premium playwright config\ndef generate_playwright_config(): pass\n"
+  );
+  writeFileSync(join(src, "c4_diagram.star"), "# REAL premium c4 diagram generator\n");
+
+  // Match exactly how the real premium.tar.gz is built (tar -C dir .), so
+  // entries get a "./" prefix - extractTarball's --strip-components=1
+  // expects that dummy leading component, not a real directory name.
+  const tarPath = join(src, "..", "premium-fixture.tar.gz");
+  execFileSync("tar", ["-czf", tarPath, "-C", src, "."]);
+  const buf = readFileSync(tarPath);
+  rmSync(src, { recursive: true, force: true });
+  rmSync(tarPath, { force: true });
+  return buf;
+}
+
+beforeEach(() => {
+  projectRoot = mkdtempSync(join(tmpdir(), "tdk-project-"));
+  destDir = mkdtempSync(join(tmpdir(), "tdk-dest-"));
+  fakeHome = mkdtempSync(join(tmpdir(), "tdk-home-"));
+
+  // Seed destDir with the free-tier stub, same as vendorTdkExtension does
+  // before ever calling applyPremiumOverlay - so we can assert it gets
+  // overwritten only when a premium fetch actually succeeds.
+  mkdirSync(join(destDir, "engine/topologies/tilt/generators/typescript"), { recursive: true });
+  writeFileSync(
+    join(destDir, "engine/topologies/tilt/generators/typescript/playwright_config.star"),
+    "# unlicensed stub\n"
+  );
+
+  process.env.HOME = fakeHome;
+  delete process.env.TDK_LICENSE_KEY;
+  delete process.env.TDK_PREMIUM_ENDPOINT;
+  vi.restoreAllMocks();
+});
+
+afterEach(() => {
+  rmSync(projectRoot, { recursive: true, force: true });
+  rmSync(destDir, { recursive: true, force: true });
+  rmSync(fakeHome, { recursive: true, force: true });
+  vi.unstubAllGlobals();
+});
+
+describe("applyPremiumOverlay", () => {
+  it("scenario 1: no license key -> returns false, never calls fetch", async () => {
+    const fetchSpy = vi.fn();
+    vi.stubGlobal("fetch", fetchSpy);
+
+    const { applyPremiumOverlay } = await import("../extension-fetch.js");
+    const applied = await applyPremiumOverlay(projectRoot, destDir);
+
+    expect(applied).toBe(false);
+    expect(fetchSpy).not.toHaveBeenCalled();
+    // Stub must be left untouched - zero side effects for free users.
+    expect(
+      readFileSync(
+        join(destDir, "engine/topologies/tilt/generators/typescript/playwright_config.star"),
+        "utf-8"
+      )
+    ).toBe("# unlicensed stub\n");
+  });
+
+  it("scenario 2: invalid/ungranted key -> tries every known resource, then falls back to free tier", async () => {
+    process.env.TDK_LICENSE_KEY = "tdk-fa411b"; // the mistyped key from the real session
+
+    const fetchSpy = vi.fn().mockResolvedValue(new Response("key does not grant resource", { status: 403 }));
+    vi.stubGlobal("fetch", fetchSpy);
+
+    const { applyPremiumOverlay } = await import("../extension-fetch.js");
+    const applied = await applyPremiumOverlay(projectRoot, destDir);
+
+    expect(applied).toBe(false);
+    // Every known resource name gets a shot before giving up.
+    expect(fetchSpy).toHaveBeenCalledTimes(6);
+    for (const call of fetchSpy.mock.calls) {
+      const url = call[0] as string;
+      expect(url).toContain("key=tdk-fa411b");
+    }
+    expect(
+      readFileSync(
+        join(destDir, "engine/topologies/tilt/generators/typescript/playwright_config.star"),
+        "utf-8"
+      )
+    ).toBe("# unlicensed stub\n");
+  });
+
+  it("scenario 3: valid key granting the first resource -> real files overlay the stubs", async () => {
+    process.env.TDK_LICENSE_KEY = "tdk-fa411a"; // the real key from the session, grants playwright
+    fixtureTarball ??= buildFixtureTarball();
+
+    const fetchSpy = vi.fn().mockImplementation((url: string) => {
+      if (url.includes("resource=playwright")) {
+        return Promise.resolve(new Response(new Uint8Array(fixtureTarball), { status: 200 }));
+      }
+      return Promise.resolve(new Response("not granted", { status: 403 }));
+    });
+    vi.stubGlobal("fetch", fetchSpy);
+
+    const { applyPremiumOverlay } = await import("../extension-fetch.js");
+    const applied = await applyPremiumOverlay(projectRoot, destDir);
+
+    expect(applied).toBe(true);
+    // Stops at the first granted resource - doesn't keep trying c4-diagram/logging.
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+
+    const playwrightOut = readFileSync(
+      join(destDir, "engine/topologies/tilt/generators/typescript/playwright_config.star"),
+      "utf-8"
+    );
+    expect(playwrightOut).toContain("REAL premium playwright config");
+    expect(playwrightOut).not.toContain("unlicensed stub");
+
+    const c4Out = readFileSync(join(destDir, "engine/topologies/tilt/generators/c4_diagram.star"), "utf-8");
+    expect(c4Out).toContain("REAL premium c4 diagram generator");
+  });
+
+  it("sends the per-project id and reuses it across calls instead of generating a new one each time", async () => {
+    process.env.TDK_LICENSE_KEY = "tdk-fa411b";
+    const seenProjectIds: string[] = [];
+    const fetchSpy = vi.fn().mockImplementation((url: string) => {
+      seenProjectIds.push(new URL(url).searchParams.get("projectId")!);
+      return Promise.resolve(new Response("not granted", { status: 403 }));
+    });
+    vi.stubGlobal("fetch", fetchSpy);
+
+    const { applyPremiumOverlay } = await import("../extension-fetch.js");
+    await applyPremiumOverlay(projectRoot, destDir);
+    const idFile = join(projectRoot, ".tdk", ".project-id");
+    expect(existsSync(idFile)).toBe(true);
+    const persistedId = readFileSync(idFile, "utf-8").trim();
+
+    expect(new Set(seenProjectIds).size).toBe(1);
+    expect(seenProjectIds[0]).toBe(persistedId);
+  });
+
+  it("caches a successful fetch and does not re-fetch within the TTL", async () => {
+    process.env.TDK_LICENSE_KEY = "tdk-fa411a";
+    fixtureTarball ??= buildFixtureTarball();
+
+    const fetchSpy = vi.fn().mockResolvedValue(new Response(new Uint8Array(fixtureTarball), { status: 200 }));
+    vi.stubGlobal("fetch", fetchSpy);
+
+    const { applyPremiumOverlay } = await import("../extension-fetch.js");
+    await applyPremiumOverlay(projectRoot, destDir);
+    await applyPremiumOverlay(projectRoot, destDir);
+
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("re-fetches once the cached bundle is older than the TTL", async () => {
+    process.env.TDK_LICENSE_KEY = "tdk-fa411a";
+    fixtureTarball ??= buildFixtureTarball();
+
+    // A Response body can only be read once - mockResolvedValue would
+    // reuse the same instance across both calls in this test, so build a
+    // fresh Response per invocation instead.
+    const fetchSpy = vi.fn().mockImplementation(() => Promise.resolve(new Response(new Uint8Array(fixtureTarball), { status: 200 })));
+    vi.stubGlobal("fetch", fetchSpy);
+
+    const { applyPremiumOverlay } = await import("../extension-fetch.js");
+    await applyPremiumOverlay(projectRoot, destDir);
+
+    const cachedPath = join(fakeHome, ".tdk", "cache", "premium-tdk-fa411a", "premium.tar.gz");
+    expect(existsSync(cachedPath)).toBe(true);
+    const longAgo = new Date(Date.now() - 13 * 60 * 60 * 1000); // TTL is 12h
+    utimesSync(cachedPath, longAgo, longAgo);
+
+    await applyPremiumOverlay(projectRoot, destDir);
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+  });
+
+  it("switching keys uses a separate cache instead of serving the other key's bundle", async () => {
+    fixtureTarball ??= buildFixtureTarball();
+
+    process.env.TDK_LICENSE_KEY = "tdk-fa411a";
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(new Response(new Uint8Array(fixtureTarball), { status: 200 })));
+    const { applyPremiumOverlay } = await import("../extension-fetch.js");
+    await applyPremiumOverlay(projectRoot, destDir);
+
+    process.env.TDK_LICENSE_KEY = "tdk-fa411b";
+    const secondFetch = vi.fn().mockResolvedValue(new Response("not granted", { status: 403 }));
+    vi.stubGlobal("fetch", secondFetch);
+    const applied = await applyPremiumOverlay(projectRoot, destDir);
+
+    expect(applied).toBe(false);
+    expect(secondFetch).toHaveBeenCalled();
+  });
+
+  it("a network error is caught, never throws, and falls back to the free tier", async () => {
+    process.env.TDK_LICENSE_KEY = "tdk-fa411a";
+    vi.stubGlobal("fetch", vi.fn().mockRejectedValue(new Error("network unreachable")));
+
+    const { applyPremiumOverlay } = await import("../extension-fetch.js");
+    await expect(applyPremiumOverlay(projectRoot, destDir)).resolves.toBe(false);
+  });
+});

package/cli/src/generator/__tests__/template-engine.test.ts

@@ -0,0 +1,70 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { loadTemplate } from "../template-engine.js";
+
+// Real template files, keyed by a substring that only appears in that specific
+// file - regression coverage for the bug where loadTemplate joined a candidate
+// *directory* (not the file) and silently fell through every candidate.
+const REAL_TEMPLATES: Record<string, string> = {
+  "TILT_RESOURCE_DEFAULTS.star.hbs": "get_resource_defaults",
+  "TILT_TECH_STACK.star.hbs": "get_tech_stack",
+  "Tiltfile.hbs": "Tiltfile",
+  ".tiltignore.hbs": "TILT IGNORE FILE",
+  "spec.master.hbs": "spec.master",
+};
+
+describe("template-engine", () => {
+  describe("loadTemplate", () => {
+    for (const [filename, marker] of Object.entries(REAL_TEMPLATES)) {
+      it(`should load ${filename} and return its own content`, () => {
+        const content = loadTemplate(filename);
+        expect(typeof content).toBe("string");
+        expect(content.length).toBeGreaterThan(0);
+        expect(content).toContain(marker);
+      });
+    }
+
+    it("should return distinct content for each template (not the same file/dir every time)", () => {
+      const contents = Object.keys(REAL_TEMPLATES).map((filename) => loadTemplate(filename));
+      expect(new Set(contents).size).toBe(contents.length);
+    });
+
+    it("should throw (not silently return directory bytes) for non-existent template", () => {
+      expect(() => loadTemplate("non-existent.hbs")).toThrow("Failed to load template");
+    });
+
+    describe("executable-relative fallback (compiled binary layout)", () => {
+      let fakeExecDir: string;
+      let originalExecPath: string;
+
+      beforeEach(() => {
+        // Mirrors what scripts/release-binaries.sh bundles next to the
+        // compiled binary: <exeDir>/tdk-cli/cli/templates/<filename>.
+        fakeExecDir = fs.mkdtempSync(path.join(os.tmpdir(), "tdk-exec-"));
+        const bundledTemplatesDir = path.join(fakeExecDir, "tdk-cli", "cli", "templates");
+        fs.mkdirSync(bundledTemplatesDir, { recursive: true });
+        fs.writeFileSync(path.join(bundledTemplatesDir, "only-in-bundle.hbs"), "bundled-marker");
+
+        originalExecPath = process.execPath;
+        Object.defineProperty(process, "execPath", {
+          value: path.join(fakeExecDir, "tdk"),
+          configurable: true,
+        });
+      });
+
+      afterEach(() => {
+        Object.defineProperty(process, "execPath", {
+          value: originalExecPath,
+          configurable: true,
+        });
+        fs.rmSync(fakeExecDir, { recursive: true, force: true });
+      });
+
+      it("finds a template that only exists next to the executable", () => {
+        expect(loadTemplate("only-in-bundle.hbs")).toBe("bundled-marker");
+      });
+    });
+  });
+});

package/cli/src/generator/extension-fetch.ts

@@ -0,0 +1,279 @@
+// Fetches the paid-tier "premium" resource bundle (playwright, c4-diagram,
+// logging, agents-md, sablier, verdaccio, and a few other extras - see
+// tdk-cli-extensions/premium/) from the gated distribution worker, when a
+// license key is configured. The free engine never needs this for its own
+// resources - docker-compose, npm, bun, etc. are already public in this
+// repo, no key required.
+//
+// DDD (domain-driven-design scaffolding) is the one paid feature that is
+// NOT a file overlay: it's gated separately by hasDddLicense() below, via
+// the shared hasLiveResourceLicense() helper, since its code stays in this
+// public repo and is turned on/off by a runtime check rather than swapped
+// in - see that helper's own comment for why it can't just be added to
+// KNOWN_RESOURCES. hasVerdaccioLicense()/hasSablierLicense() also use that
+// same helper, but only to print a "this needs a license" warning in
+// template-engine.ts - Verdaccio and Sablier's real gate is the file
+// overlay above (their public files are disabled stubs, not gated code).
+//
+// The worker (tdk-extension-dist) is the real access-control boundary: it
+// checks the key against BUNDLES_REPO/keys/*.json - existence, activation/
+// expiry dates, granted resources, and a per-key project limit - before
+// serving anything. This client just asks and, if granted, unpacks the
+// result over the vendored stub files so the generator pipeline picks up
+// the real implementations transparently. See
+// tdk-extension-dist/src/index.ts for the server-side enforcement and
+// tdk-extension-dist/src/project-limit.ts for the project-limit logic.
+
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { extractTarball } from "../utils/tar.js";
+
+const DEFAULT_ENDPOINT = "https://tdk-extension-dist.oranguman.workers.dev/v1/premium/bundle.tar.gz";
+
+// Tried in order until one is granted - the worker unlocks the whole
+// bundle on the first resource name a key is found to grant, since
+// premium.tar.gz ships all paid resources together. Keep in sync with
+// what issue-key.yml/update-key.yml accept as `resources` entries.
+const KNOWN_RESOURCES = ["playwright", "c4-diagram", "logging", "agents-md", "sablier", "verdaccio"];
+
+// Re-check the license periodically rather than trusting a local cache
+// forever - an expired or revoked key shouldn't keep unlocking premium
+// content indefinitely just because it worked once.
+const CACHE_TTL_MS = 12 * 60 * 60 * 1000;
+
+// Maps each file's path inside premium.tar.gz to where it belongs in the
+// vendored engine output, so the generator pipeline finds it in the same
+// place the free stub (or, for the never-wired items, nothing at all)
+// used to be.
+const PREMIUM_PATH_MAP: Record<string, string> = {
+  "typescript/playwright_config.star":
+    "engine/topologies/tilt/generators/typescript/playwright_config.star",
+  "generators/agents_md.star": "engine/topologies/tilt/generators/agents_md.star",
+  "c4_diagram.star": "engine/topologies/tilt/generators/c4_diagram.star",
+  "observability/logging.star": "engine/topologies/platform/observability/logging.star",
+  "generators/database_provisioner.star":
+    "engine/topologies/tilt/generators/database_provisioner.star",
+  "generators/dependency_manifest.star":
+    "engine/topologies/tilt/generators/dependency_manifest.star",
+  "generators/fixed_frontend_tsconfig.star":
+    "engine/topologies/tilt/generators/typescript/fixed_frontend_tsconfig.star",
+  "synthetic_monitor.star": "engine/resources/synthetic_monitor.star",
+  "synthetic-monitor-topology.star": "engine/topologies/platform/services/synthetic-monitor.star",
+  "database-management-service.yaml":
+    "platform/services/platform/database-management/service.yaml",
+  "networking/sablier_container_cycle.star":
+    "engine/topologies/platform/docker/networking/sablier_container_cycle.star",
+  "registries/verdaccio_loader.star": "engine/topologies/platform/registries/verdaccio_loader.star",
+};
+
+function getLicenseKey(): string | null {
+  return process.env.TDK_LICENSE_KEY?.trim() || null;
+}
+
+function getEndpoint(): string {
+  return process.env.TDK_PREMIUM_ENDPOINT?.trim() || DEFAULT_ENDPOINT;
+}
+
+// A stable per-project id for the worker's project-limit tracking - not a
+// device or user id. Generated once and persisted alongside the rest of
+// the project's .tdk/ state.
+function getOrCreateProjectId(projectRoot: string): string {
+  const idPath = join(projectRoot, ".tdk", ".project-id");
+  if (existsSync(idPath)) {
+    return readFileSync(idPath, "utf-8").trim();
+  }
+  const id = randomUUID();
+  mkdirSync(join(projectRoot, ".tdk"), { recursive: true });
+  writeFileSync(idPath, id + "\n");
+  return id;
+}
+
+function cacheTarballPath(key: string): string {
+  // Cache is per-key (not shared across different keys on the same
+  // machine) so switching license keys doesn't serve a stale bundle
+  // fetched under a different plan.
+  const safeName = key.replace(/[^a-zA-Z0-9_-]/g, "_");
+  return join(homedir(), ".tdk", "cache", `premium-${safeName}`, "premium.tar.gz");
+}
+
+function isCacheFresh(path: string): boolean {
+  if (!existsSync(path)) return false;
+  return Date.now() - statSync(path).mtimeMs < CACHE_TTL_MS;
+}
+
+async function fetchPremiumBundle(key: string, projectId: string): Promise<Buffer | null> {
+  const endpoint = getEndpoint();
+  for (const resource of KNOWN_RESOURCES) {
+    const url =
+      `${endpoint}?key=${encodeURIComponent(key)}` +
+      `&resource=${encodeURIComponent(resource)}` +
+      `&projectId=${encodeURIComponent(projectId)}`;
+
+    let res: Response;
+    try {
+      res = await fetch(url);
+    } catch (err) {
+      console.warn(`⚠️  Premium fetch failed (network error): ${(err as Error).message}`);
+      return null;
+    }
+
+    if (res.ok) {
+      return Buffer.from(await res.arrayBuffer());
+    }
+    if (res.status === 401 || res.status === 403) {
+      // Not granted for this specific resource name - try the next one
+      // before concluding the key has nothing to offer.
+      continue;
+    }
+    // Anything else (404 missing bundle release, 502 upstream failure,
+    // etc.) won't be fixed by trying a different resource name.
+    console.warn(`⚠️  Premium fetch failed: HTTP ${res.status}`);
+    return null;
+  }
+  return null;
+}
+
+/**
+ * Fetches (with a local, time-limited cache) the premium bundle for the
+ * configured license key and overlays its files onto the already-vendored
+ * free engine at destDir. Best-effort: returns false (never throws) if
+ * there's no key configured, the key doesn't grant anything, or the fetch
+ * fails - the caller should keep going with the free engine either way.
+ */
+export async function applyPremiumOverlay(projectRoot: string, destDir: string): Promise<boolean> {
+  const key = getLicenseKey();
+  if (!key) return false;
+
+  const tarballPath = cacheTarballPath(key);
+
+  if (!isCacheFresh(tarballPath)) {
+    const projectId = getOrCreateProjectId(projectRoot);
+    const bundle = await fetchPremiumBundle(key, projectId);
+    if (!bundle) {
+      console.warn("⚠️  No premium resources unlocked for this key - using free tier only.");
+      return false;
+    }
+    mkdirSync(join(tarballPath, ".."), { recursive: true });
+    writeFileSync(tarballPath, bundle);
+  }
+
+  try {
+    const extractDir = join(tarballPath, "..", "extracted");
+    mkdirSync(extractDir, { recursive: true });
+    extractTarball(readFileSync(tarballPath), extractDir);
+
+    let applied = 0;
+    for (const [src, dest] of Object.entries(PREMIUM_PATH_MAP)) {
+      const from = join(extractDir, src);
+      if (!existsSync(from)) continue;
+      const to = join(destDir, dest);
+      mkdirSync(join(to, ".."), { recursive: true });
+      writeFileSync(to, readFileSync(from));
+      applied++;
+    }
+
+    if (applied > 0) {
+      console.log(`✓ Premium resources unlocked (${applied} file${applied === 1 ? "" : "s"})`);
+      return true;
+    }
+    return false;
+  } catch (err) {
+    console.warn(`⚠️  Failed to apply premium overlay: ${(err as Error).message}`);
+    return false;
+  }
+}
+
+function liveResourceAccessCachePath(key: string, resource: string): string {
+  const safeName = key.replace(/[^a-zA-Z0-9_-]/g, "_");
+  return join(homedir(), ".tdk", "cache", `premium-${safeName}`, `${resource}-access.json`);
+}
+
+/**
+ * Checks whether the configured license key grants a given "live" premium
+ * resource. Originally added for resources with nothing to swap on disk
+ * (ddd is still exactly that: gated code baked into the free engine, no
+ * file overlay). verdaccio and sablier also use this - not because they
+ * lack a PREMIUM_PATH_MAP entry (they have one now), but because their
+ * public files are already disabled stubs regardless of license, so this
+ * check only ever drives a "you need a license for this" warning in
+ * template-engine.ts, never an actual enable/disable decision. Can't reuse
+ * KNOWN_RESOURCES/fetchPremiumBundle for that warning either: that loop
+ * stops at the FIRST resource the key grants and would report false for a
+ * key that grants this resource but not, say, playwright (or vice versa).
+ *
+ * Best-effort: returns false (never throws) if there's no key, the fetch
+ * fails, or the worker denies the resource - the caller decides what "not
+ * licensed" means. Caches the grant/deny outcome (not the bundle itself,
+ * which we never need here) for CACHE_TTL_MS so repeated checks don't
+ * re-download the full premium.tar.gz just to read a status code.
+ */
+async function hasLiveResourceLicense(projectRoot: string, resource: string): Promise<boolean> {
+  const key = getLicenseKey();
+  if (!key) return false;
+
+  const cachePath = liveResourceAccessCachePath(key, resource);
+  if (isCacheFresh(cachePath)) {
+    try {
+      const cached = JSON.parse(readFileSync(cachePath, "utf-8")) as { granted: boolean };
+      return cached.granted === true;
+    } catch {
+      // Corrupt/unreadable cache - fall through and re-check live.
+    }
+  }
+
+  const projectId = getOrCreateProjectId(projectRoot);
+  const endpoint = getEndpoint();
+  const url =
+    `${endpoint}?key=${encodeURIComponent(key)}` +
+    `&resource=${encodeURIComponent(resource)}&projectId=${encodeURIComponent(projectId)}`;
+
+  let granted = false;
+  try {
+    const res = await fetch(url);
+    granted = res.ok;
+    // Drain the body (a full premium.tar.gz on success) so we don't leave
+    // it dangling - we only need the status, not the content.
+    if (res.body) {
+      await res.arrayBuffer().catch(() => undefined);
+    }
+  } catch (err) {
+    console.warn(`⚠️  ${resource} license check failed (network error): ${(err as Error).message}`);
+    return false;
+  }
+
+  try {
+    mkdirSync(join(cachePath, ".."), { recursive: true });
+    writeFileSync(cachePath, JSON.stringify({ granted, checked: new Date().toISOString() }));
+  } catch {
+    // Best-effort cache; a write failure just means we re-check next time.
+  }
+
+  return granted;
+}
+
+/** Checks whether the configured license key grants the "verdaccio" resource. */
+export async function hasVerdaccioLicense(projectRoot: string): Promise<boolean> {
+  return hasLiveResourceLicense(projectRoot, "verdaccio");
+}
+
+/**
+ * Checks whether the configured license key grants the "ddd" resource
+ * (domain-driven-design folder structure + path aliases for backend
+ * resources - see generate_backend_path_aliases() in
+ * engine/topologies/tilt/generators/vite/helpers.star).
+ */
+export async function hasDddLicense(projectRoot: string): Promise<boolean> {
+  return hasLiveResourceLicense(projectRoot, "ddd");
+}
+
+/**
+ * Checks whether the configured license key grants the "sablier" resource
+ * (on-demand start/stop for idle resources via a `sablier: {enable: true}`
+ * manifest block - see sablier_container_cycle.star in
+ * engine/topologies/platform/docker/networking/).
+ */
+export async function hasSablierLicense(projectRoot: string): Promise<boolean> {
+  return hasLiveResourceLicense(projectRoot, "sablier");
+}