@starci/hfs 4.7.34 → 4.7.36

package/runtime/scripts/lib/source-package-imports.mjs

@@ -0,0 +1,111 @@
+// Source-package imports preserve published export and exact dependency contracts without a workspace install.
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire, registerHooks } from 'node:module';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { insidePath, pathKey, realPath } from './path-key.mjs';
+
+const packageNameOf = (specifier) => specifier.startsWith('@') ? specifier.split('/').slice(0, 2).join('/') : specifier.split('/')[0];
+
+function conditionalTarget(value, conditions) {
+  if (typeof value === 'string' || value === null) return value;
+  if (Array.isArray(value)) return value.map(entry => conditionalTarget(entry, conditions)).find(entry => entry !== undefined);
+  if (!value || typeof value !== 'object') return undefined;
+  for (const [condition, target] of Object.entries(value)) {
+    if (condition === 'default' || conditions.includes(condition)) {
+      const selected = conditionalTarget(target, conditions);
+      if (selected !== undefined) return selected;
+    }
+  }
+}
+
+/** Resolve only exports that the package publishes; private paths remain unavailable in a source checkout. */
+function exportedTarget(exports, subpath, conditions) {
+  if (!exports || typeof exports !== 'object' || Array.isArray(exports)) return subpath === '.' ? conditionalTarget(exports, conditions) : undefined;
+  const keys = Object.keys(exports);
+  if (keys.every(key => !key.startsWith('.'))) return subpath === '.' ? conditionalTarget(exports, conditions) : undefined;
+  if (Object.hasOwn(exports, subpath)) return conditionalTarget(exports[subpath], conditions);
+  const patterns = keys.filter(key => key.includes('*')).sort((a, b) => b.indexOf('*') - a.indexOf('*') || b.length - a.length);
+  for (const pattern of patterns) {
+    const [prefix, suffix] = pattern.split('*');
+    if (!subpath.startsWith(prefix) || !subpath.endsWith(suffix)) continue;
+    const match = subpath.slice(prefix.length, suffix ? -suffix.length : undefined);
+    const target = conditionalTarget(exports[pattern], conditions);
+    return typeof target === 'string' ? target.replaceAll('*', match) : target;
+  }
+}
+
+function sourcePackages(root, packages) {
+  return Object.entries(packages).filter(([, pin]) => typeof pin?.source === 'string').map(([name, pin]) => {
+    const manifestFile = realPath(path.resolve(root, pin.source));
+    if (!insidePath(root, manifestFile, { key: pathKey })) throw new Error(`Source package ${name} is outside the source tree`);
+    return { name, pin, manifestFile, root: path.dirname(manifestFile), manifest: null };
+  }).sort((a, b) => b.root.length - a.root.length);
+}
+
+function manifestOf(source) {
+  source.manifest ??= JSON.parse(fs.readFileSync(source.manifestFile, 'utf8'));
+  if (source.manifest.name !== source.name || source.manifest.version !== source.pin.version) {
+    throw new Error(`Source package ${source.name} does not match its pinned name and version`);
+  }
+  return source.manifest;
+}
+
+/** Settle each declared bare dependency before installing a hook, using the consumer first and source install second. */
+function consumerDependencyTargets(sources, consumerRoot) {
+  const consumer = createRequire(path.join(consumerRoot, 'package.json'));
+  for (const source of sources) {
+    const manifest = manifestOf(source), local = createRequire(source.manifestFile);
+    source.consumerDependencies = new Map();
+    for (const name of Object.keys({ ...manifest.peerDependencies, ...manifest.optionalDependencies, ...manifest.dependencies })) {
+      for (const require of [consumer, local]) {
+        try { source.consumerDependencies.set(name, pathToFileURL(require.resolve(name)).href); break; }
+        catch { /* The next install may carry the dependency; a missing import still fails through the native resolver. */ }
+      }
+    }
+  }
+}
+
+function resolveSource(specifier, context, nextResolve, sources, consumerRoot) {
+  if (!context.parentURL?.startsWith('file:')) return nextResolve(specifier, context);
+  const parent = fileURLToPath(context.parentURL);
+  const owner = sources.find(source => insidePath(source.root, parent, { key: pathKey }));
+  const target = sources.find(source => source.name === packageNameOf(specifier));
+  if (!target) {
+    const dependency = owner?.consumerDependencies?.get(specifier);
+    return dependency ? { url: dependency, shortCircuit: true } : nextResolve(specifier, context);
+  }
+  if (!owner && (!consumerRoot || !insidePath(consumerRoot, parent, { key: pathKey }))) return nextResolve(specifier, context);
+  const manifest = manifestOf(target);
+  if (owner) {
+    const caller = manifestOf(owner);
+    const dependency = caller.dependencies?.[target.name] ?? caller.devDependencies?.[target.name] ?? caller.optionalDependencies?.[target.name];
+    if (owner !== target && dependency !== manifest.version) throw new Error(`${owner.name} must declare its source dependency ${target.name}@${manifest.version} exactly`);
+  }
+  const subpath = `.${specifier.slice(target.name.length)}`;
+  const published = exportedTarget(manifest.exports, subpath, context.conditions);
+  if (typeof published !== 'string' || !published.startsWith('./')) throw new Error(`${specifier} is not a published source-package export`);
+  const resolved = path.resolve(target.root, published);
+  if (!insidePath(target.root, resolved, { key: pathKey }) || published.split('/').includes('node_modules')) throw new Error(`${specifier} has an invalid source-package export target`);
+  return { url: pathToFileURL(resolved).href, shortCircuit: true };
+}
+
+/**
+ * Await source imports with pinned local packages resolved through their own public exports.
+ * Imports originating inside a declared source package obey exact dependency versions and public exports.
+ * An explicit consumerRoot also redirects that consumer's selected source-package imports and resolves source
+ * packages' declared bare imports and requires from the consumer install first. This keeps a parser and its
+ * typed rules on the same dependency instances. The hook is removed on success or failure; callers await
+ * every import and dependent action. Normal installed-package resolution remains in force afterward.
+ * @param {{ root: string, packages: Record<string, { version: string, source?: string }>, consumerRoot?: string }} input - Canonical source pins and an optional bounded consumer source root.
+ * @param {() => Promise<unknown>} action - Imports whose package contracts are being checked.
+ * @returns {Promise<unknown>} The action's result, without a persistent resolver change.
+ */
+export async function withSourcePackageImports({ root, packages, consumerRoot }, action) {
+  const sources = sourcePackages(realPath(root), packages);
+  const consumer = consumerRoot === undefined ? null : realPath(consumerRoot);
+  if (consumer) consumerDependencyTargets(sources, consumer);
+  const hook = registerHooks({ resolve: (specifier, context, nextResolve) => resolveSource(specifier, context, nextResolve, sources, consumer) });
+  try { return await action(); }
+  finally { hook.deregister(); }
+}

package/runtime/scripts/work/draw/draw-layer.mjs

@@ -2,7 +2,7 @@
 // "this is KNOWLEDGE, not golden rules" - the runtime catches these from knowledge and gates, never from owner feedback).
 //
 //   DRAW_NESTED_VARIANT    knowledge/ui/proof/anatomy-source.yaml ANATOMY-2. The layer chain is page Background ->
-//                          Surface -> nested control: every form control ON a surface (a SurfaceCard of any frame, a
+//                          Surface -> nested control: every form control ON a painted surface (a SurfaceCard, a
 //                          card, a dialog / drawer panel) carries HeroUI's nested `secondary` variant - the choice
 //                          controls (Checkbox, RadioGroup, ...) as much as the text fields (case-1); a form region
 //                          (fields plus a primary submit) stands in a Surface, never directly on the Background
@@ -39,9 +39,9 @@ const VARIANT_CONTROLS = Object.freeze(['Input', 'Textarea', 'Select', 'ComboBox
 /** Every grammar field control (the variant ones plus those without a vendor variant): what makes a region a form. */
 const FIELD_CONTROLS = Object.freeze([...VARIANT_CONTROLS, 'Switch', 'Slider', 'FileDropzone']);
 /** Components that paint a surface of their own. */
-const SURFACE_COMPONENTS = Object.freeze(['SurfaceCard', 'SurfaceListCard', 'SurfaceAccordionCard', 'Rail', 'Sidebar', 'Dialog', 'Drawer', 'AlertDialog', 'Popover']);
+const SURFACE_COMPONENTS = Object.freeze(['SurfaceCard', 'SurfaceListCard', 'Sidebar', 'Dialog', 'Drawer', 'AlertDialog', 'Popover']);
 /** Boolean surface-owner hooks emitted by Grammar compositions. */
-const SURFACE_STAMPS = Object.freeze(['data-grammar-surface', 'data-grammar-surface-card', 'data-grammar-surface-list', 'data-grammar-surface-accordion-card', 'data-grammar-rail']);
+const SURFACE_STAMPS = Object.freeze(['data-grammar-surface', 'data-grammar-surface-card', 'data-grammar-surface-list', 'data-grammar-surface-accordion-card']);
 /** The vendor class prefixes that carry the layer variant (`<prefix>--primary|secondary`). */
 const VARIANT_CLASS_PREFIXES = Object.freeze(['input', 'input-group', 'textfield', 'textarea', 'select', 'combo-box', 'search-field', 'number-field',
   'date-input-group', 'date-field', 'time-field', 'date-picker', 'checkbox', 'checkbox-group', 'radio-group', 'input-otp']);
@@ -49,8 +49,9 @@ const VARIANT_CLASS_PREFIXES = Object.freeze(['input', 'input-group', 'textfield
 const VARIANT_CLASS = new RegExp(`^(?:${VARIANT_CLASS_PREFIXES.join('|')})--(primary|secondary)$`);
 const componentOf = (attrs) => attrs?.['data-component'] ?? attrs?.['data-grammar-component'] ?? null;
 
-/** Whether one parsed/DOM element establishes a surface nesting boundary, including frameless compositions. */
+/** Whether one parsed/DOM element paints a surface; unpainted layout containers inherit their parent. */
 function isSurface({ component, attrs, classes }) {
+  if (attrs['data-grammar-frame'] === 'frameless') return false;
   if (SURFACE_COMPONENTS.includes(component)) return true;
   if (attrs['data-grammar-nesting'] === 'surface') return true;
   if (SURFACE_STAMPS.some((stamp) => attrs[stamp] === 'true')) return true;

package/scaffold/app.mjs

@@ -33,6 +33,7 @@ import { init as gitInit } from '../runtime/scripts/api/git/init.mjs';
 import { insidePath, samePath } from '../runtime/scripts/lib/path-key.mjs';
 import { byCodeUnit } from '../report/order.mjs';
 import { sonarGateName } from '../sync/sonar-key.mjs';
+import { grammarLintFor } from '../runtime/scripts/lib/grammar-lint.mjs';
 
 const NAME = /^[a-z][a-z0-9-]*$/;
 const APP_DIR = '__app__';
@@ -126,7 +127,7 @@ export const packageJsonText = value => `${JSON.stringify(value, null, 2)}\n`;
 const STARTER_SIDES = Object.freeze({
   be: Object.freeze({ apps: [{ name: 'core', kind: 'api' }, { name: 'cli', kind: 'cli' }], kinds: ['api', 'cli'], connections: [{ name: 'primary', envPrefix: 'PRIMARY_DB', owner: 'core', isolation: 'database' }] }),
   // fe: the landing and the product app, over the shared ui and i18n packages (both opt-in slots, enabled here).
-  fe: Object.freeze({ apps: [{ name: 'landing', kind: 'next' }, { name: 'app', kind: 'next' }], reads: ['be/contracts/'], optionalSlots: ['fe.package.ui', 'fe.package.i18n'] }),
+  fe: Object.freeze({ grammar: 'starci', apps: [{ name: 'landing', kind: 'next' }, { name: 'app', kind: 'next' }], reads: ['be/contracts/'], optionalSlots: ['fe.package.ui', 'fe.package.i18n'] }),
 });
 
 /** The lite starter is the upgrade-safe subset: one API, one web app and one Supabase schema authority. */
@@ -137,7 +138,7 @@ const LITE_STARTER_SIDES = Object.freeze({
     connections: [{ name: 'primary', envPrefix: 'PRIMARY_DB', owner: 'api', isolation: 'schema', provider: 'supabase' }],
     reads: ['supabase/types/'],
   }),
-  fe: Object.freeze({ apps: [{ name: 'web', kind: 'next' }], reads: ['be/contracts/', 'supabase/types/'] }),
+  fe: Object.freeze({ grammar: 'starci', apps: [{ name: 'web', kind: 'next' }], reads: ['be/contracts/', 'supabase/types/'] }),
 });
 
 /** The checked local Supabase auth posture of every newly scaffolded lite app. */
@@ -313,9 +314,10 @@ const ROOT_OVERRIDES = Object.freeze(['@graphql-tools/utils', '@xyflow/react', '
  * The root package.json of a new app, the monorepo root: name, workspaces, npm, its edition's dependencies with their runtime
  * peers, the fe stack's root tools and the one-version overrides, at canon pins.
  */
-function packageManifest(name, pins, edition, stack = coreFeStackPackages()) {
+function packageManifest(name, pins, edition, grammar, stack = coreFeStackPackages()) {
   const dependencies = edition === 'lite' ? LITE_STARTER_DEPENDENCIES : STARTER_DEPENDENCIES;
-  const devDependencies = { ...dependencies.devDependencies, ...Object.fromEntries(stack.root.map(dependency => [dependency, null])) };
+  const grammarLint = grammarLintFor(grammar);
+  const devDependencies = { ...dependencies.devDependencies, ...Object.fromEntries(stack.root.map(dependency => [dependency, null])), ...(grammarLint.package ? { [grammarLint.package]: null } : {}) };
   const pkg = { name, version: '0.0.0', private: true, packageManager: PACKAGE_MANAGER, workspaces: [...WORKSPACES], dependencies: pinnedSection(dependencies.dependencies, pins), devDependencies: pinnedSection(devDependencies, pins) };
   pkg.dependencies = pinnedSection({ ...pkg.dependencies, ...peerDependencies(pkg, pins) }, pins);
   pkg.overrides = pinnedSection(Object.fromEntries(ROOT_OVERRIDES.map(dependency => [dependency, null])), pins);
@@ -667,7 +669,7 @@ export function scaffoldApp({ name, into, presets, edition = 'full', authCallbac
   const declaration = starterDeclaration(name, manifest, edition);
   if (authCallback) enableAuthCallback(declaration);
   const app = resolveRepoDeclaration(manifest, declaration);
-  const pkg = packageManifest(name, pins, app.edition);
+  const pkg = packageManifest(name, pins, app.edition, app.sides.fe.grammar);
   const timestamp = now().toISOString().replace(/\D/g, '').slice(0, 14);
   const files = [
     { path: 'hfs.json', content: jsonText(declaration) },

package/src/main.mjs

@@ -10,6 +10,8 @@
 //                                            --fast, and a repository without prettier is a refusal); soft-size backlog (report only); then the whole
 //                                            architecture machine (tiers, owners, clones, dead exports, module registration, the
 //                                            front-end and back-end source rules), each violation a finding with its why.
+//                                            ESLint executes once per side through the installed managed config; the FE config composes
+//                                            the universal canon and the explicitly selected Grammar-family canon.
 //                                            --fast: only what changed since the merge-base with origin/main (else main; --base
 //                                            overrides it); the machine
 //                                            runs on those owners without clones and dead exports. No merge-base is a refusal
@@ -60,7 +62,7 @@ import { createRequire } from 'node:module';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { isMain } from '../runtime/scripts/lib/is-main.mjs';
-import { checkDatabase, checkRepository, explainPath, trackedFiles, withCheckProofs } from '../runtime/scripts/hfs/check.mjs';
+import { changedSince, checkDatabase, checkRepository, explainPath, trackedFiles, withCheckProofs } from '../runtime/scripts/hfs/check.mjs';
 import { secretMain } from '../runtime/scripts/hfs/secret.mjs';
 import { dbBaselineMain } from '../runtime/scripts/hfs/db-baseline-verb.mjs';
 import { dbRestampMain } from '../runtime/scripts/hfs/db-restamp-verb.mjs';
@@ -79,7 +81,7 @@ import { addKind } from '../scaffold/add.mjs';
 import { scaffoldApp } from '../scaffold/app.mjs';
 import { newImages } from '../scaffold/image.mjs';
 import { contractEmitFindings } from '../runtime/scripts/hfs/rules/contract.mjs';
-import { lintRepository, parseLintArgs, printLintText } from '../lint/run.mjs';
+import { eslintRepository, lintRepository, parseLintArgs, printLintText } from '../lint/run.mjs';
 import { writeReport } from '../report/sonar.mjs';
 import { checkEdition } from '../upgrade/check.mjs';
 import { UpgradeError, upgradeMain } from '../upgrade/index.mjs';
@@ -89,13 +91,15 @@ import { dbMigrateMain } from '../db/migrate.mjs';
 import { dbPostCutoverMain } from '../db/post-cutover.mjs';
 import { dbDumpMain } from '../db/dump.mjs';
 import { dbResetMain } from '../db/reset.mjs';
+import { codemodMain } from '../codemod/button-intent.mjs';
 
-export const VERBS = Object.freeze(['scaffold', 'add', 'lint', 'sync', 'check', 'upgrade', 'stack', 'release', 'explain', 'emit', 'new', 'secret', 'ci', 'db', 'hygiene', 'coverage']);
+export const VERBS = Object.freeze(['scaffold', 'add', 'lint', 'sync', 'check', 'upgrade', 'stack', 'release', 'explain', 'emit', 'new', 'secret', 'ci', 'db', 'hygiene', 'coverage', 'codemod']);
 const DATABASE_VERBS = new Map([['baseline', dbBaselineMain], ['restamp', dbRestampMain], ['plan', dbPlanMain], ['migrate', dbMigrateMain], ['post-cutover', dbPostCutoverMain], ['dump', dbDumpMain], ['reset', dbResetMain]]);
 
 const USAGE = `starci app scaffold <name> [--into <dir>] [--edition full|lite] [--registry-visibility public|private] [--cwd <dir>]
 starci app add <api|webhook|realtime|saga|job|reactor|queue|projection|cli|table|app> <name> [options] [--cwd <dir>]
 starci app lint [--cwd <dir>] [--changed <file>...] [--workspace <dir>] [--side be|fe] [--fix] [--format text|json] [--sonar <file>]
+starci app codemod button-intent [--write] [--format json|markdown] [--report <file.json|file.md>] [--cwd <dir>]
 starci app sync (--check | --write) [--cwd <dir>]
 starci app check [--cwd <dir>] [--json] [--fast] [--base <ref>] [--db-types] [--wiring] [--coverage-from <lcov>]
 starci app db baseline [--stamp <version>] [--local] [--apply] [--cwd <dir>]
@@ -187,11 +191,17 @@ function printCheckOverview(result, out) {
   if (result.fast) out(`  ${result.fast.changed} path${result.fast.changed === 1 ? '' : 's'} changed since ${result.fast.base.slice(0, 12)}\n`);
   out(`  architecture machine: ${machineDescription(result.machine)}\n`);
   if (result.contracts) out(`  contract snapshots: ${contractDescription(result.contracts)}\n`);
+  if (result.eslint) {
+    const sides = Object.entries(result.eslint.sides).map(([side, run]) => `${side}: ${run.files} files${run.skipped ? ` (${run.skipped})` : ''}`).join(', ');
+    out(`  ESLint: ${sides}\n`);
+    for (const error of result.eslint.errors) out(`  ESLint tool error: ${error}\n`);
+  }
 }
 
 function printFindingGroup(code, list, out) {
   const first = list[0];
-  out(`\n[${first.level.toUpperCase()}] ${code} x${list.length}: ${first.titleVi}\n  ${first.whyVi}\n  -> ${first.nextStepVi}\n`);
+  if (first.engine === 'eslint') out(`\n[${first.level.toUpperCase()}] ${code} x${list.length}\n`);
+  else out(`\n[${first.level.toUpperCase()}] ${code} x${list.length}: ${first.titleVi}\n  ${first.whyVi}\n  -> ${first.nextStepVi}\n`);
   for (const finding of list.slice(0, PER_CODE_LIMIT)) out(`  - ${finding.message}\n`);
   if (list.length > PER_CODE_LIMIT) out(`  ... and ${list.length - PER_CODE_LIMIT} more (use --json for all)\n`);
 }
@@ -264,7 +274,7 @@ export function appRootAbove(dir) {
 }
 
 /** `starci app lint`: ESLint per side, the app checks and stylelint over the fe side as one report; see lint/run.mjs. */
-async function lintMain(argv, { cwd, stdout, presets, prettier }) {
+async function lintMain(argv, { cwd, stdout, presets, prettier, runLinter, checkApp = runCheck }) {
   const opts = parseLintArgs(argv);
   // --workspace names a folder from the working directory (`starci app lint --workspace .` is an fe workspace script); the app
   // root is then the nearest folder above it that holds hfs.json, and the workspace is passed on app-relative.
@@ -272,8 +282,8 @@ async function lintMain(argv, { cwd, stdout, presets, prettier }) {
   const repoRoot = path.resolve(workspaceDir ? appRootAbove(workspaceDir) : cwd);
   if (workspaceDir) opts.workspace = path.relative(repoRoot, workspaceDir).split(path.sep).join('/');
   const { report, sonar, exit } = await lintRepository({
-    repoRoot, opts, trackedFiles,
-    hfsCheck: (root) => runCheck({ repoRoot: root, only: opts.changed ?? undefined, presets, prettier }),
+    repoRoot, opts, trackedFiles, runLinter,
+    hfsCheck: (root) => checkApp({ repoRoot: root, only: opts.changed ?? undefined, presets, prettier }),
   });
   if (opts.sonar !== undefined) writeReport(path.resolve(cwd, opts.sonar), sonar);
   if (opts.format === 'json') stdout(`${JSON.stringify(report, null, 2)}
@@ -336,14 +346,19 @@ function printCheckProofs(result, out) {
   if (result.coverage) out(formatCoverageReport(result.coverage));
 }
 
-async function checkMain(opts, { cwd: repoRoot, edition, stdout: out, presets, prettier }) {
+async function checkMain(opts, { cwd: repoRoot, edition, stdout: out, presets, prettier, checkApp = runCheck, runLinter }) {
   if (opts.positional.length) throw new Error('starci app check takes no path');
   if (opts.base !== undefined && opts.fast !== true) throw new Error('--base names the ref --fast compares with; it needs --fast');
-  const checked = await checkEdition({ repoRoot, edition, normal: () => runCheck({ repoRoot, fast: opts.fast === true, base: opts.base, presets, prettier, dbTypes: opts['db-types'] === true }), presets, prettier });
-  const result = withCheckProofs(checked, { repoRoot, edition, wiring: opts.wiring === true, coverageFrom: opts['coverage-from'] });
+  const checked = await checkEdition({ repoRoot, edition, normal: () => checkApp({ repoRoot, fast: opts.fast === true, base: opts.base, presets, prettier, dbTypes: opts['db-types'] === true }), presets, prettier });
+  const proof = withCheckProofs(checked, { repoRoot, edition, wiring: opts.wiring === true, coverageFrom: opts['coverage-from'] });
+  const changed = opts.fast === true ? changedSince(repoRoot, proof.fast?.base ?? opts.base).files : null;
+  const existing = changed ? changed.filter(file => fs.existsSync(path.join(repoRoot, file))) : [];
+  const eslint = await eslintRepository({ repoRoot, changed, existing, run: runLinter });
+  const findings = [...proof.findings, ...eslint.findings.map(finding => ({ ...finding, code: finding.code ?? finding.rule, level: 'error' }))];
+  const result = { ...proof, findings, counts: { ...proof.counts, error: proof.counts.error + eslint.findings.length }, eslint: { ...eslint.engine, errors: eslint.errors }, ok: proof.ok && eslint.findings.length === 0 && eslint.errors.length === 0 };
   if (opts.json) out(`${JSON.stringify(result, null, 2)}\n`);
   else { printCheck(result, out); printCheckProofs(result, out); }
-  return result.ok ? 0 : 1;
+  return eslint.errors.length ? 2 : result.ok ? 0 : 1;
 }
 
 function emitMain(opts, { cwd: repoRoot, stdout: out, run }) {
@@ -418,7 +433,7 @@ async function stackAppMain(argv, { cwd, edition, stackMain, stdout: out, stderr
   return run(argv, { cwd, out, err });
 }
 
-const DIRECT_VERBS = new Map([['ci', async (argv, io) => (await import('../ci/cli.mjs')).ciMain(argv, io)], ['lint', lintMain], ['secret', secretMain], ['db', databaseMain], ['upgrade', upgradeAppMain], ['stack', stackAppMain], ['release', releaseMain], ['coverage', async (argv, io) => (await import('../coverage/cli.mjs')).coverageMain(argv, io)]]);
+const DIRECT_VERBS = new Map([['ci', async (argv, io) => (await import('../ci/cli.mjs')).ciMain(argv, io)], ['lint', lintMain], ['secret', secretMain], ['db', databaseMain], ['upgrade', upgradeAppMain], ['stack', stackAppMain], ['release', releaseMain], ['coverage', async (argv, io) => (await import('../coverage/cli.mjs')).coverageMain(argv, io)], ['codemod', codemodMain]]);
 const PARSED_VERBS = new Map([['check', checkMain], ['emit', emitMain], ['new', newMain], ['add', addMain], ['scaffold', scaffoldMain], ['explain', explainMain]]);
 
 function dispatchMain(verb, argv, io) {
@@ -434,10 +449,10 @@ function errorMessage(error) {
   return `starci app: ${error.message}\n${USAGE}`;
 }
 
-/** `run` injects the Supabase command runner and `stackIo` the spawn, fetch, sleep and clock seams of the Swarm tooling; IO and tool seams keep every verb independently testable. */
+/** `run` injects the Supabase runner, `runLinter` the linter transport, `checkApp` the HFS check and `stackIo` Swarm tools; production defaults execute every check. */
 export async function main(argv, {
   cwd: baseCwd = process.cwd(), stdout = (s) => process.stdout.write(s), stderr = (s) => process.stderr.write(s), presets, prettier, lock, run, stackMain,
-  env = process.env, stdin, sops, tools, platform, stackIo,
+  env = process.env, stdin, sops, tools, platform, stackIo, runLinter, checkApp,
 } = {}) {
   try {
     const global = globalOptions(argv, path.resolve(baseCwd));
@@ -445,7 +460,7 @@ export async function main(argv, {
     const out = global.quiet ? () => {} : stdout;
     if (global.help) { out(USAGE); return 0; }
     if (!VERBS.includes(verb)) { stderr(USAGE); return 2; }
-    return await dispatchMain(verb, rest, { cwd: global.cwd, edition: global.edition, stdout: out, stderr, presets, prettier, lock, run, stackMain, env, stdin, sops, tools, platform, stackIo });
+    return await dispatchMain(verb, rest, { cwd: global.cwd, edition: global.edition, stdout: out, stderr, presets, prettier, lock, run, stackMain, env, stdin, sops, tools, platform, stackIo, runLinter, checkApp });
   } catch (error) {
     stderr(errorMessage(error));
     return 2;

package/stack/config.mjs

@@ -9,7 +9,8 @@ import { refusal } from './errors.mjs';
 export const STACKS_DIR = '.starcistacks';
 export const STACKS_FILE = 'application-stacks.yaml';
 
-const readYaml = (file, what) => {
+/** Read a YAML input, refusing with a stack error naming its purpose when it is missing or invalid. */
+export const readYaml = (file, what) => {
   let source;
   try { source = fs.readFileSync(file, 'utf8'); } catch { throw refusal('STACKS_DEPLOY_FILE_MISSING', `${what} (${file}) is not readable`); }
   try { return parseYaml(source); } catch { throw refusal('STACKS_DEPLOY_FILE_INVALID', `${what} is not valid YAML`); }

package/stack/render.mjs

@@ -1,10 +1,12 @@
 // render.mjs - renders a release: the committed stack source plus a generated override (image references, plain environment, the
 // `<KEY>_FILE` pointers and the versioned secret grants) resolved by `docker stack config`. Writes `stack.generated.yaml`, `stack.yaml`
 // and `release.json` under the output directory, and nothing at all when a guard refuses. Output carries names and counts only; the
-// docker child gets a minimal environment, never the age identity or DOCKER_HOST.
+// docker child gets a minimal environment, never the age identity or DOCKER_HOST. The override mirrors the source's compose version:
+// Docker's legacy stack loader refuses mixed versions across its input files.
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { readYaml } from './config.mjs';
 import { tool } from './context.mjs';
 import { hasPlaceholderDigest, isImageReference, isReleaseId } from './digest.mjs';
 import { failure, refusal } from './errors.mjs';
@@ -35,6 +37,22 @@ function checkInputs(config, options) {
   if (options.previous !== null && options.previous !== undefined && !isReleaseId(options.previous)) throw refusal('STACK_PREVIOUS_INVALID', 'previous must be 16 lowercase hex characters');
 }
 
+/** Docker reads an absent, empty or 3 version as its current 3.x default; every other version must match exactly. */
+const versionKey = (version) => {
+  const text = version === undefined ? '' : String(version);
+  return text === '' || text === '3' ? null : text;
+};
+
+function checkComposeVersions(sourceVersion, extraCompose) {
+  for (const file of extraCompose) {
+    const version = readYaml(file, `the extra compose file ${path.basename(file)}`)?.version;
+    if (versionKey(version) !== versionKey(sourceVersion)) {
+      throw refusal('STACK_COMPOSE_VERSION_MISMATCH',
+        `${path.basename(file)} declares compose version ${version ?? '(none)'} but the stack source declares ${sourceVersion ?? '(none)'}; docker stack config refuses files whose versions differ`);
+    }
+  }
+}
+
 /** Compose interpolation treats `$` specially; the override doubles it so a value reaches the service unchanged. */
 const escapeDollar = (value) => value.replaceAll('$', '$$$$');
 
@@ -70,9 +88,10 @@ function serviceOverride(config, sealed, images, service) {
   return out;
 }
 
-function buildOverride(config, sealed, images) {
+function buildOverride(config, sealed, images, version) {
   const services = new Set([...Object.keys(config.images), ...Object.keys(config.environment), ...Object.keys(sealed.grants)]);
   return {
+    ...(version === undefined ? {} : { version }),
     services: Object.fromEntries([...services].sort((a, b) => a.localeCompare(b)).map((service) => [service, serviceOverride(config, sealed, images, service)])),
     secrets: Object.fromEntries(Object.entries(sealed.secrets).map(([key, entry]) => [key, { external: true, name: entry.runtimeName }])),
   };
@@ -124,9 +143,11 @@ function writeOutput(out, override, stackBytes, release) {
 /** Renders a release into `options.out` (a fresh temp directory when null). Effects stay local; nothing leaves the machine. */
 export async function renderRelease(ctx, config, options) {
   checkInputs(config, options);
+  const sourceVersion = readYaml(config.stackFile, 'the stack source')?.version;
+  checkComposeVersions(sourceVersion, options.extraCompose ?? []);
   const sealed = loadSealed(ctx, config);
   const configs = configObjects(config);
-  const override = buildOverride(config, sealed, options.images);
+  const override = buildOverride(config, sealed, options.images, sourceVersion);
   const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'stack-override-'));
   try {
     const overrideFile = path.join(scratch, 'stack.generated.yaml');

package/sync/index.mjs

@@ -35,6 +35,7 @@ import { isRuntimeExampleApp } from '../runtime/scripts/lib/runtime-example.mjs'
 import { ciWorkflowCommands } from './ci-commands.mjs';
 import { dependabotUpdates, hasDeclaredServices, readDeclaredQuality, readDeclaredBadges, sonarHostLine } from './quality-services.mjs';
 import { qualityServices } from '../runtime/scripts/hfs/ci-declaration.mjs';
+import { grammarLintFor } from '../runtime/scripts/lib/grammar-lint.mjs';
 
 export const TEMPLATES_DIR = path.join(import.meta.dirname, '..', 'templates');
 const NODE_MAJOR = 22;
@@ -133,11 +134,13 @@ function readBundled(name) {
 
 /**
  * Fill `{{name}}` from vars and expand `{{> partial}}` lines. A partial line may be written as a line comment (`// {{> partial}}`)
- * so a JavaScript template stays valid source before rendering. Empty variable-only lines disappear; an unknown name is an error.
+ * so a JavaScript template stays valid source before rendering. Variable-only lines may also use a line comment;
+ * empty variable-only lines disappear and an unknown name is an error.
  */
 export function render(text, vars, readTemplate = readBundled) {
   const withPartials = text.replace(/^(?:\/\/ )?\{\{> ([\w./-]+)\}\}\n/gm, (_, name) => trailingNewline(render(readTemplate(name), vars, readTemplate)));
-  const presentLines = withPartials.replace(/^[ \t]*\{\{([A-Za-z]\w*)\}\}[ \t]*(?:\n|$)/gm, (line, key) => vars[key] === '' ? '' : line);
+  const presentLines = withPartials.replace(/^[ \t]*(?:\/\/ )?\{\{([A-Za-z]\w*)\}\}[ \t]*(?:\n|$)/gm,
+    (line, key) => vars[key] === '' ? '' : line.replace(/^(\s*)\/\/ /, '$1'));
   return presentLines.replace(/\{\{([A-Za-z]\w*)\}\}/g, (_, key) => {
     if (!Object.hasOwn(vars, key)) throw new SyncError('HFS_SYNC_TEMPLATE_VARIABLE', `template names {{${key}}}, which sync does not provide`);
     return vars[key];
@@ -341,6 +344,7 @@ export function variables(app, scope, presets, sonarKey, manifest = loadSlotMani
   const lite = app.edition === 'lite';
   const providers = (app.sides.be.connections ?? []).map(connection => connection.provider);
   const quality = source.quality ?? qualityServices({});
+  const grammarLint = scope === 'fe' ? grammarLintFor(fe.grammar) : null;
   return {
     header: HEADER(scope),
     readmeBadges: source.badges ?? '',
@@ -375,6 +379,8 @@ export function variables(app, scope, presets, sonarKey, manifest = loadSlotMani
     dependabotUpdates: dependabotUpdates(quality.dependabot),
     tsconfigPaths: ['be/tsconfig.json', ...fe.apps.map(entry => `fe/apps/${entry.name}/tsconfig.json`), ...(packages ? ['fe/packages/*/tsconfig.json'] : [])].join(','),
     styleGlob: STYLE_GLOB,
+    grammarLintImport: grammarLint?.package ? `import { ${grammarLint.factory} } from "${grammarLint.package}"` : '',
+    grammarLintExport: grammarLint?.package ? `export default [...starciFeConfig({ hfs }), ...${grammarLint.factory}({ hfs })]` : 'export default starciFeConfig({ hfs })',
     imageMatrix: imageMatrix(app, source),
     imageProject: app.project,
     ...stackWorkflowVariables(stack, app.project, name => stackDockerfile(app, name)),

package/templates/app/skeleton/.starcistacks/dev/infra/compose/stack.yaml

@@ -1,5 +1,4 @@
 # Rendered development model. App images and owner infrastructure must be provisioned before use.
-version: "3.8"
 services:
   core:
     image: "{{project}}/core:v0.0.0"

package/templates/app/skeleton/.starcistacks/production/infra/swarm/stack.yaml

@@ -1,5 +1,4 @@
 # Rendered production model. All-zero app digests are illustrative; publish verified images before use.
-version: "3.8"
 services:
   core:
     image: "{{project}}/core:v0.0.0@sha256:0000000000000000000000000000000000000000000000000000000000000000"

package/templates/app/skeleton-lite/.starcistacks/dev/infra/swarm/stack.yaml

@@ -1,5 +1,4 @@
 # Illustrative development model. Replace all-zero application digests with verified published release digests before use.
-version: "3.8"
 services:
   api:
     image: "{{project}}/api:v0.0.0@sha256:0000000000000000000000000000000000000000000000000000000000000000"

package/templates/app/skeleton-lite/.starcistacks/production/infra/swarm/stack.yaml

@@ -1,5 +1,4 @@
 # Illustrative production model. Replace all-zero application digests with verified published release digests before use.
-version: "3.8"
 services:
   api:
     image: "{{project}}/api:v0.0.0@sha256:0000000000000000000000000000000000000000000000000000000000000000"

package/templates/fe/tool-config/eslint.config.mjs

@@ -1,3 +1,6 @@
 import { loadHfs, starciFeConfig } from "@starci/eslint-canon-fe"
+// {{grammarLintImport}}
 
-export default starciFeConfig({ hfs: loadHfs(import.meta.url) })
+const hfs = loadHfs(import.meta.url)
+
+// {{grammarLintExport}}