create-kumiko-app 0.3.2

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "create-kumiko-app",
+  "version": "0.3.2",
+  "description": "`bun create kumiko-app <name>` — scaffold a new Kumiko app with an interactive feature picker.",
+  "license": "BUSL-1.1",
+  "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CosmicDriftGameStudio/kumiko-framework.git",
+    "directory": "packages/create-kumiko-app"
+  },
+  "bugs": {
+    "url": "https://github.com/CosmicDriftGameStudio/kumiko-framework/issues"
+  },
+  "homepage": "https://kumiko.rocks",
+  "type": "module",
+  "kumiko": {
+    "runtime": "dev"
+  },
+  "bin": {
+    "create-kumiko-app": "./bin/cli.ts"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "vendor:manifest": "bun run scripts/vendor-manifest.ts"
+  },
+  "dependencies": {
+    "@cosmicdrift/kumiko-dev-server": "0.76.0",
+    "@cosmicdrift/kumiko-framework": "0.76.0",
+    "@inquirer/prompts": "^7.4.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "files": [
+    "bin",
+    "src",
+    "feature-manifest.json",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/__tests__/cli.test.ts

@@ -0,0 +1,78 @@
+// CLI smoke: `bun create kumiko-app demo --yes` scaffolds an app whose
+// run-config.ts imports the recommended features. Full boot is out of
+// scope here (needs DB/Redis) — the gate is "scaffold succeeds, files
+// look right".
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { parseArgv, runCreate } from "../index";
+
+describe("create-kumiko-app CLI", () => {
+  let tmp: string;
+  let logs: string[];
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), "create-kumiko-app-"));
+    logs = [];
+  });
+  afterEach(() => rmSync(tmp, { recursive: true, force: true }));
+
+  test("--yes scaffolds the recommended stack", async () => {
+    const code = await runCreate({
+      name: "demo-app",
+      yes: true,
+      cwd: tmp,
+      log: (line) => logs.push(line),
+    });
+    expect(code).toBe(0);
+
+    const dest = join(tmp, "demo-app");
+    expect(existsSync(dest)).toBe(true);
+    expect(existsSync(join(dest, "package.json"))).toBe(true);
+    expect(existsSync(join(dest, "bin/main.ts"))).toBe(true);
+
+    const cfg = readFileSync(join(dest, "src/run-config.ts"), "utf-8");
+    // Picker-MVP recommended features land in run-config.
+    expect(cfg).toContain("createAuthEmailPasswordFeature");
+    expect(cfg).toContain("createUserFeature");
+    expect(cfg).toContain("createTenantFeature");
+    expect(cfg).toContain("createDeliveryFeature");
+    // mail-transport-smtp is opt-in (not recommended, no transitive require) — should NOT auto-mount.
+    expect(cfg).not.toContain("mailTransportSmtpFeature");
+  });
+
+  test("--print-manifest emits JSON, no name needed", async () => {
+    const code = await runCreate({
+      printManifest: true,
+      log: (line) => logs.push(line),
+    });
+    expect(code).toBe(0);
+    const json = JSON.parse(logs.join(""));
+    expect(Array.isArray(json)).toBe(true);
+    expect(json.length).toBeGreaterThan(0);
+  });
+
+  test("missing name prints usage + exits 1", async () => {
+    const code = await runCreate({ log: (line) => logs.push(line) });
+    expect(code).toBe(1);
+    expect(logs.join("\n")).toContain("Usage:");
+  });
+});
+
+describe("parseArgv", () => {
+  test("first positional is the app name", () => {
+    expect(parseArgv(["my-app"]).name).toBe("my-app");
+  });
+
+  test("--yes / -y flips yes flag", () => {
+    expect(parseArgv(["--yes"]).yes).toBe(true);
+    expect(parseArgv(["-y"]).yes).toBe(true);
+  });
+
+  test("--print-manifest works alone (no name)", () => {
+    const args = parseArgv(["--print-manifest"]);
+    expect(args.printManifest).toBe(true);
+    expect(args.name).toBeUndefined();
+  });
+});

package/src/__tests__/dep-resolver.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test } from "bun:test";
+import { resolveDeps } from "../dep-resolver";
+import type { Manifest } from "../manifest";
+
+const MANIFEST: Manifest = {
+  source: "test",
+  featureCount: 5,
+  features: [
+    {
+      name: "auth-email-password",
+      description: null,
+      requires: ["user", "tenant"],
+      optionalRequires: [],
+    },
+    { name: "user", description: null, requires: [], optionalRequires: [] },
+    { name: "tenant", description: null, requires: ["config"], optionalRequires: [] },
+    { name: "config", description: null, requires: [], optionalRequires: [] },
+    { name: "billing", description: null, requires: ["tenant"], optionalRequires: [] },
+  ],
+};
+
+describe("resolveDeps", () => {
+  test("transitive requires close (auth → user + tenant + config)", () => {
+    const result = resolveDeps(["auth-email-password"], MANIFEST);
+    expect(new Set(result.featureNames)).toEqual(
+      new Set(["auth-email-password", "user", "tenant", "config"]),
+    );
+    expect(new Set(result.autoAdded)).toEqual(new Set(["user", "tenant", "config"]));
+  });
+
+  test("dedupes overlapping deps", () => {
+    const result = resolveDeps(["auth-email-password", "billing"], MANIFEST);
+    expect(result.featureNames.length).toBe(new Set(result.featureNames).size);
+    expect(new Set(result.featureNames)).toContain("tenant");
+  });
+
+  test("explicit selection NOT counted as autoAdded", () => {
+    const result = resolveDeps(["user", "auth-email-password"], MANIFEST);
+    expect(result.autoAdded).not.toContain("user");
+    expect(result.autoAdded).toContain("tenant");
+  });
+
+  test("unknown feature throws (manifest bug)", () => {
+    expect(() => resolveDeps(["does-not-exist"], MANIFEST)).toThrow(/not in manifest/);
+  });
+});

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

@@ -0,0 +1,31 @@
+// Vendored manifest.json must match the source-of-truth in
+// samples/apps/use-all-bundled/feature-manifest.json. The picker reads
+// the vendored copy at runtime; a stale copy lets the picker show old
+// features or miss new ones. Refresh with `bun run vendor:manifest`.
+
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const VENDOR = resolve(HERE, "..", "..", "feature-manifest.json");
+const SOURCE = resolve(
+  HERE,
+  "..",
+  "..",
+  "..",
+  "..",
+  "samples",
+  "apps",
+  "use-all-bundled",
+  "feature-manifest.json",
+);
+
+describe("vendored manifest", () => {
+  test("byte-identical to samples/apps/use-all-bundled/feature-manifest.json", () => {
+    const vendor = readFileSync(VENDOR, "utf-8");
+    const source = readFileSync(SOURCE, "utf-8");
+    expect(vendor).toBe(source);
+  });
+});

package/src/__tests__/picker.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, test } from "bun:test";
+import { FEATURE_CONSTRUCTORS } from "../feature-constructors";
+import { loadManifest } from "../manifest";
+import { buildChoices } from "../picker";
+
+describe("buildChoices", () => {
+  const manifest = loadManifest();
+  const choices = buildChoices(manifest);
+
+  test("only emits features that have a constructor entry", () => {
+    for (const c of choices) {
+      expect(Object.hasOwn(FEATURE_CONSTRUCTORS, c.name)).toBe(true);
+    }
+  });
+
+  test("every MVP feature is represented (no silent drops)", () => {
+    const choiceNames = new Set(choices.map((c) => c.name));
+    for (const name of Object.keys(FEATURE_CONSTRUCTORS)) {
+      expect(choiceNames.has(name)).toBe(true);
+    }
+  });
+
+  test("recommended features land checked by default", () => {
+    const recommended = choices.filter((c) => c.recommended);
+    expect(recommended.length).toBeGreaterThan(0);
+    expect(recommended.map((c) => c.name)).toContain("auth-email-password");
+  });
+
+  test("category falls back to 'other' when uiHints absent", () => {
+    for (const c of choices) {
+      expect(typeof c.category).toBe("string");
+      expect(c.category.length).toBeGreaterThan(0);
+    }
+  });
+});

package/src/dep-resolver.ts

@@ -0,0 +1,44 @@
+// Closes a feature set under `requires` (transitive hard dependencies).
+// The picker only asks about explicit selections; this resolver folds in
+// every dep so the scaffolded run-config.ts is bootable as-is.
+//
+// Output is the deterministic set of feature names, in the order the
+// caller can hand to scaffoldApp. Cycles (none in practice) self-terminate
+// via the visited-set; unknown deps (a manifest feature requires X but X
+// isn't in the manifest) throw — that's a manifest bug worth surfacing.
+
+import type { Manifest, ManifestFeatureEntry } from "./manifest";
+
+export type DepResolutionResult = {
+  /** Selected + transitively required features, in stable scaffold order. */
+  readonly featureNames: readonly string[];
+  /** Features added implicitly via requires (not in the original selection). */
+  readonly autoAdded: readonly string[];
+};
+
+export function resolveDeps(selected: readonly string[], manifest: Manifest): DepResolutionResult {
+  const byName = new Map<string, ManifestFeatureEntry>(manifest.features.map((f) => [f.name, f]));
+  const visited = new Set<string>();
+  const autoAdded = new Set<string>();
+  const selectedSet = new Set(selected);
+
+  function visit(name: string): void {
+    if (visited.has(name)) return;
+    visited.add(name);
+    const entry = byName.get(name);
+    if (!entry) {
+      throw new Error(
+        `resolveDeps: feature "${name}" not in manifest (referenced as require/selection)`,
+      );
+    }
+    if (!selectedSet.has(name)) autoAdded.add(name);
+    for (const dep of entry.requires) visit(dep);
+  }
+
+  for (const name of selected) visit(name);
+
+  return {
+    featureNames: [...visited],
+    autoAdded: [...autoAdded],
+  };
+}

package/src/feature-constructors.ts

@@ -0,0 +1,238 @@
+// Static map: feature.name (from the manifest) → ScaffoldFeatureEntry that
+// scaffoldApp consumes to render run-config.ts imports + APP_FEATURES.
+//
+// One entry per bundled feature whose constructor takes zero required args
+// (or only opts with defaults). Features requiring caller-supplied
+// transports/providers (channel-email, channel-push, subscription-stripe,
+// subscription-mollie, file-provider-s3, managed-pages, tier-engine) are
+// intentionally absent — the picker hides them, the user wires them by
+// hand after scaffold.
+//
+// Naming inconsistency is intentional and historical: most features expose
+// `create<Pascal>Feature` factories, a handful export the FeatureDefinition
+// object directly. The callExpression captures that: `()` for factories,
+// bare name for objects.
+
+import type { ScaffoldFeatureEntry } from "@cosmicdrift/kumiko-dev-server";
+
+export const FEATURE_CONSTRUCTORS: Readonly<Record<string, ScaffoldFeatureEntry>> = {
+  // --- Identity ---
+  tenant: {
+    name: "tenant",
+    importPath: "@cosmicdrift/kumiko-bundled-features/tenant",
+    exportName: "createTenantFeature",
+    callExpression: "createTenantFeature()",
+  },
+  user: {
+    name: "user",
+    importPath: "@cosmicdrift/kumiko-bundled-features/user",
+    exportName: "createUserFeature",
+    callExpression: "createUserFeature()",
+  },
+  sessions: {
+    name: "sessions",
+    importPath: "@cosmicdrift/kumiko-bundled-features/sessions",
+    exportName: "createSessionsFeature",
+    callExpression: "createSessionsFeature()",
+  },
+  "auth-email-password": {
+    name: "auth-email-password",
+    importPath: "@cosmicdrift/kumiko-bundled-features/auth-email-password",
+    exportName: "createAuthEmailPasswordFeature",
+    callExpression: "createAuthEmailPasswordFeature()",
+  },
+  "user-profile": {
+    name: "user-profile",
+    importPath: "@cosmicdrift/kumiko-bundled-features/user-profile",
+    exportName: "createUserProfileFeature",
+    callExpression: "createUserProfileFeature()",
+  },
+
+  // --- Infrastructure ---
+  config: {
+    name: "config",
+    importPath: "@cosmicdrift/kumiko-bundled-features/config",
+    exportName: "createConfigFeature",
+    callExpression: "createConfigFeature()",
+  },
+  secrets: {
+    name: "secrets",
+    importPath: "@cosmicdrift/kumiko-bundled-features/secrets",
+    exportName: "createSecretsFeature",
+    callExpression: "createSecretsFeature()",
+  },
+  "cap-counter": {
+    name: "cap-counter",
+    importPath: "@cosmicdrift/kumiko-bundled-features/cap-counter",
+    exportName: "capCounterFeature",
+    callExpression: "capCounterFeature",
+  },
+  "step-dispatcher": {
+    name: "step-dispatcher",
+    importPath: "@cosmicdrift/kumiko-bundled-features/step-dispatcher",
+    exportName: "createStepDispatcherFeature",
+    callExpression: "createStepDispatcherFeature()",
+  },
+
+  // --- Storage ---
+  files: {
+    name: "files",
+    importPath: "@cosmicdrift/kumiko-bundled-features/files",
+    exportName: "createFilesFeature",
+    callExpression: "createFilesFeature()",
+  },
+  "file-foundation": {
+    name: "file-foundation",
+    importPath: "@cosmicdrift/kumiko-bundled-features/file-foundation",
+    exportName: "fileFoundationFeature",
+    callExpression: "fileFoundationFeature",
+  },
+  "file-provider-inmemory": {
+    name: "file-provider-inmemory",
+    importPath: "@cosmicdrift/kumiko-bundled-features/file-provider-inmemory",
+    exportName: "fileProviderInMemoryFeature",
+    callExpression: "fileProviderInMemoryFeature",
+  },
+
+  // --- Notifications ---
+  delivery: {
+    name: "delivery",
+    importPath: "@cosmicdrift/kumiko-bundled-features/delivery",
+    exportName: "createDeliveryFeature",
+    callExpression: "createDeliveryFeature()",
+  },
+  "mail-foundation": {
+    name: "mail-foundation",
+    importPath: "@cosmicdrift/kumiko-bundled-features/mail-foundation",
+    exportName: "mailFoundationFeature",
+    callExpression: "mailFoundationFeature",
+  },
+  "mail-transport-inmemory": {
+    name: "mail-transport-inmemory",
+    importPath: "@cosmicdrift/kumiko-bundled-features/mail-transport-inmemory",
+    exportName: "mailTransportInMemoryFeature",
+    callExpression: "mailTransportInMemoryFeature",
+  },
+  "mail-transport-smtp": {
+    name: "mail-transport-smtp",
+    importPath: "@cosmicdrift/kumiko-bundled-features/mail-transport-smtp",
+    exportName: "mailTransportSmtpFeature",
+    callExpression: "mailTransportSmtpFeature",
+  },
+  "channel-in-app": {
+    name: "channel-in-app",
+    importPath: "@cosmicdrift/kumiko-bundled-features/channel-in-app",
+    exportName: "createChannelInAppFeature",
+    callExpression: "createChannelInAppFeature()",
+  },
+  "renderer-foundation": {
+    name: "renderer-foundation",
+    importPath: "@cosmicdrift/kumiko-bundled-features/renderer-foundation",
+    exportName: "createRendererFoundationFeature",
+    callExpression: "createRendererFoundationFeature()",
+  },
+  "renderer-simple": {
+    name: "renderer-simple",
+    importPath: "@cosmicdrift/kumiko-bundled-features/renderer-simple",
+    exportName: "createRendererSimpleFeature",
+    callExpression: "createRendererSimpleFeature()",
+  },
+  "template-resolver": {
+    name: "template-resolver",
+    importPath: "@cosmicdrift/kumiko-bundled-features/template-resolver",
+    exportName: "createTemplateResolverFeature",
+    callExpression: "createTemplateResolverFeature()",
+  },
+
+  // --- Billing ---
+  "billing-foundation": {
+    name: "billing-foundation",
+    importPath: "@cosmicdrift/kumiko-bundled-features/billing-foundation",
+    exportName: "billingFoundationFeature",
+    callExpression: "billingFoundationFeature",
+  },
+
+  // --- Compliance ---
+  audit: {
+    name: "audit",
+    importPath: "@cosmicdrift/kumiko-bundled-features/audit",
+    exportName: "createAuditFeature",
+    callExpression: "createAuditFeature()",
+  },
+  "compliance-profiles": {
+    name: "compliance-profiles",
+    importPath: "@cosmicdrift/kumiko-bundled-features/compliance-profiles",
+    exportName: "createComplianceProfilesFeature",
+    callExpression: "createComplianceProfilesFeature()",
+  },
+  "data-retention": {
+    name: "data-retention",
+    importPath: "@cosmicdrift/kumiko-bundled-features/data-retention",
+    exportName: "createDataRetentionFeature",
+    callExpression: "createDataRetentionFeature()",
+  },
+  "user-data-rights": {
+    name: "user-data-rights",
+    importPath: "@cosmicdrift/kumiko-bundled-features/user-data-rights",
+    exportName: "createUserDataRightsFeature",
+    callExpression: "createUserDataRightsFeature()",
+  },
+
+  // --- Operations ---
+  "feature-toggles": {
+    name: "feature-toggles",
+    importPath: "@cosmicdrift/kumiko-bundled-features/feature-toggles",
+    exportName: "createFeatureTogglesFeature",
+    callExpression: "createFeatureTogglesFeature()",
+  },
+  jobs: {
+    name: "jobs",
+    importPath: "@cosmicdrift/kumiko-bundled-features/jobs",
+    exportName: "createJobsFeature",
+    callExpression: "createJobsFeature()",
+  },
+  "rate-limiting": {
+    name: "rate-limiting",
+    importPath: "@cosmicdrift/kumiko-bundled-features/rate-limiting",
+    exportName: "createRateLimitingFeature",
+    callExpression: "createRateLimitingFeature()",
+  },
+  readiness: {
+    name: "readiness",
+    importPath: "@cosmicdrift/kumiko-bundled-features/readiness",
+    exportName: "readinessFeature",
+    callExpression: "readinessFeature",
+  },
+
+  // --- Content ---
+  "text-content": {
+    name: "text-content",
+    importPath: "@cosmicdrift/kumiko-bundled-features/text-content",
+    exportName: "createTextContentFeature",
+    callExpression: "createTextContentFeature()",
+  },
+  "legal-pages": {
+    name: "legal-pages",
+    importPath: "@cosmicdrift/kumiko-bundled-features/legal-pages",
+    exportName: "createLegalPagesFeature",
+    callExpression: "createLegalPagesFeature()",
+  },
+
+  // --- Data ---
+  tags: {
+    name: "tags",
+    importPath: "@cosmicdrift/kumiko-bundled-features/tags",
+    exportName: "tagsFeature",
+    callExpression: "tagsFeature",
+  },
+  "custom-fields": {
+    name: "custom-fields",
+    importPath: "@cosmicdrift/kumiko-bundled-features/custom-fields",
+    exportName: "customFieldsFeature",
+    callExpression: "customFieldsFeature",
+  },
+};
+
+export function isPickable(featureName: string): boolean {
+  return Object.hasOwn(FEATURE_CONSTRUCTORS, featureName);
+}

package/src/index.ts

@@ -0,0 +1,92 @@
+// `bun create kumiko-app <name>` → bunx create-kumiko-app <name>.
+//
+// Flow: parse args → load vendored manifest → run picker (unless
+// --print-manifest / --yes) → resolve deps → map to scaffold entries →
+// scaffoldApp() → print next-steps.
+
+import { type ScaffoldFeatureEntry, scaffoldApp } from "@cosmicdrift/kumiko-dev-server";
+import { resolveDeps } from "./dep-resolver";
+import { FEATURE_CONSTRUCTORS } from "./feature-constructors";
+import { loadManifest, type Manifest } from "./manifest";
+import { buildChoices, runPicker } from "./picker";
+
+export type CliArgs = {
+  /** App name (kebab-case). Required for `scaffold` mode. */
+  readonly name?: string;
+  /** Print the picker choices as JSON and exit (CI snapshot test). */
+  readonly printManifest?: boolean;
+  /** Skip the interactive picker, take every `recommended:true` feature. */
+  readonly yes?: boolean;
+  /** Override cwd for scaffoldApp (mostly for the smoke test). */
+  readonly cwd?: string;
+  /** Override stdout sink (default: console.log). */
+  readonly log?: (line: string) => void;
+};
+
+export async function runCreate(args: CliArgs): Promise<number> {
+  const log = args.log ?? ((line) => console.log(line));
+  const manifest = loadManifest();
+
+  if (args.printManifest) {
+    log(JSON.stringify(buildChoices(manifest), null, 2));
+    return 0;
+  }
+
+  if (!args.name) {
+    log("Usage: bun create kumiko-app <name> [--yes] [--print-manifest]");
+    return 1;
+  }
+
+  const selected = args.yes ? defaultSelection(manifest) : await runPicker(manifest);
+  if (selected.length === 0) {
+    log("Keine Features gewählt — Abbruch.");
+    return 1;
+  }
+
+  const resolved = resolveDeps(selected, manifest);
+  const features = resolved.featureNames
+    .map((name) => FEATURE_CONSTRUCTORS[name])
+    .filter((entry): entry is ScaffoldFeatureEntry => entry !== undefined);
+
+  // config/user/tenant/auth-email-password are auto-mounted by
+  // composeFeatures(includeBundled:true) at boot — only log auto-adds
+  // that actually land in the explicit APP_FEATURES list.
+  const reportableAutoAdds = resolved.autoAdded.filter((n) =>
+    Object.hasOwn(FEATURE_CONSTRUCTORS, n),
+  );
+  if (reportableAutoAdds.length > 0) {
+    log(`Auto-included via requires: ${reportableAutoAdds.join(", ")}`);
+  }
+
+  const result = scaffoldApp({
+    name: args.name,
+    cwd: args.cwd,
+    features,
+  });
+
+  log("");
+  log(`✓ ${result.appName} scaffolded → ${result.destination}`);
+  log("");
+  log("Nächste Schritte:");
+  log(`  cd ${args.name}`);
+  log("  bun install");
+  log("  cp .env.example .env  # edit JWT_SECRET + KUMIKO_SECRETS_MASTER_KEY_V1");
+  log("  bun run boot");
+  return 0;
+}
+
+function defaultSelection(manifest: Manifest): readonly string[] {
+  return buildChoices(manifest)
+    .filter((c) => c.recommended)
+    .map((c) => c.name);
+}
+
+export function parseArgv(argv: readonly string[]): CliArgs {
+  const out: { -readonly [K in keyof CliArgs]?: CliArgs[K] } = {};
+  for (const arg of argv) {
+    if (arg === "--print-manifest") out.printManifest = true;
+    else if (arg === "--yes" || arg === "-y") out.yes = true;
+    else if (!arg.startsWith("-") && out.name === undefined) out.name = arg;
+  }
+  return out;
+}

package/src/manifest.ts

@@ -0,0 +1,59 @@
+// Loads the vendored feature-manifest.json (copied from
+// samples/apps/use-all-bundled by scripts/vendor-manifest.ts) at runtime.
+// The published package ships the JSON next to package.json so the picker
+// works without network access — the source-of-truth at build time is the
+// sample-app's manifest, kept in sync via a CI drift-test.
+
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export type ManifestUiHintOption =
+  | {
+      readonly key: string;
+      readonly label: string;
+      readonly type: "boolean";
+      readonly default: boolean;
+    }
+  | {
+      readonly key: string;
+      readonly label: string;
+      readonly type: "select";
+      readonly options: readonly string[];
+      readonly default: string;
+    }
+  | {
+      readonly key: string;
+      readonly label: string;
+      readonly type: "text";
+      readonly default?: string;
+    };
+
+export type ManifestUiHints = {
+  readonly displayLabel?: string;
+  readonly category?: string;
+  readonly recommended?: boolean;
+  readonly configurableOptions?: readonly ManifestUiHintOption[];
+};
+
+export type ManifestFeatureEntry = {
+  readonly name: string;
+  readonly description: string | null;
+  readonly requires: readonly string[];
+  readonly optionalRequires: readonly string[];
+  readonly uiHints?: ManifestUiHints;
+};
+
+export type Manifest = {
+  readonly source: string;
+  readonly featureCount: number;
+  readonly features: readonly ManifestFeatureEntry[];
+};
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+export function loadManifest(): Manifest {
+  const path = resolve(HERE, "..", "feature-manifest.json");
+  const raw = readFileSync(path, "utf-8");
+  return JSON.parse(raw) as Manifest;
+}