@ashlr/stack-core 0.1.1 → 0.3.0

package/src/__tests__/telemetry.test.ts

@@ -0,0 +1,354 @@
+/**
+ * Telemetry module tests.
+ *
+ * Strategy: use __setConfigDirForTesting() to redirect all config I/O to a
+ * temp directory, bypassing the real ~/.ashlr/stack/config.json entirely.
+ * Tests write/delete the temp config file directly between runs.
+ */
+
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import {
+  __setConfigDirForTesting,
+  disable as disableTelemetry,
+  emit,
+  enable as enableTelemetry,
+  isEnabled,
+} from "../telemetry.ts";
+
+// ---------------------------------------------------------------------------
+// Temp config dir wired before any test runs
+// ---------------------------------------------------------------------------
+
+const TMP_CONFIG_DIR = join(import.meta.dir, "__telemetry_tmp__", ".ashlr", "stack");
+const TMP_CONFIG_PATH = join(TMP_CONFIG_DIR, "config.json");
+
+async function writeCfg(cfg: object): Promise<void> {
+  await mkdir(TMP_CONFIG_DIR, { recursive: true });
+  await writeFile(TMP_CONFIG_PATH, JSON.stringify(cfg, null, 2), "utf-8");
+}
+
+async function deleteCfg(): Promise<void> {
+  await rm(TMP_CONFIG_PATH, { force: true });
+}
+
+let realFetch: typeof fetch;
+
+beforeAll(async () => {
+  await mkdir(TMP_CONFIG_DIR, { recursive: true });
+  __setConfigDirForTesting(TMP_CONFIG_DIR);
+  realFetch = globalThis.fetch;
+});
+
+afterAll(async () => {
+  __setConfigDirForTesting(undefined);
+  globalThis.fetch = realFetch;
+  await rm(join(import.meta.dir, "__telemetry_tmp__"), { recursive: true, force: true });
+});
+
+beforeEach(async () => {
+  await deleteCfg();
+  globalThis.fetch = realFetch;
+  Reflect.deleteProperty(process.env, "STACK_TELEMETRY");
+  Reflect.deleteProperty(process.env, "STACK_TELEMETRY_ENDPOINT");
+});
+
+afterEach(() => {
+  globalThis.fetch = realFetch;
+  Reflect.deleteProperty(process.env, "STACK_TELEMETRY");
+  Reflect.deleteProperty(process.env, "STACK_TELEMETRY_ENDPOINT");
+});
+
+// ---------------------------------------------------------------------------
+// 1. emit when disabled is a no-op (fetch never called)
+// ---------------------------------------------------------------------------
+
+describe("emit when disabled", () => {
+  test("fetch is never called when config.enabled = false", async () => {
+    await writeCfg({ enabled: false, installId: "test-id-disabled" });
+
+    let fetchCalled = false;
+    globalThis.fetch = (async () => {
+      fetchCalled = true;
+      return new Response("ok", { status: 200 });
+    }) as unknown as typeof fetch;
+
+    await emit({ type: "command", command: "add", exitCode: 0, durationMs: 100 });
+    await new Promise((r) => setTimeout(r, 50));
+    expect(fetchCalled).toBe(false);
+  });
+
+  test("fetch is never called when no config file exists", async () => {
+    let fetchCalled = false;
+    globalThis.fetch = (async () => {
+      fetchCalled = true;
+      return new Response("ok", { status: 200 });
+    }) as unknown as typeof fetch;
+
+    await emit({ type: "command", command: "scan" });
+    await new Promise((r) => setTimeout(r, 50));
+    expect(fetchCalled).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 2. emit when enabled POSTs with expected payload
+// ---------------------------------------------------------------------------
+
+describe("emit when enabled", () => {
+  test("POSTs JSON with correct shape when STACK_TELEMETRY_ENDPOINT is set", async () => {
+    await writeCfg({ enabled: true, installId: "fixed-install-id" });
+    process.env.STACK_TELEMETRY_ENDPOINT = "https://example.com/v1/events";
+
+    let capturedBody: unknown;
+    let capturedUrl: string | undefined;
+    globalThis.fetch = (async (url: string, init?: RequestInit) => {
+      capturedUrl = url as string;
+      capturedBody = JSON.parse(init?.body as string);
+      return new Response("ok", { status: 200 });
+    }) as unknown as typeof fetch;
+
+    await emit({ type: "command", command: "add", exitCode: 0, durationMs: 42 });
+    await new Promise((r) => setTimeout(r, 100));
+
+    expect(capturedUrl).toBe("https://example.com/v1/events");
+    const body = capturedBody as Record<string, unknown>;
+    expect(body.type).toBe("command");
+    expect(body.command).toBe("add");
+    expect(body.exitCode).toBe(0);
+    expect(body.durationMs).toBe(42);
+    expect(body.installId).toBe("fixed-install-id");
+    expect(typeof body.runId).toBe("string");
+    expect(body.platform).toBeDefined();
+    expect(body.stackVersion).toBeDefined();
+  });
+
+  test("fetch is never called when enabled but no endpoint configured", async () => {
+    await writeCfg({ enabled: true, installId: "no-endpoint-id" });
+    // Neither STACK_TELEMETRY_ENDPOINT nor config.endpoint is set.
+
+    let fetchCalled = false;
+    globalThis.fetch = (async () => {
+      fetchCalled = true;
+      return new Response("ok", { status: 200 });
+    }) as unknown as typeof fetch;
+
+    await emit({ type: "command", command: "add", exitCode: 0, durationMs: 10 });
+    await new Promise((r) => setTimeout(r, 50));
+    expect(fetchCalled).toBe(false);
+  });
+
+  test("config.endpoint is used when STACK_TELEMETRY_ENDPOINT is not set", async () => {
+    await writeCfg({
+      enabled: true,
+      installId: "cfg-endpoint-id",
+      endpoint: "https://self-hosted.example.com/events",
+    });
+
+    let capturedUrl: string | undefined;
+    globalThis.fetch = (async (url: string) => {
+      capturedUrl = url as string;
+      return new Response("ok", { status: 200 });
+    }) as unknown as typeof fetch;
+
+    await emit({ type: "command", command: "scan" });
+    await new Promise((r) => setTimeout(r, 100));
+    expect(capturedUrl).toBe("https://self-hosted.example.com/events");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 3. STACK_TELEMETRY=0 overrides to disabled
+// ---------------------------------------------------------------------------
+
+describe("STACK_TELEMETRY env var", () => {
+  test("STACK_TELEMETRY=0 prevents emit even when config.enabled = true", async () => {
+    await writeCfg({ enabled: true, installId: "env-off-test" });
+    process.env.STACK_TELEMETRY = "0";
+
+    let fetchCalled = false;
+    globalThis.fetch = (async () => {
+      fetchCalled = true;
+      return new Response("ok", { status: 200 });
+    }) as unknown as typeof fetch;
+
+    await emit({ type: "command", command: "scan" });
+    await new Promise((r) => setTimeout(r, 50));
+    expect(fetchCalled).toBe(false);
+  });
+
+  // ---------------------------------------------------------------------------
+  // 4. STACK_TELEMETRY=1 without prior opt-in stays disabled
+  // ---------------------------------------------------------------------------
+
+  test("STACK_TELEMETRY=1 alone does not enable telemetry (no prior opt-in)", async () => {
+    await writeCfg({ enabled: false, installId: "env-on-test" });
+    process.env.STACK_TELEMETRY = "1";
+
+    let fetchCalled = false;
+    globalThis.fetch = (async () => {
+      fetchCalled = true;
+      return new Response("ok", { status: 200 });
+    }) as unknown as typeof fetch;
+
+    // isEnabled() must return false — env=1 is not a substitute for opt-in.
+    expect(await isEnabled()).toBe(false);
+
+    await emit({ type: "command", command: "add" });
+    await new Promise((r) => setTimeout(r, 50));
+    expect(fetchCalled).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 5. emit with fetch throwing → no error propagated
+// ---------------------------------------------------------------------------
+
+describe("emit error swallowing", () => {
+  test("network error does not propagate to the caller", async () => {
+    await writeCfg({ enabled: true, installId: "throw-test-id" });
+    process.env.STACK_TELEMETRY_ENDPOINT = "https://example.com/v1/events";
+    globalThis.fetch = (async () => {
+      throw new Error("network failure");
+    }) as unknown as typeof fetch;
+
+    await expect(
+      emit({ type: "error", command: "add", exitCode: 1, durationMs: 5 }),
+    ).resolves.toBeUndefined();
+
+    await new Promise((r) => setTimeout(r, 100));
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 6. installId persists across calls
+// ---------------------------------------------------------------------------
+
+describe("installId persistence", () => {
+  test("same installId is emitted on every call", async () => {
+    await writeCfg({ enabled: true, installId: "persisted-id-123" });
+    process.env.STACK_TELEMETRY_ENDPOINT = "https://example.com/v1/events";
+
+    const ids: string[] = [];
+    globalThis.fetch = (async (_url: string, init?: RequestInit) => {
+      const body = JSON.parse(init?.body as string) as Record<string, unknown>;
+      ids.push(body.installId as string);
+      return new Response("ok", { status: 200 });
+    }) as unknown as typeof fetch;
+
+    await emit({ type: "command", command: "add" });
+    await emit({ type: "command", command: "scan" });
+    await new Promise((r) => setTimeout(r, 150));
+
+    expect(ids.length).toBe(2);
+    expect(ids[0]).toBe("persisted-id-123");
+    expect(ids[1]).toBe("persisted-id-123");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 7. No path/cwd/project in the emitted payload
+// ---------------------------------------------------------------------------
+
+describe("privacy: banned fields absent from payload", () => {
+  const BANNED_KEYS = [
+    "cwd",
+    "projectName",
+    "project_name",
+    "project",
+    "provider",
+    "providerName",
+    "secret",
+    "secretValue",
+    "secretKey",
+    "envValue",
+    "homePath",
+    "home",
+    "stackToml",
+    "stack_toml",
+  ];
+
+  test("emitted payload contains none of the banned keys", async () => {
+    await writeCfg({ enabled: true, installId: "privacy-test-id" });
+    process.env.STACK_TELEMETRY_ENDPOINT = "https://example.com/v1/events";
+
+    let capturedBody: Record<string, unknown> = {};
+    globalThis.fetch = (async (_url: string, init?: RequestInit) => {
+      capturedBody = JSON.parse(init?.body as string) as Record<string, unknown>;
+      return new Response("ok", { status: 200 });
+    }) as unknown as typeof fetch;
+
+    await emit({ type: "command", command: "add", exitCode: 0, durationMs: 10 });
+    await new Promise((r) => setTimeout(r, 100));
+
+    for (const key of BANNED_KEYS) {
+      expect(Object.prototype.hasOwnProperty.call(capturedBody, key)).toBe(false);
+    }
+  });
+
+  test("installId is a UUID (no path segments)", async () => {
+    await writeCfg({ enabled: true, installId: crypto.randomUUID() });
+    process.env.STACK_TELEMETRY_ENDPOINT = "https://example.com/v1/events";
+
+    let capturedBody: Record<string, unknown> = {};
+    globalThis.fetch = (async (_url: string, init?: RequestInit) => {
+      capturedBody = JSON.parse(init?.body as string) as Record<string, unknown>;
+      return new Response("ok", { status: 200 });
+    }) as unknown as typeof fetch;
+
+    await emit({ type: "command", command: "scan" });
+    await new Promise((r) => setTimeout(r, 100));
+
+    const installId = capturedBody.installId as string;
+    expect(installId).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i);
+    expect(installId).not.toContain("/");
+    expect(installId).not.toContain("\\");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 8. isEnabled reflects stored config
+// ---------------------------------------------------------------------------
+
+describe("isEnabled", () => {
+  test("returns false when no config file exists", async () => {
+    expect(await isEnabled()).toBe(false);
+  });
+
+  test("returns true when config.enabled = true", async () => {
+    await writeCfg({ enabled: true, installId: "check-id" });
+    expect(await isEnabled()).toBe(true);
+  });
+
+  test("returns false when STACK_TELEMETRY=0 even if enabled=true", async () => {
+    await writeCfg({ enabled: true, installId: "check-id" });
+    process.env.STACK_TELEMETRY = "0";
+    expect(await isEnabled()).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 9. disable() and enable() round-trip
+// ---------------------------------------------------------------------------
+
+describe("disable / enable", () => {
+  test("disable() writes enabled=false", async () => {
+    await writeCfg({ enabled: true, installId: "round-trip-id" });
+    await disableTelemetry();
+    expect(await isEnabled()).toBe(false);
+  });
+
+  test("enable() writes enabled=true and creates installId if missing", async () => {
+    await writeCfg({ enabled: false });
+    await enableTelemetry();
+    expect(await isEnabled()).toBe(true);
+
+    const raw = await readFile(TMP_CONFIG_PATH, "utf-8");
+    const cfg = JSON.parse(raw) as { installId?: string };
+    expect(cfg.installId).toBeDefined();
+    expect(cfg.installId).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
+    );
+  });
+});

package/src/__tests__/template-litellm-gateway.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { PROVIDERS_REF } from "../catalog.ts";
+import { loadTemplate } from "../templates.ts";
+
+const dir = join(import.meta.dir, "..", "..", "..", "..", "templates", "litellm-gateway");
+const readme = readFileSync(join(dir, "README.md"), "utf-8");
+
+describe("litellm-gateway template", () => {
+  test("declares only catalog providers and their own secret slots, no values", async () => {
+    const cfg = await loadTemplate("litellm-gateway");
+    expect(cfg).toBeDefined();
+    const services = Object.entries(cfg?.services ?? {});
+    expect(services.length).toBeGreaterThan(0);
+    for (const [name, svc] of services) {
+      const ref = PROVIDERS_REF.find((p) => p.name === svc.provider);
+      expect(ref, `${name} uses a provider in the catalog`).toBeDefined();
+      for (const secret of svc.secrets ?? []) expect(ref?.secrets).toContain(secret);
+    }
+    const raw = readFileSync(join(dir, "stack.toml"), "utf-8");
+    expect(raw).not.toMatch(/sk-[A-Za-z0-9]/);
+    expect(raw).toContain('template = "litellm-gateway"');
+  });
+
+  test("README keeps the pin and isolation guidance", () => {
+    for (const phrase of [
+      "Pin, never float",
+      "GHSA-5mg7-485q-xm76",
+      "no mounted dotfiles",
+      "Bind to loopback",
+      "Placeholders only",
+      "allow_client_side_credentials: false",
+      "NO_DOCS",
+      "Cursor is not supported",
+    ]) {
+      expect(readme, phrase).toContain(phrase);
+    }
+    expect(readme).not.toContain("\u2014");
+  });
+
+  test("README prerequisites match the template and distinguish local checks from integration", async () => {
+    const cfg = await loadTemplate("litellm-gateway");
+    expect(cfg).toBeDefined();
+    const table = readme.match(
+      /\| Service \| Phantom secret name \|\n\| --- \| --- \|\n((?:\| `[^`]+` \| `[^`]+` \|\n)+)/,
+    );
+    expect(table).not.toBeNull();
+    const documentedSlots = [...(table?.[1] ?? "").matchAll(/\| `([^`]+)` \| `([^`]+)` \|/g)].map(
+      ([, service, secret]) => [service, secret],
+    );
+    const configuredSlots = Object.entries(cfg?.services ?? {}).flatMap(([service, entry]) =>
+      entry.secrets.map((secret) => [service, secret]),
+    );
+    expect(documentedSlots).toEqual(configuredSlots);
+    expect(cfg?.environments).toEqual([{ name: "dev", default: true }]);
+    expect(configuredSlots.flat()).not.toContain("LITELLM_MASTER_KEY");
+    for (const phrase of [
+      "stack init --template litellm-gateway --noProvision",
+      "service is already in the stack",
+      "does not set it",
+      "stack templates list --json",
+      "template-litellm-gateway.test.ts",
+      "local mock upstream and dummy credentials",
+      "does not establish those properties",
+    ]) {
+      expect(readme, phrase).toContain(phrase);
+    }
+  });
+});

package/src/__tests__/template-temporal-worker-phantom.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { loadTemplate } from "../templates.ts";
+
+const dir = join(import.meta.dir, "..", "..", "..", "..", "templates", "temporal-worker-phantom");
+const readme = readFileSync(join(dir, "README.md"), "utf-8");
+
+describe("temporal-worker-phantom template", () => {
+  test("loads with no services and holds no secret values", async () => {
+    const cfg = await loadTemplate("temporal-worker-phantom");
+    expect(cfg).toBeDefined();
+    expect(cfg?.services).toEqual({});
+    expect(cfg?.environments).toEqual([{ name: "dev", default: true }]);
+    const raw = readFileSync(join(dir, "stack.toml"), "utf-8");
+    expect(raw).toContain('template = "temporal-worker-phantom"');
+  });
+
+  test("README describes the configuration and limits of local verification", () => {
+    for (const phrase of [
+      "stack init --template temporal-worker-phantom",
+      "stack list --json",
+      '"services": []',
+      "default `dev` environment",
+      "not connectivity, credentials or worker execution",
+      "does not guarantee raw credentials",
+    ]) {
+      expect(readme, phrase).toContain(phrase);
+    }
+  });
+
+  test("README keeps the security rules and avoids em dashes", () => {
+    for (const phrase of [
+      "phantom exec",
+      "No secret values in workflow data",
+      "Codec Server stays local",
+      "noopAuthorizer",
+      "start-dev",
+      "Keep Temporal optional",
+    ]) {
+      expect(readme, phrase).toContain(phrase);
+    }
+    expect(readme).not.toContain("\u2014");
+  });
+});

package/src/__tests__/templates.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
-import { listTemplates, loadTemplate } from "../templates.ts";
 import { listProviderNames } from "../providers/index.ts";
+import { listTemplates, loadTemplate } from "../templates.ts";
 
 describe("starter templates", () => {
   test("all templates reference only registered providers", async () => {

package/src/__tests__/turso-provider.test.ts

@@ -1,6 +1,6 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import turso from "../providers/turso.ts";
 import type { ProviderContext } from "../providers/_base.ts";
+import turso from "../providers/turso.ts";
 import { type Harness, setupFakePhantom } from "./_harness.ts";
 
 describe("turso provider (mocked fetch)", () => {
@@ -22,10 +22,7 @@ describe("turso provider (mocked fetch)", () => {
       const u = String(url);
       const method = init?.method ?? "GET";
       if (u.endsWith("/organizations") && method === "GET") {
-        return new Response(
-          JSON.stringify([{ slug: "my-org", name: "My Org" }]),
-          { status: 200 },
-        );
+        return new Response(JSON.stringify([{ slug: "my-org", name: "My Org" }]), { status: 200 });
       }
       if (u.endsWith("/organizations/my-org/databases") && method === "POST") {
         return new Response(