@starci/hfs 4.2.17 → 4.4.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 4.4.0 - 2026-10-15
+- Fixed: a swarm service on a shared external edge network no longer keeps the implicit short service name as an alias (`docker stack deploy` adds `api` for nivo_api on every network, so another tenant resolving `http://api` reached the wrong stack). `starci app stack deploy` and rollback reconcile the edge attachment to exactly the declared aliases right after `docker stack deploy` (`STACK_DEPLOY_EDGE_ALIAS` when they still differ), `stack verify` refuses an undeclared alias on an edge-attached service, and the deploy preflight and `stack doctor` extend `STACK_DEPLOY_ALIAS_SHARED` to a short name that another container or service of the edge network already resolves (`STACK_DEPLOY_EDGE_UNREADABLE` when the network cannot be inspected).
+- Added: R295 `BE_MODULE_DEFINITION_MISSING`: every Nest module has a module definition (owner ruling 2026-10-15 `owner:module-definition-everywhere`). The slot manifest allows `<x>.module-definition.ts` and `<x>.options.ts` beside every feature, transport, cli group, queue, reactor and job module; the generators of `starci app add` and `starci app new` write the three files and register the module as `X.register({})`.
+- Changed: `module-per-transport` accepts a module-definition beside the application module, the transport module of its folder and a cli group, and refuses one anywhere else.
+
+## 4.3.0 - 2026-10-14
+- Added: the app file role `<app>.env.ts` (`apps/<app>/src/`, every `be.app.*` slot, budget 150): a typed `<App>Env` interface and fail-fast `read<App>Env` reader (secrets `_FILE` first), imported by `main.ts` so the entry stays within its 80 lines. Only `main.ts` and the app's own env file read the environment; the env file lists no module and imports no feature. The api, lite api and cli scaffolds write it.
+- Added: `starci app secret` custody verbs `init`, `set <env> <slug> <KEY>` (stdin or `--generate <bytes>`), `get <env> <slug> [KEY] --to-file [--reveal]`, `materialize <env>` and `list <env>` over sops dotenv files under `.starcistacks/<env>/secrets/`; the age identity lives outside the repository, materialized values go under the local StarCi secrets directory for `*_FILE` reading, and no value reaches stdout unless `--reveal`. The scaffolded `.sops.yaml` carries the `init` instruction and the be config template reads `<NAME>_FILE` before `<NAME>`. An untracked root `secrets.env` of a lite app is an `HFS_PLAINTEXT_SECRET` warning.
+- Added: lite delivery slots `app.deploy` (`deploy/`), `app.ci-deploy`, `app.ci-authorize-deploy-key` and `app.scripts.delivery`; R06 scans all of them.
+- Added: fe tier edge `feature -> feature` narrowed by `mayImportKinds` (pages compose overlays and blocks) and render props in the pure half (`render*` callbacks in `props` of a non-block component); `FE_CONNECTED_BLOCK_RENDER_PAIR` reads the exact sibling `XBase` twin.
+- Changed: a lite app's `.starciwork/` holds only `.gitignore`, `workspace.yaml` and `brand/**` and is optional (index.yaml, shell, features, resources, UAT and br are forbidden); the work readers (validate, kernel, uat, example refs) skip the removed workspace, index, shell and feature records under lite, and the lite scaffold and example no longer write them.
+- Changed: a pure re-export `index.ts` gets the 400-line `barrel` budget (hooks slots); an `fe.modules` instance with no `.ts`/`.tsx` file needs no `index.ts` (`HFS_REQUIRED_FILE_MISSING`, `HFS_SLOT_REQUIRED_MISSING`).
+- Changed: `BE_BACKGROUND_UNOWNED` decides by context (job processor, scheduler, saga, event handler and what they call), never by a `retry*`/`replay*` method name; resolvers and controllers are never background.
+- Changed: `HFS_DUPLICATE_CODE` drops canon scaffold shapes; `HFS_UNUSED_EXPORT` counts staged test consumers; `FE_I18N_KEYS` reads in-segment template keys (`t(`stage_${x}`)`) as globs.
+- Changed: the scaffolded pre-commit hook passes staged files to eslint and prettier in chunks of 50 (Windows command-line limit); `DB_MIGRATION_SHAPE` orders a new migration against HEAD's active migrations, not the clock or the base branch.
+
+
+- Added: HFS manifest 3.1.0 (rule catalog 3.1.0, owner ruling 2026-10-14, R245 and R246): every `be.app.*` slot allows the composition groups `compose/<area>.ts` and budgets its composition files (`app.module.ts` 250, `<app>.options.ts` 200, `compose/<area>.ts` 120, `main.ts` 80); `<app>.options.ts` holds env-derived options and port bindings only (`BE_APP_OPTIONS_COMPOSITION`, `BE_APP_COMPOSITION_BUDGET`).
+- Changed: `starci app scaffold` writes `apps/<api app>/src/compose/platform.ts` (the platform capabilities as one group, `platformModules(options)`) in both editions, and the scaffolded `app.module.ts` spreads it before the domain modules and the guards.
+- Changed: `add table` lists the table's error kinds where the app keeps its error kinds array: the root `app.module.ts`, or else the `compose/` group that holds it.
+- Changed: the architecture machine reads an app's root and its `compose/` groups as one composition (register-once, module-per-transport, the connection and context maps).
+
 ## 4.2.17 - 2026-10-14
 
 - Fixed: the webhook door spec template signs with a per-run key (`randomBytes`) instead of a literal, so a scaffolded spec holds no plaintext secret-shaped value the release secret scan could flag.
@@ -99,6 +121,12 @@
 - New: `hfs secret list|show|set|gen` (alpha.5 item 6.4), the canon command over the sealed secrets of `.starcistacks/<env>/secrets/<slug>.enc`, on the runtime's sops api (a new `seal` call: the value travels on stdin, never on an argument list). Replaces the plain `sops` commands of runbooks and KEYS.md files.
 - Changed: HFS_REQUIRED_FILE_MISSING now also carries what BE_REQUIRED_MODULE_MISSING reported, and BE_TEST_TOPOLOGY what HFS_TEST_KIND_RETIRED reported (one code per obligation); the bundled architecture machine follows `APP_GUARD` and `APP_FILTER` providers built by a helper outside the app root file.
 - Changed: the managed fe scripts (`dev:fe`, `start:<app>`, `build:fe`) run `next` from the app directory (`cd fe/apps/<app> && next ...`) so next-intl finds its request config; the fe skeleton reads the request locale through `next/root-params` (`experimental.rootParams`), pins the workspace root three levels above the app and uses the `.*[.].*` proxy matcher; the bundled runtime carries the `&&`/`||`-aware FE_SWR_KEY_IDENTITY check.
+## Unreleased (a18 R281)
+
+- Fixed: the bundled architecture machine (`function-spec-providers.mjs`, `unit-spec-providers.mjs`) takes the callable subset of a function-only subject's exports (constants, enums, re-exports and overload signatures are ignored) and lets the spec of a value-object class (undecorated, no constructor injection token) construct it with `new`.
+- Security (canon pins, npm audit of 2026-10-16): `next` 16.1.6 to 16.4.2 (critical, with the `postcss` and `sharp` highs it brings), `axios` 1.15.2 to 1.20.0 and `@nestjs/platform-express` 11.2.5 to 11.2.7 (with `multer`) in `knowledge/hfs/canon-pins.yaml`; the example apps (`ecommerce-app`, `lite-app`, `shape-slot`) and `packages/test-world` carry the new pins and lockfiles.
+- Known advisory, accepted (owner ruling `graphql-13-advisory-accepted-until-a19`, 2026-10-16): `@nestjs/graphql` and `@nestjs/apollo` stay on 13.4.5. `npm audit --omit=dev --audit-level=high` still reports their highs (and `@graphql-tools/utils` through them); the fix is 14.0.3, a semver major, deferred to alpha.19.
+
 ## Unreleased (C0 batch)
 
 - Fixed (contract change `sonar-coverage-exclusions`): SonarQube has no `sonar.coverage.inclusions` property, so Sonar ignored it and counted every executable be/ file at 0% (overall coverage 65.8% and 45.2% on the examples, although every service was at 100). The managed `sonar-project.properties` now renders `sonar.coverage.exclusions` as the complement of the services. `coverageExclusions(presets, manifest)` in `sync/index.mjs` derives it from the preset's `COVERAGE_SOURCES` and the slot manifest, and lists:

package/README.md

@@ -34,6 +34,12 @@ out the test world and event machinery.
 `app.supabase.types` artifact from the app's local Supabase stack; if that generation cannot run, scaffolding fails and removes
 the app it began instead of leaving a partial tree.
 
+The lite `app.starciwork` slot is optional when the app has no brand records. When present, it holds only `.gitignore`,
+optional `workspace.yaml` metadata and `brand/**` (R212): the existing brand record, drawing records, references and assets.
+Workspace metadata supplies the project id and repo roles for app-root detection and front-end role mapping. Lite readers
+read workspace metadata normally and skip the feature catalog, shell and feature records. The scaffold writes `.gitignore`
+and `workspace.yaml` and retains `brand/` only when present.
+
 The lite additions are deliberately narrow:
 
 - `starci app add table <name> [--fe] [--no-types]` adds the migration and matching back-end capability. `--fe` also adds the table's
@@ -77,6 +83,7 @@ Its own checks (`scripts/hfs/check.mjs`, `scripts/hfs/rules/`; the rendered-file
 | `HFS_SLOT_AMBIGUOUS` | error | two slots own the path equally (a manifest gap) |
 | `HFS_TRACKED_MUST_BE_IGNORED` | error | a tracked path in an `ignored` slot (build output, generated) |
 | `HFS_FORBIDDEN_PRESENT` | error | a tracked path in a forbidden / `external` slot |
+| `HFS_STARCIWORK_LITE_FORBIDDEN` | error | content outside the lite `app.starciwork` boundary: "lite .starciwork holds only workspace.yaml and brand/ (plus .gitignore)" (R212) |
 | `HFS_SLOT_REQUIRED_MISSING` | error | a file or directory a required slot, app or instance must contain |
 | `HFS_MIN_INSTANCES` | error | fewer instances of a slot than `minInstances` |
 | `HFS_CANON_PIN_DRIFT` | error | a dependency not at the exact version of `knowledge/hfs/canon-pins.yaml` |

package/db/migrate.mjs

@@ -0,0 +1,361 @@
+// migrate.mjs - `starci app db migrate`: puts a database's migration history in the state the app's repository declares, idempotently.
+// The optional `database:` block of .starcistacks/application-stacks.yaml names the baseline migration, the optional second baseline (standard),
+// the held-back migrations (applied later by `db post-cutover`), the restamp pairs and the archive directory. The plan, from the remote history:
+//   repair    revert each restamped old version still on the remote and mark its new version applied
+//   baseline  revert the archived rows, mark the baseline applied (it is NOT run)
+//   forward   push every other migration, EXCEPT the held-back ones (they are never copied into the push project)
+// When the remote already is baseline + forward (held-back ones may or may not be applied) it prints `nothing to do` and makes no mutating call.
+// The Supabase CLI runs through ctx.spawn with scratch workdirs; a password travels only in the child environment (SUPABASE_DB_PASSWORD from the
+// environment or the sealed custody, PGPASSWORD split off a --url-env connection string), never in argv, a file, a line or an error.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { isPlainObject as plain } from '../runtime/engine/plain-object.mjs';
+import { byCodeUnit } from '../runtime/engine/by-code-unit.mjs';
+import { readMap } from '../runtime/scripts/hfs/secret-store.mjs';
+import { STACKS_DIR } from '../stack/config.mjs';
+import { firstLine, tool } from '../stack/context.mjs';
+import { approvalMissing, failure, refusal } from '../stack/errors.mjs';
+import { readDeclaration, runVerb } from '../release/index.mjs';
+
+const DATABASE_CODE = 'DB_CONFIG_INVALID';
+
+const SEGMENT = /^[A-Za-z0-9._-]+$/u;
+const NAME = /^[A-Za-z0-9][A-Za-z0-9_-]*$/u;
+const IDENT = /^[a-z][a-z0-9_]*$/u;
+const SLUG = /^[a-z][a-z0-9-]*$/u;
+const KEY = /^[A-Z][A-Z0-9_]*$/u;
+const STAMP = /^\d{14}$/u;
+const PROJECT_REF = /^[a-z0-9]{10,40}$/u;
+const SIGNATURE = /^[A-Za-z0-9_."(), ]+$/u;
+const MIGRATION = /^(\d{14})_([A-Za-z0-9_-]+)\.sql$/u;
+const PENDING = /(\d{14})_[^\s"]+?\.sql/gu;
+
+const matches = (pattern) => (value) => typeof value === 'string' && pattern.test(value);
+const listOf = (item) => (value) => Array.isArray(value) && value.every((entry) => item(entry));
+const dirOk = (value) => typeof value === 'string' && value.split('/').every((part) => SEGMENT.test(part) && part !== '..');
+const pairOk = (value) => plain(value) && Object.keys(value).length === 2 && matches(STAMP)(value.from) && matches(STAMP)(value.to);
+const passwordOk = (value) => plain(value) && Object.keys(value).length === 3 && matches(SLUG)(value.env) && matches(SLUG)(value.member) && matches(KEY)(value.key);
+const POST_FIELDS = ['schema', 'functionPrefixes', 'functionNames', 'functions', 'minAgeHours'];
+const POST_CHECKS = {
+  schema: matches(IDENT), functionPrefixes: listOf(matches(IDENT)), functionNames: listOf(matches(IDENT)),
+  functions: listOf(matches(SIGNATURE)), minAgeHours: (value) => Number.isFinite(value) && value >= 0,
+};
+const postOk = (value) => plain(value) && Object.keys(value).every((key) => POST_FIELDS.includes(key) && POST_CHECKS[key](value[key]));
+
+const CHECKS = {
+  migrationsDir: [dirOk, 'must be a relative directory inside the app'],
+  archiveDir: [dirOk, 'must be a relative directory inside the app'],
+  baseline: [matches(NAME), `must match ${NAME} (the name after the stamp)`],
+  standard: [matches(NAME), `must match ${NAME} (the name after the stamp)`],
+  heldBack: [listOf(matches(NAME)), 'must be a list of migration names'],
+  projectRef: [matches(PROJECT_REF), `must match ${PROJECT_REF}`],
+  restamp: [listOf(pairOk), 'must be a list of { from, to } fourteen-digit stamps'],
+  password: [passwordOk, 'must be { env, member, key } naming a sealed value'],
+  postCutover: [postOk, `must use only ${POST_FIELDS.join(', ')} with valid values`],
+};
+
+/** Judges the `database:` block. Returns { config } or { problems }; `baseline` is the one required field. */
+export function normalizeDatabase(block) {
+  if (!plain(block)) return { problems: ['database: must be a mapping'] };
+  const problems = [];
+  for (const [key, value] of Object.entries(block)) {
+    if (!Object.hasOwn(CHECKS, key)) problems.push(`database.${key}: is not a field of the database block`);
+    else if (!CHECKS[key][0](value)) problems.push(`database.${key}: ${CHECKS[key][1]}`);
+  }
+  if (block.baseline === undefined) problems.push('database.baseline: is required');
+  if (problems.length > 0) return { problems };
+  const config = {
+    migrationsDir: 'supabase/migrations', archiveDir: null, standard: null, heldBack: [], projectRef: null, restamp: [], password: null, postCutover: null, ...block,
+  };
+  return { config };
+}
+
+/** The normalised `database:` block of the app at `root`; absent or invalid is a refusal (these verbs need the declaration). */
+export function loadDatabase(root) {
+  const block = readDeclaration(root).database;
+  if (block === undefined) throw refusal('DB_UNDECLARED', 'the app declares no database: block in .starcistacks/application-stacks.yaml');
+  const { config, problems } = normalizeDatabase(block);
+  if (!config) throw refusal(DATABASE_CODE, `${problems.length} problem(s) in database: ${problems.slice(0, 6).join('; ')}`);
+  return config;
+}
+
+/* ---- the repository model */
+
+const sqlNames = (dir, what) => {
+  try { return fs.readdirSync(dir).filter((name) => name.endsWith('.sql')).sort(byCodeUnit); } catch { throw refusal('DB_MIGRATIONS_MISSING', `${what} (${dir}) is not readable`); }
+};
+
+const stampOf = (file) => file.split('_')[0];
+
+function archiveOf(root, decl) {
+  if (decl.archiveDir === null || !fs.existsSync(path.join(root, decl.archiveDir))) return [];
+  const moved = new Map(decl.restamp.map((pair) => [pair.from, pair.to]));
+  return sqlNames(path.join(root, decl.archiveDir), 'the archive directory').map((file) => {
+    const version = moved.get(stampOf(file)) ?? stampOf(file);
+    return { from: path.join(root, decl.archiveDir, file), name: `${version}_${file.slice(file.indexOf('_') + 1)}`, version };
+  });
+}
+
+function stampProblems(model, decl) {
+  const { files, baselineFile, standardFile, baseline, standard } = model;
+  for (const file of files) {
+    const version = stampOf(file);
+    if (file !== baselineFile && version <= baseline) throw refusal('DB_STAMP_ORDER', `${file} sorts at or before the baseline: it would run before the baseline on a fresh database`);
+    if (standardFile && file !== baselineFile && file !== standardFile && version <= standard) throw refusal('DB_STAMP_ORDER', `${file} sorts before the second baseline`);
+    if (decl.restamp.some((pair) => pair.to === version)) throw refusal('DB_STAMP_COLLISION', `${file} collides with a restamp target`);
+  }
+}
+
+/** The migration files of the app and its baseline pair; refuses badly named, duplicate-stamped or missing files. */
+function checkedFiles(root, decl) {
+  const files = sqlNames(path.join(root, decl.migrationsDir), 'the migrations directory');
+  const bad = files.filter((file) => !MIGRATION.test(file));
+  if (bad.length > 0) throw refusal('DB_MIGRATION_NAME', `migration files must be <14-digit stamp>_<name>.sql (got ${bad[0]})`);
+  if (new Set(files.map(stampOf)).size !== files.length) throw refusal('DB_STAMP_DUPLICATE', 'two migrations share one stamp');
+  const baselineFile = files.find((file) => file.endsWith(`_${decl.baseline}.sql`));
+  const standardFile = decl.standard === null ? undefined : files.find((file) => file.endsWith(`_${decl.standard}.sql`));
+  if (!baselineFile) throw refusal('DB_BASELINE_MISSING', `no migration named ${decl.baseline} in ${decl.migrationsDir}`);
+  if (decl.standard !== null && !standardFile) throw refusal('DB_BASELINE_MISSING', `no migration named ${decl.standard} in ${decl.migrationsDir}`);
+  return { files, baselineFile, standardFile };
+}
+
+/** Classifies the migration files of the app: baseline pair, held-back, forward, restamp pairs and archive. Refuses an inconsistent repository. */
+export function buildModel(root, decl) {
+  const { files, baselineFile, standardFile } = checkedFiles(root, decl);
+  const held = files.filter((file) => decl.heldBack.some((name) => file.endsWith(`_${name}.sql`)));
+  const push = files.filter((file) => !held.includes(file));
+  const baseline = stampOf(baselineFile);
+  const model = {
+    root, decl, files, baselineFile, standardFile, baseline, standard: standardFile ? stampOf(standardFile) : null, held, push,
+    heldVersions: held.map(stampOf), pushPending: push.filter((file) => file !== baselineFile).map(stampOf), archive: archiveOf(root, decl),
+  };
+  stampProblems(model, decl);
+  return { ...model, pushVersions: new Set([baseline, ...model.pushPending]), allowed: new Set([baseline, ...model.pushPending, ...model.heldVersions]) };
+}
+
+/* ---- reading the CLI */
+
+/** Versions from the JSON form of `supabase migration list`, or null when the text holds no readable JSON. */
+function jsonVersions(text) {
+  const start = text.indexOf('{"migrations"');
+  if (start < 0) return null;
+  const end = text.indexOf('\n', start);
+  try {
+    const items = JSON.parse(text.slice(start, end > 0 ? end : undefined)).migrations;
+    return { remote: new Set(items.filter((item) => item.remote).map((item) => item.remote)), local: new Set(items.filter((item) => item.local).map((item) => item.local)) };
+  } catch { return null; }
+}
+
+/** Versions from the older table form: rows of `local | remote | time`. */
+function tableVersions(text) {
+  const remote = new Set();
+  const local = new Set();
+  for (const cells of text.split('\n').map((line) => line.split('|').map((cell) => cell.trim())).filter((row) => row.length >= 3)) {
+    if (STAMP.test(cells[0])) local.add(cells[0]);
+    if (STAMP.test(cells[1])) remote.add(cells[1]);
+  }
+  return { remote, local };
+}
+
+/** Remote (and local) versions from `supabase migration list`: the JSON form, or the older table. */
+export const parseMigrationList = (text) => jsonVersions(text) ?? tableVersions(text);
+
+/** The versions a `db push --dry-run` would apply. */
+export const pendingVersions = (text) => [...new Set([...text.matchAll(PENDING)].map((match) => match[1]))];
+
+/* ---- the target */
+
+const scrub = (text, secrets) => secrets.reduce((out, secret) => out.replaceAll(secret, '[value]'), String(text));
+
+function parseConnection(value) {
+  try {
+    const url = new URL(value);
+    if (!/^postgres(?:ql)?:$/u.test(url.protocol)) return null;
+    const password = decodeURIComponent(url.password);
+    url.password = '';
+    return { url: url.toString(), password };
+  } catch { return null; }
+}
+
+function urlTarget(ctx, name) {
+  if (!KEY.test(name)) throw refusal('DB_USAGE', '--url-env must name an UPPER_CASE environment variable');
+  const value = ctx.env[name];
+  if (typeof value !== 'string' || value === '') throw refusal('DB_URL_ENV_MISSING', `${name} is not set`);
+  const parsed = parseConnection(value);
+  if (!parsed) throw refusal('DB_URL_INVALID', `${name} is not a postgres connection URL`);
+  const secrets = [value, parsed.password].filter(Boolean);
+  return { kind: 'url', how: `connection string from ${name}`, url: parsed.url, env: parsed.password ? { PGPASSWORD: parsed.password } : {}, secrets };
+}
+
+function sealedPassword(ctx, spec) {
+  let map;
+  try { map = readMap(path.join(ctx.cwd, STACKS_DIR, spec.env, 'secrets', `${spec.member}.enc`), ctx.sops); } catch { throw refusal('DB_PASSWORD_UNREADABLE', `the sealed member ${spec.member} cannot be opened`); }
+  if (typeof map[spec.key] !== 'string' || map[spec.key] === '') throw refusal('DB_PASSWORD_UNREADABLE', `the sealed member ${spec.member} has no value for ${spec.key}`);
+  return map[spec.key];
+}
+
+/** The database password for the linked CLI: SUPABASE_DB_PASSWORD from the environment, else the declared sealed value, else none (the CLI mints a login). */
+function linkedPassword(ctx, decl) {
+  const given = ctx.env.SUPABASE_DB_PASSWORD;
+  if (typeof given === 'string' && given !== '') return given;
+  return decl.password === null ? null : sealedPassword(ctx, decl.password);
+}
+
+function linkedTarget(ctx, decl) {
+  let ref;
+  try { ref = fs.readFileSync(path.join(ctx.cwd, 'supabase', '.temp', 'project-ref'), 'utf8').trim(); } catch { throw refusal('DB_NOT_LINKED', 'no linked project (supabase/.temp/project-ref): run supabase link first'); }
+  if (decl.projectRef !== null && ref !== decl.projectRef) throw refusal('DB_WRONG_PROJECT', `the app is linked to ${ref}, not the declared project ${decl.projectRef}`);
+  const password = linkedPassword(ctx, decl);
+  return { kind: 'linked', how: `linked project ${ref}`, ref, url: null, env: password ? { SUPABASE_DB_PASSWORD: password } : {}, secrets: password ? [password] : [] };
+}
+
+/** { kind, how, env, secrets, url }: the linked project of the app (default) or the connection string in the named environment variable. */
+export function resolveTarget(ctx, decl, options) {
+  if (options.linked === true && options.urlEnv !== undefined) throw refusal('DB_USAGE', '--linked and --url-env exclude each other');
+  return options.urlEnv === undefined ? linkedTarget(ctx, decl) : urlTarget(ctx, options.urlEnv);
+}
+
+/** CLI arguments that select the database and the local supabase folder. */
+export const targetArgs = (target, dir) => (target.kind === 'url' ? ['--db-url', target.url, '--workdir', dir] : ['--linked', '--workdir', dir]);
+
+/** Refuses a mutation unless the operator armed it with STARCI_DB_ARMED=1. */
+export function requireArmed(ctx) {
+  if (ctx.env.STARCI_DB_ARMED !== '1') throw approvalMissing('DB_NOT_ARMED', 'set STARCI_DB_ARMED=1 to apply database changes');
+}
+
+const supabaseCommand = (root) => {
+  const script = path.join(root, 'node_modules', 'supabase', 'dist', 'supabase.js');
+  return fs.existsSync(script) ? [process.execPath, script] : ['supabase'];
+};
+
+/** Runs the Supabase CLI through the seam; a failure names the first stderr line with every secret scrubbed. Returns { stdout, text } (text = stdout plus stderr). */
+export function runCli(session, args) {
+  const { ctx, target } = session;
+  const [command, ...lead] = supabaseCommand(ctx.cwd);
+  const run = tool(ctx, command, [...lead, ...args], { cwd: ctx.cwd, env: { ...ctx.env, ...target.env } });
+  if (run.error) throw failure('DB_CLI_MISSING', `cannot run the Supabase CLI (${scrub(run.error.message, target.secrets)})`);
+  if (run.status !== 0) throw failure('DB_CLI_FAILED', `supabase ${args.slice(0, 2).join(' ')} failed: ${scrub(firstLine(run.stderr), target.secrets)}`);
+  return { stdout: run.stdout ?? '', text: `${run.stdout ?? ''}${run.stderr ?? ''}` };
+}
+
+/** The remote history as a Set of versions (read-only). */
+export const listRemote = (session) => parseMigrationList(runCli(session, ['migration', 'list', ...targetArgs(session.target, session.ctx.cwd)]).text).remote;
+
+/* ---- the plan */
+
+/** Pure: what to do given the remote history. `done` means baseline + forward are present and nothing else is. */
+export function planMigration(model, remote) {
+  const done = [...model.pushVersions].every((version) => remote.has(version)) && [...remote].every((version) => model.allowed.has(version));
+  const sim = new Set(remote);
+  const repairs = model.decl.restamp.filter((pair) => sim.has(pair.from));
+  for (const pair of repairs) {
+    sim.delete(pair.from);
+    sim.add(pair.to);
+  }
+  const reverts = sim.has(model.baseline) ? [] : model.archive.map((item) => item.version).filter((version) => sim.has(version));
+  for (const version of reverts) sim.delete(version);
+  const mark = !sim.has(model.baseline);
+  sim.add(model.baseline);
+  const push = model.pushPending.filter((version) => !sim.has(version));
+  for (const version of push) sim.add(version);
+  const archived = new Set(model.archive.map((item) => item.version));
+  const missingFiles = repairs.map((pair) => pair.to).filter((version) => !archived.has(version));
+  return { done, repairs, reverts, mark, push, missingFiles, unexpected: [...sim].filter((version) => !model.allowed.has(version)), final: sim.size };
+}
+
+function planLines(model, session, remote, plan) {
+  const nameOf = (version) => model.files.find((file) => file.startsWith(`${version}_`));
+  return [
+    `target         ${session.target.how}`,
+    `remote history ${remote.size} version(s)`,
+    [`repairs        ${plan.repairs.length} restamped version(s) to move`, ...plan.repairs.map((pair) => `  ${pair.from} -> ${pair.to}`)].join('\n'),
+    `archive revert ${plan.reverts.length} archived version(s) present on the remote`,
+    `baseline       ${model.baseline} ${plan.mark ? 'will be marked applied (not run)' : 'already applied'}`,
+    `forward push   ${plan.push.length} migration(s): ${plan.push.map(nameOf).join(', ') || 'none'}`,
+    `held back      ${model.held.join(', ') || 'none'} (never applied here; starci app db post-cutover)`,
+  ];
+}
+
+const dataOf = (model, plan, remote, extra) => ({
+  remoteCount: remote.size, repairs: plan.repairs.length, reverts: plan.reverts, baseline: model.baseline, markBaseline: plan.mark, push: plan.push,
+  heldBack: model.heldVersions, done: plan.done, ...extra,
+});
+
+/* ---- applying */
+
+/** A scratch supabase project holding exactly the given migration files; the link state of the app is copied so --linked works from it. */
+function buildScratch(session, dir, copies) {
+  fs.mkdirSync(path.join(dir, 'supabase', 'migrations'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'supabase', 'config.toml'), 'project_id = "starci-db-scratch"\n');
+  for (const copy of copies) fs.copyFileSync(copy.from, path.join(dir, 'supabase', 'migrations', copy.name));
+  if (session.target.kind === 'linked') fs.cpSync(path.join(session.ctx.cwd, 'supabase', '.temp'), path.join(dir, 'supabase', '.temp'), { recursive: true });
+}
+
+const repair = (session, status, versions, dir) => runCli(session, ['migration', 'repair', '--status', status, ...versions, ...targetArgs(session.target, dir)]);
+
+function applyRepairs(session, plan, scratch) {
+  const dir = path.join(scratch, 'archive');
+  buildScratch(session, dir, session.model.archive.map((item) => ({ from: item.from, name: item.name })));
+  repair(session, 'reverted', plan.repairs.map((pair) => pair.from), dir);
+  repair(session, 'applied', plan.repairs.map((pair) => pair.to), dir);
+}
+
+function applyForward(session, plan, scratch) {
+  const { model } = session;
+  const dir = path.join(scratch, 'baseline');
+  buildScratch(session, dir, model.push.map((file) => ({ from: path.join(model.root, model.decl.migrationsDir, file), name: file })));
+  if (plan.reverts.length > 0) repair(session, 'reverted', plan.reverts, dir);
+  if (plan.mark) repair(session, 'applied', [model.baseline], dir);
+  const pending = pendingVersions(runCli(session, ['db', 'push', '--dry-run', ...targetArgs(session.target, dir)]).text);
+  const stray = pending.filter((version) => !model.pushPending.includes(version));
+  if (stray.length > 0) throw failure('DB_PUSH_STRAY', `the dry run lists versions outside the push list: ${stray.join(', ')}. Stopped before pushing.`);
+  if (pending.length > 0) runCli(session, ['db', 'push', '--yes', ...targetArgs(session.target, dir)]);
+  return pending;
+}
+
+function applyPlan(session, plan) {
+  const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'starci-db-'));
+  try {
+    if (plan.repairs.length > 0) applyRepairs(session, plan, scratch);
+    const after = planMigration(session.model, listRemote(session));
+    return applyForward(session, after, scratch);
+  } finally {
+    fs.rmSync(scratch, { recursive: true, force: true });
+  }
+}
+
+/**
+ * `starci app db migrate`. options: { execute, linked, urlEnv }. Dry run reads the remote history once and prints the plan; --execute (with
+ * STARCI_DB_ARMED=1) applies it. Already baseline + forward: `nothing to do`, no mutating call, ok.
+ */
+export async function migrateDatabase(ctx, decl, options = {}) {
+  const model = buildModel(ctx.cwd, decl);
+  const session = { ctx, model, target: resolveTarget(ctx, decl, options) };
+  const remote = listRemote(session);
+  const plan = planMigration(model, remote);
+  if (plan.done) return { ok: true, lines: [`target         ${session.target.how}`, 'remote history already is the baseline plus the forward migrations (held-back ones may or may not be applied). Nothing to do.'], data: dataOf(model, plan, remote, { executed: false }) };
+  const lines = planLines(model, session, remote, plan);
+  const red = [
+    ...plan.missingFiles.map((version) => `no archived migration file for the restamped version ${version}`),
+    ...plan.unexpected.map((version) => `remote version ${version} is outside baseline + forward + held-back and no restamp or archive row explains it`),
+  ];
+  if (red.length > 0) return { ok: false, lines: [...lines, ...red.map((item) => `RED: ${item}`), 'nothing applied.'], data: dataOf(model, plan, remote, { red, executed: false }) };
+  if (options.execute !== true) return { ok: true, lines: [...lines, `dry run: read-only (one migration list); the final history would be ${plan.final} version(s). Nothing applied.`], data: dataOf(model, plan, remote, { executed: false }) };
+  requireArmed(ctx);
+  const pushed = applyPlan(session, plan);
+  const final = listRemote(session);
+  const verdict = planMigration(model, final);
+  if (!verdict.done) throw failure('DB_FINAL_MISMATCH', `the remote history is not baseline + forward migrations (${[...final].join(', ')})`);
+  return { ok: true, lines: [...lines, `applied: ${pushed.length} forward migration(s) pushed; the remote history now holds ${final.size} version(s). Held back: ${model.held.join(', ') || 'nothing'}.`], data: dataOf(model, plan, remote, { executed: true, pushed, remoteCountAfter: final.size }) };
+}
+
+const SPEC = { boolean: ['--execute', '--json', '--linked'], value: ['--url-env'] };
+
+/** Entry of the verb: `starci app db migrate [--execute] [--linked | --url-env NAME] [--json]`. `io` is the app IO of src/main.mjs. */
+export function dbMigrateMain(argv, io = {}) {
+  return runVerb({
+    label: 'starci app db migrate', name: 'db migrate', code: 'DB_USAGE', io, argv, spec: SPEC,
+    run: (ctx, flags) => migrateDatabase(ctx, loadDatabase(ctx.cwd), { execute: flags.execute === true, linked: flags.linked === true, urlEnv: flags['url-env'] }),
+  });
+}

package/db/post-cutover.mjs

@@ -0,0 +1,136 @@
+// post-cutover.mjs - `starci app db post-cutover`: applies the held-back migrations (database.heldBack) that `db migrate` skipped, e.g. the one that
+// drops the old engine's tables. After it a rollback to the old app needs a database restore, so it is guarded three ways:
+//   1. a READ-ONLY pg_proc preflight (also in the dry run): every function of the declared families (database.postCutover.functionPrefixes and
+//      functionNames in database.postCutover.schema) that exists on the database must be covered by the DROP FUNCTION statements of the held-back
+//      migration (or database.postCutover.functions); a function nobody drops is a function something may still need, so nothing is applied;
+//   2. a time gate: --green-at <ISO> at least minAgeHours (48) ago, or --owner-confirms-old-app-gone;
+//   3. STARCI_DB_ARMED=1.
+// Idempotent: when every held-back version is already on the remote it prints `nothing to do`. The pg_proc query goes through `options.query(sql)`
+// (specs inject one) or, by default, `supabase db query` of the linked project or the --url-env connection.
+import fs from 'node:fs';
+import path from 'node:path';
+import { failure, refusal } from '../stack/errors.mjs';
+import { runVerb } from '../release/index.mjs';
+import { buildModel, listRemote, loadDatabase, pendingVersions, requireArmed, resolveTarget, runCli, targetArgs } from './migrate.mjs';
+
+const DROP_FUNCTION = /^drop\s+function\s+/iu;
+const IF_EXISTS = /^if\s+exists\s+/iu;
+const MS_PER_HOUR = 3.6e6;
+const DEFAULT_MIN_AGE_HOURS = 48;
+
+/** Makes a DROP signature comparable with pg_proc's regprocedure text. */
+export function normalizeSignature(signature, schema) {
+  const lowered = signature.trim().toLowerCase();
+  const bare = lowered.startsWith(`${schema}.`) ? lowered.slice(schema.length + 1) : lowered;
+  const words = bare
+    .replace(/\bint\b/gu, 'integer')
+    .replace(/\btimestamptz\b/gu, 'timestamp with time zone')
+    .replace(/\s+/gu, ' ');
+  return [...'(),'].reduce((out, mark) => out.replaceAll(` ${mark}`, mark).replaceAll(`${mark} `, mark), words);
+}
+
+/** The signature a `DROP FUNCTION [IF EXISTS] <signature>` statement drops, or null for any other statement. */
+function droppedSignature(statement) {
+  const head = DROP_FUNCTION.exec(statement);
+  return head ? statement.slice(head[0].length).replace(IF_EXISTS, '') : null;
+}
+
+/** The signatures a migration drops: every `DROP FUNCTION [IF EXISTS] <signature>;` statement. */
+export function dropSignatures(sql, schema) {
+  return sql.replace(/--[^\n]*/gu, '').split(';').flatMap((statement) => {
+    const signature = droppedSignature(statement.trim());
+    return signature === null ? [] : [normalizeSignature(signature, schema)];
+  });
+}
+
+const settingsOf = (post) => ({
+  schema: post.schema ?? 'public', prefixes: post.functionPrefixes ?? [], names: post.functionNames ?? [], extra: post.functions ?? [],
+});
+
+/** The read-only pg_proc query of the declared function families (identifiers are validated, so nothing free-form reaches the SQL). */
+export function preflightSql({ schema, prefixes, names }) {
+  const escaped = (prefix) => prefix.replaceAll('_', String.raw`\_`);
+  const clauses = [...names.map((name) => `proname = '${name}'`), ...prefixes.map((prefix) => `proname like '${escaped(prefix)}%'`)];
+  return `select oid::regprocedure::text as signature from pg_proc where pronamespace = '${schema}'::regnamespace and (${clauses.join(' or ')})`;
+}
+
+const cliQuery = (session) => (sql) => JSON.parse(runCli(session, ['db', 'query', sql, '--output', 'json', '--agent', 'no', ...targetArgs(session.target, session.ctx.cwd)]).stdout);
+
+async function queryRows(session, sql, options) {
+  try {
+    const rows = await (options.query ?? cliQuery(session))(sql);
+    if (Array.isArray(rows) && rows.every((row) => typeof row?.signature === 'string')) return rows;
+  } catch { /* the cause may hold a connection detail: it is withheld */ }
+  throw failure('DB_PREFLIGHT_UNREADABLE', 'the read-only function preflight could not query the database; nothing applied');
+}
+
+/** The pg_proc preflight: refuses when a function of the declared families is not dropped by the held-back migration(s). */
+async function functionPreflight(session, options) {
+  const { model, decl } = session;
+  const settings = settingsOf(decl.postCutover);
+  if (settings.prefixes.length + settings.names.length === 0) return { count: 0, line: 'function preflight: no function family declared; nothing to check' };
+  const dropped = model.held.flatMap((file) => dropSignatures(fs.readFileSync(path.join(model.root, decl.migrationsDir, file), 'utf8'), settings.schema));
+  const allowed = new Set([...dropped, ...settings.extra.map((item) => normalizeSignature(item, settings.schema))]);
+  const rows = await queryRows(session, preflightSql(settings), options);
+  const uncovered = rows.map((row) => normalizeSignature(row.signature, settings.schema)).filter((item) => !allowed.has(item));
+  if (uncovered.length > 0) throw refusal('DB_PREFLIGHT_UNCOVERED', `function signatures not covered by the held-back migration:\n${uncovered.join('\n')}`);
+  return { count: rows.length, line: `read-only function preflight: ${rows.length} signature(s), all covered by the held-back migration` };
+}
+
+/** The time gate: { open, line }. Dry run only reports it; --execute refuses while it is closed. */
+function timeGate(ctx, post, options) {
+  if (options.ownerConfirms === true) return { open: true, line: 'gate: the owner confirms the old app is gone: OPEN' };
+  if (options.greenAt === undefined) return { open: false, line: 'gate: CLOSED (needs --green-at <ISO> old enough, or --owner-confirms-old-app-gone)' };
+  const at = Date.parse(options.greenAt);
+  if (Number.isNaN(at)) throw refusal('DB_USAGE', '--green-at must be an ISO time');
+  const hours = (ctx.now() - at) / MS_PER_HOUR;
+  const need = post.minAgeHours ?? DEFAULT_MIN_AGE_HOURS;
+  return { open: hours >= need, line: `gate: last green ${options.greenAt} (${hours.toFixed(1)} h ago, ${need} h needed): ${hours >= need ? 'OPEN' : 'CLOSED'}` };
+}
+
+function applyHeld(session, remote) {
+  const { model, ctx } = session;
+  const lacking = [...model.pushVersions].filter((version) => !remote.has(version));
+  if (lacking.length > 0) throw refusal('DB_BASELINE_NOT_APPLIED', `the remote history lacks ${lacking.join(', ')}: run starci app db migrate first`);
+  const args = ['db', 'push', '--include-all'];
+  const pending = pendingVersions(runCli(session, [...args, '--dry-run', ...targetArgs(session.target, ctx.cwd)]).text);
+  const stray = pending.filter((version) => !model.heldVersions.includes(version));
+  if (stray.length > 0) throw failure('DB_PUSH_STRAY', `the dry run lists more than the held-back migrations: ${pending.join(', ')}. Stopped.`);
+  if (pending.length > 0) runCli(session, [...args, '--yes', ...targetArgs(session.target, ctx.cwd)]);
+  return pending;
+}
+
+/**
+ * `starci app db post-cutover`. options: { execute, linked, urlEnv, greenAt, ownerConfirms, query }. Dry run: remote read plus the read-only preflight.
+ * --execute: gate open and STARCI_DB_ARMED=1, then `db push --include-all` of exactly the held-back versions.
+ */
+export async function postCutoverDatabase(ctx, decl, options = {}) {
+  const model = buildModel(ctx.cwd, decl);
+  if (model.held.length === 0) return { ok: true, lines: ['no held-back migration in the repository. Nothing to do.'], data: { held: [], done: true, executed: false } };
+  if (decl.postCutover === null) throw refusal('DB_POSTCUTOVER_UNDECLARED', 'database.postCutover is not declared: the function preflight needs it (an empty mapping declares no family)');
+  const session = { ctx, decl, model, target: resolveTarget(ctx, decl, options) };
+  const remote = listRemote(session);
+  const data = { held: model.heldVersions, done: false, executed: false };
+  if (model.heldVersions.every((version) => remote.has(version))) return { ok: true, lines: [`held-back migrations ${model.held.join(', ')} are already applied. Nothing to do.`], data: { ...data, done: true } };
+  const gate = timeGate(ctx, decl.postCutover, options);
+  const preflight = await functionPreflight(session, options);
+  const lines = [`held-back migrations: ${model.held.join(', ')}`, preflight.line, gate.line, 'WARNING: after this step a rollback to the old app needs a database restore.'];
+  if (options.execute !== true) return { ok: true, lines: [...lines, 'dry run: only read-only calls were made; nothing applied.'], data: { ...data, gateOpen: gate.open, signatures: preflight.count } };
+  if (!gate.open) throw refusal('DB_POSTCUTOVER_GATE_CLOSED', 'the time gate is closed; nothing applied');
+  requireArmed(ctx);
+  const pending = applyHeld(session, remote);
+  if (!model.heldVersions.every((version) => listRemote(session).has(version))) throw failure('DB_HELD_MISSING', 'a held-back migration is still missing from the remote history');
+  return { ok: true, lines: [...lines, pending.length > 0 ? `applied: ${pending.join(', ')}` : 'nothing pending: already applied.'], data: { ...data, done: true, executed: true, pushed: pending, signatures: preflight.count } };
+}
+
+const SPEC = { boolean: ['--execute', '--json', '--linked', '--owner-confirms-old-app-gone'], value: ['--url-env', '--green-at'] };
+
+/** Entry of the verb: `starci app db post-cutover [--execute] [--green-at <ISO> | --owner-confirms-old-app-gone] [--linked | --url-env NAME] [--json]`. */
+export function dbPostCutoverMain(argv, io = {}) {
+  return runVerb({
+    label: 'starci app db post-cutover', name: 'db post-cutover', code: 'DB_USAGE', io, argv, spec: SPEC,
+    run: (ctx, flags) => postCutoverDatabase(ctx, loadDatabase(ctx.cwd), {
+      execute: flags.execute === true, linked: flags.linked === true, urlEnv: flags['url-env'], greenAt: flags['green-at'], ownerConfirms: flags['owner-confirms-old-app-gone'] === true,
+    }),
+  });
+}

package/emit/db-types.mjs

@@ -74,6 +74,15 @@ const withNpxFallback = (run, platform) => (file, args, options = {}) => {
 /** The first meaningful line of a failure output, for the error a human acts on. */
 const firstLine = (text) => String(text ?? '').split(/\r?\n/).map((line) => line.trim()).filter(Boolean)[0];
 
+const START_TAIL_LINES = 12;
+const START_LINE_CHARS = 300;
+/** The last lines (bounded) of a failed `supabase start`: its cause (42501 permission denied to alter role) sits after the first progress lines, so the first line alone hid it. */
+const startDetail = (started) => {
+  const text = [started?.stderr, started?.stdout, started?.error?.message ?? started?.error].map((part) => String(part ?? '')).find((part) => part.trim()) ?? '';
+  const lines = text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).map((line) => (line.length > START_LINE_CHARS ? `${line.slice(0, START_LINE_CHARS)}...` : line));
+  return lines.length ? lines.slice(-START_TAIL_LINES).join(' | ') : 'no output';
+};
+
 /**
  * The schemas `supabase/config.toml` exposes under [api] (`[]` when the file or the list is absent - the CLI then reads its
  * own defaults). A config that does not parse is a refusal: L08 reads the same file and the emit must not guess.
@@ -127,7 +136,7 @@ export function generateDbTypes({ root, run = spawn, platform = process.platform
   const started = execute(SUPABASE_CLI, ['start', '-x', 'studio,mailpit,logflare,vector,edge-runtime,imgproxy,supavisor'], { cwd: root });
   const already = /already (?:running|started)/i.test(`${started?.stderr ?? ''}${started?.stdout ?? ''}`);
   if (started?.error || (started?.status !== 0 && !already)) {
-    throw new DbTypesError(`\`${SUPABASE_CLI} start\` failed${started?.status != null ? ` (exit ${started.status})` : ''}: ${firstLine(started?.stderr) ?? firstLine(started?.error?.message ?? started?.error) ?? 'no output'}; Docker must be running`, { file: dbTypesPath });
+    throw new DbTypesError(`\`${SUPABASE_CLI} start\` failed${started?.status != null ? ` (exit ${started.status})` : ''}: ${startDetail(started)} (the last ${START_TAIL_LINES} output lines at most; with no cause among them, Docker must be running)`, { file: dbTypesPath });
   }
   try {
     return emitDbTypesWithRunner({ root, run: execute });

package/lint/run.mjs

@@ -94,7 +94,7 @@ async function runLinter({ cwd, pkg, bin, args, bound = null }) {
   // ESLint prints its report on stdout; stylelint uses stderr. JSON does not prove a completed child: only exits 0/1
   // without a spawn error or signal are measurable, and exit 1 must carry findings.
   let results;
-  try { results = JSON.parse(run.stdout.trim() || run.stderr); } catch { return { error: `${pkg} produced no json report in ${path.basename(cwd)}/ (exit ${run.status}): ${String(run.stderr || run.stdout).trim().split('\n')[0]}` }; }
+  try { results = JSON.parse(run.stdout.trim() || run.stderr); } catch { return { error: `${pkg} produced no json report in ${path.basename(cwd)}/ (exit ${run.status}): ${String(run.stderr || run.stdout).trim().split('\n').slice(0, 8).join(' | ')}` }; }
   if (!Array.isArray(results)) return { error: `${pkg} produced a report that is not a result list` };
   const completed = !run.error && !run.signal && [0, 1].includes(run.status)
     && (run.status === 0 || results.some((result) => result?.messages?.length || result?.warnings?.length));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.2.17",
+  "version": "4.4.0",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "type": "module",
   "license": "MIT",
@@ -18,6 +18,9 @@
     "LICENSE",
     "src/main.mjs",
     "emit/**",
+    "stack/**",
+    "release/**",
+    "db/**",
     "lint/**",
     "scaffold/**",
     "report/**",