create-loomstack-app 0.0.1 → 0.0.3

package/README.md

@@ -1,25 +1,104 @@
 # create-loomstack-app
 
-Create a new loomstack full-stack application from npm.
+Create an agent-operable TypeScript fullstack application with React, Vite, Koa, PostgreSQL, Zod, pnpm, and Vitest.
+
+## Quick start
+
+**Requirements:** Node 22+, pnpm 11+, and Docker Compose.
 
 ```bash
 npm create loomstack-app@latest my-app
-# or
-npx create-loomstack-app@latest my-app
+cd my-app
+pnpm install
+pnpm loomstack init
+```
+
+`init` validates the project and starts the web, API, and PostgreSQL development services. Open [http://localhost:3000](http://localhost:3000) when it finishes.
+
+Use `pnpm loomstack init --no-start` to initialize without starting Docker, or `pnpm loomstack init --skip-install` when dependencies are managed separately.
+
+## Create your first feature
+
+```bash
+pnpm loomstack create feature people --json
+pnpm loomstack context feature people --json
+```
+
+Then describe the product behavior to your coding agent:
+
+```text
+Implement the people feature. Users can create people with a name and optional
+job title, list only their own people newest-first, and open the list at /people.
+Read AGENTS.md first. Generate, verify, and test before finishing.
+```
+
+LoomStack gives the agent a deterministic context → edit → generate → verify → test workflow and keeps product behavior in canonical feature slices.
+
+## What gets created
+
+```text
+apps/web/              React + Vite presentation
+apps/api/              Koa RPC transport
+features/              Product behavior and tests
+shared/generated/      Generated registries
+.loomstack/             Generated context, graph, and hashes
+compose.yaml            Web, API, and PostgreSQL services
+AGENTS.md               Project-specific agent instructions
 ```
 
-The generated application uses TypeScript, React, Vite, Koa, PostgreSQL, Zod, pnpm, and Vitest.
+Generated wiring is marked as do-not-edit. Schemas, policies, actions, queries, views, and tests remain authored inside `features/`.
+
+## Common commands
+
+| Command | Purpose |
+|---|---|
+| `pnpm loomstack context --json` | Inspect the project and architectural rules |
+| `pnpm loomstack context feature <name> --json` | Inspect one feature before editing |
+| `pnpm loomstack create feature <name> --json` | Scaffold a canonical feature |
+| `pnpm loomstack affected <file> --json` | Find related authored files |
+| `pnpm loomstack generate --json` | Regenerate deterministic wiring |
+| `pnpm loomstack verify --json` | Verify contracts, boundaries, and generated files |
+| `pnpm loomstack dev status --json` | Check development service status |
+| `pnpm loomstack doctor --json` | Diagnose environment and setup problems |
+| `pnpm loomstack explain <code> --json` | Get repair guidance for a stable error code |
 
-## Options
+## Creator options
 
 ```text
 create-loomstack-app <name> [--cwd <directory>] [--json]
 ```
 
-After creation:
+- `<name>` must be lowercase kebab-case.
+- `--cwd` selects the parent directory.
+- `--json` emits one machine-readable result document.
+- Existing target directories are never overwritten.
+
+You can also run the initializer directly:
 
 ```bash
-cd my-app
-pnpm install
-pnpm loomstack init
+npx create-loomstack-app@latest my-app
+```
+
+## Troubleshooting
+
+Check the local environment:
+
+```bash
+pnpm loomstack doctor --json
+```
+
+If a command returns a `loomstack…` error code, inspect its repair contract:
+
+```bash
+pnpm loomstack explain <code> --json
 ```
+
+Normal source edits use hot reload. Run `pnpm loomstack dev refresh --json` only after dependency, Dockerfile, Compose, or environment changes.
+
+## Links
+
+- [Documentation](https://github.com/DenizOkcu/loomstack/tree/master/docs)
+- [Architecture](https://github.com/DenizOkcu/loomstack/blob/master/docs/architecture.md)
+- [CLI contracts](https://github.com/DenizOkcu/loomstack/blob/master/docs/commands.md)
+- [GitHub repository](https://github.com/DenizOkcu/loomstack)
+- [Issue tracker](https://github.com/DenizOkcu/loomstack/issues)

package/dist/{chunk-QTMEZJHE.js → chunk-PJ2RR44E.js}

@@ -30,157 +30,157 @@ var ERROR_CATALOG = {
     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"
+    docs: "https://github.com/DenizOkcu/loomstack/blob/master/docs/architecture.md#verification-and-errors"
   },
   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"
+    docs: "https://github.com/DenizOkcu/loomstack/blob/master/docs/architecture.md#feature-contracts"
   },
   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"
+    docs: "https://github.com/DenizOkcu/loomstack/blob/master/docs/architecture.md#actions-queries-and-policies"
   },
   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"
+    docs: "https://github.com/DenizOkcu/loomstack/blob/master/docs/architecture.md#actions-queries-and-policies"
   },
   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"
+    docs: "https://github.com/DenizOkcu/loomstack/blob/master/docs/architecture.md#feature-contracts"
   },
   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"
+    docs: "https://github.com/DenizOkcu/loomstack/blob/master/docs/architecture.md#feature-contracts"
   },
   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"
+    docs: "https://github.com/DenizOkcu/loomstack/blob/master/docs/architecture.md#actions-queries-and-policies"
   },
   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"
+    docs: "https://github.com/DenizOkcu/loomstack/blob/master/docs/architecture.md#actions-queries-and-policies"
   },
   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"
+    docs: "https://github.com/DenizOkcu/loomstack/blob/master/docs/architecture.md#react-presentation"
   },
   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"
+    docs: "https://github.com/DenizOkcu/loomstack/blob/master/docs/architecture.md#schemas-and-persistence"
   },
   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"
+    docs: "https://github.com/DenizOkcu/loomstack/blob/master/docs/architecture.md#feature-contracts"
   },
   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"
+    docs: "https://github.com/DenizOkcu/loomstack/blob/master/docs/architecture.md#verification-and-errors"
   },
   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"
+    docs: "https://github.com/DenizOkcu/loomstack/blob/master/docs/architecture.md#verification-and-errors"
   },
   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"
+    docs: "https://github.com/DenizOkcu/loomstack/blob/master/docs/architecture.md#verification-and-errors"
   },
   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"
+    docs: "https://github.com/DenizOkcu/loomstack/blob/master/docs/architecture.md#actions-queries-and-policies"
   },
   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"
+    docs: "https://github.com/DenizOkcu/loomstack/blob/master/docs/architecture.md#actions-queries-and-policies"
   },
   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"
+    docs: "https://github.com/DenizOkcu/loomstack/blob/master/docs/architecture.md#actions-queries-and-policies"
   },
   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"
+    docs: "https://github.com/DenizOkcu/loomstack/blob/master/docs/architecture.md#koa-transport"
   },
   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"
+    docs: "https://github.com/DenizOkcu/loomstack/blob/master/docs/architecture.md#koa-transport"
   },
   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"
+    docs: "https://github.com/DenizOkcu/loomstack/blob/master/docs/architecture.md#koa-transport"
   },
   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"
+    docs: "https://github.com/DenizOkcu/loomstack/blob/master/docs/architecture.md#generation"
   },
   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"
+    docs: "https://github.com/DenizOkcu/loomstack/blob/master/docs/architecture.md#generation"
   },
   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"
+    docs: "https://github.com/DenizOkcu/loomstack/blob/master/docs/architecture.md#application-structure"
   },
   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"
+    docs: "https://github.com/DenizOkcu/loomstack/blob/master/docs/commands.md#creation"
   },
   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"
+    docs: "https://github.com/DenizOkcu/loomstack/blob/master/docs/architecture.md#application-structure"
   },
   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"
+    docs: "https://github.com/DenizOkcu/loomstack/blob/master/docs/architecture.md#schemas-and-persistence"
   }
 };
 function frameworkError(code, options = {}) {
@@ -677,7 +677,7 @@ function appTemplateFiles(appName) {
   return {
     "package.json": `${JSON.stringify({
       name: appName,
-      version: "0.0.1",
+      version: "0.0.2",
       private: true,
       type: "module",
       packageManager: "pnpm@11.11.0",
@@ -694,10 +694,10 @@ function appTemplateFiles(appName) {
         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",
+        "@loomstack/cli": "^0.0.2",
+        "@loomstack/react": "^0.0.2",
+        "@loomstack/runtime": "^0.0.2",
+        "@loomstack/postgres": "^0.0.2",
         "@types/node": "^24.0.0",
         "@types/react": "^19.0.0",
         "@types/react-dom": "^19.0.0",
@@ -931,13 +931,13 @@ volumes:
     "features/.gitkeep": "",
     "apps/web/package.json": `${JSON.stringify({
       name: `@${appName}/web`,
-      version: "0.0.1",
+      version: "0.0.2",
       private: true,
       type: "module",
       scripts: { dev: "vite", build: "vite build" },
       dependencies: {
-        "@loomstack/react": "^0.0.1",
-        "@loomstack/runtime": "^0.0.1",
+        "@loomstack/react": "^0.0.2",
+        "@loomstack/runtime": "^0.0.2",
         "@vitejs/plugin-react": "^6.0.3",
         react: "^19.2.7",
         "react-dom": "^19.2.7",
@@ -996,14 +996,14 @@ export default defineConfig({
 `,
     "apps/api/package.json": `${JSON.stringify({
       name: `@${appName}/api`,
-      version: "0.0.1",
+      version: "0.0.2",
       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",
+        "@loomstack/koa": "^0.0.2",
+        "@loomstack/runtime": "^0.0.2",
+        "@loomstack/postgres": "^0.0.2",
         koa: "^3.2.1",
         "koa-bodyparser": "^4.4.1"
       },
@@ -1083,7 +1083,7 @@ Create a production-ready loomstack application.`);
   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("-")
+    (value, index) => value !== "--json" && value !== "--cwd" && (cwdIndex < 0 || index !== cwdIndex + 1) && !value.startsWith("-")
   );
   const name = positional[0];
   if (!name || cwdIndex >= 0 && !cwdValue) {
@@ -1094,7 +1094,7 @@ Repair: ${error.repair}`);
     return 1;
   }
   try {
-    const result = createApp(resolve4(cwdValue ?? process.cwd()), name);
+    const result = createApp(resolve4(cwdValue ?? io.cwd?.() ?? process.cwd()), name);
     if (json) io.stdout(JSON.stringify({ ok: true, data: result }));
     else {
       io.stdout(`Created loomstack app: ${result.appName}`);

package/dist/cli.js

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

package/dist/index.d.ts

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

package/dist/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-loomstack-app",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Create a full-stack loomstack application",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
     "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@loomstack/generator": "0.0.1"
+    "@loomstack/generator": "0.0.2"
   },
   "engines": {
     "node": ">=22.0.0"