create-loomstack-app 0.0.1

package/README.md

@@ -0,0 +1,25 @@
+# create-loomstack-app
+
+Create a new loomstack full-stack application from npm.
+
+```bash
+npm create loomstack-app@latest my-app
+# or
+npx create-loomstack-app@latest my-app
+```
+
+The generated application uses TypeScript, React, Vite, Koa, PostgreSQL, Zod, pnpm, and Vitest.
+
+## Options
+
+```text
+create-loomstack-app <name> [--cwd <directory>] [--json]
+```
+
+After creation:
+
+```bash
+cd my-app
+pnpm install
+pnpm loomstack init
+```

package/dist/chunk-QTMEZJHE.js

@@ -0,0 +1,1115 @@
+// src/index.ts
+import { resolve as resolve4 } from "path";
+
+// ../generator/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");
+}
+
+// ../generator/src/scaffold.ts
+import { existsSync as existsSync3, mkdirSync as mkdirSync2 } from "fs";
+import { join as join3, resolve as resolve2 } from "path";
+
+// ../core/src/errors.ts
+var ERROR_CATALOG = {
+  loomstack1001: {
+    title: "Feature ID does not match folder name",
+    defaultMessage: "The feature manifest ID must match its folder name.",
+    repair: "Rename the folder or update feature.yaml so the feature ID matches the folder name.",
+    docs: "implementation-plan/docs/10-verifier-and-error-system.md"
+  },
+  loomstack1002: {
+    title: "Missing or invalid feature manifest field",
+    defaultMessage: "A required feature manifest field is missing or invalid.",
+    repair: "Add the required field to feature.yaml using the canonical manifest shape.",
+    docs: "implementation-plan/docs/03-feature-contract.md"
+  },
+  loomstack1003: {
+    title: "Manifest action is not exported",
+    defaultMessage: "An action declared in the manifest has no implementation.",
+    repair: "Create the action file or update the manifest action name.",
+    docs: "implementation-plan/docs/05-action-query-runtime.md"
+  },
+  loomstack1004: {
+    title: "Exported action is missing from manifest",
+    defaultMessage: "An exported action is not declared in feature.yaml.",
+    repair: "Add the action name to feature.yaml or remove the action implementation.",
+    docs: "implementation-plan/docs/05-action-query-runtime.md"
+  },
+  loomstack1005: {
+    title: "Duplicate route path",
+    defaultMessage: "Route paths must be globally unique.",
+    repair: "Change one route path so every route path is globally unique.",
+    docs: "implementation-plan/docs/03-feature-contract.md"
+  },
+  loomstack1006: {
+    title: "Invalid feature manifest YAML",
+    defaultMessage: "feature.yaml could not be parsed.",
+    repair: "Fix the YAML syntax and run loomstack verify again.",
+    docs: "implementation-plan/docs/03-feature-contract.md"
+  },
+  loomstack1007: {
+    title: "Manifest query is not exported",
+    defaultMessage: "A query declared in the manifest has no implementation.",
+    repair: "Create the query file or update the manifest query name.",
+    docs: "implementation-plan/docs/05-action-query-runtime.md"
+  },
+  loomstack1008: {
+    title: "Exported query is missing from manifest",
+    defaultMessage: "An exported query is not declared in feature.yaml.",
+    repair: "Add the query name to feature.yaml or remove the query implementation.",
+    docs: "implementation-plan/docs/05-action-query-runtime.md"
+  },
+  loomstack1009: {
+    title: "Manifest view is not exported",
+    defaultMessage: "A route references a view that does not exist.",
+    repair: "Create the declared *.view.tsx file or update the route view in feature.yaml.",
+    docs: "implementation-plan/docs/06-react-frontend-adapter.md"
+  },
+  loomstack1010: {
+    title: "Manifest entity is not exported",
+    defaultMessage: "An entity declared in the manifest has no schema export.",
+    repair: "Export the entity from model.schema.ts or update the manifest entity name.",
+    docs: "implementation-plan/docs/04-schema-and-domain-layer.md"
+  },
+  loomstack1011: {
+    title: "Invalid feature name",
+    defaultMessage: "Feature IDs must be kebab-case.",
+    repair: "Use a lowercase kebab-case feature name such as project-notes.",
+    docs: "implementation-plan/docs/03-feature-contract.md"
+  },
+  loomstack2001: {
+    title: "Forbidden database import in UI file",
+    defaultMessage: "Database imports are forbidden in React UI files.",
+    repair: "Move database access into queries/*.query.ts or actions/*.action.ts.",
+    docs: "implementation-plan/docs/10-verifier-and-error-system.md"
+  },
+  loomstack2002: {
+    title: "Forbidden raw fetch in UI file",
+    defaultMessage: "Raw fetch is forbidden in React UI files.",
+    repair: "Use the generated loomstack action/query client.",
+    docs: "implementation-plan/docs/10-verifier-and-error-system.md"
+  },
+  loomstack2003: {
+    title: "Koa import in feature logic",
+    defaultMessage: "Feature logic must be transport-independent.",
+    repair: "Remove the Koa dependency and use LoomStackRequestContext.",
+    docs: "implementation-plan/docs/10-verifier-and-error-system.md"
+  },
+  loomstack3001: {
+    title: "Action input validation failed",
+    defaultMessage: "Action input did not match its schema.",
+    repair: "Send input matching the action input schema.",
+    docs: "implementation-plan/docs/05-action-query-runtime.md"
+  },
+  loomstack3002: {
+    title: "Runtime output validation failed",
+    defaultMessage: "Action or query output did not match its schema.",
+    repair: "Return a value matching the declared output schema.",
+    docs: "implementation-plan/docs/05-action-query-runtime.md"
+  },
+  loomstack3003: {
+    title: "Authentication required",
+    defaultMessage: "This operation requires an authenticated user.",
+    repair: "Authenticate the request before calling this operation.",
+    docs: "implementation-plan/docs/05-action-query-runtime.md"
+  },
+  loomstack4040: {
+    title: "Unknown action",
+    defaultMessage: "The requested action is not registered.",
+    repair: "Use an action declared in feature.yaml and run loomstack generate.",
+    docs: "implementation-plan/docs/07-koa-backend-adapter.md"
+  },
+  loomstack4041: {
+    title: "Unknown query",
+    defaultMessage: "The requested query is not registered.",
+    repair: "Use a query declared in feature.yaml and run loomstack generate.",
+    docs: "implementation-plan/docs/07-koa-backend-adapter.md"
+  },
+  loomstack4050: {
+    title: "Invalid RPC method",
+    defaultMessage: "loomstack RPC endpoints accept only HTTP POST.",
+    repair: "Send the action or query request with HTTP POST.",
+    docs: "implementation-plan/docs/07-koa-backend-adapter.md"
+  },
+  loomstack4001: {
+    title: "Generated file was manually modified",
+    defaultMessage: "A generated file does not match its recorded hash.",
+    repair: "Run loomstack generate or move custom logic out of the generated file.",
+    docs: "implementation-plan/docs/09-code-generation.md"
+  },
+  loomstack4002: {
+    title: "Generated file is stale",
+    defaultMessage: "Generated output does not match current feature contracts.",
+    repair: "Run loomstack generate.",
+    docs: "implementation-plan/docs/09-code-generation.md"
+  },
+  loomstack5001: {
+    title: "Missing loomstack config",
+    defaultMessage: "No loomstack.config.ts was found.",
+    repair: "Create loomstack.config.ts or run the command inside a loomstack project.",
+    docs: "implementation-plan/docs/02-repository-structure.md"
+  },
+  loomstack5002: {
+    title: "Target already exists",
+    defaultMessage: "The requested target already exists.",
+    repair: "Choose another name or remove the existing target first.",
+    docs: "implementation-plan/docs/08-cli-specification.md"
+  },
+  loomstack5003: {
+    title: "Invalid project configuration",
+    defaultMessage: "loomstack.config.ts does not contain the required golden-path values.",
+    repair: "Use React, Koa, PostgreSQL, pnpm, and explicit featuresDir/generatedDir values.",
+    docs: "implementation-plan/docs/02-repository-structure.md"
+  },
+  loomstack6001: {
+    title: "Unsupported PostgreSQL field",
+    defaultMessage: "An entity field cannot be represented by the v0.1 PostgreSQL adapter.",
+    repair: "Use a supported scalar field or provide explicit persistence logic.",
+    docs: "implementation-plan/docs/04-schema-and-domain-layer.md"
+  }
+};
+function frameworkError(code, options = {}) {
+  const definition = ERROR_CATALOG[code];
+  return {
+    code,
+    severity: options.severity ?? "error",
+    message: options.message ?? definition.defaultMessage,
+    repair: definition.repair,
+    docs: definition.docs,
+    ...options.file ? { file: options.file } : {},
+    ...options.relatedFiles ? { relatedFiles: options.relatedFiles } : {},
+    ...options.location ? { location: options.location } : {}
+  };
+}
+
+// ../core/src/scanner.ts
+import { existsSync as existsSync2, readdirSync, readFileSync, statSync } from "fs";
+import { dirname as dirname2, join as join2, relative, resolve, sep } from "path";
+import { parse } from "yaml";
+var FEATURE_ID = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+var DEFAULT_CONFIG = {
+  packageManager: "pnpm",
+  frontend: "react",
+  backend: "koa",
+  database: "postgres",
+  featuresDir: "features",
+  generatedDir: ".loomstack"
+};
+function toProjectPath(path) {
+  return path.split(sep).join("/");
+}
+function quotedValue(source2, key) {
+  const match = source2.match(new RegExp(`${key}\\s*:\\s*["']([^"']+)["']`));
+  return match?.[1];
+}
+function loadProjectConfig(root) {
+  const configPath = join2(root, "loomstack.config.ts");
+  if (!existsSync2(configPath)) {
+    return { errors: [frameworkError("loomstack5001", { file: "loomstack.config.ts" })] };
+  }
+  const source2 = readFileSync(configPath, "utf8");
+  const appName = quotedValue(source2, "appName");
+  const values = {
+    packageManager: quotedValue(source2, "packageManager"),
+    frontend: quotedValue(source2, "frontend"),
+    backend: quotedValue(source2, "backend"),
+    database: quotedValue(source2, "database"),
+    featuresDir: quotedValue(source2, "featuresDir"),
+    generatedDir: quotedValue(source2, "generatedDir")
+  };
+  if (!appName || values.packageManager !== DEFAULT_CONFIG.packageManager || values.frontend !== DEFAULT_CONFIG.frontend || values.backend !== DEFAULT_CONFIG.backend || values.database !== DEFAULT_CONFIG.database || values.featuresDir !== DEFAULT_CONFIG.featuresDir || values.generatedDir !== DEFAULT_CONFIG.generatedDir) {
+    return { errors: [frameworkError("loomstack5003", { file: "loomstack.config.ts" })] };
+  }
+  return {
+    config: {
+      appName,
+      packageManager: "pnpm",
+      frontend: "react",
+      backend: "koa",
+      database: "postgres",
+      featuresDir: values.featuresDir,
+      generatedDir: values.generatedDir
+    },
+    errors: []
+  };
+}
+function filesIn(directory, suffix) {
+  if (!existsSync2(directory)) return [];
+  return readdirSync(directory).filter((name) => name.endsWith(suffix) && statSync(join2(directory, name)).isFile()).sort().map((name) => join2(directory, name));
+}
+function discoverNamedFiles(root, directory, suffix, kind) {
+  const expression = new RegExp(`export\\s+const\\s+([A-Za-z_$][\\w$]*)\\s*=\\s*${kind}\\b`);
+  return filesIn(directory, suffix).flatMap((file) => {
+    const match = readFileSync(file, "utf8").match(expression);
+    return match?.[1] ? [{ name: match[1], file: toProjectPath(relative(root, file)) }] : [];
+  });
+}
+function discoverViews(root, directory) {
+  return filesIn(directory, ".view.tsx").flatMap((file) => {
+    const source2 = readFileSync(file, "utf8");
+    const loomStackName = source2.match(/\bname\s*:\s*["']([A-Za-z_$][\w$]*)["']/)?.[1];
+    const namedExport = source2.match(/export\s+const\s+([A-Za-z_$][\w$]*)\s*=\s*view\s*\(/)?.[1];
+    const name = loomStackName ?? namedExport;
+    return name ? [{ name, file: toProjectPath(relative(root, file)) }] : [];
+  });
+}
+function discoverSchemas(root, featureDirectory) {
+  const file = join2(featureDirectory, "model.schema.ts");
+  if (!existsSync2(file)) return [];
+  const source2 = readFileSync(file, "utf8");
+  return [...source2.matchAll(/export\s+const\s+([A-Za-z_$][\w$]*)Schema\s*=\s*entity\s*\(\s*["']([^"']+)["']/g)].map((match) => ({ name: match[2] ?? match[1] ?? "", file: toProjectPath(relative(root, file)) })).filter((item) => item.name);
+}
+function validateManifest(value, manifestPath, folderName) {
+  const errors = [];
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return { errors: [frameworkError("loomstack1002", { file: manifestPath })] };
+  }
+  const input = value;
+  const requiredStrings = ["id", "name"];
+  for (const key of requiredStrings) {
+    if (typeof input[key] !== "string" || input[key].length === 0) {
+      errors.push(frameworkError("loomstack1002", { message: `Missing or invalid required field: ${key}.`, file: manifestPath }));
+    }
+  }
+  for (const key of ["entities", "routes", "actions", "queries"]) {
+    if (!Array.isArray(input[key])) {
+      errors.push(frameworkError("loomstack1002", { message: `Missing or invalid required array: ${key}.`, file: manifestPath }));
+    }
+  }
+  if (errors.length > 0) return { errors };
+  const id = input.id;
+  if (!FEATURE_ID.test(id)) errors.push(frameworkError("loomstack1011", { file: manifestPath }));
+  if (id !== folderName) {
+    errors.push(frameworkError("loomstack1001", { message: `Feature ID "${id}" does not match folder "${folderName}".`, file: manifestPath }));
+  }
+  if (input.description !== void 0 && typeof input.description !== "string") {
+    errors.push(frameworkError("loomstack1002", { message: "description must be a string when provided.", file: manifestPath }));
+  }
+  if (input.permissions !== void 0 && (!input.permissions || typeof input.permissions !== "object" || Array.isArray(input.permissions) || Object.values(input.permissions).some((value2) => typeof value2 !== "string"))) {
+    errors.push(frameworkError("loomstack1002", { message: "permissions must map string names to string requirements.", file: manifestPath }));
+  }
+  for (const key of ["entities", "actions", "queries"]) {
+    const values = input[key];
+    if (values.some((value2) => typeof value2 !== "string" || value2.length === 0) || new Set(values).size !== values.length) {
+      errors.push(frameworkError("loomstack1002", { message: `${key} must contain unique, non-empty strings.`, file: manifestPath }));
+    }
+  }
+  if (input.entities.some((name) => !/^[A-Z][A-Za-z0-9]*$/.test(name))) {
+    errors.push(frameworkError("loomstack1002", { message: "Entity names must be PascalCase identifiers.", file: manifestPath }));
+  }
+  for (const key of ["actions", "queries"]) {
+    if (input[key].some((name) => !/^[A-Za-z_$][\w$]*$/.test(name))) {
+      errors.push(frameworkError("loomstack1002", { message: `${key} names must be JavaScript identifiers.`, file: manifestPath }));
+    }
+  }
+  const routes = input.routes;
+  const routeIds = /* @__PURE__ */ new Set();
+  for (const route of routes) {
+    if (!route || typeof route !== "object") {
+      errors.push(frameworkError("loomstack1002", { message: "Every route must be an object with id, path, and view.", file: manifestPath }));
+      continue;
+    }
+    const candidate = route;
+    if (["id", "path", "view"].some((key) => typeof candidate[key] !== "string" || candidate[key].length === 0)) {
+      errors.push(frameworkError("loomstack1002", { message: "Every route requires string id, path, and view fields.", file: manifestPath }));
+    } else if (!candidate.path.startsWith("/") || !/^[A-Za-z_$][\w$]*$/.test(candidate.view)) {
+      errors.push(frameworkError("loomstack1002", { message: "Route paths must start with / and route views must be JavaScript identifiers.", file: manifestPath }));
+    }
+    if (typeof candidate.id === "string") {
+      if (routeIds.has(candidate.id)) errors.push(frameworkError("loomstack1002", { message: `Duplicate route ID: ${candidate.id}.`, file: manifestPath }));
+      routeIds.add(candidate.id);
+    }
+  }
+  if (errors.length > 0) return { errors };
+  return { manifest: input, errors };
+}
+function scanProject(rootInput) {
+  const root = resolve(rootInput);
+  const loaded = loadProjectConfig(root);
+  if (!loaded.config) return { errors: loaded.errors };
+  const config = loaded.config;
+  const featuresDirectory = join2(root, config.featuresDir);
+  const errors = [...loaded.errors];
+  const features = [];
+  if (existsSync2(featuresDirectory)) {
+    const featureFolders = readdirSync(featuresDirectory).filter((name) => statSync(join2(featuresDirectory, name)).isDirectory()).sort();
+    for (const folderName of featureFolders) {
+      const directory = join2(featuresDirectory, folderName);
+      const absoluteManifest = join2(directory, "feature.yaml");
+      if (!existsSync2(absoluteManifest)) continue;
+      const manifestPath = toProjectPath(relative(root, absoluteManifest));
+      let raw;
+      try {
+        raw = parse(readFileSync(absoluteManifest, "utf8"));
+      } catch (error) {
+        errors.push(frameworkError("loomstack1006", { message: `Invalid YAML: ${error instanceof Error ? error.message : String(error)}`, file: manifestPath }));
+        continue;
+      }
+      const validated = validateManifest(raw, manifestPath, folderName);
+      errors.push(...validated.errors);
+      if (!validated.manifest) continue;
+      const feature = {
+        id: folderName,
+        directory: toProjectPath(relative(root, directory)),
+        manifestPath,
+        manifest: validated.manifest,
+        schemas: discoverSchemas(root, directory),
+        actions: discoverNamedFiles(root, join2(directory, "actions"), ".action.ts", "action"),
+        queries: discoverNamedFiles(root, join2(directory, "queries"), ".query.ts", "query"),
+        views: discoverViews(root, join2(directory, "ui")),
+        tests: filesIn(join2(directory, "tests"), ".test.ts").map((file) => toProjectPath(relative(root, file)))
+      };
+      feature.views = feature.views.map((view) => {
+        const route = feature.manifest.routes.find((candidate) => candidate.view === view.name)?.path;
+        return route ? { ...view, route } : view;
+      });
+      features.push(feature);
+    }
+  }
+  const paths = /* @__PURE__ */ new Map();
+  for (const feature of features) {
+    for (const route of feature.manifest.routes) {
+      const owner = paths.get(route.path);
+      if (owner) {
+        errors.push(frameworkError("loomstack1005", {
+          message: `Route path "${route.path}" is declared by both ${owner} and ${feature.id}.`,
+          file: feature.manifestPath,
+          relatedFiles: [features.find((item) => item.id === owner)?.manifestPath ?? owner]
+        }));
+      } else paths.set(route.path, feature.id);
+    }
+  }
+  const graph = {
+    features: features.map((feature) => ({
+      id: feature.id,
+      manifest: feature.manifestPath,
+      entities: [...feature.manifest.entities].sort(),
+      actions: [...feature.actions].sort((a, b) => a.name.localeCompare(b.name)),
+      queries: [...feature.queries].sort((a, b) => a.name.localeCompare(b.name)),
+      views: [...feature.views].sort((a, b) => a.name.localeCompare(b.name)),
+      tests: [...feature.tests].sort(),
+      routes: feature.manifest.routes.map((route) => route.path).sort()
+    })),
+    dependencies: []
+  };
+  return {
+    project: { root, configPath: "loomstack.config.ts", config, features, graph },
+    errors
+  };
+}
+
+// ../generator/src/scaffold.ts
+var GeneratorFailure = class extends Error {
+  constructor(errors) {
+    super(errors.map((error) => `${error.code}: ${error.message}`).join("\n"));
+    this.errors = errors;
+    this.name = "GeneratorFailure";
+  }
+  errors;
+};
+
+// ../generator/src/generate.ts
+import { existsSync as existsSync4, readFileSync as readFileSync2 } from "fs";
+import { join as join4 } from "path";
+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) => frameworkError("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 relative2 = `../../../${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(relative2)})) },`;
+    }),
+    "]"
+  ]);
+}
+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(frameworkError("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(frameworkError("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(frameworkError("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(frameworkError("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(frameworkError("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(frameworkError("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(frameworkError(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() };
+}
+
+// ../generator/src/app.ts
+import { existsSync as existsSync5, mkdirSync as mkdirSync3, readdirSync as readdirSync2 } from "fs";
+import { basename, join as join5, resolve as resolve3 } from "path";
+
+// ../generator/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}\`))
+`
+  };
+}
+
+// ../generator/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([frameworkError("loomstack5003", {
+      message: `App names must be lowercase kebab-case: ${appName}.`
+    })]);
+  }
+  const parent = resolve3(parentInput);
+  const root = join5(parent, appName);
+  if (existsSync5(root)) {
+    throw new GeneratorFailure([frameworkError("loomstack5002", { message: `Target directory already exists: ${appName}.`, file: appName })]);
+  }
+  mkdirSync3(root, { recursive: false });
+  return renderApp(root, appName, [`cd ${appName}`, "pnpm install", "loomstack init"]);
+}
+
+// src/index.ts
+function usage() {
+  return "Usage: create-loomstack-app <name> [--cwd <directory>] [--json]";
+}
+function runCreateLoomStackApp(argv, io = { stdout: console.log, stderr: console.error }) {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    io.stdout(`${usage()}
+
+Create a production-ready loomstack application.`);
+    return 0;
+  }
+  const json = argv.includes("--json");
+  const cwdIndex = argv.indexOf("--cwd");
+  const cwdValue = cwdIndex >= 0 ? argv[cwdIndex + 1] : void 0;
+  const positional = argv.filter(
+    (value, index) => value !== "--json" && value !== "--cwd" && index !== cwdIndex + 1 && !value.startsWith("-")
+  );
+  const name = positional[0];
+  if (!name || cwdIndex >= 0 && !cwdValue) {
+    const error = { code: "loomstack5003", message: usage(), repair: "Provide a lowercase kebab-case application name." };
+    if (json) io.stdout(JSON.stringify({ ok: false, errors: [error] }));
+    else io.stderr(`${error.message}
+Repair: ${error.repair}`);
+    return 1;
+  }
+  try {
+    const result = createApp(resolve4(cwdValue ?? process.cwd()), name);
+    if (json) io.stdout(JSON.stringify({ ok: true, data: result }));
+    else {
+      io.stdout(`Created loomstack app: ${result.appName}`);
+      io.stdout(`Next: ${result.nextCommands.join(" && ")}`);
+    }
+    return 0;
+  } catch (error) {
+    const errors = error instanceof GeneratorFailure ? error.errors : [{ code: "loomstack5003", message: error instanceof Error ? error.message : String(error), repair: "Retry with a writable target directory." }];
+    if (json) io.stdout(JSON.stringify({ ok: false, errors }));
+    else for (const item of errors) io.stderr(`${item.code}: ${item.message}
+Repair: ${item.repair}`);
+    return 1;
+  }
+}
+
+export {
+  runCreateLoomStackApp
+};

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import {
+  runCreateLoomStackApp
+} from "./chunk-QTMEZJHE.js";
+
+// src/cli.ts
+process.exitCode = runCreateLoomStackApp(process.argv.slice(2));

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+interface CreateLoomStackAppIO {
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+}
+declare function runCreateLoomStackApp(argv: string[], io?: CreateLoomStackAppIO): number;
+
+export { type CreateLoomStackAppIO, runCreateLoomStackApp };

package/dist/index.js

@@ -0,0 +1,6 @@
+import {
+  runCreateLoomStackApp
+} from "./chunk-QTMEZJHE.js";
+export {
+  runCreateLoomStackApp
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "create-loomstack-app",
+  "version": "0.0.1",
+  "description": "Create a full-stack loomstack application",
+  "type": "module",
+  "bin": {
+    "create-loomstack-app": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "@loomstack/generator": "0.0.1"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "keywords": [
+    "loomstack",
+    "create-app",
+    "fullstack",
+    "typescript",
+    "react",
+    "koa",
+    "postgresql"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DenizOkcu/loomstack.git",
+    "directory": "packages/create-loomstack-app"
+  },
+  "homepage": "https://github.com/DenizOkcu/loomstack#readme",
+  "bugs": "https://github.com/DenizOkcu/loomstack/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup --config tsup.config.ts",
+    "test": "vitest run --root ../.. packages/create-loomstack-app/tests"
+  }
+}