@loomstack/generator 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+import { FrameworkError, GeneratedFilesManifest, LoomStackProject } from '@loomstack/core';
+
+declare const GENERATED_SOURCE_MARKER = "// GENERATED BY loomstack. DO NOT EDIT.";
+declare function stableJson(value: unknown): string;
+declare function sha256(content: string): string;
+declare function writeProjectFile(root: string, path: string, content: string, overwrite?: boolean): void;
+
+declare class GeneratorFailure extends Error {
+    readonly errors: FrameworkError[];
+    constructor(errors: FrameworkError[]);
+}
+interface GenerateResult {
+    createdFiles: string[];
+}
+declare function createFeature(rootInput: string, name: string): GenerateResult;
+
+declare function renderGeneratedFiles(project: LoomStackProject): Record<string, string>;
+declare function generatedManifest(files: Record<string, string>): GeneratedFilesManifest;
+interface ProjectGenerationResult {
+    generatedFiles: string[];
+}
+declare function generateProject(root: string): ProjectGenerationResult;
+declare function readGeneratedManifest(project: LoomStackProject): GeneratedFilesManifest | undefined;
+
+interface CreateAppResult {
+    appName: string;
+    root: string;
+    createdFiles: string[];
+    nextCommands: string[];
+}
+declare function createApp(parentInput: string, appName: string): CreateAppResult;
+declare function createAppInPlace(rootInput: string): CreateAppResult;
+
+export { type CreateAppResult, GENERATED_SOURCE_MARKER, type GenerateResult, GeneratorFailure, type ProjectGenerationResult, createApp, createAppInPlace, createFeature, generateProject, generatedManifest, readGeneratedManifest, renderGeneratedFiles, sha256, stableJson, writeProjectFile };

package/dist/index.js

@@ -0,0 +1,791 @@
+// src/files.ts
+import { createHash } from "crypto";
+import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+var GENERATED_SOURCE_MARKER = "// GENERATED BY loomstack. DO NOT EDIT.";
+function stableJson(value) {
+  return `${JSON.stringify(value, null, 2)}
+`;
+}
+function sha256(content) {
+  return createHash("sha256").update(content).digest("hex");
+}
+function writeProjectFile(root, path, content, overwrite = true) {
+  const absolute = join(root, path);
+  if (!overwrite && existsSync(absolute)) throw new Error(`Target already exists: ${path}`);
+  mkdirSync(dirname(absolute), { recursive: true });
+  writeFileSync(absolute, content, "utf8");
+}
+
+// src/scaffold.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync2 } from "fs";
+import { join as join2, resolve } from "path";
+import { frameworkError, loadProjectConfig } from "@loomstack/core";
+var FEATURE_ID = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+var GeneratorFailure = class extends Error {
+  constructor(errors) {
+    super(errors.map((error) => `${error.code}: ${error.message}`).join("\n"));
+    this.errors = errors;
+    this.name = "GeneratorFailure";
+  }
+  errors;
+};
+function titleCase(id) {
+  return id.split("-").map((part) => `${part[0]?.toUpperCase() ?? ""}${part.slice(1)}`).join(" ");
+}
+function camelCase(id) {
+  return id.split("-").map((part, index) => index === 0 ? part : `${part[0]?.toUpperCase() ?? ""}${part.slice(1)}`).join("");
+}
+function createFeature(rootInput, name) {
+  const root = resolve(rootInput);
+  if (!FEATURE_ID.test(name)) throw new GeneratorFailure([frameworkError("loomstack1011", { message: `Invalid feature name: ${name}.` })]);
+  const loaded = loadProjectConfig(root);
+  if (!loaded.config) throw new GeneratorFailure(loaded.errors);
+  const base = `${loaded.config.featuresDir}/${name}`;
+  if (existsSync2(join2(root, base))) {
+    throw new GeneratorFailure([frameworkError("loomstack5002", { message: `Feature already exists: ${name}.`, file: base })]);
+  }
+  const title = titleCase(name);
+  const files = {
+    [`${base}/feature.yaml`]: `id: ${name}
+name: ${title}
+description: ${title} product capability.
+
+entities: []
+routes: []
+actions: []
+queries: []
+`,
+    [`${base}/AGENTS.md`]: `# ${title} Feature Agent Instructions
+
+## Purpose
+
+${title} product capability.
+
+## Source of truth
+
+- Manifest: \`feature.yaml\`
+- Schema: \`model.schema.ts\`
+- Permissions: \`permissions.policy.ts\`
+
+## Rules
+
+- Mutations belong in \`actions/*.action.ts\`.
+- Reads belong in \`queries/*.query.ts\`.
+- Route UI belongs in \`ui/*.view.tsx\`.
+- Never import database or Koa modules from UI.
+- Never call raw fetch from UI.
+- Update tests with every contract change.
+
+## Verify
+
+\`pnpm loomstack verify feature ${name} --json\`
+`,
+    [`${base}/model.schema.ts`]: `import { entity } from "@loomstack/runtime"
+
+// Add and export manifest-declared entities here with entity().
+void entity
+`,
+    [`${base}/permissions.policy.ts`]: `import { policy } from "@loomstack/runtime"
+
+export const ${camelCase(name)}Policy = policy({})
+`
+  };
+  const createdFiles = Object.keys(files).sort();
+  for (const path of createdFiles) writeProjectFile(root, path, files[path] ?? "", false);
+  for (const directory of ["actions", "queries", "ui", "tests"]) {
+    const path = `${base}/${directory}/.gitkeep`;
+    mkdirSync2(join2(root, base, directory), { recursive: true });
+    writeProjectFile(root, path, "", false);
+    createdFiles.push(path);
+  }
+  return { createdFiles: createdFiles.sort() };
+}
+
+// src/generate.ts
+import { existsSync as existsSync3, readFileSync } from "fs";
+import { join as join3 } from "path";
+import { ERROR_CATALOG, frameworkError as frameworkError2, scanProject } from "@loomstack/core";
+function source(lines) {
+  return `${GENERATED_SOURCE_MARKER}
+
+${lines.join("\n").trimEnd()}
+`;
+}
+function importPath(path) {
+  return `../../${path.replace(/\.(tsx?|jsx?)$/, ".js")}`;
+}
+function featureRegistry(project) {
+  const entries = project.features.map(
+    (feature) => `  ${JSON.stringify(feature.id)}: { id: ${JSON.stringify(feature.id)}, name: ${JSON.stringify(feature.manifest.name)}, manifestPath: ${JSON.stringify(feature.manifestPath)} }`
+  );
+  return source([
+    "export const featureRegistry = {",
+    entries.join(",\n"),
+    "} as const"
+  ]);
+}
+function actionRegistry(project) {
+  const actions = project.features.flatMap((feature) => feature.actions).sort((a, b) => a.name.localeCompare(b.name));
+  return source([
+    ...actions.map((item) => `import { ${item.name} } from ${JSON.stringify(importPath(item.file))}`),
+    actions.length ? "" : "",
+    "export const actionRegistry = {",
+    ...actions.map((item) => `  ${item.name},`),
+    "} as const"
+  ]);
+}
+function queryRegistry(project) {
+  const queries = project.features.flatMap((feature) => feature.queries).sort((a, b) => a.name.localeCompare(b.name));
+  return source([
+    ...queries.map((item) => `import { ${item.name} } from ${JSON.stringify(importPath(item.file))}`),
+    queries.length ? "" : "",
+    "export const queryRegistry = {",
+    ...queries.map((item) => `  ${item.name},`),
+    "} as const"
+  ]);
+}
+function schemaRegistry(project) {
+  const schemas = project.features.flatMap((feature) => feature.manifest.entities.map((name) => ({
+    name,
+    file: `${feature.directory}/model.schema.ts`
+  }))).sort((a, b) => a.name.localeCompare(b.name));
+  return source([
+    ...schemas.map((item) => `import { ${item.name}Schema } from ${JSON.stringify(importPath(item.file))}`),
+    schemas.length ? "" : "",
+    "export const schemaRegistry = {",
+    ...schemas.map((item) => `  ${item.name}: ${item.name}Schema,`),
+    "} as const"
+  ]);
+}
+function resolveView(feature, viewName) {
+  return feature.views.find((item) => item.name === viewName)?.file;
+}
+function reactRoutes(project) {
+  const routes = project.features.flatMap((feature) => feature.manifest.routes.map((route) => ({ ...route, feature }))).sort((a, b) => a.path.localeCompare(b.path) || a.id.localeCompare(b.id));
+  const missing = routes.filter((route) => !resolveView(route.feature, route.view));
+  if (missing.length) {
+    throw new GeneratorFailure(missing.map((route) => frameworkError2("loomstack1009", {
+      message: `Route ${route.id} references missing view ${route.view}.`,
+      file: route.feature.manifestPath
+    })));
+  }
+  return source([
+    'import { lazy } from "react"',
+    'import type { ComponentType, LazyExoticComponent } from "react"',
+    "",
+    "export interface LoomStackRoute {",
+    "  id: string",
+    "  feature: string",
+    "  path: string",
+    "  component: LazyExoticComponent<ComponentType>",
+    "}",
+    "",
+    "export const routes: LoomStackRoute[] = [",
+    ...routes.map((route) => {
+      const file = resolveView(route.feature, route.view) ?? "";
+      const relative = `../../../${file.replace(/\.(tsx?|jsx?)$/, "")}`;
+      return `  { id: ${JSON.stringify(route.id)}, feature: ${JSON.stringify(route.feature.id)}, path: ${JSON.stringify(route.path)}, component: lazy(() => import(${JSON.stringify(relative)})) },`;
+    }),
+    "]"
+  ]);
+}
+function apiClient(project) {
+  const actions = project.features.flatMap((feature) => feature.actions).sort((a, b) => a.name.localeCompare(b.name));
+  const queries = project.features.flatMap((feature) => feature.queries).sort((a, b) => a.name.localeCompare(b.name));
+  return source([
+    'import { createActionClient, createQueryClient } from "@loomstack/react"',
+    ...actions.map((item) => `import type { ${item.name} as _${item.name}Definition } from ${JSON.stringify(`../../../${item.file.replace(/\.(tsx?|jsx?)$/, ".js")}`)}`),
+    ...queries.map((item) => `import type { ${item.name} as _${item.name}Definition } from ${JSON.stringify(`../../../${item.file.replace(/\.(tsx?|jsx?)$/, ".js")}`)}`),
+    "",
+    "export const api = {",
+    "  actions: {",
+    ...actions.map((item) => `    ${item.name}: createActionClient<Parameters<typeof _${item.name}Definition.run>[1], Awaited<ReturnType<typeof _${item.name}Definition.run>>>(${JSON.stringify(item.name)}),`),
+    "  },",
+    "  queries: {",
+    ...queries.map((item) => `    ${item.name}: createQueryClient<Parameters<typeof _${item.name}Definition.run>[1], Awaited<ReturnType<typeof _${item.name}Definition.run>>>(${JSON.stringify(item.name)}),`),
+    "  }",
+    "} as const"
+  ]);
+}
+function koaRoutes() {
+  return source([
+    'import type Koa from "koa"',
+    'import { registerLoomStackRoutes } from "@loomstack/koa"',
+    'import { actionRegistry } from "../../../shared/generated/action-registry.generated.js"',
+    'import { queryRegistry } from "../../../shared/generated/query-registry.generated.js"',
+    'import { createRequestContext } from "./context.js"',
+    "",
+    "export function registerGeneratedRoutes(app: Koa) {",
+    "  registerLoomStackRoutes(app, { actionRegistry, queryRegistry, createRequestContext })",
+    "}"
+  ]);
+}
+function contextDocument(project) {
+  return {
+    generatedBy: "loomstack",
+    doNotEdit: true,
+    project: {
+      name: project.config.appName,
+      frontend: project.config.frontend,
+      backend: project.config.backend,
+      database: project.config.database,
+      packageManager: project.config.packageManager
+    },
+    paths: { features: project.config.featuresDir, web: "apps/web", api: "apps/api" },
+    commands: {
+      dev: "pnpm dev",
+      verify: "pnpm loomstack verify",
+      test: "pnpm test",
+      typecheck: "pnpm typecheck"
+    },
+    features: project.features.map((feature) => feature.id),
+    rules: [
+      { id: "feature-source-of-truth", description: "Product behavior lives in features/*.", errorCode: null },
+      { id: "no-db-in-ui", description: "React UI files may not import database code.", errorCode: "loomstack2001" },
+      { id: "no-fetch-in-ui", description: "React UI files may not call raw fetch.", errorCode: "loomstack2002" },
+      { id: "transport-independent-features", description: "Feature logic may not import Koa.", errorCode: "loomstack2003" }
+    ]
+  };
+}
+function graphDocument(project) {
+  return { generatedBy: "loomstack", doNotEdit: true, ...project.graph };
+}
+function commandsDocument() {
+  return {
+    generatedBy: "loomstack",
+    doNotEdit: true,
+    commands: {
+      install: "pnpm install",
+      dev: "pnpm dev",
+      test: "pnpm test",
+      typecheck: "pnpm typecheck",
+      verify: "pnpm loomstack verify",
+      verifyFeature: "pnpm loomstack verify feature <feature>"
+    }
+  };
+}
+function errorsDocument() {
+  return {
+    generatedBy: "loomstack",
+    doNotEdit: true,
+    errors: Object.fromEntries(Object.entries(ERROR_CATALOG).sort(([a], [b]) => a.localeCompare(b)).map(([code, definition]) => [code, {
+      title: definition.title,
+      repair: definition.repair,
+      docs: definition.docs
+    }]))
+  };
+}
+function renderGeneratedFiles(project) {
+  const generatedDir = project.config.generatedDir;
+  const entries = [
+    ["apps/web/src/routes.generated.tsx", reactRoutes(project)],
+    ["apps/web/src/api-client.generated.ts", apiClient(project)],
+    ["apps/api/src/routes.generated.ts", koaRoutes()],
+    ["shared/generated/feature-registry.generated.ts", featureRegistry(project)],
+    ["shared/generated/schema-registry.generated.ts", schemaRegistry(project)],
+    ["shared/generated/action-registry.generated.ts", actionRegistry(project)],
+    ["shared/generated/query-registry.generated.ts", queryRegistry(project)],
+    [`${generatedDir}/context.json`, stableJson(contextDocument(project))],
+    [`${generatedDir}/graph.json`, stableJson(graphDocument(project))],
+    [`${generatedDir}/commands.json`, stableJson(commandsDocument())],
+    [`${generatedDir}/errors.json`, stableJson(errorsDocument())]
+  ];
+  return Object.fromEntries(entries.sort(([a], [b]) => a.localeCompare(b)));
+}
+function generatedManifest(files) {
+  return {
+    generatedBy: "loomstack",
+    doNotEdit: true,
+    files: Object.entries(files).map(([path, content]) => ({ path, sha256: sha256(content) })).sort((a, b) => a.path.localeCompare(b.path))
+  };
+}
+function generationContractErrors(project) {
+  const errors = [];
+  const operationOwners = /* @__PURE__ */ new Map();
+  for (const feature of project.features) {
+    const actionNames = new Set(feature.actions.map((item) => item.name));
+    const queryNames = new Set(feature.queries.map((item) => item.name));
+    const viewNames = new Set(feature.views.map((item) => item.name));
+    const schemaNames = new Set(feature.schemas.map((item) => item.name));
+    for (const name of feature.manifest.actions) {
+      if (!actionNames.has(name)) errors.push(frameworkError2("loomstack1003", { message: `Manifest action "${name}" is not exported.`, file: feature.manifestPath }));
+    }
+    for (const operation of feature.actions) {
+      if (!feature.manifest.actions.includes(operation.name)) errors.push(frameworkError2("loomstack1004", { message: `Exported action "${operation.name}" is missing from feature.yaml.`, file: operation.file }));
+    }
+    for (const name of feature.manifest.queries) {
+      if (!queryNames.has(name)) errors.push(frameworkError2("loomstack1007", { message: `Manifest query "${name}" is not exported.`, file: feature.manifestPath }));
+    }
+    for (const operation of feature.queries) {
+      if (!feature.manifest.queries.includes(operation.name)) errors.push(frameworkError2("loomstack1008", { message: `Exported query "${operation.name}" is missing from feature.yaml.`, file: operation.file }));
+    }
+    for (const route of feature.manifest.routes) {
+      if (!viewNames.has(route.view)) errors.push(frameworkError2("loomstack1009", { message: `Route "${route.id}" references missing view "${route.view}".`, file: feature.manifestPath }));
+    }
+    for (const name of feature.manifest.entities) {
+      if (!schemaNames.has(name)) errors.push(frameworkError2("loomstack1010", { message: `Manifest entity "${name}" is not exported by model.schema.ts.`, file: feature.manifestPath }));
+    }
+    for (const [kind, operations] of [["action", feature.actions], ["query", feature.queries]]) {
+      for (const operation of operations) {
+        const owner = operationOwners.get(operation.name);
+        if (owner) errors.push(frameworkError2(kind === "action" ? "loomstack1004" : "loomstack1008", { message: `Operation "${operation.name}" is also exported by ${owner}.`, file: operation.file }));
+        else operationOwners.set(operation.name, feature.id);
+      }
+    }
+  }
+  return errors;
+}
+function generateProject(root) {
+  const result = scanProject(root);
+  if (!result.project || result.errors.length > 0) throw new GeneratorFailure(result.errors);
+  const contractErrors = generationContractErrors(result.project);
+  if (contractErrors.length > 0) throw new GeneratorFailure(contractErrors);
+  const files = renderGeneratedFiles(result.project);
+  for (const [path, content] of Object.entries(files)) writeProjectFile(result.project.root, path, content);
+  const manifestPath = `${result.project.config.generatedDir}/generated-files.json`;
+  writeProjectFile(result.project.root, manifestPath, stableJson(generatedManifest(files)));
+  return { generatedFiles: [...Object.keys(files), manifestPath].sort() };
+}
+function readGeneratedManifest(project) {
+  const path = join3(project.root, project.config.generatedDir, "generated-files.json");
+  if (!existsSync3(path)) return void 0;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+
+// src/app.ts
+import { existsSync as existsSync4, mkdirSync as mkdirSync3, readdirSync } from "fs";
+import { basename, join as join4, resolve as resolve2 } from "path";
+import { frameworkError as frameworkError3 } from "@loomstack/core";
+
+// src/app-template.ts
+function appTemplateFiles(appName) {
+  return {
+    "package.json": `${JSON.stringify({
+      name: appName,
+      version: "0.0.1",
+      private: true,
+      type: "module",
+      packageManager: "pnpm@11.11.0",
+      scripts: {
+        loomstack: "loomstack",
+        dev: "loomstack dev start",
+        "dev:refresh": "loomstack dev refresh",
+        "dev:stop": "loomstack dev stop",
+        "dev:status": "loomstack dev status",
+        generate: "loomstack generate",
+        verify: "loomstack verify",
+        test: "vitest run --passWithNoTests",
+        typecheck: "tsc --noEmit",
+        build: "pnpm generate && pnpm -r --filter './apps/*' build"
+      },
+      devDependencies: {
+        "@loomstack/cli": "^0.0.1",
+        "@loomstack/react": "^0.0.1",
+        "@loomstack/runtime": "^0.0.1",
+        "@loomstack/postgres": "^0.0.1",
+        "@types/node": "^24.0.0",
+        "@types/react": "^19.0.0",
+        "@types/react-dom": "^19.0.0",
+        react: "^19.2.7",
+        "react-dom": "^19.2.7",
+        typescript: "^5.9.3",
+        vitest: "^4.1.10"
+      }
+    }, null, 2)}
+`,
+    "pnpm-workspace.yaml": "packages:\n  - apps/*\n\nallowBuilds:\n  esbuild: true\n",
+    "tsconfig.json": `${JSON.stringify({
+      compilerOptions: {
+        target: "ES2023",
+        module: "ESNext",
+        moduleResolution: "Bundler",
+        lib: ["ES2023", "DOM", "DOM.Iterable"],
+        strict: true,
+        noUncheckedIndexedAccess: true,
+        exactOptionalPropertyTypes: true,
+        esModuleInterop: true,
+        skipLibCheck: true,
+        resolveJsonModule: true,
+        jsx: "react-jsx"
+      },
+      include: ["apps/**/*.ts", "apps/**/*.tsx", "features/**/*.ts", "features/**/*.tsx", "shared/**/*.ts", "loomstack.config.ts"]
+    }, null, 2)}
+`,
+    "vitest.config.ts": `import { defineConfig } from "vitest/config"
+
+export default defineConfig({ test: { include: ["features/**/*.test.ts", "features/**/*.test.tsx"] } })
+`,
+    "loomstack.config.ts": `import { defineLoomStackConfig } from "@loomstack/runtime"
+
+export default defineLoomStackConfig({
+  appName: "${appName}",
+  packageManager: "pnpm",
+  frontend: "react",
+  backend: "koa",
+  database: "postgres",
+  featuresDir: "features",
+  generatedDir: ".loomstack"
+})
+`,
+    "AGENTS.md": `# ${appName} agent instructions
+
+This is a LoomStack app. Humans define product intent; agents implement it through explicit feature contracts.
+
+## Architecture
+
+\`\`\`text
+React = presentation
+Koa = transport
+features/* = product behavior and source of truth
+generated files = derived wiring, never product behavior
+\`\`\`
+
+## Command convention
+
+Invoke the project CLI as \`pnpm loomstack\`. Always use \`--json\` when available so output and repair guidance remain structured. \`loomstack init\` is the human onboarding entrypoint; it starts containers and prints agent guidance but never launches an agent. Do not invoke it from an existing agent session.
+
+## Start every task efficiently
+
+1. Read this file and any in-scope \`features/<feature>/AGENTS.md\`.
+2. Use \`pnpm loomstack doctor --json\` only when environment or setup may be relevant.
+3. Discover scope before broad file exploration:
+   - Existing feature: \`pnpm loomstack context feature <name> --json\`
+   - New or cross-feature work: \`pnpm loomstack context --json\`
+   - Dependencies or routes: \`pnpm loomstack graph --json\`
+4. Before editing an existing authored file, run \`pnpm loomstack affected <path> --json\`.
+5. Create missing features with \`pnpm loomstack create feature <kebab-case-name> --json\`; do not hand-build feature folders.
+
+## Tool selection
+
+| Need | Command |
+|---|---|
+| Validate setup | \`pnpm loomstack doctor --json\` |
+| Understand the app | \`pnpm loomstack context --json\` |
+| Understand one feature | \`pnpm loomstack context feature <name> --json\` |
+| Inspect relationships/routes | \`pnpm loomstack graph --json\` |
+| Find companion files | \`pnpm loomstack affected <authored-file> --json\` |
+| Scaffold a feature | \`pnpm loomstack create feature <name> --json\` |
+| Rebuild derived wiring | \`pnpm loomstack generate --json\` |
+| Check one feature | \`pnpm loomstack verify feature <name> --json\` |
+| Check the whole app | \`pnpm loomstack verify --json\` |
+| Understand an error | \`pnpm loomstack explain <code> --json\` |
+
+When a command returns an error code, run \`pnpm loomstack explain <code> --json\` and follow its repair guidance before inventing a workaround.
+
+## Development containers
+
+The complete development app runs in Docker Compose: Vite web server, Koa API, and PostgreSQL. The source tree is bind-mounted, so normal TypeScript and React edits reload automatically.
+
+- Start before browser/API validation: \`pnpm loomstack dev start --json\`.
+- Check state when uncertain: \`pnpm loomstack dev status --json\`.
+- Use \`pnpm loomstack dev refresh --json\` after dependency, Dockerfile, Compose, or environment changes. Do not refresh for ordinary source edits; hot reload handles them.
+- Stop with \`pnpm loomstack dev stop --json\` when the user requests it or when the task explicitly requires cleanup. Do not stop containers if the user expects the app to remain available.
+- If lifecycle commands fail, run \`pnpm loomstack doctor --json\` and follow the returned repair guidance.
+
+## Canonical feature layout
+
+- \`feature.yaml\`: declared entities, routes, actions, and queries
+- \`model.schema.ts\`: domain entities and schemas
+- \`permissions.policy.ts\`: authorization policy
+- \`actions/*.action.ts\`: mutations
+- \`queries/*.query.ts\`: reads
+- \`ui/*.view.tsx\`: routes and presentation
+- \`tests/*.test.ts\`: behavior proof
+
+Keep names synchronized across the manifest and authored exports.
+
+## Hard rules
+
+- Never edit files containing \`GENERATED BY loomstack\` or JSON with \`"generatedBy": "loomstack"\`.
+- Never put database access or raw fetch in feature UI.
+- Never import Koa in feature logic.
+- Put product behavior only in canonical feature files.
+- Do not bypass verifier errors with alternate architecture.
+- Update tests for every behavior change.
+
+## Minimal implementation loop
+
+\`\`\`bash
+pnpm loomstack context feature <name> --json
+pnpm loomstack affected <authored-file> --json
+# Edit only relevant canonical authored files.
+pnpm loomstack generate --json
+pnpm loomstack verify feature <name> --json
+pnpm test
+\`\`\`
+
+Use scoped verification while iterating. Finish cross-feature, routing, configuration, or generated-wiring work with \`pnpm loomstack verify --json\`, \`pnpm typecheck\`, and \`pnpm build\`. Do not repeatedly run full generation/build after every small edit.
+
+## Completion report
+
+State the behavior implemented, authored files changed, generated files refreshed, validation run, and any remaining error codes or environment requirements.
+`,
+    "CLAUDE.md": `# ${appName} LoomStack memory
+
+Read the root \`AGENTS.md\` before acting, then read every feature-local \`AGENTS.md\` in scope. Product behavior lives in \`features/*\`; React renders and Koa transports. Never edit generated files, use generated RPC clients, and finish with \`pnpm loomstack generate --json && pnpm loomstack verify --json\`.
+`,
+    ".gitignore": "node_modules/\ndist/\ncoverage/\n.env\n.env.local\n.DS_Store\n",
+    ".dockerignore": "node_modules\n**/node_modules\ndist\n**/dist\ncoverage\n.git\n.env\n.env.local\n",
+    ".env.example": "DATABASE_URL=postgresql://loomstack:loomstack@db:5432/loomstack\nPORT=3001\n",
+    "Dockerfile.dev": `FROM node:22-alpine
+
+RUN corepack enable
+WORKDIR /app
+
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
+COPY apps/web/package.json apps/web/package.json
+COPY apps/api/package.json apps/api/package.json
+COPY .loomstack/local-packages .loomstack/local-packages
+RUN pnpm install --frozen-lockfile
+
+COPY . .
+`,
+    "compose.yaml": `services:
+  db:
+    image: postgres:17-alpine
+    environment:
+      POSTGRES_DB: loomstack
+      POSTGRES_USER: loomstack
+      POSTGRES_PASSWORD: loomstack
+    ports:
+      - "5432:5432"
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U loomstack -d loomstack"]
+      interval: 2s
+      timeout: 3s
+      retries: 15
+
+  api:
+    build:
+      context: .
+      dockerfile: Dockerfile.dev
+    command: pnpm --filter './apps/api' dev
+    environment:
+      DATABASE_URL: postgresql://loomstack:loomstack@db:5432/loomstack
+      PORT: 3001
+      CI: "true"
+    ports:
+      - "3001:3001"
+    volumes:
+      - .:/app
+      - api-root-node-modules:/app/node_modules
+      - api-node-modules:/app/apps/api/node_modules
+    depends_on:
+      db:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "node", "-e", "require('net').connect(3001, '127.0.0.1').on('connect', () => process.exit(0)).on('error', () => process.exit(1))"]
+      interval: 2s
+      timeout: 3s
+      retries: 30
+
+  web:
+    build:
+      context: .
+      dockerfile: Dockerfile.dev
+    command: pnpm --filter './apps/web' dev --host 0.0.0.0
+    environment:
+      LOOMSTACK_API_URL: http://api:3001
+      CHOKIDAR_USEPOLLING: "true"
+      CI: "true"
+    ports:
+      - "3000:3000"
+    volumes:
+      - .:/app
+      - web-root-node-modules:/app/node_modules
+      - web-node-modules:/app/apps/web/node_modules
+    depends_on:
+      api:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "node", "-e", "require('net').connect(3000, '127.0.0.1').on('connect', () => process.exit(0)).on('error', () => process.exit(1))"]
+      interval: 2s
+      timeout: 3s
+      retries: 30
+
+volumes:
+  postgres-data:
+  api-root-node-modules:
+  api-node-modules:
+  web-root-node-modules:
+  web-node-modules:
+`,
+    ".loomstack/local-packages/.gitkeep": "",
+    "features/.gitkeep": "",
+    "apps/web/package.json": `${JSON.stringify({
+      name: `@${appName}/web`,
+      version: "0.0.1",
+      private: true,
+      type: "module",
+      scripts: { dev: "vite", build: "vite build" },
+      dependencies: {
+        "@loomstack/react": "^0.0.1",
+        "@loomstack/runtime": "^0.0.1",
+        "@vitejs/plugin-react": "^6.0.3",
+        react: "^19.2.7",
+        "react-dom": "^19.2.7",
+        vite: "^8.1.4"
+      }
+    }, null, 2)}
+`,
+    "apps/web/index.html": `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>${appName}</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+`,
+    "apps/web/src/main.tsx": `import { StrictMode } from "react"
+import { createRoot } from "react-dom/client"
+import { App } from "./app.js"
+
+const root = document.getElementById("root")
+if (!root) throw new Error("Missing #root element")
+createRoot(root).render(<StrictMode><App /></StrictMode>)
+`,
+    "apps/web/src/app.tsx": `import { Suspense } from "react"
+import { routes } from "./routes.generated.js"
+
+function matches(pattern: string, path: string) {
+  const expected = pattern.split("/").filter(Boolean)
+  const actual = path.split("/").filter(Boolean)
+  return expected.length === actual.length && expected.every((part, index) => part.startsWith(":") || part === actual[index])
+}
+
+export function App() {
+  const route = routes.find((candidate) => matches(candidate.path, window.location.pathname))
+  if (!route) return <main><h1>Not found</h1></main>
+  const Component = route.component
+  return <Suspense fallback={<main>Loading\u2026</main>}><Component /></Suspense>
+}
+`,
+    "apps/web/vite.config.ts": `import { defineConfig } from "vite"
+import react from "@vitejs/plugin-react"
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    host: "0.0.0.0",
+    port: 3000,
+    proxy: { "/_loomstack": process.env.LOOMSTACK_API_URL ?? "http://localhost:3001" }
+  }
+})
+`,
+    "apps/api/package.json": `${JSON.stringify({
+      name: `@${appName}/api`,
+      version: "0.0.1",
+      private: true,
+      type: "module",
+      scripts: { dev: "tsx watch src/server.ts", build: "tsup src/server.ts --format esm --clean" },
+      dependencies: {
+        "@loomstack/koa": "^0.0.1",
+        "@loomstack/runtime": "^0.0.1",
+        "@loomstack/postgres": "^0.0.1",
+        koa: "^3.2.1",
+        "koa-bodyparser": "^4.4.1"
+      },
+      devDependencies: {
+        "@types/koa": "^3.0.3",
+        "@types/koa-bodyparser": "^4.3.13",
+        tsup: "^8.5.0",
+        tsx: "^4.20.0"
+      }
+    }, null, 2)}
+`,
+    "apps/api/src/context.ts": `import type Koa from "koa"
+import { PostgresDatabase } from "@loomstack/postgres"
+
+export const db = new PostgresDatabase()
+
+export async function createRequestContext(ctx: Koa.Context) {
+  const userId = ctx.get("x-user-id")
+  return {
+    requestId: ctx.get("x-request-id") || crypto.randomUUID(),
+    ...(userId ? { user: { id: userId } } : {}),
+    db,
+    logger: console
+  }
+}
+`,
+    "apps/api/src/server.ts": `import Koa from "koa"
+import bodyParser from "koa-bodyparser"
+import { registerGeneratedRoutes } from "./routes.generated.js"
+
+const app = new Koa()
+app.use(bodyParser())
+registerGeneratedRoutes(app)
+
+const port = Number(process.env.PORT ?? 3001)
+app.listen(port, () => console.log(\`loomstack API listening on http://localhost:\${port}\`))
+`
+  };
+}
+
+// src/app.ts
+var APP_NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+function renderApp(root, appName, nextCommands) {
+  const files = appTemplateFiles(appName);
+  for (const path of Object.keys(files).sort()) writeProjectFile(root, path, files[path] ?? "", false);
+  const generation = generateProject(root);
+  const createdFiles = [...Object.keys(files), ...generation.generatedFiles].filter((value, index, all) => all.indexOf(value) === index).sort();
+  return { appName, root, createdFiles, nextCommands };
+}
+function createApp(parentInput, appName) {
+  if (!APP_NAME.test(appName)) {
+    throw new GeneratorFailure([frameworkError3("loomstack5003", {
+      message: `App names must be lowercase kebab-case: ${appName}.`
+    })]);
+  }
+  const parent = resolve2(parentInput);
+  const root = join4(parent, appName);
+  if (existsSync4(root)) {
+    throw new GeneratorFailure([frameworkError3("loomstack5002", { message: `Target directory already exists: ${appName}.`, file: appName })]);
+  }
+  mkdirSync3(root, { recursive: false });
+  return renderApp(root, appName, [`cd ${appName}`, "pnpm install", "loomstack init"]);
+}
+function createAppInPlace(rootInput) {
+  const root = resolve2(rootInput);
+  const appName = basename(root);
+  if (!APP_NAME.test(appName)) {
+    throw new GeneratorFailure([frameworkError3("loomstack5003", {
+      message: `The directory name must be lowercase kebab-case: ${appName}.`,
+      file: appName
+    })]);
+  }
+  if (!existsSync4(root)) mkdirSync3(root, { recursive: true });
+  if (readdirSync(root).length > 0) {
+    throw new GeneratorFailure([frameworkError3("loomstack5002", {
+      message: "The current directory is not empty and is not a LoomStack project.",
+      file: "."
+    })]);
+  }
+  return renderApp(root, appName, ["pnpm install", "loomstack init"]);
+}
+export {
+  GENERATED_SOURCE_MARKER,
+  GeneratorFailure,
+  createApp,
+  createAppInPlace,
+  createFeature,
+  generateProject,
+  generatedManifest,
+  readGeneratedManifest,
+  renderGeneratedFiles,
+  sha256,
+  stableJson,
+  writeProjectFile
+};

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@loomstack/generator",
+  "version": "0.0.1",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@loomstack/core": "0.0.1"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run"
+  }
+}