Merge remote-tracking branch 'origin/main' into claude/issue-16025-hono-auth-mount-basepath

Author: claude

.changeset/flow-template-leaves-outside-filters.md

@@ -0,0 +1,11 @@
+---
+"@objectstack/lint": patch
+---
+
+`flow-template-unknown-field` and `flow-template-lookup-traversal` now reach a `{record.<field>}` template that sits outside a node filter — the `warning` half both rules already declared, and never emitted.
+
+A `{record.<field>}` token in a filter has always been reported as an `error`: an unresolved token there erases the condition and the CRUD node refuses to run. A token anywhere else — a message body, an http request payload, a created row's field values — is the quiet failure the rules were written for: it renders as an empty string on every run, and nothing reports it at either end — no build-time finding, no run-time error — so a hand-off payload naming a renamed field ships an empty value and the run is recorded as a success. That half was silent.
+
+The cause was one key, in the shared flow walk rather than in either rule. A rule that scans a node's config recursively has to read a view of it with the nested regions removed, or it reports every finding inside a `loop` / `try_catch` / `parallel` a second time against the container. That view was built by removing every key that holds a region on *any* node type — and `body` is `loop`'s region slot **and** the canonical request-payload key on an `http` node. So `config.body` was deleted from every node's view before any rule read it, and the whole of an http payload was invisible. The view now removes only the slots the node's own type declares, which is exactly the set the walk descended into: nothing is double-reported, and nothing that was never a region is dropped.
+
+Expect new `warning` findings on flows that publish clean today. Each one names a token that renders empty at run time; `warning` does not change `os validate`'s exit code, so a build that passed still passes.

.changeset/scaffold-skills-single-committed-copy.md

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

.changeset/visibility-bare-identifier-has-occurrence.md

@@ -0,0 +1,11 @@
+---
+"@objectstack/lint": patch
+---
+
+`visibility-bare-identifier` now reports an identifier written bare beside a `has()` guard in the same visibility predicate.
+
+`has(status) && status == "qualified"` published clean while `status == "qualified"` — the same defect, without the guard — gated at `error`. The guarded spelling is the one the totality discipline pushes authors toward, so an author who correctly adds `has()` and forgets the `record.` prefix on both halves landed in the silent row. That predicate never evaluates for any record, and an unevaluable `visibleWhen` on a form surface fails OPEN: the field renders and carries its `required: true` into the console's submit check.
+
+The cause was not the exclusion a `has()` argument earns — that is correct and stays. `firstUndeclaredReference` reads the first error the CEL checker reports and acts only on `Unknown variable: X`; a bare `has(x)` fails that check with `has() invalid argument` instead, and a first error of a different class masked every undeclared reference behind it in the same predicate, whatever it was called. Each `has(…)` call is now masked out of the source before the checker sees it, using the canonical AST's own spans, so the argument occurrence is excluded and every other occurrence is judged exactly as it would be with no guard written beside it.
+
+Expect new `error` findings on predicates that used to publish clean: a guarded-but-unprefixed `visibleWhen` on a view, page component or form section is now refused at build, validate and lint alike. That is the fail-open shape the rule exists to catch. A `has()` argument that is the only bare occurrence — `has(status)` on its own — stays silent, as it did before.

packages/cli/src/commands/generate-field-type-vocabulary.pin.test.ts

@@ -512,8 +512,10 @@ describe('#14828 — the SQL answers are the platform’s, not this file’s inv
       expect(
         tsColumn(type),
         `os generate migration (typescript) gave a ${type} column something other than a string ` +
-        'column. A platform id is 26 characters (driver-sql spells one out in its lookup arm), ' +
-        'so a `uuid` column refuses it outright on Postgres with 22P02.',
+        'column. A platform id is not a uuid, and its width is not a fixed number (driver-sql\'s ' +
+        'lookup arm states both: it mints a 16-character nanoid, and stores a supplied id at ' +
+        'whatever width the caller chose), so a `uuid` column refuses it outright on Postgres ' +
+        'with 22P02.',
       ).toBe(`table.string('f_${type}')`);
     }
     // The width is knex's default for a bare `table.string(name)`, which is the

packages/cli/src/commands/generate-multiple-json-column.pin.test.ts

@@ -273,7 +273,9 @@ describe('#14829 — `multiple: true` is one answer across all three surfaces',
   it('#14828 discharged — the five disputed SCALAR answers are the platform’s', () => {
     // A reference column holds the target's `id`: `table.string(name)`, knex's
     // varchar(255). `table.uuid` was the one HARD failure of the five — a
-    // platform id is 26 characters and Postgres refuses one in a `uuid` column.
+    // platform id is not a uuid, and its width is not a fixed number (driver-sql
+    // mints a 16-character nanoid, and stores a supplied id at whatever width
+    // the caller chose), so Postgres refuses one in a `uuid` column.
     expect(sqlColumn('single_lookup')).toBe('VARCHAR(255)');
     expect(tsColumn('single_lookup')).toBe("table.string('single_lookup')");
 

packages/cli/src/commands/generate.ts

@@ -992,10 +992,13 @@ async function runClientGeneration(configPath: string | undefined, flags: { outp
  *   `lookup` /    VARCHAR(36) → VARCHAR(255), with the migration switch's
  *   `master_detail`             `table.uuid` corrected in the same breath. The
  *                 `uuid` half is the only HARD failure of the five: a platform
- *                 id is 26 characters (`createColumn`'s lookup arm says so and
- *                 spells one out — `01JQ8XKZ9M4N7P2R5T6V8W0Y3B`), and Postgres
- *                 refuses one in a `uuid` column with `22P02`. The width half
- *                 is the same rule for the whole REFERENCE_VALUE_TYPES class:
+ *                 id is NOT a uuid, and its width is not a fixed number at all
+ *                 (`createColumn`'s lookup arm states both): the driver mints a
+ *                 16-character nanoid when the caller supplies none, and stores
+ *                 a SUPPLIED id verbatim at whatever width the caller chose.
+ *                 Postgres refuses either in a `uuid` column with `22P02`. The
+ *                 width half is the same rule for the whole
+ *                 REFERENCE_VALUE_TYPES class:
  *                 `user` and `tree` moved with them, because a reference column
  *                 holds the TARGET's `id` — which the driver itself emits as
  *                 `table.string('id').primary()`, i.e. `varchar(255)` — and
@@ -1886,10 +1889,12 @@ export function generateMigrationTs(config: Record<string, unknown>): string {
         // answer: `createColumn`'s `case 'lookup': case 'user':` is
         // `table.string(name)`, and `master_detail` reaches the same call
         // through its catch-all. `table.uuid` was the one HARD failure among
-        // this card's five rows — a platform id is 26 characters
-        // (`01JQ8XKZ9M4N7P2R5T6V8W0Y3B`, spelled out in that same driver arm),
-        // and Postgres refuses one in a `uuid` column with `22P02 invalid
-        // input syntax for type uuid` on the very first insert.
+        // this card's five rows — a platform id is NOT a uuid, and its width
+        // is not a fixed number at all: that same driver arm mints a
+        // 16-character nanoid when the caller supplies no id, and stores a
+        // SUPPLIED one verbatim at whatever width the caller chose. Postgres
+        // refuses either in a `uuid` column with `22P02 invalid input syntax
+        // for type uuid` on the very first insert.
         case 'lookup': case 'master_detail':
         case 'user': case 'tree':
         case 'image': case 'file': case 'avatar': case 'video': case 'audio':

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

packages/create-objectstack/src/created-summary.ts

@@ -28,15 +28,18 @@
 //
 //   1. template copy + identity rewrite + AGENTS.md/copilot-instructions.md
 //   2. `<pm> install`                      -> pnpm-lock.yaml, node_modules/
-//   3. `npx skills add … --all`            -> .agents/, agent/, .claude/,
-//                                             skills-lock.json
+//   3. `npx skills add … --agent …`        -> .claude/, skills-lock.json
 //
 // and the list was printed between (1) and (2). Phases 2 and 3 are third-party
 // processes whose outputs this package does not choose and cannot enumerate
-// ahead of time — the `skills` CLI fans out to every agent runtime it knows,
-// and that set changes with ITS releases, not ours. So any hand-maintained
-// list is not merely incomplete, it is unmaintainable: it drifts the next time
-// a dependency learns a new destination, silently, in the one direction that
+// ahead of time. Phase 3's destination set was the sharpest case: the run
+// measured above used `--all`, which fanned the catalog out to `.agents/`,
+// `agent/` AND `.claude/` — three trees, all committed, which is the defect
+// `skills-install.ts` now closes by naming one agent. Naming it does not make
+// the destination OURS to enumerate: the path is still the skills CLI's
+// choice, and it moves with ITS releases. So any hand-maintained list is not
+// merely incomplete, it is unmaintainable: it drifts the next time a
+// dependency learns a new destination, silently, in the one direction that
 // hides files rather than inventing them.
 //
 // Reading the directory afterwards is what makes the summary self-correcting.

packages/create-objectstack/src/index.ts

@@ -39,11 +39,12 @@
  * `--skip-install` there is no resolved version, so the template keeps `latest`
  * and its comment keeps telling the reader to pin by hand — true in that path.
  *
- * Finally we (best-effort) install the ObjectStack skills bundle via
- * `npx skills add objectstack-ai/objectstack/skills --all`.
- * The `/skills` subpath scopes discovery to the curated, customer-published
- * catalog — repo-internal skills (e.g. under `.claude/skills/`) must never
- * reach scaffolded projects.
+ * Finally we (best-effort) install the ObjectStack skills bundle, for ONE
+ * agent runtime (`skills-install.ts` carries the command and the measurement
+ * behind that choice: `--all` writes the same bundle to three destinations and
+ * the project then commits all three). The `/skills` subpath scopes discovery
+ * to the curated, customer-published catalog — repo-internal skills (e.g.
+ * under `.claude/skills/` in THIS repo) must never reach scaffolded projects.
  *
  * Only THEN is the "Created files" summary printed, and it is a walk of the
  * finished project directory rather than a list accumulated during the copy
@@ -72,6 +73,13 @@ import {
 import { lookupTemplate, templateNames } from './template-registry.js';
 import { readResolvedCliVersion, pinRuntimeImage } from './runtime-image.js';
 import { summarizeTree, describeEntry } from './created-summary.js';
+import {
+  DEFAULT_SKILLS_AGENT,
+  DEFAULT_SKILLS_DIR,
+  EXAMPLE_OTHER_AGENT,
+  SKILLS_INSTALL_COMMAND,
+  skillsInstallHint,
+} from './skills-install.js';
 import { renderVersionBanner } from './banner.js';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -521,24 +529,26 @@ const program = new Command()
       }
 
       // Which top-level paths belong to the skills install is measured, not
-      // assumed: `skills add --all` fans the catalog out to every agent
-      // runtime IT knows about (77 at the version measured), so the
-      // destination set moves with that package's releases. Diffing the
-      // directory across the call keeps the ⚠ marks correct without this file
-      // carrying a list it cannot keep current.
+      // assumed. Naming one agent makes the destination set small and
+      // knowable (`skills-install.ts`), but it is still THEIR path to choose,
+      // and it moves with that package's releases — so the ⚠ marks come from
+      // diffing the directory across the call rather than from a list this
+      // file would have to keep current.
       const beforeSkills = topLevelNames(targetDir);
+      let skillsInstalled = false;
       if (!options.skipInstall && !options.skipSkills) {
         printStep('Installing AI skills for your coding agent...');
         try {
-          execSync('npx -y skills add objectstack-ai/objectstack/skills --all', {
+          execSync(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',
+              `    ${skillsInstallHint(DEFAULT_SKILLS_AGENT)}`,
           );
           console.log('');
         }
@@ -569,10 +579,29 @@ const program = new Command()
       console.log(chalk.dim(`    ${devLabel.padEnd(labelWidth)}# Start development server`));
       console.log(chalk.dim(`    ${validateLabel.padEnd(labelWidth)}# Verify metadata: schema + predicates + bindings`));
       console.log(chalk.dim(`    ${' '.repeat(labelWidth)}# (run after every metadata edit — see AGENTS.md)`));
-      if (options.skipInstall || options.skipSkills) {
-        console.log('');
+      // The skills block is printed on EVERY path, not only the skipped one.
+      // The install now targets a single agent runtime, so a run that
+      // succeeded still leaves every other runtime uninstalled — and a
+      // capability that is absent has to say so, with the remedy, rather than
+      // leave the reader to discover the gap. The command printed here is the
+      // one this scaffolder ran, with a different agent name.
+      console.log('');
+      if (skillsInstalled) {
+        console.log(chalk.bold('  AI Skills:'));
+        console.log(
+          chalk.dim(
+            `    Installed for ${DEFAULT_SKILLS_AGENT} → ${DEFAULT_SKILLS_DIR} — commit it with your project.`,
+          ),
+        );
+        console.log(chalk.dim('    Using a different agent? Add it one runtime at a time:'));
+        console.log(chalk.dim(`      ${skillsInstallHint(EXAMPLE_OTHER_AGENT)}`));
+        console.log(chalk.dim('      (`npx skills add --help` lists every agent name)'));
+      } else {
         console.log(chalk.bold('  AI Skills (recommended):'));
-        console.log(chalk.dim('    npx skills add objectstack-ai/objectstack/skills'));
+        console.log(chalk.dim(`    ${skillsInstallHint(DEFAULT_SKILLS_AGENT)}`));
+        console.log(
+          chalk.dim(`    Replace \`${DEFAULT_SKILLS_AGENT}\` with your own agent runtime if it differs.`),
+        );
       }
       console.log('');
     } catch (error) {