create-objectstack 17.3.0 → 17.4.0

package/CHANGELOG.md

@@ -1,5 +1,102 @@
 # create-objectstack
 
+## 17.4.0
+
+### Minor Changes
+
+- 4998efa: Scaffolded projects now ship a CI workflow, and a `lint` script for it to run.
+  The blank template carries `.github/workflows/ci.yml` — one job, on `push` and
+  `pull_request`: checkout, pnpm, Node 22, `pnpm install --frozen-lockfile`, then
+  `pnpm validate`, `pnpm lint` and `pnpm typecheck`.
+  
+  `lint` is new to the template (`objectstack lint`). It is not a second spelling
+  of `validate`: the two share the authoring-rule engine but only `lint` runs the
+  hook-body lowering check, which catches handlers that have silently stopped
+  lowering to metadata-only bodies — a change of deployment shape produced by a
+  refactor that looks like tidying.
+  
+  The scaffolder already created `.github/` at runtime for a single file
+  (`copilot-instructions.md`) while the template's gates shipped as npm scripts
+  nothing ever ran, so a fresh project started with no CI at all — and ObjectStack
+  metadata mistakes fail silently at runtime, which makes `objectstack validate`
+  the only place they surface early. That gate is now unskippable for a human and
+  for an AI agent authoring metadata in the project, instead of advisory.
+  
+  Existing projects are unaffected; copy the file from a fresh scaffold to adopt
+  it.
+- 813d6c5: `npx create-objectstack` now declares the same TypeScript range as `os init` and
+  `os create`, and the value is generated rather than restated.
+  
+  Three scaffolders write a new project's `package.json`, and the range that
+  decides whether that project type-checks at all had split: `os init` and
+  `os create` emitted `typescript: ^5.3.0` from a shared emission policy, while
+  this package's bundled template carried `^6.0.0`. Two projects created the same
+  day got different TypeScript **majors** depending on which documented entry
+  point the reader followed.
+  
+  - **What changed for a scaffolded project.** Its declared `typescript`
+    devDependency floor moves from `^6.0.0` to `^5.3.0`. Both resolve to the same
+    installed compiler on a fresh install; what moves is the floor the project
+    **declares**, and a floor is a support promise. `^5.3.0` is the promise the
+    docs already make — "ObjectStack works with TypeScript 5.3+" on the getting
+    started page, "TypeScript 5.3.0 or later" in the deployment troubleshooting
+    page — and it is measured rather than assumed: TypeScript 5.3.3 type-checks
+    every shape these scaffolders emit with results identical to 6.0.3. The repo's
+    own `typescript@^6.0.3` devDependency is deliberately not this value; the same
+    doc sentence states both halves ("…but the project itself is built and tested
+    against TypeScript 6.x"). `engines.pnpm` was already in agreement and is now
+    held there by the same mechanism.
+  - **Why the value is generated.** This package cannot import from
+    `@objectstack/cli`: the dependency edge runs the other way, and the `npx`
+    package must not pull the CLI's package closure. So the values are stamped
+    into the bundled template at build time by
+    `scripts/sync-scaffold-emission-policy.mjs`, read out of the same
+    `SCAFFOLD_*` constants the other two scaffolders import, and
+    `pnpm check:scaffold-emission-policy` reddens the moment the inlined values
+    disagree with that source. Editing the two into agreement by hand would have
+    left them free to diverge again on the next move, silently, for the same
+    structural reason — which is how they diverged the first time.
+- fd75728: Scaffolded projects now install the AI skills bundle for **one** agent runtime
+  instead of every runtime the skills CLI knows, so the bundle is committed once.
+  
+  **Route B of the two the card offered was taken**, and the choice was measured
+  rather than argued. Against `skills@1.5.23` and the 11-skill catalog, the old
+  `--all` (shorthand for `--skill '*' --agent '*' -y`) wrote the same bundle to
+  three destinations — `.agents/` (46 real files, 604,102 B), `agent/` (46 real
+  files, 602,682 B, identical bodies with re-serialised frontmatter) and
+  `.claude/` (11 symlinks into `.agents/`). The template's `.gitignore` excluded
+  none of it, so a new project's first `git add -A` staged 22 `SKILL.md` paths
+  plus 11 symlinks. That reached the initial commit of a real app before anyone
+  noticed.
+  
+  The scaffolder now runs
+  `npx skills add objectstack-ai/objectstack/skills --skill '*' --agent claude-code -y`,
+  which writes 46 real files to `.claude/skills/` and nothing else: 11 staged
+  `SKILL.md` paths, no symlinks, and a clone of that commit has readable skill
+  files on every platform.
+  
+  Route A (keep `--all`, exclude the duplicates in the template `_gitignore`) was
+  built and cloned, not reasoned about, and both of its shapes were rejected.
+  Ignoring `.agents/` and `agent/` while committing `.claude/` gives a fresh
+  cloner 11 dangling symlinks and zero readable `SKILL.md`. Ignoring only
+  `agent/` works on POSIX but commits 11 symlinks that a `core.symlinks=false`
+  clone — git-for-Windows' default — materialises as ordinary files whose whole
+  content is the link target. `--all --copy`, the other way to make `.claude/`
+  real, fans out to 56 destination directories totalling 33.8 MB. A denylist is
+  also the wrong shape regardless of which paths it names: this package does not
+  choose the destination set, the skills CLI does, and it moves with that
+  package's releases.
+  
+  The cost is the multi-runtime default, and it is paid in the open: the closing
+  summary now always prints an **AI Skills** block naming where the bundle landed
+  and the one-line command for any other runtime, one agent at a time. The
+  bundle is identical whichever agent is named.
+  
+  Existing projects are unaffected. To shrink one that already carries the
+  triplicate, delete `.agents/` and `agent/` and re-run the single-agent command
+  above; `skills-lock.json` records source and hash, not paths, so it does not
+  change.
+
 ## 17.3.0
 
 ### Minor Changes

package/README.md

@@ -56,9 +56,12 @@ you so rather than failing as an unknown template.
    every object name in the template is re-prefixed to match
    (`blank_note` → `my_app_note`).
 2. Installs dependencies (pnpm if available, otherwise npm).
-3. Installs the ObjectStack AI skills bundle for coding agents
-   (`npx skills add objectstack-ai/objectstack/skills --all` — scoped to the
-   curated `skills/` catalog).
+3. Installs the ObjectStack AI skills bundle for **one** coding agent —
+   `npx skills add objectstack-ai/objectstack/skills --skill '*' --agent claude-code -y`,
+   scoped to the curated `skills/` catalog. One agent, not `--all`, so the
+   bundle lands in exactly one directory (`.claude/skills/`) and a scaffolded
+   project commits it once; `src/skills-install.ts` carries the measurement.
+   The closing summary prints the same command for any other runtime.
 4. Writes `AGENTS.md` and `.github/copilot-instructions.md` with the project
    conventions — unless the template ships its own.
 

package/dist/index.js

@@ -245,6 +245,19 @@ function pinRuntimeImage(targetDir, version) {
   return { pinned: true, tag: version };
 }
 
+// src/skills-install.ts
+var SKILLS_CATALOG = "objectstack-ai/objectstack/skills";
+var DEFAULT_SKILLS_AGENT = "claude-code";
+var DEFAULT_SKILLS_DIR = ".claude/skills/";
+var EXAMPLE_OTHER_AGENT = "codex";
+function skillsAddArgs(agent) {
+  return `skills add ${SKILLS_CATALOG} --skill '*' --agent ${agent} -y`;
+}
+var SKILLS_INSTALL_COMMAND = `npx -y ${skillsAddArgs(DEFAULT_SKILLS_AGENT)}`;
+function skillsInstallHint(agent) {
+  return `npx ${skillsAddArgs(agent)}`;
+}
+
 // src/banner.ts
 import chalk from "chalk";
 var PREFIX = "   \u25C6 Create ObjectStack ";
@@ -526,17 +539,20 @@ var program = new Command().name("create-objectstack").description("Create a new
       }
     }
     const beforeSkills = topLevelNames(targetDir);
+    let skillsInstalled = false;
     if (!options.skipInstall && !options.skipSkills) {
       printStep("Installing AI skills for your coding agent...");
       try {
-        execSync2("npx -y skills add objectstack-ai/objectstack/skills --all", {
+        execSync2(SKILLS_INSTALL_COMMAND, {
           stdio: "inherit",
           cwd: targetDir
         });
+        skillsInstalled = true;
         console.log("");
       } catch {
         printWarning(
-          "Skills installation skipped. Run manually:\n    npx skills add objectstack-ai/objectstack/skills"
+          `Skills installation skipped. Run manually:
+    ${skillsInstallHint(DEFAULT_SKILLS_AGENT)}`
         );
         console.log("");
       }
@@ -560,10 +576,23 @@ var program = new Command().name("create-objectstack").description("Create a new
     console.log(chalk2.dim(`    ${devLabel.padEnd(labelWidth)}# Start development server`));
     console.log(chalk2.dim(`    ${validateLabel.padEnd(labelWidth)}# Verify metadata: schema + predicates + bindings`));
     console.log(chalk2.dim(`    ${" ".repeat(labelWidth)}# (run after every metadata edit \u2014 see AGENTS.md)`));
-    if (options.skipInstall || options.skipSkills) {
-      console.log("");
+    console.log("");
+    if (skillsInstalled) {
+      console.log(chalk2.bold("  AI Skills:"));
+      console.log(
+        chalk2.dim(
+          `    Installed for ${DEFAULT_SKILLS_AGENT} \u2192 ${DEFAULT_SKILLS_DIR} \u2014 commit it with your project.`
+        )
+      );
+      console.log(chalk2.dim("    Using a different agent? Add it one runtime at a time:"));
+      console.log(chalk2.dim(`      ${skillsInstallHint(EXAMPLE_OTHER_AGENT)}`));
+      console.log(chalk2.dim("      (`npx skills add --help` lists every agent name)"));
+    } else {
       console.log(chalk2.bold("  AI Skills (recommended):"));
-      console.log(chalk2.dim("    npx skills add objectstack-ai/objectstack/skills"));
+      console.log(chalk2.dim(`    ${skillsInstallHint(DEFAULT_SKILLS_AGENT)}`));
+      console.log(
+        chalk2.dim(`    Replace \`${DEFAULT_SKILLS_AGENT}\` with your own agent runtime if it differs.`)
+      );
     }
     console.log("");
   } catch (error) {

package/dist/templates/AGENTS.md

@@ -73,13 +73,19 @@ Run `npm run build` when you need the compiled `dist/objectstack.json` artifact.
 
 ## AI Skills
 
-This project uses ObjectStack skills from `objectstack-ai/objectstack`.
-Install or update skills with the standard [skills CLI](https://skills.sh/):
+This project uses ObjectStack skills from `objectstack-ai/objectstack`. They
+were installed for one agent runtime, live in `.claude/skills/`, and are
+committed with the project. Install or update them with the standard
+[skills CLI](https://skills.sh/), naming your runtime:
 
 ```bash
-npx skills add objectstack-ai/objectstack/skills
+npx skills add objectstack-ai/objectstack/skills --skill '*' --agent claude-code -y
 ```
 
+Adding a second runtime? Re-run it with that runtime's `--agent` name.
+⛔ Do not use `--all`: it writes the same bundle to `.agents/`, `agent/` and
+`.claude/` at once, and all three then land in your next commit.
+
 Skills are triggered automatically based on task context:
 
 | Skill | Trigger Context |

package/dist/templates/blank/.github/workflows/ci.yml

@@ -0,0 +1,67 @@
+# Continuous integration for this ObjectStack app.
+#
+# ObjectStack metadata fails SILENTLY at runtime, not at edit time: a mistyped
+# permission grant or a bare field name in an action predicate raises nothing,
+# it just behaves wrongly for whoever hits it first. `objectstack validate` is
+# where that class surfaces — and running it is something a human, or an AI
+# agent authoring metadata in this project, has to remember. This workflow is
+# what makes it unskippable. AGENTS.md carries the authoring conventions it
+# enforces.
+#
+# One job, one file: a starting point, not a CI framework. Grow it with the
+# project — add a step when you add a script, a second job when you deploy.
+
+name: CI
+
+on: [push, pull_request]
+
+# Read-only. Nothing here writes to the repository or publishes anything.
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    name: Validate
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v7
+
+      # pnpm BEFORE setup-node, deliberately. `cache: pnpm` below makes
+      # setup-node shell out to pnpm to locate the store, so pnpm has to be on
+      # PATH by then. Reversed, this does not degrade — the job dies in the
+      # setup step with "Unable to locate executable file: pnpm".
+      #
+      # `version` is explicit because this project declares no `packageManager`
+      # field — pinning one would make the project pnpm-only, and a
+      # corepack-driven npm or yarn then refuses to run in it — so
+      # pnpm/action-setup has nothing to resolve from. Keep this in step with
+      # the `engines.pnpm` floor in package.json.
+      - uses: pnpm/action-setup@v6
+        with:
+          version: 10
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '22'
+          cache: pnpm
+
+      # `--frozen-lockfile` installs exactly what the lockfile records and fails
+      # when the two disagree, so `pnpm-lock.yaml` has to be committed.
+      # Scaffolding wrote it for you unless you passed `--skip-install`; in that
+      # case run `pnpm install` once and commit the result.
+      - run: pnpm install --frozen-lockfile
+
+      # The gate this file exists for: schema, CEL predicates and widget
+      # bindings. The same checks `pnpm build` runs, without producing an
+      # artifact.
+      - run: pnpm validate
+
+      # Not a second spelling of `validate`. The two share the authoring-rule
+      # engine but not the rule set — the hook-body lowering check, which
+      # catches handlers that silently stop lowering to metadata-only bodies
+      # (a change of deployment shape, from a refactor that looks like
+      # tidying), runs here and nowhere else.
+      - run: pnpm lint
+
+      - run: pnpm typecheck

package/dist/templates/blank/README.md

@@ -100,6 +100,8 @@ After editing any metadata, run:
 
 ```bash
 pnpm validate     # schema + CEL predicates + widget bindings (no artifact)
+pnpm lint         # authoring rules validate does not run — e.g. a handler that
+                  # stopped lowering to a metadata-only body
 pnpm typecheck    # TypeScript types against @objectstack/spec
 ```
 
@@ -138,5 +140,10 @@ covered in [Self-Hosted Deployment](https://objectstack.ai/docs/deployment/self-
 - Add a flow or automation: see `objectstack-automation`.
 - Add an AI agent: see `objectstack-ai`.
 
-Skills are installed with `npx skills add objectstack-ai/objectstack/skills`
-(see `AGENTS.md`) and also show up in the in-IDE assistant catalog.
+Skills live in `.claude/skills/` and are committed with this project, once.
+They are installed one agent runtime at a time (see `AGENTS.md`), and also show
+up in the in-IDE assistant catalog:
+
+```bash
+npx skills add objectstack-ai/objectstack/skills --skill '*' --agent claude-code -y
+```

package/dist/templates/blank/package.json

@@ -11,6 +11,7 @@
     "start": "objectstack start",
     "build": "objectstack build",
     "validate": "objectstack validate",
+    "lint": "objectstack lint",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
@@ -23,6 +24,6 @@
   },
   "devDependencies": {
     "@objectstack/cli": "^17.0.0",
-    "typescript": "^6.0.0"
+    "typescript": "^5.3.0"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-objectstack",
-  "version": "17.3.0",
+  "version": "17.4.0",
   "description": "Create a new ObjectStack project — npx create-objectstack",
   "bin": {
     "create-objectstack": "./bin/create-objectstack.js"
@@ -28,7 +28,8 @@
     "@types/node": "^26.2.0",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.10",
+    "yaml": "^2.9.0"
   },
   "repository": {
     "type": "git",
@@ -49,7 +50,7 @@
     "node": ">=22.0.0"
   },
   "scripts": {
-    "build": "tsup && node ../../scripts/check-dts-emitted.mjs",
+    "build": "node ../../scripts/sync-scaffold-emission-policy.mjs && tsup && node ../../scripts/check-dts-emitted.mjs",
     "typecheck": "tsc --noEmit",
     "dev": "tsup --watch",
     "test": "vitest run"