create-objectstack 10.0.0 → 10.3.0

package/dist/index.js

@@ -238,6 +238,29 @@ function rewriteProjectIdentity(targetDir, projectName, namespace) {
     md = md.replace(/^#\s+.*$/m, `# ${title}`);
     fs.writeFileSync(readmePath, md);
   }
+  writeAgentGuides(targetDir, title, projectName);
+}
+function writeAgentGuides(targetDir, title, projectName) {
+  const templatePath = path.join(BUNDLED_TEMPLATES_DIR, "AGENTS.md");
+  let template;
+  try {
+    template = fs.readFileSync(templatePath, "utf8");
+  } catch (err) {
+    if (err?.code === "ENOENT") return;
+    throw err;
+  }
+  const rendered = template.replace(/\{\{PROJECT_TITLE\}\}/g, title).replace(/\{\{PROJECT_NAME\}\}/g, projectName);
+  writeIfAbsent(path.join(targetDir, "AGENTS.md"), rendered);
+  const copilotPath = path.join(targetDir, ".github", "copilot-instructions.md");
+  fs.mkdirSync(path.dirname(copilotPath), { recursive: true });
+  writeIfAbsent(copilotPath, rendered);
+}
+function writeIfAbsent(filePath, contents) {
+  try {
+    fs.writeFileSync(filePath, contents, { flag: "wx" });
+  } catch (err) {
+    if (err?.code !== "EEXIST") throw err;
+  }
 }
 var program = new Command().name("create-objectstack").description("Create a new ObjectStack environment").version(readCliVersion()).argument("[name]", "Environment name (defaults to current directory name)").option(
   "-t, --template <template>",
@@ -325,7 +348,8 @@ var program = new Command().name("create-objectstack").description("Create a new
       console.log(chalk.dim("    npm install"));
     }
     console.log(chalk.dim("    npm run dev           # Start development server"));
-    console.log(chalk.dim("    npm run validate      # Check configuration"));
+    console.log(chalk.dim("    npm run validate      # Verify metadata: schema + predicates + bindings"));
+    console.log(chalk.dim("                          # (run after every metadata edit \u2014 see AGENTS.md)"));
     if (options.skipInstall || options.skipSkills) {
       console.log("");
       console.log(chalk.bold("  AI Skills (recommended):"));

package/dist/templates/{copilot-instructions.md → AGENTS.md}

@@ -1,6 +1,8 @@
-# {{PROJECT_TITLE}} — Copilot Instructions
+# {{PROJECT_TITLE}} — Agent Instructions
 
-> Auto-generated by `create-objectstack`. Customise freely.
+> Auto-generated by `create-objectstack`. Read by Claude Code, Cursor, Codex
+> (`AGENTS.md`) and GitHub Copilot (`.github/copilot-instructions.md`).
+> Customise freely.
 
 ## Project Context
 
@@ -10,6 +12,27 @@ that defines business objects, views, automations, and AI agents in TypeScript.
 - **Entry point:** `objectstack.config.ts` (uses `defineStack()`)
 - **Spec package:** `@objectstack/spec` (Zod-first schemas and types)
 
+## Verify your work (do this after every metadata change)
+
+Metadata mistakes fail **silently at runtime**, not at edit time — a bare field
+reference in a predicate (`done` instead of `record.done`) evaluates to `null`
+and silently hides an action on every record; a dangling widget binding renders
+an empty chart. Catch them before you ship:
+
+```bash
+npm run validate      # schema + CEL predicates + widget bindings (no artifact)
+npm run typecheck     # TypeScript types against @objectstack/spec
+```
+
+`npm run validate` runs the **same gates as `npm run build`** (Zod protocol
+schema, CEL/predicate validation with `record.<field>` existence checks, and
+dashboard widget-binding integrity) but emits no `dist/` — so it is the fast
+inner-loop check after editing an `*.object.ts` / `*.view.ts` / `*.action.ts` /
+`*.flow.ts`. Both exit non-zero with a located, corrective message on failure.
+Run `npm run build` when you need the compiled `dist/objectstack.json` artifact.
+
+**Never report a metadata change as done until `npm run validate` passes.**
+
 ## Naming Conventions
 
 | Context | Convention | Example |
@@ -25,6 +48,10 @@ that defines business objects, views, automations, and AI agents in TypeScript.
 2. `defineStack()` is the single configuration entry point in `objectstack.config.ts`.
 3. Use `Object.values()` barrel pattern for metadata arrays.
 4. Import from `@objectstack/spec` — never use relative paths into the spec package.
+5. **Predicates are CEL** — `visible`, `disabled`, `requiredWhen`, validation rules,
+   flow conditions and sharing rules reference record fields as `record.<field>`,
+   never bare `<field>`. A bare reference is a silent runtime bug (`npm run validate`
+   now rejects it).
 
 ## Project Structure
 

package/dist/templates/blank/README.md

@@ -16,6 +16,20 @@ The REST API is served at `http://localhost:3000/api`.
 - `objectstack.config.ts` — environment manifest (objects, API, plugins)
 - `src/objects/` — object definitions (one file per object)
 
+## Verify your changes
+
+After editing any metadata, run:
+
+```bash
+pnpm validate     # schema + CEL predicates + widget bindings (no artifact)
+pnpm typecheck    # TypeScript types against @objectstack/spec
+```
+
+`pnpm validate` runs the same gates as `pnpm build` and catches mistakes that
+otherwise fail *silently at runtime* — e.g. a bare `done` (instead of
+`record.done`) in an action predicate that would hide the action on every
+record. See `AGENTS.md` for the full convention.
+
 ## Next steps
 
 - Add an object: see the `objectstack-data` skill.

package/dist/templates/blank/package.json

@@ -4,8 +4,8 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "objectstack serve --watch",
-    "start": "objectstack serve",
+    "dev": "objectstack dev",
+    "start": "objectstack start",
     "build": "objectstack build",
     "validate": "objectstack validate",
     "typecheck": "tsc --noEmit"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-objectstack",
-  "version": "10.0.0",
+  "version": "10.3.0",
   "description": "Create a new ObjectStack project — npx create-objectstack",
   "bin": {
     "create-objectstack": "./bin/create-objectstack.js"