@ashlr/stack-core 0.2.2 → 0.3.1

package/src/__tests__/scan-missing-dir.test.ts

@@ -0,0 +1,45 @@
+import { afterEach, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { scanSource } from "../detect-source.ts";
+import { SourceDirectoryNotFoundError } from "../errors.ts";
+
+const roots: string[] = [];
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+function makeRoot(): string {
+  const root = mkdtempSync(join(tmpdir(), "stack-scan-missing-"));
+  roots.push(root);
+  return root;
+}
+
+test("a missing directory fails with a typed error without being created", async () => {
+  const path = join(makeRoot(), "missing", "project");
+  try {
+    await scanSource(path);
+    throw new Error("expected scanSource to reject");
+  } catch (error) {
+    expect(error).toBeInstanceOf(SourceDirectoryNotFoundError);
+    expect((error as SourceDirectoryNotFoundError).code).toBe("SOURCE_DIRECTORY_NOT_FOUND");
+    expect((error as Error).message).toContain(path);
+  }
+  expect(existsSync(path)).toBe(false);
+  expect(existsSync(join(path, ".."))).toBe(false);
+});
+
+test("a file path and a path beneath a file fail with the typed error", async () => {
+  const path = join(makeRoot(), "file");
+  writeFileSync(path, "unchanged");
+  await expect(scanSource(path)).rejects.toBeInstanceOf(SourceDirectoryNotFoundError);
+  await expect(scanSource(join(path, "child"))).rejects.toBeInstanceOf(
+    SourceDirectoryNotFoundError,
+  );
+  expect(readFileSync(path, "utf8")).toBe("unchanged");
+});
+
+test("an empty directory still has no detections", async () => {
+  expect(await scanSource(makeRoot())).toEqual([]);
+});

package/src/__tests__/stack-manifest.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from "bun:test";
+import cli from "../../../cli/package.json";
+import mcp from "../../../mcp/package.json";
+import plugin from "../../../plugin/.claude-plugin/plugin.json";
+import core from "../../package.json";
+import { STACK_MANIFEST, type StackManifest } from "../index.ts";
+import fixture from "./fixtures/stack-manifest.v1.json";
+
+describe("Stack ecosystem manifest v1", () => {
+  test("public export preserves the fixture's JSON wire contract", () => {
+    const manifest: StackManifest = STACK_MANIFEST;
+    expect(JSON.parse(JSON.stringify(manifest))).toEqual(fixture);
+  });
+
+  test("every distributable matches its source name and version", () => {
+    const metadata = { core, cli, mcp, plugin };
+    const manifest: StackManifest = STACK_MANIFEST;
+    expect(Object.keys(metadata).sort()).toEqual(manifest.components.map(({ id }) => id).sort());
+    for (const component of manifest.components) {
+      expect(component.name).toBe(metadata[component.id].name);
+      expect(component.version).toBe(metadata[component.id].version);
+      expect(component.version).toMatch(/^\d+\.\d+\.\d+(?:-[\da-zA-Z.-]+)?(?:\+[\da-zA-Z.-]+)?$/);
+    }
+  });
+
+  test("component IDs are unique", () => {
+    const ids = STACK_MANIFEST.components.map(({ id }) => id);
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+
+  test("shared metadata cannot be mutated by consumers", () => {
+    expect(Object.isFrozen(STACK_MANIFEST)).toBe(true);
+    expect(Object.isFrozen(STACK_MANIFEST.components)).toBe(true);
+    for (const component of STACK_MANIFEST.components) {
+      expect(Object.isFrozen(component)).toBe(true);
+    }
+  });
+});

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

@@ -38,4 +38,33 @@ describe("litellm-gateway template", () => {
     }
     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

@@ -11,10 +11,24 @@ describe("temporal-worker-phantom template", () => {
     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",

package/src/ai/phantom-wire.ts

@@ -9,9 +9,16 @@
  *      fail or block the real value from landing later.
  *   2. For webhook-capable providers (Stripe, Clerk, Supabase, GitHub),
  *      scaffold a commented-out handler stub in `.stack/webhooks/<provider>.ts`
- *      so the user has somewhere concrete to land the signature verification.
+ *      as an example only. Signature verification is not implemented: the
+ *      stub's TODO states the trust limitation — a present signature header
+ *      authenticates nothing and the body is untrusted input — and points at
+ *      the provider-specific verification to add before deploying a handler.
  *
  * An opt-out (`--no-wire`) skips both steps.
+ *
+ * Recipe manifests are unsigned: signature verification is not implemented.
+ * Checking provider names against the catalog does not authenticate a recipe's
+ * origin or integrity; callers must use recipes from a trusted source.
  */
 
 import { mkdir, writeFile } from "node:fs/promises";
@@ -33,10 +40,8 @@ export interface WireResult {
 }
 
 /**
- * Providers with webhooks worth pre-wiring. Keep this list tight — each entry
- * gets a hand-maintained stub in `webhookStubFor`. Adding a new provider here
- * without also adding its stub produces an empty file, which is worse than
- * no file.
+ * Providers with webhooks worth pre-wiring. Keep this list tight and update
+ * the provider-specific secret and signature header mappings for each entry.
  */
 const WEBHOOK_PROVIDERS = new Set(["stripe", "clerk", "supabase", "github"]);
 
@@ -112,20 +117,53 @@ async function writeWebhookStub(cwd: string, provider: string): Promise<string>
 function webhookStubFor(provider: string): string {
   const base = `// Auto-generated by \`stack apply\` — webhook handler stub for ${provider}.
 // Fill in the secret retrieval + signature verification before deploying.
+// This entire example is commented out and does not verify signatures.
+// If uncommented as-is, it accepts any non-empty signature header and returns
+// 200 without authenticating the request. Implement verification first.
 //
 // The secret lives in Phantom; read it at call time with:
 //   phantom reveal ${webhookSecretKeyFor(provider)}
 //
 // export async function handle${capitalize(provider)}Webhook(req: Request): Promise<Response> {
 //   const signature = req.headers.get("${signatureHeaderFor(provider)}");
+//   if (!signature) return new Response("Missing signature", { status: 400 });
 //   const body = await req.text();
-//   // TODO: verify(signature, body) before trusting.
+//   // TODO(security): signature verification is NOT implemented here. The
+//   // header check above proves only that a signature header arrived; its
+//   // value is never compared to anything. Until this TODO is done, \`body\`
+//   // is unauthenticated, attacker-controlled input — anyone who can POST
+//   // to this endpoint can forge a ${provider} webhook.
+//   // ${verificationHintFor(provider)}
+//   // Verify over the exact raw body bytes with the webhook secret
+//   // (\`phantom reveal ${webhookSecretKeyFor(provider)}\`) and compare in
+//   // constant time; reject missing or invalid signatures, and only then
+//   // parse, trust, or act on the body.
 //   return new Response("ok", { status: 200 });
 // }
 `;
   return base;
 }
 
+/**
+ * One-line pointer to the provider's documented signature scheme, inlined into
+ * the stub's TODO so the implementer starts at the right verification API.
+ * Falls back to a generic instruction for providers added later.
+ */
+function verificationHintFor(provider: string): string {
+  switch (provider) {
+    case "stripe":
+      return "Stripe: `stripe.webhooks.constructEvent` — HMAC-SHA256 with timestamp tolerance.";
+    case "clerk":
+      return "Clerk (svix): `new Webhook(secret).verify(body, headers)`.";
+    case "supabase":
+      return "Supabase: `x-supabase-signature` per Supabase's documented webhook scheme.";
+    case "github":
+      return "GitHub: `x-hub-signature-256` is `sha256=` + HMAC-SHA256 of the raw body.";
+    default:
+      return "Verify per the provider's documented signature scheme.";
+  }
+}
+
 function webhookSecretKeyFor(provider: string): string {
   switch (provider) {
     case "stripe":

package/src/detect-source.ts

@@ -1,6 +1,7 @@
 import { existsSync, readdirSync } from "node:fs";
-import { readFile } from "node:fs/promises";
+import { readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
+import { SourceDirectoryNotFoundError } from "./errors.ts";
 
 /**
  * Source-level provider detection. Reads package.json / requirements.txt /
@@ -165,6 +166,18 @@ export async function scanSource(
   cwd: string,
   _opts: SourceScanOptions = {},
 ): Promise<SourceDetection[]> {
+  let root: Awaited<ReturnType<typeof stat>>;
+  try {
+    root = await stat(cwd);
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT" || code === "ENOTDIR") {
+      throw new SourceDirectoryNotFoundError(cwd, { cause: error });
+    }
+    throw error;
+  }
+  if (!root.isDirectory()) throw new SourceDirectoryNotFoundError(cwd);
+
   const hits = new Map<string, SourceDetection>();
 
   const add = (provider: string, signal: string, confidence: DetectionConfidence) => {

package/src/errors.ts

@@ -27,3 +27,9 @@ export class ConfigNotFoundError extends StackError {
     super("CONFIG_NOT_FOUND", `No .stack.toml at ${path}. Run \`stack init\` first.`);
   }
 }
+
+export class SourceDirectoryNotFoundError extends StackError {
+  constructor(path: string, options?: { cause?: unknown }) {
+    super("SOURCE_DIRECTORY_NOT_FOUND", `Source directory not found: ${path}`, options);
+  }
+}

package/src/index.ts

@@ -1,4 +1,5 @@
 export * from "./config.ts";
+export { STACK_MANIFEST, type StackManifest, type StackComponent } from "./stack-manifest.ts";
 export {
   isEnabled as isTelemetryEnabled,
   promptFirstRun as promptTelemetryFirstRun,

package/src/phantom-process.ts

@@ -0,0 +1,72 @@
+import { constants, accessSync, statSync } from "node:fs";
+import { delimiter, resolve } from "node:path";
+import { PhantomNotInstalledError } from "./errors.ts";
+
+// Keep runtime, terminal and vault-location settings, plus Phantom's explicit
+// vault unlock input. Never forward arbitrary provider credentials or loader hooks.
+const ENV_KEYS = [
+  "PATH",
+  "HOME",
+  "USER",
+  "USERPROFILE",
+  "SystemRoot",
+  "APPDATA",
+  "LOCALAPPDATA",
+  "PATHEXT",
+  "XDG_CONFIG_HOME",
+  "XDG_DATA_HOME",
+  "XDG_STATE_HOME",
+  "XDG_RUNTIME_DIR",
+  "TMPDIR",
+  "TEMP",
+  "TMP",
+  "LANG",
+  "LC_ALL",
+  "LC_CTYPE",
+  "TERM",
+  "NO_COLOR",
+  "PHANTOM_VAULT_PASSPHRASE",
+] as const;
+
+export function phantomEnv(source: NodeJS.ProcessEnv): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const key of ENV_KEYS) {
+    const value = source[key];
+    if (value !== undefined) env[key] = value;
+  }
+  if (process.platform === "win32") {
+    // Windows environment names are case insensitive. Emit one canonical key.
+    for (const key of ENV_KEYS) {
+      const alias = Object.keys(source).find((name) => name.toLowerCase() === key.toLowerCase());
+      if (alias !== undefined && source[alias] !== undefined) env[key] = source[alias];
+    }
+  }
+  // Normalize PATH while the caller's cwd is still unambiguous: after spawn
+  // applies the operation cwd, a relative entry would resolve inside that
+  // project. Empty entries (an implicit current directory) are dropped, not
+  // resolved anywhere.
+  if (env.PATH !== undefined) {
+    env.PATH = env.PATH.split(delimiter)
+      .filter((entry) => entry !== "")
+      .map((entry) => resolve(entry))
+      .join(delimiter);
+  }
+  return env;
+}
+
+/** Resolve before spawn changes cwd; do not search an implicit current directory. */
+export function resolvePhantomBinary(env: NodeJS.ProcessEnv, cwd = process.cwd()): string {
+  const name = process.platform === "win32" ? "phantom.exe" : "phantom";
+  for (const dir of (env.PATH ?? "").split(delimiter)) {
+    if (!dir) continue;
+    const candidate = resolve(cwd, dir, name);
+    try {
+      if (!statSync(candidate).isFile()) continue;
+      accessSync(candidate, constants.X_OK);
+      return candidate;
+    } catch {
+      // Missing or non-executable entries do not shadow a later installation.
+    }
+  }
+  throw new PhantomNotInstalledError();
+}

package/src/phantom.ts

@@ -1,5 +1,6 @@
 import { spawn } from "node:child_process";
 import { PhantomNotInstalledError, StackError } from "./errors.ts";
+import { phantomEnv, resolvePhantomBinary } from "./phantom-process.ts";
 
 /**
  * Thin wrapper around the `phantom` CLI. Stack never stores secrets locally —
@@ -13,6 +14,16 @@ export interface PhantomExecResult {
   code: number;
   signal?: NodeJS.Signals;
   completion?: "exited" | "signal" | "unknown";
+  /** True when `timeoutMs` elapsed and Stack killed the child. */
+  timedOut?: boolean;
+}
+
+/** A phantom call was killed after its `timeoutMs`. Distinct from a failed or unparseable call. */
+export class PhantomTimeoutError extends Error {
+  constructor(args: string[], timeoutMs: number | undefined) {
+    super(`phantom ${args[0] ?? ""} timed out after ${timeoutMs ?? "?"}ms`);
+    this.name = "PhantomTimeoutError";
+  }
 }
 
 /** Interpret close fields only; this does not attest provider or vault state. */
@@ -25,15 +36,31 @@ export function completionForClose(
 
 let cachedInstalled: boolean | undefined;
 
-export async function isPhantomInstalled(): Promise<boolean> {
-  if (cachedInstalled !== undefined) return cachedInstalled;
+/**
+ * `phantom --version` as three states. A timeout is not cached, because a slow
+ * Phantom is still installed; the next probe asks again.
+ */
+export async function probePhantomInstalled(opts?: {
+  timeoutMs?: number;
+}): Promise<"installed" | "missing" | "timeout"> {
+  if (cachedInstalled !== undefined) return cachedInstalled ? "installed" : "missing";
   try {
-    const result = await exec(["--version"], { allowFailure: true });
+    const result = await exec(
+      ["--version"],
+      opts?.timeoutMs !== undefined
+        ? { allowFailure: true, timeoutMs: opts.timeoutMs }
+        : { allowFailure: true },
+    );
+    if (result.timedOut) return "timeout";
     cachedInstalled = result.code === 0 && result.completion === "exited";
   } catch {
     cachedInstalled = false;
   }
-  return cachedInstalled;
+  return cachedInstalled ? "installed" : "missing";
+}
+
+export async function isPhantomInstalled(opts?: { timeoutMs?: number }): Promise<boolean> {
+  return (await probePhantomInstalled(opts)) === "installed";
 }
 
 export async function assertPhantomInstalled(): Promise<void> {
@@ -46,17 +73,98 @@ export interface ExecOptions {
   stdin?: string;
   /** If true, inherit stdio so interactive flows (OAuth browser) work. */
   interactive?: boolean;
+  /** Kill the phantom child after this many milliseconds. */
+  timeoutMs?: number;
 }
 
 export async function exec(args: string[], opts: ExecOptions = {}): Promise<PhantomExecResult> {
+  // Filter the inherited environment and resolve against the caller's PATH
+  // before applying the project cwd; see phantom-process.ts.
+  const env = phantomEnv(process.env);
+  const binary = resolvePhantomBinary(env);
   return new Promise((resolvePromise, reject) => {
-    const child = spawn("phantom", args, {
+    const hasTimeout = typeof opts.timeoutMs === "number" && Number.isFinite(opts.timeoutMs);
+    // A timed probe gets its own process group (POSIX) so a timeout can kill
+    // phantom and any grandchild holding its stdio. Interactive runs stay in
+    // the foreground group so the TTY keeps working.
+    const useGroup = hasTimeout && !opts.interactive && process.platform !== "win32";
+    const child = spawn(binary, args, {
+      env,
       cwd: opts.cwd,
       stdio: opts.interactive ? "inherit" : ["pipe", "pipe", "pipe"],
+      ...(useGroup ? { detached: true } : {}),
     });
 
     let stdout = "";
     let stderr = "";
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let timedOut = false;
+    let settled = false;
+    const clearTimer = () => {
+      if (timer !== undefined) {
+        clearTimeout(timer);
+        timer = undefined;
+      }
+    };
+    const killTree = () => {
+      if (useGroup && child.pid !== undefined) {
+        try {
+          process.kill(-child.pid, "SIGKILL");
+          return;
+        } catch {
+          // Group already gone or not a group leader; fall back to the child.
+        }
+      }
+      try {
+        child.kill("SIGKILL");
+      } catch {
+        // Already exited.
+      }
+    };
+    const releaseChild = () => {
+      // A grandchild may still hold the pipes; never let them (or the child)
+      // keep the CLI's event loop alive after we have settled.
+      child.stdin?.destroy();
+      child.stdout?.destroy();
+      child.stderr?.destroy();
+      child.unref();
+    };
+    const settle = (code: number | null, signal: NodeJS.Signals | null) => {
+      if (settled) return;
+      settled = true;
+      clearTimer();
+      if (timedOut) releaseChild();
+      // A signal/unknown exit is not evidence that a vault mutation committed.
+      const result: PhantomExecResult = {
+        stdout,
+        stderr,
+        code: signal ? code || 1 : (code ?? 1),
+        completion: completionForClose(code, signal),
+        ...(signal ? { signal } : {}),
+        ...(timedOut ? { timedOut: true } : {}),
+      };
+      if (result.code !== 0 && !opts.allowFailure) {
+        reject(
+          new StackError(
+            "PHANTOM_EXEC_FAILED",
+            result.completion === "exited"
+              ? `phantom ${formatArgsForError(args)} failed (exit ${result.code}): ${stderr.trim() || stdout.trim()}`
+              : `phantom ${formatArgsForError(args)} did not complete (${result.completion}); result unconfirmed`,
+          ),
+        );
+        return;
+      }
+      resolvePromise(result);
+    };
+    if (hasTimeout) {
+      timer = setTimeout(() => {
+        timer = undefined;
+        timedOut = true;
+        killTree();
+        // Settle now: do not wait for `close`, which a grandchild can delay.
+        settle(null, "SIGKILL");
+      }, opts.timeoutMs);
+    }
 
     if (!opts.interactive) {
       child.stdout?.on("data", (chunk) => {
@@ -75,6 +183,9 @@ export async function exec(args: string[], opts: ExecOptions = {}): Promise<Phan
     }
 
     child.on("error", (err) => {
+      if (settled) return;
+      settled = true;
+      clearTimer();
       if ((err as NodeJS.ErrnoException).code === "ENOENT") {
         reject(new PhantomNotInstalledError());
         return;
@@ -82,28 +193,9 @@ export async function exec(args: string[], opts: ExecOptions = {}): Promise<Phan
       reject(err);
     });
 
-    child.on("close", (code, signal) => {
-      // A signal/unknown exit is not evidence that a vault mutation committed.
-      const result: PhantomExecResult = {
-        stdout,
-        stderr,
-        code: signal ? code || 1 : (code ?? 1),
-        completion: completionForClose(code, signal),
-        ...(signal ? { signal } : {}),
-      };
-      if (result.code !== 0 && !opts.allowFailure) {
-        reject(
-          new StackError(
-            "PHANTOM_EXEC_FAILED",
-            result.completion === "exited"
-              ? `phantom ${formatArgsForError(args)} failed (exit ${result.code}): ${stderr.trim() || stdout.trim()}`
-              : `phantom ${formatArgsForError(args)} did not complete (${result.completion}); result unconfirmed`,
-          ),
-        );
-        return;
-      }
-      resolvePromise(result);
-    });
+    // `close` waits for stdio to drain, so normal runs keep full output.
+    // A timed out run has already settled from the timer.
+    child.on("close", (code, signal) => settle(code, signal));
   });
 }
 
@@ -175,9 +267,17 @@ export async function removeSecret(
  * Secret names in the vault, from `phantom list --json` (never values). The
  * human `phantom list` output is a decorated table and is not parsed.
  */
-export async function listSecrets(cwd?: string): Promise<string[]> {
-  await assertPhantomInstalled();
-  const { stdout, code } = await exec(["list", "--json"], { cwd, allowFailure: true });
+export async function listSecrets(
+  cwd?: string,
+  opts?: { timeoutMs?: number; skipInstallCheck?: boolean },
+): Promise<string[]> {
+  if (!opts?.skipInstallCheck) await assertPhantomInstalled();
+  const { stdout, code, timedOut } = await exec(["list", "--json"], {
+    cwd,
+    allowFailure: true,
+    ...(opts?.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+  });
+  if (timedOut) throw new PhantomTimeoutError(["list"], opts?.timeoutMs);
   if (code !== 0) {
     throw new StackError(
       "PHANTOM_METADATA_UNAVAILABLE",
@@ -224,10 +324,21 @@ export async function listSecrets(cwd?: string): Promise<string[]> {
  * inventory cannot be read (Phantom missing, no .phantom.toml, unrecognized
  * output), so callers never report an unreadable vault as empty.
  */
-export async function countSecrets(cwd?: string): Promise<number | null> {
+export async function countSecrets(
+  cwd?: string,
+  opts?: { timeoutMs?: number; skipInstallCheck?: boolean },
+): Promise<number | null> {
   try {
-    if (!(await isPhantomInstalled())) return null;
-    return (await listSecrets(cwd)).length;
+    // skipInstallCheck lets `stack status` overlap this list with the version probe.
+    if (
+      !opts?.skipInstallCheck &&
+      !(await isPhantomInstalled(
+        opts?.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : undefined,
+      ))
+    ) {
+      return null;
+    }
+    return (await listSecrets(cwd, opts)).length;
   } catch {
     return null;
   }

package/src/stack-manifest.ts

@@ -0,0 +1,39 @@
+/** A distributable Stack component, rather than an installed companion tool. */
+export interface StackComponent {
+  readonly id: "core" | "cli" | "mcp" | "plugin";
+  readonly name: string;
+  readonly version: string;
+  readonly distribution: "npm" | "claude-code-plugin";
+}
+
+/**
+ * Source release metadata for ecosystem consumers. Versions do not establish
+ * registry publication or describe tools installed on the current machine.
+ * Additive fields may stay in v1; removals or renames require a schema bump.
+ */
+export interface StackManifest {
+  readonly schema_version: 1;
+  readonly kind: "ashlr-stack-manifest";
+  readonly components: readonly StackComponent[];
+}
+
+/**
+ * Import from @ashlr/stack-core. This JSON-safe export performs no filesystem,
+ * network, credential or subprocess access. Keep versions in sync on release;
+ * the fixture contract test checks the package and plugin metadata for drift.
+ */
+export const STACK_MANIFEST = Object.freeze({
+  schema_version: 1,
+  kind: "ashlr-stack-manifest",
+  components: Object.freeze([
+    Object.freeze({ id: "core", name: "@ashlr/stack-core", version: "0.3.1", distribution: "npm" }),
+    Object.freeze({ id: "cli", name: "@ashlr/stack", version: "0.3.1", distribution: "npm" }),
+    Object.freeze({ id: "mcp", name: "ashlr-stack-mcp", version: "0.3.1", distribution: "npm" }),
+    Object.freeze({
+      id: "plugin",
+      name: "stack",
+      version: "0.1.0",
+      distribution: "claude-code-plugin",
+    }),
+  ]),
+} as const) satisfies StackManifest;