@starci/hfs 4.11.22 → 4.12.0

package/sync/sonar-key.mjs

@@ -4,56 +4,57 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { parseYaml as bundledParseYaml } from '../runtime/engine/yaml.mjs';
-
 /** The stack declaration, app-relative: .starcistacks sits at the app root, beside be/, fe/ and .starciwork. */
 export const DECLARATION = path.join('.starcistacks', 'application-stacks.yaml');
-
 /** The repository name the declaration lists its projects under: the app package.json name, else the folder name. */
 export function repositoryName(root) {
-  try {
-    const name = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).name;
-    if (typeof name === 'string' && name) return name;
-  } catch {
-    // no readable package.json: the folder name stands in
-  }
-  return path.basename(path.resolve(root));
+    try {
+        const name = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).name;
+        if (typeof name === 'string' && name)
+            return name;
+    }
+    catch {
+        // no readable package.json: the folder name stands in
+    }
+    return path.basename(path.resolve(root));
 }
-
 /** The keys services.sonar declares for `repository` in a parsed declaration (empty when it declares none). */
 export function declaredSonarKeys(declaration, repository) {
-  const projects = declaration?.services?.sonar?.projects;
-  if (!Array.isArray(projects)) return [];
-  return projects.filter(project => project?.repository === repository && typeof project.key === 'string' && project.key).map(project => project.key);
+    const projects = declaration?.services?.sonar?.projects;
+    if (!Array.isArray(projects))
+        return [];
+    return projects.filter((project) => project?.repository === repository && typeof project.key === 'string' && project.key).map((project) => project.key);
 }
-
 /**
  * The declared key of the app at `root`, or null when the app has no stack declaration or the declaration names none for it.
  * Two keys for one app are refused through `fail`. `parseYaml(text)` is injected; the default is the YAML parser bundled in this
  * package (the package installs with no node_modules).
  */
 export async function readDeclaredSonarKey(root, { parseYaml, fail }) {
-  const file = path.join(root, DECLARATION);
-  if (!fs.existsSync(file)) return null;
-  const parse = parseYaml ?? bundledParseYaml;
-  const keys = declaredSonarKeys(parse(fs.readFileSync(file, 'utf8')), repositoryName(root));
-  if (keys.length > 1) fail(`${DECLARATION.split(path.sep).join('/')} declares ${keys.length} Sonar projects for ${repositoryName(root)} (${keys.join(', ')}); one app has one key`);
-  return keys[0] ?? null;
+    const file = path.join(root, DECLARATION);
+    if (!fs.existsSync(file))
+        return null;
+    const parse = parseYaml ?? bundledParseYaml;
+    const keys = declaredSonarKeys(parse(fs.readFileSync(file, 'utf8')), repositoryName(root));
+    if (keys.length > 1)
+        fail(`${DECLARATION.split(path.sep).join('/')} declares ${keys.length} Sonar projects for ${repositoryName(root)} (${keys.join(', ')}); one app has one key`);
+    return keys[0] ?? null;
 }
-
 /**
  * The quality gate the declaration names for Sonar: `{ file, qualityGate }` (file app-relative), or null when there is no
  * declaration, Sonar is disabled in it, or it declares no Sonar service. The one gate is knowledge/sonar-gate.yaml; an app names it
  * and never states thresholds of its own.
  */
 export function readDeclaredSonarGate(root, { parseYaml } = {}) {
-  const file = path.join(root, DECLARATION);
-  if (!fs.existsSync(file)) return null;
-  const sonar = (parseYaml ?? bundledParseYaml)(fs.readFileSync(file, 'utf8'))?.services?.sonar;
-  if (!sonar || sonar.mode === 'disabled') return null;
-  return { file: path.relative(root, file).split(path.sep).join('/'), qualityGate: typeof sonar.qualityGate === 'string' ? sonar.qualityGate : null };
+    const file = path.join(root, DECLARATION);
+    if (!fs.existsSync(file))
+        return null;
+    const sonar = (parseYaml ?? bundledParseYaml)(fs.readFileSync(file, 'utf8'))?.services?.sonar;
+    if (!sonar || sonar.mode === 'disabled')
+        return null;
+    return { file: path.relative(root, file).split(path.sep).join('/'), qualityGate: typeof sonar.qualityGate === 'string' ? sonar.qualityGate : null };
 }
-
 /** The quality-gate name for an app edition from the one sonar-gate document. */
 export function sonarGateName(document, edition = 'full') {
-  return (edition === 'lite' ? document?.lite : document)?.gate?.name ?? null;
+    return (edition === 'lite' ? document?.lite : document)?.gate?.name ?? null;
 }

package/sync/stack-images.d.mts

@@ -0,0 +1,36 @@
+type Declaration = any;
+type ParseYaml = (text: string) => Declaration;
+/** One image of the declaration: the service, its app and whether it carries build arguments. */
+export interface StackImage {
+    service: string;
+    app: string;
+    buildArgs: boolean;
+}
+/** What the managed workflows render from the declaration. */
+export interface DeclaredStack {
+    images: StackImage[];
+    passEnv: string[];
+    imageEnvironments?: Record<string, string[]>;
+}
+/**
+ * What the managed workflows render from the declaration at `root`: { images, passEnv, imageEnvironments } (empty when the app has no
+ * declaration, no deploy block or a declaration that does not parse; `starci app check` judges those). `parseYaml(text)` is injected.
+ */
+export declare function readDeclaredStack(root: string, { parseYaml }?: {
+    parseYaml?: ParseYaml | undefined;
+}): DeclaredStack;
+/** Parsed declarations share the exact image, environment and pass-env projection used by sync. */
+export declare function declaredStack(declaration: Declaration): DeclaredStack;
+/**
+ * The text blocks the stack-deploy.yml template places at the end of a line (each already indented for its position, every line led by
+ * a newline; empty when there is nothing to place):
+ *   stackGuard       the first step of the release job when the app declares no image (it fails with the reason)
+ *   stackNames       the `names` step lines assigning each image repository (ghcr.io/<lowercase owner>/<project>-<app>)
+ *   stackImageSteps  per image: the optional build-args step and the build-and-push step
+ *   stackImageEnv    the env entries of the deploy step: IMAGE_<SERVICE> = repository@digest
+ *   stackImageArgs   the `--image "<service>=$IMAGE_<SERVICE>" \` continuation lines of the deploy command
+ *   stackPassEnv     the env entries of the deploy step for the declared host variables (vars.<NAME>)
+ * `dockerfileOf(app)` names the Dockerfile of an app (the sync module knows the layout).
+ */
+export declare function stackWorkflowVariables({ images, passEnv, imageEnvironments: environments }: DeclaredStack, project: string, dockerfileOf: (app: string) => string): Record<string, string>;
+export {};

package/sync/stack-images.mjs

@@ -10,106 +10,97 @@ import path from 'node:path';
 import { parseYaml as bundledParseYaml } from '../runtime/engine/yaml.mjs';
 import { DECLARATION } from './sonar-key.mjs';
 import { byCodeUnit } from '../report/order.mjs';
-
 const NAME = /^[a-z][a-z0-9-]*$/u;
 const KEY = /^[A-Z][A-Z0-9_]*$/u;
 const INDENT = ' '.repeat(6);
 const CONTINUE = '\\';
 const NO_IMAGES_MESSAGE = 'no image is declared: declare environments.<env>.deploy (with images) in .starcistacks/application-stacks.yaml before running this workflow';
-
-const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
-const hasBuildArgs = args => record(args) && (Object.keys(record(args.values) ? args.values : {}).length > 0 || record(args.sealed));
-
+const record = (value) => value !== null && typeof value === 'object' && !Array.isArray(value); // reason: a YAML mapping
+const hasBuildArgs = (args) => record(args) && (Object.keys(record(args.values) ? args.values : {}).length > 0 || record(args.sealed));
 function environmentImages(environment) {
-  const images = environment?.deploy?.images;
-  if (!record(images)) return [];
-  return Object.entries(images)
-    .filter(([service, entry]) => NAME.test(service) && record(entry) && NAME.test(String(entry.app)))
-    .map(([service, entry]) => ({ service, app: entry.app, buildArgs: hasBuildArgs(entry.buildArgs) }));
+    const images = environment?.deploy?.images;
+    if (!record(images))
+        return [];
+    return Object.entries(images)
+        .filter(([service, entry]) => NAME.test(service) && record(entry) && NAME.test(String(entry.app)))
+        .map(([service, entry]) => ({ service, app: entry.app, buildArgs: hasBuildArgs(entry.buildArgs) }));
 }
-
 /**
  * The images of a parsed declaration, [{ service, app, buildArgs }] sorted by service: the union over its environments (the first
  * environment that names a service decides its app; a later one only adds build arguments). A declaration with no deploy block has none.
  */
 function declaredStackImages(declaration) {
-  const byService = new Map();
-  for (const environment of Object.values(record(declaration?.environments) ? declaration.environments : {})) {
-    for (const image of environmentImages(environment)) {
-      const known = byService.get(image.service);
-      byService.set(image.service, known ? { ...known, buildArgs: known.buildArgs || image.buildArgs } : image);
+    const byService = new Map();
+    for (const environment of Object.values(record(declaration?.environments) ? declaration.environments : {})) {
+        for (const image of environmentImages(environment)) {
+            const known = byService.get(image.service);
+            byService.set(image.service, known ? { ...known, buildArgs: known.buildArgs || image.buildArgs } : image);
+        }
     }
-  }
-  return [...byService.values()].sort((a, b) => byCodeUnit(a.service, b.service));
+    return [...byService.values()].sort((a, b) => byCodeUnit(a.service, b.service));
 }
-
 /** The host variables (names only) the declared environments interpolate into `docker stack config`: the union of `deploy.passEnv`. */
 function declaredPassEnv(declaration) {
-  const names = Object.values(record(declaration?.environments) ? declaration.environments : {})
-    .flatMap(environment => (Array.isArray(environment?.deploy?.passEnv) ? environment.deploy.passEnv : []))
-    .filter(name => typeof name === 'string' && KEY.test(name));
-  return [...new Set(names)].sort(byCodeUnit);
+    const names = Object.values(record(declaration?.environments) ? declaration.environments : {})
+        .flatMap(environment => (Array.isArray(environment?.deploy?.passEnv) ? environment.deploy.passEnv : []))
+        .filter((name) => typeof name === 'string' && KEY.test(name));
+    return [...new Set(names)].sort(byCodeUnit);
 }
-
 /** Release builds select the sole image environment, or production when several environments deploy images. */
 function imageEnvironments(declaration) {
-  return Object.fromEntries(Object.entries(declaration?.environments ?? {})
-    .filter(([name, environment]) => NAME.test(name) && environmentImages(environment).length > 0)
-    .map(([name, environment]) => [name, environmentImages(environment).map(image => image.app)]));
+    return Object.fromEntries(Object.entries(declaration?.environments ?? {})
+        .filter(([name, environment]) => NAME.test(name) && environmentImages(environment).length > 0)
+        .map(([name, environment]) => [name, environmentImages(environment).map(image => image.app)]));
 }
-
 /**
  * What the managed workflows render from the declaration at `root`: { images, passEnv, imageEnvironments } (empty when the app has no
  * declaration, no deploy block or a declaration that does not parse; `starci app check` judges those). `parseYaml(text)` is injected.
  */
 export function readDeclaredStack(root, { parseYaml = bundledParseYaml } = {}) {
-  const file = path.join(root, DECLARATION);
-  if (!fs.existsSync(file)) return { images: [], passEnv: [] };
-  let declaration;
-  try {
-    declaration = parseYaml(fs.readFileSync(file, 'utf8'));
-  } catch {
-    return { images: [], passEnv: [] };
-  }
-  return declaredStack(declaration);
+    const file = path.join(root, DECLARATION);
+    if (!fs.existsSync(file))
+        return { images: [], passEnv: [] };
+    let declaration;
+    try {
+        declaration = parseYaml(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return { images: [], passEnv: [] };
+    }
+    return declaredStack(declaration);
 }
-
 /** Parsed declarations share the exact image, environment and pass-env projection used by sync. */
 export function declaredStack(declaration) {
-  return { images: declaredStackImages(declaration), passEnv: declaredPassEnv(declaration), imageEnvironments: imageEnvironments(declaration) };
+    return { images: declaredStackImages(declaration), passEnv: declaredPassEnv(declaration), imageEnvironments: imageEnvironments(declaration) };
 }
-
-const envName = service => `IMAGE_${service.toUpperCase().replaceAll('-', '_')}`;
+const envName = (service) => `IMAGE_${service.toUpperCase().replaceAll('-', '_')}`;
 /** Lines placed at the end of a template line: each one starts with a newline, so nothing declared leaves nothing, not even a blank line. */
 const block = (items, indent = INDENT) => items.map(item => `\n${indent}${item}`).join('');
-
 function buildArgsStep(image) {
-  return [
-    `- name: public build values of ${image.service}`,
-    `  id: args-${image.service}`,
-    '  env:',
-    '    SOPS_AGE_KEY: ${{ secrets.SOPS_AGE_KEY }}',
-    `  run: npx --no-install starci app stack build-args --env "$STACK_ENVIRONMENT" --app ${image.app}`,
-  ];
+    return [
+        `- name: public build values of ${image.service}`,
+        `  id: args-${image.service}`,
+        '  env:',
+        '    SOPS_AGE_KEY: ${{ secrets.SOPS_AGE_KEY }}',
+        `  run: npx --no-install starci app stack build-args --env "$STACK_ENVIRONMENT" --app ${image.app}`,
+    ];
 }
-
 function buildPushStep(image, dockerfile) {
-  return [
-    `- name: build and push ${image.service}`,
-    `  id: build-${image.service}`,
-    '  uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6.19.2',
-    '  with:',
-    '    context: .',
-    `    file: ${dockerfile}`,
-    '    push: true',
-    '    provenance: false',
-    `    tags: \${{ steps.names.outputs.${image.service} }}:\${{ github.sha }}`,
-    ...(image.buildArgs ? [`    build-args: \${{ steps.args-${image.service}.outputs.args }}`] : []),
-    `    cache-from: type=gha,scope=${image.service}`,
-    `    cache-to: type=gha,scope=${image.service},mode=max`,
-  ];
+    return [
+        `- name: build and push ${image.service}`,
+        `  id: build-${image.service}`,
+        '  uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6.19.2',
+        '  with:',
+        '    context: .',
+        `    file: ${dockerfile}`,
+        '    push: true',
+        '    provenance: false',
+        `    tags: \${{ steps.names.outputs.${image.service} }}:\${{ github.sha }}`,
+        ...(image.buildArgs ? [`    build-args: \${{ steps.args-${image.service}.outputs.args }}`] : []),
+        `    cache-from: type=gha,scope=${image.service}`,
+        `    cache-to: type=gha,scope=${image.service},mode=max`,
+    ];
 }
-
 /**
  * The text blocks the stack-deploy.yml template places at the end of a line (each already indented for its position, every line led by
  * a newline; empty when there is nothing to place):
@@ -122,37 +113,36 @@ function buildPushStep(image, dockerfile) {
  * `dockerfileOf(app)` names the Dockerfile of an app (the sync module knows the layout).
  */
 export function stackWorkflowVariables({ images = [], passEnv = [], imageEnvironments: environments = {} }, project, dockerfileOf) {
-  const guard = images.length ? '' : block([
-    '- name: require a declared image',
-    '  shell: bash',
-    `  run: 'echo "::error::${NO_IMAGES_MESSAGE}"; exit 1'`,
-  ]);
-  const names = images.map(image => `echo "${image.service}=ghcr.io/\${owner}/${project}-${image.app}" >> "$GITHUB_OUTPUT"`);
-  return {
-    ...releaseImageVariables(environments),
-    stackGuard: guard,
-    stackNames: block(names, ' '.repeat(10)),
-    stackImageSteps: images.map(image => block([...(image.buildArgs ? buildArgsStep(image) : []), ...buildPushStep(image, dockerfileOf(image.app))])).join(''),
-    stackImageEnv: block(images.map(image => `${envName(image.service)}: \${{ steps.names.outputs.${image.service} }}@\${{ steps.build-${image.service}.outputs.digest }}`), ' '.repeat(10)),
-    stackImageArgs: block(images.map(image => `--image "${image.service}=$${envName(image.service)}" ${CONTINUE}`), ' '.repeat(12)),
-    stackPassEnv: block(passEnv.map(name => `${name}: \${{ vars.${name} }}`), ' '.repeat(10)),
-  };
+    const guard = images.length ? '' : block([
+        '- name: require a declared image',
+        '  shell: bash',
+        `  run: 'echo "::error::${NO_IMAGES_MESSAGE}"; exit 1'`,
+    ]);
+    const names = images.map(image => `echo "${image.service}=ghcr.io/\${owner}/${project}-${image.app}" >> "$GITHUB_OUTPUT"`);
+    return {
+        ...releaseImageVariables(environments),
+        stackGuard: guard,
+        stackNames: block(names, ' '.repeat(10)),
+        stackImageSteps: images.map(image => block([...(image.buildArgs ? buildArgsStep(image) : []), ...buildPushStep(image, dockerfileOf(image.app))])).join(''),
+        stackImageEnv: block(images.map(image => `${envName(image.service)}: \${{ steps.names.outputs.${image.service} }}@\${{ steps.build-${image.service}.outputs.digest }}`), ' '.repeat(10)),
+        stackImageArgs: block(images.map(image => `--image "${image.service}=$${envName(image.service)}" ${CONTINUE}`), ' '.repeat(12)),
+        stackPassEnv: block(passEnv.map(name => `${name}: \${{ vars.${name} }}`), ' '.repeat(10)),
+    };
 }
-
 /** The matrix uses the deploy verb only for apps the selected environment deploys; undeployed images retain Dockerfile defaults. */
 function releaseImageVariables(environments) {
-  const names = Object.keys(environments);
-  const selectedApp = names.map(name => `(env.STACK_ENVIRONMENT == '${name}' && contains(fromJSON('${JSON.stringify(environments[name])}'), matrix.name))`).join(' || ') || 'false';
-  const multiple = names.length > 1;
-  const environment = multiple ? 'production' : names[0] ?? 'production';
-  return {
-    imageEnvironment: environment,
-    imageJobEnvironment: names.length ? `\n    environment: ${environment}` : '',
-    imageEnvironmentGuard: multiple ? block([
-      '- name: require a declared image environment',
-      `  if: \${{ !contains(fromJSON('${JSON.stringify(names)}'), env.STACK_ENVIRONMENT) }}`,
-      '  run: \'echo "::error::STACKS_DEPLOY_ENV_UNKNOWN: selected environment declares no deploy images"; exit 1\'',
-    ]) : '',
-    imageBuildArgsIf: `\${{ ${selectedApp} }}`,
-  };
+    const names = Object.keys(environments);
+    const selectedApp = names.map(name => `(env.STACK_ENVIRONMENT == '${name}' && contains(fromJSON('${JSON.stringify(environments[name])}'), matrix.name))`).join(' || ') || 'false';
+    const multiple = names.length > 1;
+    const environment = multiple ? 'production' : names[0] ?? 'production';
+    return {
+        imageEnvironment: environment,
+        imageJobEnvironment: names.length ? `\n    environment: ${environment}` : '',
+        imageEnvironmentGuard: multiple ? block([
+            '- name: require a declared image environment',
+            `  if: \${{ !contains(fromJSON('${JSON.stringify(names)}'), env.STACK_ENVIRONMENT) }}`,
+            '  run: \'echo "::error::STACKS_DEPLOY_ENV_UNKNOWN: selected environment declares no deploy images"; exit 1\'',
+        ]) : '',
+        imageBuildArgsIf: `\${{ ${selectedApp} }}`,
+    };
 }

package/sync/ts-strict.d.mts

@@ -0,0 +1,14 @@
+export declare const TS_STRICT_FILE = "tsconfig.json";
+/** One HFS_TS_STRICT finding. */
+export type TsStrictFinding = {
+    code: 'HFS_TS_STRICT';
+    level: 'error';
+    path: string;
+    flag: string;
+    message: string;
+};
+/**
+ * The HFS_TS_STRICT findings of one tsconfig.json text against the rendered one: [{ code, level, path, flag, message }].
+ * `flag` names the offending key (`extends`, `paths`, a compiler option, or a top-level key).
+ */
+export declare function tsStrictFindings(actualText: string, expectedText: string, file?: string): TsStrictFinding[];

package/sync/ts-strict.mjs

@@ -4,45 +4,54 @@
 // include/exclude/files/references, has left the preset. The expected shape is read from the rendered
 // template (templates/<profile>/tool-config/tsconfig.json), so the preset name and the aliases exist in one place only.
 export const TS_STRICT_FILE = 'tsconfig.json';
-
 const same = (left, right) => JSON.stringify(left) === JSON.stringify(right);
 const describe = (value) => (value === undefined ? 'unset' : JSON.stringify(value));
-
 /**
  * The HFS_TS_STRICT findings of one tsconfig.json text against the rendered one: [{ code, level, path, flag, message }].
  * `flag` names the offending key (`extends`, `paths`, a compiler option, or a top-level key).
  */
 export function tsStrictFindings(actualText, expectedText, file = TS_STRICT_FILE) {
-  const expected = JSON.parse(expectedText);
-  const finding = (flag, message) => ({ code: 'HFS_TS_STRICT', level: 'error', path: file, flag, message: `${file}: ${message}` });
-  let actual;
-  try {
-    actual = JSON.parse(actualText);
-  } catch (error) {
-    return [finding('parse', `is not valid JSON (${String(error.message).split('\n')[0]}); it must be the rendered file, which extends ${expected.extends}`)];
-  }
-  if (!actual || typeof actual !== 'object' || Array.isArray(actual)) return [finding('parse', `is not a JSON object; it must extend ${expected.extends}`)];
-  const findings = [];
-  if (actual.extends !== expected.extends) findings.push(finding('extends', `extends ${describe(actual.extends)}, but the only preset is ${expected.extends}`));
-  for (const key of Object.keys(actual)) {
-    if (key === 'extends' || key === 'compilerOptions') continue;
-    if (key in expected && same(actual[key], expected[key])) continue;
-    findings.push(finding(key, key in expected ? `${key} must be ${describe(expected[key])}, found ${describe(actual[key])}` : `sets ${key}: the program is the template's, narrowed by nothing else`));
-  }
-  for (const key of Object.keys(expected)) {
-    if (key !== 'extends' && key !== 'compilerOptions' && !(key in actual)) findings.push(finding(key, `${key} is missing; it must be ${describe(expected[key])}`));
-  }
-  const options = actual.compilerOptions && typeof actual.compilerOptions === 'object' && !Array.isArray(actual.compilerOptions) ? actual.compilerOptions : {};
-  for (const [flag, value] of Object.entries(options)) {
-    if (flag === 'paths') continue;
-    findings.push(finding(flag, `${value === false ? 'lowers' : 'sets'} ${flag} (${describe(value)}); every compiler option comes from the preset`));
-  }
-  const aliases = expected.compilerOptions?.paths ?? {};
-  for (const alias of Object.keys(aliases)) {
-    if (!same(options.paths?.[alias], aliases[alias])) findings.push(finding('paths', `paths must map ${alias} to ${describe(aliases[alias])}, found ${describe(options.paths?.[alias])}`));
-  }
-  for (const alias of Object.keys(options.paths ?? {})) {
-    if (!(alias in aliases)) findings.push(finding('paths', `paths adds the alias ${alias}; the aliases of the template are the only ones`));
-  }
-  return findings;
+    // reason: tsconfig JSON parsed from disk; its keys are exactly what this check compares
+    const expected = JSON.parse(expectedText);
+    const finding = (flag, message) => ({ code: 'HFS_TS_STRICT', level: 'error', path: file, flag, message: `${file}: ${message}` });
+    // reason: tsconfig JSON parsed from disk
+    let actual;
+    try {
+        actual = JSON.parse(actualText);
+    }
+    catch (error) {
+        return [finding('parse', `is not valid JSON (${String(error.message).split('\n')[0]}); it must be the rendered file, which extends ${expected.extends}`)];
+    }
+    if (!actual || typeof actual !== 'object' || Array.isArray(actual))
+        return [finding('parse', `is not a JSON object; it must extend ${expected.extends}`)];
+    const findings = [];
+    if (actual.extends !== expected.extends)
+        findings.push(finding('extends', `extends ${describe(actual.extends)}, but the only preset is ${expected.extends}`));
+    for (const key of Object.keys(actual)) {
+        if (key === 'extends' || key === 'compilerOptions')
+            continue;
+        if (key in expected && same(actual[key], expected[key]))
+            continue;
+        findings.push(finding(key, key in expected ? `${key} must be ${describe(expected[key])}, found ${describe(actual[key])}` : `sets ${key}: the program is the template's, narrowed by nothing else`));
+    }
+    for (const key of Object.keys(expected)) {
+        if (key !== 'extends' && key !== 'compilerOptions' && !(key in actual))
+            findings.push(finding(key, `${key} is missing; it must be ${describe(expected[key])}`));
+    }
+    const options = actual.compilerOptions && typeof actual.compilerOptions === 'object' && !Array.isArray(actual.compilerOptions) ? actual.compilerOptions : {};
+    for (const [flag, value] of Object.entries(options)) {
+        if (flag === 'paths')
+            continue;
+        findings.push(finding(flag, `${value === false ? 'lowers' : 'sets'} ${flag} (${describe(value)}); every compiler option comes from the preset`));
+    }
+    const aliases = expected.compilerOptions?.paths ?? {};
+    for (const alias of Object.keys(aliases)) {
+        if (!same(options.paths?.[alias], aliases[alias]))
+            findings.push(finding('paths', `paths must map ${alias} to ${describe(aliases[alias])}, found ${describe(options.paths?.[alias])}`));
+    }
+    for (const alias of Object.keys(options.paths ?? {})) {
+        if (!(alias in aliases))
+            findings.push(finding('paths', `paths adds the alias ${alias}; the aliases of the template are the only ones`));
+    }
+    return findings;
 }

package/templates/app/ci-workflows/github/workflows/ci.yml

@@ -83,7 +83,7 @@ jobs:
           pattern: coverage-shard-*
           path: {{lcovShardsDir}}
       - name: merge coverage
-        run: npx starci app coverage merge --out {{lcovReport}} {{lcovShardsDir}}
+        run: npx --no-install starci app coverage merge --out {{lcovReport}} {{lcovShardsDir}}
       - name: coverage proof
         run: {{ciCoverageProof}}
         env:

package/templates/app/ci-workflows/github/workflows/images.yml

@@ -2,7 +2,7 @@
 # Builds the image of every app on its release tag, so a Dockerfile that no longer builds fails that release.
 # It never pushes: publishing an image is the product's decision, not this file's.
 # When an environment declares images, the job is bound to that protected GitHub environment and opens its sealed build
-# arguments with that environment's SOPS_AGE_KEY (its server identity, starci app secret server-key <env> --backup github).
+# arguments with that environment's SOPS_AGE_KEY (its server identity, starci app secret server-key --env <env> --backup github --execute).
 name: images
 
 on:

package/templates/app/ci-workflows/github/workflows/stack-deploy.yml

@@ -7,7 +7,7 @@
 # operation rollback  redeploys a stored release; "release" is 16 lowercase hex characters, empty means the previous accepted release
 # The environment input names a protected GitHub environment (required reviewers) that holds:
 #   vars    VPS_HOST, VPS_USER (the swarm manager); a variable named in deploy.passEnv, when the stack interpolates one
-#   secrets SOPS_AGE_KEY (that environment's server identity, stored there by starci app secret server-key <env> --backup github;
+#   secrets SOPS_AGE_KEY (that environment's server identity, stored there by starci app secret server-key --env <env> --backup github --execute;
 #           both jobs are bound to the environment, so they read it and never a repository secret of that name), VPS_SSH_KEY
 #           (CI-only deploy key), VPS_KNOWN_HOSTS (pinned host keys)
 # Nothing else is a secret: images are pushed with the workflow token, which also reads the CI verdict of the tag's commit a production deploy
@@ -96,7 +96,7 @@ jobs:
           SOPS_AGE_KEY: ${{ secrets.SOPS_AGE_KEY }}{{stackImageEnv}}{{stackPassEnv}}
         run: |
           npx --no-install starci app stack deploy --env "$STACK_ENVIRONMENT" \{{stackImageArgs}}
-            --source-sha "$GITHUB_SHA" --execute
+            --sha "$GITHUB_SHA" --execute
       - name: disconnect from the swarm manager
         env:
           XDG_DATA_HOME: ${{ runner.temp }}/starci-data

package/templates/app/ci-workflows/github/workflows/stack-key-restore.yml

@@ -1,5 +1,5 @@
 {{header}}
-# Restores the deploy server's age identity from its GitHub Environment backup (starci app secret server-key <env> --backup github
+# Restores the deploy server's age identity from its GitHub Environment backup (starci app secret server-key --env <env> --backup github --execute
 # stored it; --restore github dispatches this file). It runs by hand only and writes {{serverAgeIdentity}} on the server when no
 # identity is there and the secret's public key is the recipient input (deploy.remote.serverRecipient), with umask 077 and mode 600,
 # owned by root; it never echoes the identity and never overwrites one.

package/templates/app/ci-workflows-lite/github/workflows/ci.yml

@@ -83,7 +83,7 @@ jobs:
           pattern: coverage-shard-*
           path: {{lcovShardsDir}}
       - name: merge coverage
-        run: npx starci app coverage merge --out {{lcovReport}} {{lcovShardsDir}}
+        run: npx --no-install starci app coverage merge --out {{lcovReport}} {{lcovShardsDir}}
       - name: coverage proof
         run: {{ciCoverageProof}}
         env:

package/templates/app/ci-workflows-lite/github/workflows/db-deploy.yml

@@ -56,8 +56,8 @@ jobs:
           test -s "$BACKUP_RECEIPT"
           secret_dir="$XDG_DATA_HOME/StarCi/secrets/{{project}}/$STACK_ENVIRONMENT"
           trap 'rm -rf -- "$secret_dir"' EXIT
-          npx --no-install starci app secret materialize "$STACK_ENVIRONMENT"
+          npx --no-install starci app secret materialize --env "$STACK_ENVIRONMENT"
           DATABASE_URL="$(cat "$secret_dir/DATABASE_URL")"
           export DATABASE_URL
-          npx --no-install starci app db migrate --url-env DATABASE_URL
-          STARCI_DB_ARMED=1 npx --no-install starci app db migrate --url-env DATABASE_URL --execute
+          npx --no-install starci app db migrate --db-url-env DATABASE_URL || test "$?" -eq 1
+          STARCI_DB_ARMED=1 npx --no-install starci app db migrate --db-url-env DATABASE_URL --execute

package/templates/app/ci-workflows-lite/github/workflows/images.yml

@@ -2,7 +2,7 @@
 # Builds each image declared by the lite app. The API image is required; a front-end image is emitted only when declared.
 # It runs on the release tag, so every image is built there, and never pushes.
 # When an environment declares images, the job is bound to that protected GitHub environment and opens its sealed build
-# arguments with that environment's SOPS_AGE_KEY (its server identity, starci app secret server-key <env> --backup github).
+# arguments with that environment's SOPS_AGE_KEY (its server identity, starci app secret server-key --env <env> --backup github --execute).
 name: images
 
 on:

package/templates/app/ci-workflows-lite/github/workflows/stack-deploy.yml

@@ -7,7 +7,7 @@
 # operation rollback  redeploys a stored release; "release" is 16 lowercase hex characters, empty means the previous accepted release
 # The environment input names a protected GitHub environment (required reviewers) that holds:
 #   vars    VPS_HOST, VPS_USER (the swarm manager); a variable named in deploy.passEnv, when the stack interpolates one
-#   secrets SOPS_AGE_KEY (that environment's server identity, stored there by starci app secret server-key <env> --backup github;
+#   secrets SOPS_AGE_KEY (that environment's server identity, stored there by starci app secret server-key --env <env> --backup github --execute;
 #           both jobs are bound to the environment, so they read it and never a repository secret of that name), VPS_SSH_KEY
 #           (CI-only deploy key), VPS_KNOWN_HOSTS (pinned host keys)
 # Nothing else is a secret: images are pushed with the workflow token, which also reads the CI verdict of the tag's commit a production deploy
@@ -96,7 +96,7 @@ jobs:
           SOPS_AGE_KEY: ${{ secrets.SOPS_AGE_KEY }}{{stackImageEnv}}{{stackPassEnv}}
         run: |
           npx --no-install starci app stack deploy --env "$STACK_ENVIRONMENT" \{{stackImageArgs}}
-            --source-sha "$GITHUB_SHA" --execute
+            --sha "$GITHUB_SHA" --execute
       - name: disconnect from the swarm manager
         env:
           XDG_DATA_HOME: ${{ runner.temp }}/starci-data

package/templates/app/ci-workflows-lite/github/workflows/stack-key-restore.yml

@@ -1,5 +1,5 @@
 {{header}}
-# Restores the deploy server's age identity from its GitHub Environment backup (starci app secret server-key <env> --backup github
+# Restores the deploy server's age identity from its GitHub Environment backup (starci app secret server-key --env <env> --backup github --execute
 # stored it; --restore github dispatches this file). It runs by hand only and writes {{serverAgeIdentity}} on the server when no
 # identity is there and the secret's public key is the recipient input (deploy.remote.serverRecipient), with umask 077 and mode 600,
 # owned by root; it never echoes the identity and never overwrites one.

package/templates/app/codegen-lite/scripts/codegen.mjs

@@ -1,4 +1,4 @@
-// Generated by {{appBinary}} sync (app root). Do not edit: run "npx {{appBinary}} sync --write".
+// Generated by {{appBinary}} sync (app root). Do not edit: run "npx {{appBinary}} sync --execute".
 // The GraphQL wire types of the front end (`npm run codegen`, also `npm run codegen:graphql`); a lite app generates no database types.
 // {{> app/codegen-prelude.mjs.partial}}
 

package/templates/app/db-bootstrap/db/bootstrap.sql

@@ -1,4 +1,4 @@
--- Managed by starci app sync (slot app.db.bootstrap); do not edit: run "npx starci app sync --write".
+-- Managed by starci app sync (slot app.db.bootstrap); do not edit: run "npx starci app sync --execute".
 -- The pre-migration bootstrap of a lite app's self-hosted PostgreSQL (ruling lite-self-hosted-postgres-passport-minio), run on the official
 -- postgres image of .starcistacks/images/db/Dockerfile (ruling lite-official-postgres-image). Migrations written for Supabase reference objects GoTrue and Supabase
 -- Storage created: the browser roles, the `auth` schema (auth.users, auth.identities, auth.sessions, auth.uid/jwt/role) and the `storage`

package/templates/app/db-image/starcistacks/images/db/Dockerfile

@@ -1,4 +1,4 @@
-# Managed by starci app sync (slot app.db.image); do not edit: run "npx starci app sync --write".
+# Managed by starci app sync (slot app.db.image); do not edit: run "npx starci app sync --execute".
 # The image of the db service of a lite app, kept with the stacks (rulings lite-official-postgres-image, lite-pgmq-bus-bullmq-jobs and
 # lite-db-image-in-stacks): the Docker Official postgres image, pinned by digest, plus pgvector from the PGDG repository the image
 # already configures and pgmq, the event bus, from its pinned release source verified by sha256 (pgmq is SQL objects only, so its

package/templates/app/hooks/husky/pre-commit

@@ -3,8 +3,8 @@
 # swallowed failure: HFS_BYPASS_MARKER) of the staged files, managed files equal to their render, eslint of the staged files of each
 # side (the fe packages are built first: the apps import their emitted types, the way the managed lint script does), stylelint over the staged CSS of fe, a prettier check of the staged files. Every step ends the hook when it fails: none can be
 # skipped. Types and the targeted specs belong to the op gate.
-npx starci app hygiene || exit $?
-npx starci app sync --check || exit $?
+npx --no-install starci app check --staged || exit $?
+npx --no-install starci app sync || exit $?
 # NUL-delimited paths keep filenames intact; bounded batches fit the Windows command line.
 git diff --cached --name-only --diff-filter=ACMR -z --relative=be -- '*.ts' '*.mts' '*.cts' '*.js' '*.mjs' '*.cjs' |
   xargs -0 -n 50 sh -c 'if [ "$#" -gt 0 ]; then cd be && npx eslint -- "$@"; fi' sh || exit $?