feat(create-objectstack): ship a CI workflow in the blank template so a scaffolded app has gates from its first push (#16364)

* feat(create-objectstack): ship a CI workflow in the blank template

The scaffolder already created `.github/` at runtime for one file
(copilot-instructions.md) while the template's own gates — `validate` and
`typecheck` — shipped as npm scripts nothing ever ran, so every scaffolded
project started with zero CI and the "metadata mistakes fail silently at
runtime, the gates are where they surface" claim rested on a human
remembering to type the command.

Adds `.github/workflows/ci.yml` to the blank template: one job, one file,
checkout -> pnpm/action-setup -> setup-node (Node 22, pnpm cache) ->
`pnpm install --frozen-lockfile` -> `pnpm validate` -> `pnpm typecheck`.

No `pnpm lint` step: the blank template declares no `lint` script and
neither scaffolder writes one, so that step would fail on the first push of
every scaffolded project. The new test derives the allowed step set from the
template's package.json so the two cannot drift.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PbJ5Cy9KDAzeQHo8bsMadG

* fix(docs-audit): scope the dot-directory prune premise to the files the walk collects

`walkSourceFiles` prunes every dot-directory under `packages/**` as build
residue, and `--self-test` re-measures the premise that makes that safe rather
than quoting it. The premise was stated over ALL tracked files, but the walk
collects `.ts` and nothing else, so it was strictly stronger than the property
the prune rests on.

The blank project template now commits `.github/workflows/ci.yml` — a template
asset this audit has never had a reason to read — which reds the pin while the
prune's actual safety is untouched. A false positive about a real premise is
the shape most likely to get a good pin deleted, so the measurement is scoped to
the extension the walk collects and stays armed for the first tracked `.ts`
under a dot-directory, which is the case the comment describes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PbJ5Cy9KDAzeQHo8bsMadG

* feat(create-objectstack): the blank template declares `lint`, and CI runs it

The workflow shipped `validate` and `typecheck` only, because the template
declared no `lint` script and a step naming one would have failed on the first
push of every scaffolded project. Adding the script is inside this package, so
the omission rested on an untested option rather than on a measurement.

Measured instead: scaffolded a project for real from the repo-built scaffolder,
installed its dependencies from the registry (@objectstack/cli 17.3.0), wired
`"lint": "objectstack lint"` and ran it — exit 0, "All checks passed". So the
script and the step both land.

`lint` is not a second spelling of `validate`. `validate.ts` and `lint.ts` share
the authoring-rule engine, but `checkHookBodyLowering` is imported by `lint.ts`
alone — so without this step a scaffolded project has no way to reach the
hook-body lowering rule, one of the two defects this card was filed about.

The derived-step test now requires `lint` alongside `validate` and `typecheck`,
and still derives the ALLOWED set from the template's own package.json, so the
step list and the script list cannot drift apart in either direction.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PbJ5Cy9KDAzeQHo8bsMadG

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: claude[bot]

.changeset/scaffold-blank-template-ci-workflow.md

@@ -0,0 +1,24 @@
+---
+"create-objectstack": minor
+---
+
+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.

packages/create-objectstack/package.json

@@ -34,7 +34,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",

packages/create-objectstack/src/template-ci-workflow.test.ts

@@ -0,0 +1,221 @@
+// Copyright (c) 2026 ObjectStack contributors. Apache-2.0 license.
+//
+// The bundled template's own CI workflow (#16330).
+//
+// The scaffolder already creates a `.github/` directory at runtime — for one
+// file, `copilot-instructions.md` — while the template's gates (`validate`,
+// `typecheck`) shipped as npm scripts nothing ever ran. A scaffolded project
+// therefore started with zero CI, and the product claim that metadata mistakes
+// surface at authoring time rested entirely on a human remembering to type the
+// command. `.github/workflows/ci.yml` is the fix; this file is what keeps it
+// honest.
+//
+// Three properties, each of which failed silently before it was pinned:
+//
+//   1. The file is real YAML. A workflow GitHub cannot parse is not reported as
+//      a broken workflow to the user who just scaffolded — it is reported as no
+//      CI at all, which is indistinguishable from the defect being fixed here.
+//   2. Every `pnpm <script>` step names a script the template's own
+//      package.json declares. This is not hypothetical: the template shipped no
+//      `lint` script while the card asked for a `pnpm lint` step, and that step
+//      would have failed on the first push of every scaffolded project with
+//      `Command "lint" not found`. The template now declares `lint` — measured
+//      green against a real scaffold before the step was added — and this pin
+//      is what keeps the step list and the script list from drifting apart
+//      again, in either direction.
+//   3. `.github/` survives the copy. It is the first dot-DIRECTORY the template
+//      has ever carried, and dotfiles have been a packaging problem here before
+//      (`_gitignore`; see TEMPLATE_FILE_ALIASES). The tarball half of that
+//      question is answered by the packing ratchet in
+//      `template-consistency.test.ts`, which packs for real; this file covers
+//      the scaffold-copy half.
+//
+// On the YAML dependency: the sibling `scaffold-e2e-boot-probe.test.ts`
+// deliberately hand-parses a workflow instead of importing a parser, because it
+// needs a `run:` block's bytes verbatim and a parser would normalise a
+// malformed file away. Here the parse IS the assertion, so that reasoning
+// inverts — and `yaml` is a devDependency, which never reaches the published
+// tarball (`files` ships `dist` alone).
+
+import { describe, it, expect } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parse as parseYaml } from 'yaml';
+import { copyDir } from './template-copy.js';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const pkgRoot = path.resolve(HERE, '..');
+const blankDir = path.join(pkgRoot, 'src', 'templates', 'blank');
+
+/** Where the workflow lives in the template, and where it must land in a scaffold. */
+const WORKFLOW_REL = '.github/workflows/ci.yml';
+const workflowPath = path.join(blankDir, ...WORKFLOW_REL.split('/'));
+
+interface WorkflowStep {
+  name?: string;
+  uses?: string;
+  run?: string;
+  with?: Record<string, unknown>;
+}
+
+const readWorkflow = (): Record<string, any> =>
+  parseYaml(fs.readFileSync(workflowPath, 'utf8')) as Record<string, any>;
+
+/**
+ * The `on:` block.
+ *
+ * Read through a fallback because `on` is a YAML **1.1** boolean literal: a
+ * parser on that schema returns the trigger block under the key `true`, not
+ * `"on"`. This package parses with `yaml`, which defaults to the 1.2 core
+ * schema and keeps the string — the fallback is here so a schema change
+ * downgrades to a still-correct read instead of an assertion about `undefined`.
+ */
+const triggersOf = (doc: Record<string, any>): unknown =>
+  doc.on ?? doc[true as unknown as string];
+
+const stepsOf = (doc: Record<string, any>): WorkflowStep[] =>
+  Object.values(doc.jobs as Record<string, { steps?: WorkflowStep[] }>).flatMap(
+    (job) => job.steps ?? [],
+  );
+
+describe('bundled template CI workflow', () => {
+  it('ships a workflow at .github/workflows/ci.yml', () => {
+    expect(
+      fs.existsSync(workflowPath),
+      `the blank template must carry ${WORKFLOW_REL} — without it every scaffolded ` +
+        'project starts with no CI and its validate/typecheck scripts are advisory',
+    ).toBe(true);
+  });
+
+  it('parses as YAML and declares at least one job with steps', () => {
+    const doc = readWorkflow();
+    expect(typeof doc, 'the workflow did not parse to a mapping').toBe('object');
+    expect(doc.name).toBeTruthy();
+
+    const jobs = doc.jobs as Record<string, { steps?: unknown[] }>;
+    expect(Object.keys(jobs).length, 'the workflow declares no jobs').toBeGreaterThan(0);
+    for (const [id, job] of Object.entries(jobs)) {
+      expect(Array.isArray(job.steps), `job "${id}" declares no steps`).toBe(true);
+      expect(job.steps!.length, `job "${id}" has an empty step list`).toBeGreaterThan(0);
+    }
+  });
+
+  it('runs on push and on pull_request', () => {
+    const triggers = triggersOf(readWorkflow());
+    const names = Array.isArray(triggers)
+      ? triggers.map(String)
+      : Object.keys(triggers as Record<string, unknown>);
+    expect(names).toContain('push');
+    expect(names).toContain('pull_request');
+  });
+
+  // The load-bearing one. A workflow step naming a script the project does not
+  // declare fails with `Command "<script>" not found` on the first push — a
+  // scaffold whose CI is red out of the box teaches the user to ignore CI,
+  // which is worse than shipping none. Derived from the template's real
+  // package.json rather than restated, so adding a step for a script that does
+  // not exist (or deleting a script a step runs) reds here.
+  it('runs only package.json scripts the template actually declares', () => {
+    const templatePkg = JSON.parse(
+      fs.readFileSync(path.join(blankDir, 'package.json'), 'utf8'),
+    ) as { scripts: Record<string, string> };
+
+    const invoked: string[] = [];
+    for (const step of stepsOf(readWorkflow())) {
+      if (!step.run) continue;
+      for (const line of step.run.split('\n')) {
+        // `pnpm <word>` where <word> is not a pnpm builtin is a script run.
+        const m = /^\s*pnpm(?:\s+run)?\s+([a-z][a-z0-9:_-]*)/i.exec(line);
+        if (!m) continue;
+        const word = m[1];
+        if (word === 'install' || word === 'exec' || word === 'dlx') continue;
+        invoked.push(word);
+      }
+    }
+
+    expect(invoked.length, 'the workflow runs no project script at all').toBeGreaterThan(0);
+    for (const script of invoked) {
+      expect(
+        Object.keys(templatePkg.scripts),
+        `${WORKFLOW_REL} runs \`pnpm ${script}\`, but the blank template's package.json ` +
+          'declares no such script — the step would fail on the first push of every ' +
+          'scaffolded project. Add the script to the template (and to the other ' +
+          'scaffolder, packages/cli/src/commands/init.ts) or drop the step.',
+      ).toContain(script);
+    }
+
+    // The three gates this workflow exists to run. `lint` is here on a
+    // MEASUREMENT, not on the card's wording: scaffolded for real from the
+    // repo-built scaffolder, `npm install` against the registry, then
+    // `npm run lint` -> exit 0, "All checks passed". It is not a second
+    // spelling of `validate` either — `validate.ts` and `lint.ts` share the
+    // authoring-rule engine but only `lint.ts` imports `checkHookBodyLowering`,
+    // so dropping this step drops that rule from every scaffolded project.
+    expect(invoked).toContain('validate');
+    expect(invoked).toContain('lint');
+    expect(invoked).toContain('typecheck');
+  });
+
+  // Derived from the Dockerfile's build stage rather than restated: the
+  // template states its Node floor there (its `engines` block carries only a
+  // pnpm floor), so these are the same declaration and must not drift.
+  it('pins the same Node major the template Dockerfile builds on', () => {
+    const dockerfile = fs.readFileSync(path.join(blankDir, 'Dockerfile'), 'utf8');
+    const fromNode = /^FROM\s+node:(\d+)[-\s]/m.exec(dockerfile);
+    expect(fromNode, 'the template Dockerfile no longer builds on a node: base image').toBeTruthy();
+
+    const setupNode = stepsOf(readWorkflow()).find((s) => s.uses?.startsWith('actions/setup-node@'));
+    expect(setupNode, 'the workflow has no actions/setup-node step').toBeTruthy();
+    expect(
+      String(setupNode!.with!['node-version']),
+      "the workflow's Node pin and the Dockerfile's build image are one declaration",
+    ).toBe(fromNode![1]);
+  });
+
+  // pnpm must be on PATH before setup-node runs, because `cache: pnpm` makes
+  // setup-node shell out to pnpm to locate the store. Getting the order wrong
+  // does not degrade — it kills the job in the setup step.
+  it('acquires pnpm before the setup-node step that caches through it', () => {
+    const steps = stepsOf(readWorkflow());
+    const pnpmAt = steps.findIndex((s) => s.uses?.startsWith('pnpm/action-setup@'));
+    const nodeAt = steps.findIndex((s) => s.uses?.startsWith('actions/setup-node@'));
+    expect(pnpmAt, 'the workflow never acquires pnpm').toBeGreaterThanOrEqual(0);
+    expect(nodeAt).toBeGreaterThanOrEqual(0);
+    if (String(steps[nodeAt].with?.cache ?? '') === 'pnpm') {
+      expect(
+        pnpmAt,
+        'setup-node with `cache: pnpm` shells out to pnpm; acquiring pnpm after it ' +
+          'fails the job with "Unable to locate executable file: pnpm"',
+      ).toBeLessThan(nodeAt);
+    }
+  });
+
+  it('pins every action to a version tag', () => {
+    for (const step of stepsOf(readWorkflow())) {
+      if (!step.uses) continue;
+      expect(step.uses, `unpinned action reference: ${step.uses}`).toMatch(/@v\d+/);
+    }
+  });
+
+  // The dot-DIRECTORY half of the packaging question. `.github/` is the first
+  // one this template has carried; `copyDir` is what materialises a scaffold,
+  // so this is the real copy, not a re-implementation of it. The tarball half
+  // — whether `npm pack` strips the directory — is answered by the packing
+  // ratchet in template-consistency.test.ts, which packs for real.
+  it('lands in a scaffold under its real dot-directory name', () => {
+    const out = fs.mkdtempSync(path.join(os.tmpdir(), 'create-objectstack-ci-'));
+    try {
+      const collected: string[] = [];
+      copyDir(blankDir, out, collected);
+
+      const landed = path.join(out, ...WORKFLOW_REL.split('/'));
+      expect(fs.existsSync(landed), `${WORKFLOW_REL} did not survive the scaffold copy`).toBe(true);
+      expect(collected).toContain(WORKFLOW_REL);
+      expect(fs.readFileSync(landed, 'utf8')).toBe(fs.readFileSync(workflowPath, 'utf8'));
+    } finally {
+      fs.rmSync(out, { recursive: true, force: true });
+    }
+  });
+});

packages/create-objectstack/src/template-consistency.test.ts

@@ -365,6 +365,17 @@ describe('templates survive npm packing', () => {
     expect(rules).toContain('.env');
   });
 
+  // The first dot-DIRECTORY the template has ever carried (#16330). The set
+  // comparison above already covers it, but it names nothing: a strip of
+  // `.github` would read there as "some file went missing". Naming the path
+  // literally, the way the .dockerignore case below does, is what makes the
+  // answer to "do nested dot-directories survive `npm pack`?" readable.
+  it('carries the .github workflow directory through the tarball and the scaffold', () => {
+    expect(packed).toContain('blank/.github/workflows/ci.yml');
+    expect(scaffolded).toContain('.github/workflows/ci.yml');
+    expect(TEMPLATE_FILE_ALIASES.has('.github')).toBe(false);
+  });
+
   it('leaves a literal template dotfile that packs fine alone', () => {
     // .dockerignore is NOT stripped — verified against the published 15.1.1
     // tarball, which ships it while .gitignore is absent. It stays literal, so

packages/create-objectstack/src/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

packages/create-objectstack/src/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
 ```
 

packages/create-objectstack/src/templates/blank/package.json

@@ -11,6 +11,7 @@
     "start": "objectstack start",
     "build": "objectstack build",
     "validate": "objectstack validate",
+    "lint": "objectstack lint",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {