@stardeck-customer-apps/compose 0.1.0 → 0.2.0

package/SKILL.md

@@ -28,12 +28,30 @@ it manually — `npx stardeck-compose` before `next dev` / `next build` / your
 typecheck — after changing any `module.json`. The `predev` / `prebuild` /
 `pretypecheck` / `pretest` wiring that makes this automatic has not landed yet.
 
-**Caveat: compose has no platform database.** It composes from `module.json`
-alone, so Module data-store bindings resolve to none (`module-datastores.gen.ts`
-comes out empty) and every Module's registry version reads `unreleased`. An app
-whose platform-side rail resolved real data-store bindings must not run compose
-until the consumer wiring supplies them — compose would otherwise overwrite the
-bindings with nothing.
+Needs `typescript` >=5 <7 (it parses your route entries with the compiler API).
+
+**compose has no platform database.** The two facts the platform rail reads from
+one — the data stores connected to the app, and each Module's install row — come
+from `apps/web/stardeck.compose.json` instead:
+
+```jsonc
+{
+  "connectedStores": [
+    { "storeId": "ds_123", "slug": "media", "bindingKey": null, "accessLevel": "write" }
+  ],
+  "installs": {
+    "pos": { "installedVersion": "7.49.0", "datastoreBindings": { "media": "ds_123" } }
+  }
+}
+```
+
+The platform writes it at deploy time; write it by hand to compose locally
+against real stores. It is an input, not a result — compose still resolves and
+validates the bindings itself. Without the file, `module-datastores.gen.ts`
+composes empty and every registry version reads `unreleased`, so an app with
+bound stores must not compose without it. A malformed file is a hard error, never
+a silent fallback. It holds deployment facts: gitignore it (`apps/web/.gitignore`:
+`stardeck.compose.json`).
 
 - `--enabled` — comma-separated **feature** Module names. Unset composes every
   installed Module. Library and contract Modules are always composed. A name
@@ -57,3 +75,12 @@ bindings with nothing.
 - `@stardeck-customer-apps/compose/runtime` exports `isModuleEnabledByList`,
   the single enablement rule, and imports nothing — it is safe in client
   components.
+
+## Generated ignore list
+
+After each run compose rewrites `apps/web/src/app/.gitignore` with one entry per
+stub it emits — stubs are scattered one-per-route and cannot be globbed. Commit
+that file: it is deterministic output, and compose rewrites it only when the set
+of stubs changes, so an unchanged compose leaves `git status` clean. It does not
+list the five `src/*.gen.ts`; a static `src/*.gen.ts` line in `apps/web/.gitignore`
+covers those. Compose refuses to touch the file if line 1 is not its own header.

package/dist/cli.js

@@ -1886,6 +1886,9 @@ var MODULE_INIT_SERVER_GEN_PATH = `${APP_WEB_PREFIX}src/module-init.server.gen.t
 var MODULES_GEN_PATH = `${APP_WEB_PREFIX}src/modules.gen.ts`;
 var APP_EXTENSIONS_PATH = `${APP_WEB_PREFIX}src/lib/modules/app-extensions.ts`;
 
+// src/cli.ts
+var import_typescript5 = __toESM(require("typescript"));
+
 // src/index.ts
 var import_node_child_process2 = require("child_process");
 var import_node_fs2 = __toESM(require("fs"));
@@ -3546,6 +3549,7 @@ function planCompositionArtifacts(input) {
       endpointStubs: stubs.endpointStubs,
       routeStubs: stubs.routeStubs,
       writes,
+      desiredPaths: [...desired.keys()].sort(compareNames2),
       deletes
     }
   };
@@ -5116,6 +5120,7 @@ async function reconcileCompositionArtifacts(context, options = {}) {
     registryPath: planned.plan.registryPath,
     writePaths: planned.plan.writes.map((w) => w.path),
     deletePaths: planned.plan.deletes,
+    artifactPaths: planned.plan.desiredPaths,
     changed,
     composedModules: composedNames,
     excludedModules
@@ -5125,7 +5130,89 @@ var HOME_I18N_SUBSTRATE_DIR = `${APP_PACKAGE_DIR}/src/lib/i18n/substrate`;
 var HOME_I18N_MESSAGES_DIR = `${APP_PACKAGE_DIR}/src/lib/i18n/messages`;
 
 // src/index.ts
+var import_zod9 = require("zod");
 var MODULES_DIR2 = MODULES_SANDBOX_DIR;
+var COMPOSE_INPUTS_PATH = "apps/web/stardeck.compose.json";
+var composeInputsSchema = import_zod9.z.strictObject({
+  connectedStores: import_zod9.z.array(
+    import_zod9.z.strictObject({
+      storeId: import_zod9.z.string().min(1),
+      slug: import_zod9.z.string().min(1),
+      bindingKey: import_zod9.z.string().min(1).nullish(),
+      accessLevel: import_zod9.z.enum(["read", "write", "admin"])
+    })
+  ).default([]),
+  installs: import_zod9.z.record(
+    import_zod9.z.string(),
+    import_zod9.z.strictObject({
+      installedVersion: import_zod9.z.string().min(1),
+      datastoreBindings: import_zod9.z.record(import_zod9.z.string(), import_zod9.z.string()).nullish()
+    })
+  ).default({})
+});
+function readComposeInputs(cwd) {
+  const file = import_node_path2.default.join(cwd, COMPOSE_INPUTS_PATH);
+  if (!import_node_fs2.default.existsSync(file)) return { connectedStores: [], installs: {} };
+  let raw;
+  try {
+    raw = JSON.parse(import_node_fs2.default.readFileSync(file, "utf8"));
+  } catch (error) {
+    throw new Error(
+      `[compose] ${file} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  const parsed = composeInputsSchema.safeParse(raw);
+  if (!parsed.success) {
+    const issues = parsed.error.issues.map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`).join("; ");
+    throw new Error(`[compose] ${file} is invalid: ${issues}`);
+  }
+  return {
+    connectedStores: parsed.data.connectedStores.map((store) => ({
+      storeId: store.storeId,
+      slug: store.slug,
+      bindingKey: store.bindingKey ?? null,
+      accessLevel: store.accessLevel
+    })),
+    installs: parsed.data.installs
+  };
+}
+function assertSupportedTypescript(versionMajorMinor) {
+  const major = Number.parseInt(versionMajorMinor.split(".")[0] ?? "", 10);
+  if (!Number.isInteger(major) || major < 5 || major >= 7) {
+    throw new Error(`[compose] typescript ${versionMajorMinor} is not supported (need >=5 <7)`);
+  }
+}
+var APP_DIR_PREFIX2 = "apps/web/src/app/";
+var STUB_GITIGNORE_PATH = "apps/web/src/app/.gitignore";
+var STUB_GITIGNORE_HEADER = "# Generated by stardeck-compose \u2014 Module-rail stubs are build outputs; do not edit or commit them.";
+function escapeGitignore(pattern) {
+  const escaped = pattern.replace(/[\\[\]*?]/g, (char) => `\\${char}`);
+  return /^[#!]/.test(escaped) ? `\\${escaped}` : escaped;
+}
+function stubGitignoreEntries(artifactPaths) {
+  return artifactPaths.filter((artifact) => artifact.startsWith(APP_DIR_PREFIX2)).map((artifact) => escapeGitignore(`/${artifact.slice(APP_DIR_PREFIX2.length)}`)).sort();
+}
+function writeStubGitignore(cwd, artifactPaths) {
+  const entries = stubGitignoreEntries(artifactPaths);
+  const content = [STUB_GITIGNORE_HEADER, ...entries].join("\n") + "\n";
+  const file = import_node_path2.default.join(cwd, STUB_GITIGNORE_PATH);
+  const existing = import_node_fs2.default.existsSync(file) ? import_node_fs2.default.readFileSync(file, "utf8") : null;
+  if (existing !== content) {
+    import_node_fs2.default.mkdirSync(import_node_path2.default.dirname(file), { recursive: true });
+    import_node_fs2.default.writeFileSync(file, content);
+  }
+  return entries.length;
+}
+function assertStubGitignoreOwned(cwd) {
+  const file = import_node_path2.default.join(cwd, STUB_GITIGNORE_PATH);
+  if (!import_node_fs2.default.existsSync(file)) return;
+  const firstLine = import_node_fs2.default.readFileSync(file, "utf8").split("\n", 1)[0] ?? "";
+  if (firstLine !== STUB_GITIGNORE_HEADER) {
+    throw new Error(
+      `[compose] refusing to overwrite ${STUB_GITIGNORE_PATH}: it is not compose-generated (line 1 is not the generated header)`
+    );
+  }
+}
 function assertAppRoot(cwd) {
   const modulesPath = import_node_path2.default.join(cwd, MODULES_DIR2);
   if (!import_node_fs2.default.existsSync(modulesPath)) {
@@ -5210,12 +5297,14 @@ function removeDir(absolute) {
 }
 async function compose(options) {
   assertAppRoot(options.cwd);
+  assertStubGitignoreOwned(options.cwd);
+  const inputs = readComposeInputs(options.cwd);
   if (options.prune) assertModuleTreeClean(options.cwd);
   const sandbox = localFsSandbox(options.cwd);
   const deps = {
     sandbox,
-    getModuleInstall: async () => null,
-    listDatabaseStoresForProject: async () => []
+    getModuleInstall: async (_db, _projectId, moduleName) => inputs.installs[moduleName] ?? null,
+    listDatabaseStoresForProject: async () => inputs.connectedStores
   };
   const context = {
     db: {},
@@ -5234,6 +5323,7 @@ async function compose(options) {
   const result = await reconcileCompositionArtifacts(context, {
     enabledModulesRaw: options.enabled
   });
+  const gitignoreEntries = options.enabled ? null : writeStubGitignore(options.cwd, result.artifactPaths);
   let pruned = 0;
   if (options.prune) {
     for (const name of result.excludedModules) {
@@ -5250,12 +5340,14 @@ async function compose(options) {
     excludedModules: result.excludedModules,
     writes: result.writePaths.length,
     deletes: result.deletePaths.length,
-    pruned
+    pruned,
+    gitignoreEntries
   };
 }
 
 // src/cli.ts
 async function main() {
+  assertSupportedTypescript(import_typescript5.default.versionMajorMinor);
   const { values } = (0, import_node_util.parseArgs)({
     options: {
       enabled: { type: "string" },
@@ -5276,7 +5368,7 @@ async function main() {
     prune: values.prune
   });
   console.log(
-    `[compose] modules=${result.composedModules.join(",") || "none"} excluded=${result.excludedModules.join(",") || "none"} writes=${result.writes} deletes=${result.deletes} pruned=${result.pruned}`
+    `[compose] modules=${result.composedModules.join(",") || "none"} excluded=${result.excludedModules.join(",") || "none"} writes=${result.writes} deletes=${result.deletes} pruned=${result.pruned} gitignore=${result.gitignoreEntries ?? "kept"} stub paths`
   );
 }
 main().catch((error) => {

package/dist/index.d.mts

@@ -1,3 +1,13 @@
+import { z } from 'zod';
+
+/** A data store connected to a project, as the composition rail consumes it. */
+type ConnectedStore = {
+    storeId: string;
+    slug: string;
+    bindingKey: string | null;
+    accessLevel: "read" | "write" | "admin";
+};
+
 interface ComposeOptions {
     /** Repo root of the customer app (the directory holding `apps/web`). */
     cwd: string;
@@ -16,11 +26,54 @@ interface ComposeResult {
     deletes: number;
     /** Directories removed by `prune` (excluded Modules + orphaned enhancements). */
     pruned: number;
+    /** Stub paths listed in the generated `src/app/.gitignore`. */
+    /** Null when a partial (`--enabled`) compose left the committed list untouched. */
+    gitignoreEntries: number | null;
 }
+/** Repo-relative inputs file: the platform's two database reads, as JSON. */
+declare const COMPOSE_INPUTS_PATH = "apps/web/stardeck.compose.json";
+declare const composeInputsSchema: z.ZodObject<{
+    connectedStores: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        storeId: z.ZodString;
+        slug: z.ZodString;
+        bindingKey: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        accessLevel: z.ZodEnum<{
+            read: "read";
+            write: "write";
+            admin: "admin";
+        }>;
+    }, z.core.$strict>>>;
+    installs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        installedVersion: z.ZodString;
+        datastoreBindings: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodString>>>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+type ComposeInstall = z.infer<typeof composeInputsSchema>["installs"][string];
+interface ComposeInputs {
+    connectedStores: ConnectedStore[];
+    installs: Record<string, ComposeInstall>;
+}
+/**
+ * The platform rail resolves data-store bindings and installed versions from
+ * its database. A standalone app has none, so compose reads the same two facts
+ * from a file the platform writes at deploy time (or a developer writes by
+ * hand). Absent file: no stores, every version `unreleased`. A malformed file
+ * is fatal — silently composing empty bindings is how an app loses its stores.
+ */
+declare function readComposeInputs(cwd: string): ComposeInputs;
+/** Compose needs the TypeScript API the emitters parse route entries with. */
+declare function assertSupportedTypescript(versionMajorMinor: string): void;
+/**
+ * gitignore patterns are fnmatch, so a Next.js path segment is not a literal:
+ * `[lang]` is a character class and `/[lang]/…/page.tsx` ignores nothing.
+ * Escapes every metacharacter, plus a leading `#`/`!` (the caller's `/` prefix
+ * rules those out today; a total helper keeps it that way).
+ */
+declare function escapeGitignore(pattern: string): string;
 /**
  * Regenerate the Module-rail artifacts (the five `src/*.gen.ts` files and every
  * route/endpoint stub under `src/app`) for the app rooted at `options.cwd`.
  */
 declare function compose(options: ComposeOptions): Promise<ComposeResult>;
 
-export { type ComposeOptions, type ComposeResult, compose };
+export { COMPOSE_INPUTS_PATH, type ComposeInputs, type ComposeOptions, type ComposeResult, assertSupportedTypescript, compose, escapeGitignore, readComposeInputs };

package/dist/index.d.ts

@@ -1,3 +1,13 @@
+import { z } from 'zod';
+
+/** A data store connected to a project, as the composition rail consumes it. */
+type ConnectedStore = {
+    storeId: string;
+    slug: string;
+    bindingKey: string | null;
+    accessLevel: "read" | "write" | "admin";
+};
+
 interface ComposeOptions {
     /** Repo root of the customer app (the directory holding `apps/web`). */
     cwd: string;
@@ -16,11 +26,54 @@ interface ComposeResult {
     deletes: number;
     /** Directories removed by `prune` (excluded Modules + orphaned enhancements). */
     pruned: number;
+    /** Stub paths listed in the generated `src/app/.gitignore`. */
+    /** Null when a partial (`--enabled`) compose left the committed list untouched. */
+    gitignoreEntries: number | null;
 }
+/** Repo-relative inputs file: the platform's two database reads, as JSON. */
+declare const COMPOSE_INPUTS_PATH = "apps/web/stardeck.compose.json";
+declare const composeInputsSchema: z.ZodObject<{
+    connectedStores: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        storeId: z.ZodString;
+        slug: z.ZodString;
+        bindingKey: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        accessLevel: z.ZodEnum<{
+            read: "read";
+            write: "write";
+            admin: "admin";
+        }>;
+    }, z.core.$strict>>>;
+    installs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        installedVersion: z.ZodString;
+        datastoreBindings: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodString>>>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+type ComposeInstall = z.infer<typeof composeInputsSchema>["installs"][string];
+interface ComposeInputs {
+    connectedStores: ConnectedStore[];
+    installs: Record<string, ComposeInstall>;
+}
+/**
+ * The platform rail resolves data-store bindings and installed versions from
+ * its database. A standalone app has none, so compose reads the same two facts
+ * from a file the platform writes at deploy time (or a developer writes by
+ * hand). Absent file: no stores, every version `unreleased`. A malformed file
+ * is fatal — silently composing empty bindings is how an app loses its stores.
+ */
+declare function readComposeInputs(cwd: string): ComposeInputs;
+/** Compose needs the TypeScript API the emitters parse route entries with. */
+declare function assertSupportedTypescript(versionMajorMinor: string): void;
+/**
+ * gitignore patterns are fnmatch, so a Next.js path segment is not a literal:
+ * `[lang]` is a character class and `/[lang]/…/page.tsx` ignores nothing.
+ * Escapes every metacharacter, plus a leading `#`/`!` (the caller's `/` prefix
+ * rules those out today; a total helper keeps it that way).
+ */
+declare function escapeGitignore(pattern: string): string;
 /**
  * Regenerate the Module-rail artifacts (the five `src/*.gen.ts` files and every
  * route/endpoint stub under `src/app`) for the app rooted at `options.cwd`.
  */
 declare function compose(options: ComposeOptions): Promise<ComposeResult>;
 
-export { type ComposeOptions, type ComposeResult, compose };
+export { COMPOSE_INPUTS_PATH, type ComposeInputs, type ComposeOptions, type ComposeResult, assertSupportedTypescript, compose, escapeGitignore, readComposeInputs };

package/dist/index.js

@@ -30,7 +30,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  compose: () => compose
+  COMPOSE_INPUTS_PATH: () => COMPOSE_INPUTS_PATH,
+  assertSupportedTypescript: () => assertSupportedTypescript,
+  compose: () => compose,
+  escapeGitignore: () => escapeGitignore,
+  readComposeInputs: () => readComposeInputs
 });
 module.exports = __toCommonJS(index_exports);
 var import_node_child_process2 = require("child_process");
@@ -3554,6 +3558,7 @@ function planCompositionArtifacts(input) {
       endpointStubs: stubs.endpointStubs,
       routeStubs: stubs.routeStubs,
       writes,
+      desiredPaths: [...desired.keys()].sort(compareNames2),
       deletes
     }
   };
@@ -5124,6 +5129,7 @@ async function reconcileCompositionArtifacts(context, options = {}) {
     registryPath: planned.plan.registryPath,
     writePaths: planned.plan.writes.map((w) => w.path),
     deletePaths: planned.plan.deletes,
+    artifactPaths: planned.plan.desiredPaths,
     changed,
     composedModules: composedNames,
     excludedModules
@@ -5133,7 +5139,89 @@ var HOME_I18N_SUBSTRATE_DIR = `${APP_PACKAGE_DIR}/src/lib/i18n/substrate`;
 var HOME_I18N_MESSAGES_DIR = `${APP_PACKAGE_DIR}/src/lib/i18n/messages`;
 
 // src/index.ts
+var import_zod9 = require("zod");
 var MODULES_DIR2 = MODULES_SANDBOX_DIR;
+var COMPOSE_INPUTS_PATH = "apps/web/stardeck.compose.json";
+var composeInputsSchema = import_zod9.z.strictObject({
+  connectedStores: import_zod9.z.array(
+    import_zod9.z.strictObject({
+      storeId: import_zod9.z.string().min(1),
+      slug: import_zod9.z.string().min(1),
+      bindingKey: import_zod9.z.string().min(1).nullish(),
+      accessLevel: import_zod9.z.enum(["read", "write", "admin"])
+    })
+  ).default([]),
+  installs: import_zod9.z.record(
+    import_zod9.z.string(),
+    import_zod9.z.strictObject({
+      installedVersion: import_zod9.z.string().min(1),
+      datastoreBindings: import_zod9.z.record(import_zod9.z.string(), import_zod9.z.string()).nullish()
+    })
+  ).default({})
+});
+function readComposeInputs(cwd) {
+  const file = import_node_path2.default.join(cwd, COMPOSE_INPUTS_PATH);
+  if (!import_node_fs2.default.existsSync(file)) return { connectedStores: [], installs: {} };
+  let raw;
+  try {
+    raw = JSON.parse(import_node_fs2.default.readFileSync(file, "utf8"));
+  } catch (error) {
+    throw new Error(
+      `[compose] ${file} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  const parsed = composeInputsSchema.safeParse(raw);
+  if (!parsed.success) {
+    const issues = parsed.error.issues.map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`).join("; ");
+    throw new Error(`[compose] ${file} is invalid: ${issues}`);
+  }
+  return {
+    connectedStores: parsed.data.connectedStores.map((store) => ({
+      storeId: store.storeId,
+      slug: store.slug,
+      bindingKey: store.bindingKey ?? null,
+      accessLevel: store.accessLevel
+    })),
+    installs: parsed.data.installs
+  };
+}
+function assertSupportedTypescript(versionMajorMinor) {
+  const major = Number.parseInt(versionMajorMinor.split(".")[0] ?? "", 10);
+  if (!Number.isInteger(major) || major < 5 || major >= 7) {
+    throw new Error(`[compose] typescript ${versionMajorMinor} is not supported (need >=5 <7)`);
+  }
+}
+var APP_DIR_PREFIX2 = "apps/web/src/app/";
+var STUB_GITIGNORE_PATH = "apps/web/src/app/.gitignore";
+var STUB_GITIGNORE_HEADER = "# Generated by stardeck-compose \u2014 Module-rail stubs are build outputs; do not edit or commit them.";
+function escapeGitignore(pattern) {
+  const escaped = pattern.replace(/[\\[\]*?]/g, (char) => `\\${char}`);
+  return /^[#!]/.test(escaped) ? `\\${escaped}` : escaped;
+}
+function stubGitignoreEntries(artifactPaths) {
+  return artifactPaths.filter((artifact) => artifact.startsWith(APP_DIR_PREFIX2)).map((artifact) => escapeGitignore(`/${artifact.slice(APP_DIR_PREFIX2.length)}`)).sort();
+}
+function writeStubGitignore(cwd, artifactPaths) {
+  const entries = stubGitignoreEntries(artifactPaths);
+  const content = [STUB_GITIGNORE_HEADER, ...entries].join("\n") + "\n";
+  const file = import_node_path2.default.join(cwd, STUB_GITIGNORE_PATH);
+  const existing = import_node_fs2.default.existsSync(file) ? import_node_fs2.default.readFileSync(file, "utf8") : null;
+  if (existing !== content) {
+    import_node_fs2.default.mkdirSync(import_node_path2.default.dirname(file), { recursive: true });
+    import_node_fs2.default.writeFileSync(file, content);
+  }
+  return entries.length;
+}
+function assertStubGitignoreOwned(cwd) {
+  const file = import_node_path2.default.join(cwd, STUB_GITIGNORE_PATH);
+  if (!import_node_fs2.default.existsSync(file)) return;
+  const firstLine = import_node_fs2.default.readFileSync(file, "utf8").split("\n", 1)[0] ?? "";
+  if (firstLine !== STUB_GITIGNORE_HEADER) {
+    throw new Error(
+      `[compose] refusing to overwrite ${STUB_GITIGNORE_PATH}: it is not compose-generated (line 1 is not the generated header)`
+    );
+  }
+}
 function assertAppRoot(cwd) {
   const modulesPath = import_node_path2.default.join(cwd, MODULES_DIR2);
   if (!import_node_fs2.default.existsSync(modulesPath)) {
@@ -5218,12 +5306,14 @@ function removeDir(absolute) {
 }
 async function compose(options) {
   assertAppRoot(options.cwd);
+  assertStubGitignoreOwned(options.cwd);
+  const inputs = readComposeInputs(options.cwd);
   if (options.prune) assertModuleTreeClean(options.cwd);
   const sandbox = localFsSandbox(options.cwd);
   const deps = {
     sandbox,
-    getModuleInstall: async () => null,
-    listDatabaseStoresForProject: async () => []
+    getModuleInstall: async (_db, _projectId, moduleName) => inputs.installs[moduleName] ?? null,
+    listDatabaseStoresForProject: async () => inputs.connectedStores
   };
   const context = {
     db: {},
@@ -5242,6 +5332,7 @@ async function compose(options) {
   const result = await reconcileCompositionArtifacts(context, {
     enabledModulesRaw: options.enabled
   });
+  const gitignoreEntries = options.enabled ? null : writeStubGitignore(options.cwd, result.artifactPaths);
   let pruned = 0;
   if (options.prune) {
     for (const name of result.excludedModules) {
@@ -5258,10 +5349,15 @@ async function compose(options) {
     excludedModules: result.excludedModules,
     writes: result.writePaths.length,
     deletes: result.deletePaths.length,
-    pruned
+    pruned,
+    gitignoreEntries
   };
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  compose
+  COMPOSE_INPUTS_PATH,
+  assertSupportedTypescript,
+  compose,
+  escapeGitignore,
+  readComposeInputs
 });

package/dist/index.mjs

@@ -3520,6 +3520,7 @@ function planCompositionArtifacts(input) {
       endpointStubs: stubs.endpointStubs,
       routeStubs: stubs.routeStubs,
       writes,
+      desiredPaths: [...desired.keys()].sort(compareNames2),
       deletes
     }
   };
@@ -5090,6 +5091,7 @@ async function reconcileCompositionArtifacts(context, options = {}) {
     registryPath: planned.plan.registryPath,
     writePaths: planned.plan.writes.map((w) => w.path),
     deletePaths: planned.plan.deletes,
+    artifactPaths: planned.plan.desiredPaths,
     changed,
     composedModules: composedNames,
     excludedModules
@@ -5099,7 +5101,89 @@ var HOME_I18N_SUBSTRATE_DIR = `${APP_PACKAGE_DIR}/src/lib/i18n/substrate`;
 var HOME_I18N_MESSAGES_DIR = `${APP_PACKAGE_DIR}/src/lib/i18n/messages`;
 
 // src/index.ts
+import { z as z9 } from "zod";
 var MODULES_DIR2 = MODULES_SANDBOX_DIR;
+var COMPOSE_INPUTS_PATH = "apps/web/stardeck.compose.json";
+var composeInputsSchema = z9.strictObject({
+  connectedStores: z9.array(
+    z9.strictObject({
+      storeId: z9.string().min(1),
+      slug: z9.string().min(1),
+      bindingKey: z9.string().min(1).nullish(),
+      accessLevel: z9.enum(["read", "write", "admin"])
+    })
+  ).default([]),
+  installs: z9.record(
+    z9.string(),
+    z9.strictObject({
+      installedVersion: z9.string().min(1),
+      datastoreBindings: z9.record(z9.string(), z9.string()).nullish()
+    })
+  ).default({})
+});
+function readComposeInputs(cwd) {
+  const file = path2.join(cwd, COMPOSE_INPUTS_PATH);
+  if (!fs2.existsSync(file)) return { connectedStores: [], installs: {} };
+  let raw;
+  try {
+    raw = JSON.parse(fs2.readFileSync(file, "utf8"));
+  } catch (error) {
+    throw new Error(
+      `[compose] ${file} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  const parsed = composeInputsSchema.safeParse(raw);
+  if (!parsed.success) {
+    const issues = parsed.error.issues.map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`).join("; ");
+    throw new Error(`[compose] ${file} is invalid: ${issues}`);
+  }
+  return {
+    connectedStores: parsed.data.connectedStores.map((store) => ({
+      storeId: store.storeId,
+      slug: store.slug,
+      bindingKey: store.bindingKey ?? null,
+      accessLevel: store.accessLevel
+    })),
+    installs: parsed.data.installs
+  };
+}
+function assertSupportedTypescript(versionMajorMinor) {
+  const major = Number.parseInt(versionMajorMinor.split(".")[0] ?? "", 10);
+  if (!Number.isInteger(major) || major < 5 || major >= 7) {
+    throw new Error(`[compose] typescript ${versionMajorMinor} is not supported (need >=5 <7)`);
+  }
+}
+var APP_DIR_PREFIX2 = "apps/web/src/app/";
+var STUB_GITIGNORE_PATH = "apps/web/src/app/.gitignore";
+var STUB_GITIGNORE_HEADER = "# Generated by stardeck-compose \u2014 Module-rail stubs are build outputs; do not edit or commit them.";
+function escapeGitignore(pattern) {
+  const escaped = pattern.replace(/[\\[\]*?]/g, (char) => `\\${char}`);
+  return /^[#!]/.test(escaped) ? `\\${escaped}` : escaped;
+}
+function stubGitignoreEntries(artifactPaths) {
+  return artifactPaths.filter((artifact) => artifact.startsWith(APP_DIR_PREFIX2)).map((artifact) => escapeGitignore(`/${artifact.slice(APP_DIR_PREFIX2.length)}`)).sort();
+}
+function writeStubGitignore(cwd, artifactPaths) {
+  const entries = stubGitignoreEntries(artifactPaths);
+  const content = [STUB_GITIGNORE_HEADER, ...entries].join("\n") + "\n";
+  const file = path2.join(cwd, STUB_GITIGNORE_PATH);
+  const existing = fs2.existsSync(file) ? fs2.readFileSync(file, "utf8") : null;
+  if (existing !== content) {
+    fs2.mkdirSync(path2.dirname(file), { recursive: true });
+    fs2.writeFileSync(file, content);
+  }
+  return entries.length;
+}
+function assertStubGitignoreOwned(cwd) {
+  const file = path2.join(cwd, STUB_GITIGNORE_PATH);
+  if (!fs2.existsSync(file)) return;
+  const firstLine = fs2.readFileSync(file, "utf8").split("\n", 1)[0] ?? "";
+  if (firstLine !== STUB_GITIGNORE_HEADER) {
+    throw new Error(
+      `[compose] refusing to overwrite ${STUB_GITIGNORE_PATH}: it is not compose-generated (line 1 is not the generated header)`
+    );
+  }
+}
 function assertAppRoot(cwd) {
   const modulesPath = path2.join(cwd, MODULES_DIR2);
   if (!fs2.existsSync(modulesPath)) {
@@ -5184,12 +5268,14 @@ function removeDir(absolute) {
 }
 async function compose(options) {
   assertAppRoot(options.cwd);
+  assertStubGitignoreOwned(options.cwd);
+  const inputs = readComposeInputs(options.cwd);
   if (options.prune) assertModuleTreeClean(options.cwd);
   const sandbox = localFsSandbox(options.cwd);
   const deps = {
     sandbox,
-    getModuleInstall: async () => null,
-    listDatabaseStoresForProject: async () => []
+    getModuleInstall: async (_db, _projectId, moduleName) => inputs.installs[moduleName] ?? null,
+    listDatabaseStoresForProject: async () => inputs.connectedStores
   };
   const context = {
     db: {},
@@ -5208,6 +5294,7 @@ async function compose(options) {
   const result = await reconcileCompositionArtifacts(context, {
     enabledModulesRaw: options.enabled
   });
+  const gitignoreEntries = options.enabled ? null : writeStubGitignore(options.cwd, result.artifactPaths);
   let pruned = 0;
   if (options.prune) {
     for (const name of result.excludedModules) {
@@ -5224,9 +5311,14 @@ async function compose(options) {
     excludedModules: result.excludedModules,
     writes: result.writePaths.length,
     deletes: result.deletePaths.length,
-    pruned
+    pruned,
+    gitignoreEntries
   };
 }
 export {
-  compose
+  COMPOSE_INPUTS_PATH,
+  assertSupportedTypescript,
+  compose,
+  escapeGitignore,
+  readComposeInputs
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stardeck-customer-apps/compose",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Regenerates a Stardeck app's Module-rail artifacts — the five src/*.gen.ts registries and every route/endpoint stub — from src/modules/*/module.json",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -51,7 +51,7 @@
     "zod": "^4.3.5"
   },
   "peerDependencies": {
-    "typescript": ">=5.0.0"
+    "typescript": ">=5.0.0 <7"
   },
   "devDependencies": {
     "@eslint/js": "^9.0.0",