@starci/hfs 4.0.8 → 4.0.10

package/bin/hfs.mjs

@@ -1,233 +0,0 @@
-#!/usr/bin/env node
-// hfs - the HFS command line of a StarCi app: one repository, `<app>/`, with one package.json, lockfile and node_modules at its root
-// and two sides, be/ and fe/, declared by the one hfs.json of kind app. Every verb runs at the app root.
-//   hfs check   [--repo <dir>] [--json] [--fast] [--base <ref>]
-//                                            every tracked path has a slot; required files exist; nothing forbidden or
-//                                            tracked-that-must-be-ignored; pins match; every managed file equals its render
-//                                            (sync/managed.mjs, the .gitignore block and sonar-project.properties included); no empty or ghost
-//                                            directory, no untracked entry outside an ignored slot; plaintext secrets, the .starcistacks shape, CI
-//                                            and pre-push canon steps, dependency version skew, the contract snapshot and the test, wire and i18n
-//                                            trees; prettier over every tracked file through the repository's own install (sync/format.mjs; not under
-//                                            --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.
-//                                            --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
-//                                            (exit 2), never a silent full pass. Exit 1 on any error-level finding. The root checks run once and
-//                                            the side checks and the machine once per side, the side folder as their root; every path is app-relative.
-//   hfs lint    [--repo <dir>] [--changed <file>...] [--fix] [--format text|json] [--sonar <file>]
-//                                            the ONE lint entry (npm run lint): ESLint per side with that side's canon config (per-file rules and
-//                                            the project-graph rules), this check's findings, and stylelint over the fe side, as one starci/lint@1
-//                                            report; --sonar writes the one Sonar import file. Exit 0 clean, 1 findings, 2 a tool could not run (lint/run.mjs).
-//   hfs scaffold app <name> [--into <dir>]  a new app <dir>/<name>/: the root (hfs.json, package.json, managed files, .starciwork) and the
-//                                            be/ and fe/ skeletons (scaffold/app.mjs). Refuses an existing directory.
-//   hfs explain <path> [--repo <dir>] [--json]   which slot owns the path, its tier, allowed imports, required tests.
-//   hfs emit-contracts [--repo <dir>]      write be/contracts/<app>/schema.graphql of every api app that serves GraphQL (emit/contracts.mjs):
-//                                            printSchema(lexicographicSortSchema) of the resolvers the app root composes; no env, no database, no network.
-//   hfs sync (--check | --write) [--root <dir>]  the managed files of the root (scripts, husky, CI, .gitignore block, sonar, prettier) and
-//                                            of each side (tsconfig, eslint, jest, stylelint); sync/cli.mjs
-//   hfs work-hygiene                              the pre-commit guard: staged .starciwork and .starcistacks paths, and the secrets guard over every staged file (read from the index); sync/cli.mjs
-//   hfs new service <dir> <name> [--inject <Decorator>=<module>:<Type> | <Class>=<module>]... [--repo <dir>]
-//                                            a back-end `<name>.service.ts` and its `<name>.service.spec.ts` skeleton (scaffold/service.mjs; <dir> is
-//                                            relative to be/): the spec is built
-//                                            with Test.createTestingModule, one provider per constructor dependency (kit doubles from @starci/jest-preset),
-//                                            one placeholder it per public method. Never overwrites a file.
-//   hfs new spec <file>.service.ts [--repo <dir>]  the spec skeleton of an existing service, read from its constructor with the repository's TypeScript
-// Every finding names a why code and carries its Vietnamese text. check, lint and explain read the app, never write to it. Exit codes:
-// 0 clean, 1 error findings, 2 a refusal or bad usage.
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { isMain } from '../runtime/scripts/lib/is-main.mjs';
-import { checkRepository, explainPath, trackedFiles } from '../runtime/scripts/hfs/check.mjs';
-import { HfsSlotsError, loadSlotManifest, readRepoDeclaration } from '../runtime/scripts/hfs/slots.mjs';
-import { formatFindings } from '../sync/format.mjs';
-import { main as syncMain } from '../sync/cli.mjs';
-import { SyncError, loadPresets } from '../sync/index.mjs';
-import { managedFindings } from '../sync/managed.mjs';
-import { emitContracts } from '../emit/contracts.mjs';
-import { ScaffoldError, newService, newSpec } from '../scaffold/service.mjs';
-import { scaffoldApp } from '../scaffold/app.mjs';
-import { contractEmitFindings } from '../runtime/scripts/hfs/rules/contract.mjs';
-import { lintRepository, parseLintArgs, printLintText } from '../lint/run.mjs';
-import { writeReport } from '../report/sonar.mjs';
-
-const USAGE = `hfs check [--repo <dir>] [--json] [--fast] [--base <ref>]
-hfs lint [--repo <dir>] [--changed <file>...] [--fix] [--format text|json] [--sonar <file>]
-hfs scaffold app <name> [--into <dir>]
-hfs emit-contracts [--repo <dir>]
-hfs explain <path> [--repo <dir>] [--json]
-hfs sync (--check | --write) [--root <dir>]
-hfs work-hygiene
-hfs new service <dir> <name> [--inject <Decorator>=<module>:<Type> | <Class>=<module>]... [--repo <dir>]
-hfs new spec <file>.service.ts [--repo <dir>]
-`;
-const PER_CODE_LIMIT = 25;
-const VALUE_FLAGS = new Set(['--repo', '--base', '--inject', '--into']);
-/** Flags that may repeat: their values are collected in order. */
-const LIST_FLAGS = new Set(['--inject']);
-const BOOL_FLAGS = new Set(['--json', '--fast']);
-
-function parse(argv) {
-  const opts = { positional: [] };
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-    if (VALUE_FLAGS.has(arg)) {
-      if (argv[i + 1] === undefined) throw new Error(`${arg} needs a value`);
-      opts[arg.slice(2)] = LIST_FLAGS.has(arg) ? [...(opts[arg.slice(2)] ?? []), argv[i + 1]] : argv[i + 1];
-      i += 1;
-    }
-    else if (BOOL_FLAGS.has(arg)) opts[arg.slice(2)] = true;
-    else if (arg.startsWith('--')) throw new Error(`unknown flag ${arg}`);
-    else opts.positional.push(arg);
-  }
-  return opts;
-}
-
-function printCheck(result, out) {
-  const { counts } = result;
-  out(`hfs check${result.fast ? ' --fast' : ''} ${result.repoRoot} (profile ${result.profile ?? 'unknown'}, manifest ${result.manifest}, ${result.tracked} tracked paths)\n`);
-  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: ${result.machine.status === 'ran' ? `ran over ${result.machine.files} source files${result.machine.paths ? ` (owners ${result.machine.paths.join(', ')})` : ''}` : `skipped, ${result.machine.reason}`}\n`);
-  if (result.contracts) out(`  contract snapshots: ${result.contracts.status === 'checked' ? `emitted and compared, ${result.contracts.apps.map((a) => `${a.app}/${a.artifact} ${a.status}`).join(', ') || 'no api app'}` : `skipped, ${result.contracts.reason}`}
-`);
-  const byCode = new Map();
-  for (const f of result.findings) byCode.set(f.code, [...(byCode.get(f.code) ?? []), f]);
-  for (const [code, list] of byCode) {
-    const first = list[0];
-    out(`\n[${first.level.toUpperCase()}] ${code} x${list.length}: ${first.titleVi}\n  ${first.whyVi}\n  -> ${first.nextStepVi}\n`);
-    for (const f of list.slice(0, PER_CODE_LIMIT)) out(`  - ${f.message}\n`);
-    if (list.length > PER_CODE_LIMIT) out(`  ... and ${list.length - PER_CODE_LIMIT} more (use --json for all)\n`);
-  }
-  out(`\n${counts.error} error finding${counts.error === 1 ? '' : 's'}, ${counts.info} report-only\n`);
-}
-
-function printExplain(e, out) {
-  out(`${e.path}\n`);
-  if (e.status === 'no-slot') {
-    out(`  no slot owns this path (${e.code}): ${e.titleVi}\n  ${e.whyVi}\n`);
-    if (e.nearest) out(`  nearest slot ${e.nearest.slot}, pattern ${e.nearest.pattern}; matched ${e.nearest.matchedPrefix || '.'}, then expected ${e.nearest.expectedNext ?? 'nothing'}\n`);
-    return;
-  }
-  if (e.status === 'ambiguous') { out(`  owned equally by ${e.candidates.join(', ')} (${e.code}): ${e.titleVi}\n`); return; }
-  out(`  slot       ${e.slot}  (${e.pattern})\n  presence   ${e.presence}, ${e.tracking}\n  tier       ${e.tier}${e.owner ? `  owner ${e.owner.root} (${e.owner.slot})` : ''}\n`);
-  out(`  imports    ${e.allowedImports ? `may import ${e.allowedImports.join(', ')}; ${e.importRule}` : (e.importRule ?? 'not applicable')}\n`);
-  out(`  tests      ${e.tests}: ${e.testsMeaning}\n`);
-  if (e.requiredFiles.length) out(`  requires   ${e.requiredFiles.join(', ')}\n`);
-  if (e.goesTo) out(`  belongs at ${e.goesTo}\n`);
-  if (e.rules) out(`  rules      ${e.rules.join(', ')}\n`);
-  if (e.code) out(`  ${e.code}: ${e.titleVi}\n  ${e.whyVi}\n`);
-}
-
-/**
- * The app pass: slots, managed files, formatter, contract snapshots and the architecture machine's check surface, root and sides.
- * `only` limits the formatter to those (app-relative) files.
- */
-async function runCheck({ repoRoot, fast = false, base, only, presets, prettier }) {
-  const tracked = trackedFiles(repoRoot);
-  // Managed files of the root and both sides, the .gitignore block and sonar against their render (R04, R05, R11, ...), and prettier
-  // through the app's own install (R19, never under --fast).
-  const extraFindings = [...await managedFindings({ repoRoot, tracked, presets }), ...(fast ? [] : await formatFindings({ repoRoot, files: only ?? tracked, prettier }))];
-  // R23 against the be side itself (full pass only): the committed snapshots equal what `emit-contracts` writes now.
-  let contracts = null;
-  let be = null;
-  try { be = readRepoDeclaration(loadSlotManifest(), repoRoot).sides?.be ?? null; } catch { /* checkRepository reports the unreadable declaration */ }
-  if (be) {
-    if (fast) contracts = { status: 'skipped', reason: '--fast does not emit the apps' };
-    else {
-      const files = tracked.filter((file) => file.startsWith('be/')).map((file) => file.slice('be/'.length));
-      const emitted = contractEmitFindings({ repoRoot: path.join(repoRoot, 'be'), files, repo: be, emit: emitContracts });
-      extraFindings.push(...emitted.findings.map((finding) => ({ ...finding, side: 'be', path: `be/${finding.path}` })));
-      contracts = { status: 'checked', apps: emitted.apps };
-    }
-  }
-  const result = checkRepository({ repoRoot, fast, base, extraFindings });
-  if (contracts) result.contracts = contracts;
-  return result;
-}
-
-/** `hfs lint`: ESLint per side, the app checks and stylelint over the fe side as one report; see lint/run.mjs. */
-async function lintMain(argv, { stdout, presets, prettier }) {
-  const opts = parseLintArgs(argv);
-  const repoRoot = path.resolve(opts.repo ?? process.cwd());
-  const { report, sonar, exit } = await lintRepository({
-    repoRoot, opts, trackedFiles,
-    hfsCheck: (root) => runCheck({ repoRoot: root, only: opts.changed ?? undefined, presets, prettier }),
-  });
-  if (opts.sonar !== undefined) writeReport(path.resolve(opts.sonar), sonar);
-  if (opts.format === 'json') stdout(`${JSON.stringify(report, null, 2)}
-`); else printLintText(report, stdout);
-  return exit;
-}
-
-/**
- * The jest preset a new app renders its Sonar exclusions from: the one installed beside this @starci/hfs (`npx -p @starci/hfs -p
- * @starci/jest-preset hfs scaffold app <name>`, or an install that holds both). None is a refusal, never a render without it.
- */
-async function scaffoldPresets() {
-  try { return await loadPresets(path.dirname(fileURLToPath(import.meta.url))); } catch (error) {
-    throw new SyncError('HFS_SYNC_PRESET_MISSING', `${error.message.replace(/^[A-Z_]+: /, '')}; run hfs scaffold with @starci/jest-preset installed beside @starci/hfs (npx -p @starci/hfs -p @starci/jest-preset hfs scaffold app <name>)`);
-  }
-}
-
-/** `presets` and `prettier` are test seams: the Sonar exclusions sync would load from the repository's installed preset, and the repository's own prettier. */
-export async function main(argv, { stdout = (s) => process.stdout.write(s), stderr = (s) => process.stderr.write(s), presets, prettier } = {}) {
-  const [verb, ...rest] = argv;
-  if (!['check', 'lint', 'scaffold', 'explain', 'sync', 'work-hygiene', 'emit-contracts', 'new'].includes(verb)) { stderr(USAGE); return 2; }
-  try {
-    if (verb === 'sync' || verb === 'work-hygiene') return await syncMain(argv);
-    if (verb === 'lint') return await lintMain(rest, { stdout, presets, prettier });
-    const opts = parse(rest);
-    const repoRoot = path.resolve(opts.repo ?? process.cwd());
-    if (verb === 'check') {
-      if (opts.positional.length) throw new Error('hfs 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 result = await runCheck({ repoRoot, fast: opts.fast === true, base: opts.base, presets, prettier });
-      if (opts.json) stdout(`${JSON.stringify(result, null, 2)}\n`); else printCheck(result, stdout);
-      return result.ok ? 0 : 1;
-    }
-    if (verb === 'emit-contracts') {
-      if (opts.positional.length) throw new Error('hfs emit-contracts takes no path');
-      const be = readRepoDeclaration(loadSlotManifest(), repoRoot).sides?.be;
-      if (!be) throw new Error('hfs emit-contracts runs at the app root (the folder of hfs.json)');
-      const { written, skipped, standIns } = emitContracts({ repoRoot: path.join(repoRoot, 'be'), declaration: be });
-      for (const file of written) stdout(`wrote be/${file}
-`);
-      stdout(`hfs emit-contracts: ${written.length} written${skipped.length ? `, ${skipped.join(', ')} serve no GraphQL` : ''}
-`);
-      for (const [app, lines] of Object.entries(standIns)) {
-        stdout(`${app}: ${lines.length} dependenc${lines.length === 1 ? 'y' : 'ies'} of the resolvers could not load here and stood in (no GraphQL type is affected):\n`);
-        for (const line of lines) stdout(`  ${line}\n`);
-      }
-      return 0;
-    }
-    if (verb === 'new') {
-      const [kind, ...args] = opts.positional;
-      let written;
-      if (kind === 'service' && args.length === 2) written = newService({ repoRoot, dir: args[0], name: args[1], inject: opts.inject ?? [] });
-      else if (kind === 'spec' && args.length === 1 && opts.inject === undefined) written = newSpec({ repoRoot, file: args[0] });
-      else throw new Error('hfs new takes `service <dir> <name> [--inject ...]` or `spec <file>.service.ts`');
-      for (const file of written) stdout(`created ${file}
-`);
-      return 0;
-    }
-    if (verb === 'scaffold') {
-      const [kind, name, ...extra] = opts.positional;
-      if (kind !== 'app' || !name || extra.length || opts.repo !== undefined) throw new Error('hfs scaffold takes `app <name> [--into <dir>]`');
-      const { root: created, files } = scaffoldApp({ name, into: path.resolve(opts.into ?? process.cwd()), presets: presets ?? await scaffoldPresets() });
-      stdout(`hfs scaffold app: created ${created} (${files.length} files); next: npm ci, then npm run lint\n`);
-      return 0;
-    }
-    if (opts.positional.length !== 1) throw new Error('hfs explain takes exactly one path');
-    const explained = explainPath({ repoRoot, input: opts.positional[0] });
-    if (opts.json) stdout(`${JSON.stringify(explained, null, 2)}\n`); else printExplain(explained, stdout);
-    return explained.status === 'no-slot' || explained.status === 'ambiguous' ? 1 : 0;
-  } catch (error) {
-    stderr(error instanceof HfsSlotsError || error instanceof SyncError ? `${error.message}\n` : error instanceof ScaffoldError ? `${error.code}: ${error.message}\n` : `hfs: ${error.message}\n${USAGE}`);
-    return 2;
-  }
-}
-
-// Run when this file is the entry point, compared by real path: through a node_modules junction or an npx shim argv[1] is
-// the junction path while import.meta.url is the resolved one, and a plain comparison silently skipped main (hfs printed nothing).
-if (isMain(import.meta.url)) process.exitCode = await main(process.argv.slice(2));

package/runtime/scripts/api/fs/rmdir-link.mjs

@@ -1,12 +0,0 @@
-// rmdir-link.mjs — the link-safe removal primitive: `cmd /d /c rmdir <link>` (no /s) removes a Windows junction or
-// directory symlink as a link and never touches its target. scripts/api/fs/safe-remove.mjs removeLink is its one caller and
-// checks afterwards that the link is gone (unlinkOnly); this file only issues the call.
-
-import { spawnSync } from 'node:child_process';
-
-/** Issue `cmd /d /c rmdir <p>` on Windows; elsewhere nothing (a POSIX link is unlinked by the caller). {status, error}. */
-export function rmdirLink(p, { platform = process.platform } = {}) {
-  if (platform !== 'win32') return { status: null, error: null };
-  const r = spawnSync('cmd', ['/d', '/c', 'rmdir', p], { windowsHide: true, encoding: 'utf8' });
-  return { status: r.status, error: r.error?.message ?? null };
-}

package/runtime/scripts/lib/test-secrets.mjs

@@ -1,116 +0,0 @@
-#!/usr/bin/env node
-// test-secrets.mjs — test credentials follow the product repository's own `.starcistacks` convention (owner ruling
-// push-scan-test-secrets-encrypted, 2026-09-28: they work exactly like the stack custody and a plaintext password is never pushed).
-// There is no store of the runtime's own: a test credential lives at `<repo>/.starcistacks/<stack>/secrets/test/<name>`,
-// its plaintext git-ignored by the repo's `.starcistacks/**` rules and only the sops-encrypted twin `<name>.enc`
-// committed. It is written with the repository's existing command (`node scripts/stack-secret.mjs set
-// <stack>/secrets/test/<name>`, npm run secret:set), which encrypts against the recipients `.sops.yaml` names and
-// removes the plaintext; this module only READS: the local plaintext when present, else the `.enc` decrypted by sops
-// with the shared age identity (SOPS_AGE_KEY_FILE, default ~/.starci/master.identity) into memory.
-// A credential that need not be stable across runs (a disposable account registered per run) is generated per run
-// and stored nowhere. A value is never logged.
-//
-//   node scripts/lib/test-secrets.mjs get <name> --repo <path> [--stack dev] [--reveal]   prints nothing unless --reveal
-//
-// In a script:  import { testSecret } from '<runtime>/scripts/lib/test-secrets.mjs';
-//               const password = testSecret('login-capture-password', { repo });
-// The push secret scan (scripts/supervisor/push-mains.mjs) passes a `.enc` only when isSopsEnvelope holds.
-import fs from 'node:fs';
-import path from 'node:path';
-import { sopsDecrypt } from '../api/sops/decrypt.mjs';
-import { fileURLToPath } from 'node:url';
-import { parseYaml } from '../../engine/yaml.mjs';
-
-const NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/;
-const STACK = /^[a-z0-9][a-z0-9-]{0,31}$/;
-/** One sops-encrypted leaf: `ENC[AES256_GCM,data:...,iv:...,tag:...,type:...]` (data may be empty). */
-const SOPS_VALUE = /^ENC\[AES256_GCM,data:[A-Za-z0-9+/=]*,iv:[A-Za-z0-9+/=]+,tag:[A-Za-z0-9+/=]+,type:[a-z]+\]$/;
-
-/** Where test credential `name` of `stack` lives in `repo`: {plain, enc, rel}. `rel` is the path the repo's
- *  `stack-secret.mjs set` takes. */
-export function testSecretPaths(name, { repo, stack = 'dev' } = {}) {
-  if (!NAME.test(String(name ?? ''))) throw new Error(`test secret name must match ${NAME} (got ${JSON.stringify(name)})`);
-  if (!STACK.test(String(stack ?? ''))) throw new Error(`stack must match ${STACK} (got ${JSON.stringify(stack)})`);
-  if (!repo) throw new Error('test secret needs {repo}: the product repository whose .starcistacks holds it');
-  const rel = `${stack}/secrets/test/${name}`;
-  const plain = path.join(path.resolve(String(repo)), '.starcistacks', stack, 'secrets', 'test', name);
-  return { plain, enc: `${plain}.enc`, rel };
-}
-
-/** The command that stores a test credential, in the product repository's own tooling. */
-export const setCommand = (name = '<name>', stack = 'dev') => `node scripts/stack-secret.mjs set ${stack}/secrets/test/${name}`;
-
-/** sops' format for a plaintext path, as the repository's stack-secret.mjs formatFor decides it. */
-export const sopsFormatFor = (file) => (file.endsWith('.env') ? 'dotenv' : /\.json$/.test(file) ? 'json' : /\.(ya?ml|kubeconfig)$/.test(file) ? 'yaml' : 'binary');
-
-/** The sops binary: PATH, then winget's Links and Packages (spawn without a shell ignores PATHEXT). */
-export function resolveSops(env = process.env) {
-  const win = process.platform === 'win32';
-  const names = win ? ['sops.exe', 'sops'] : ['sops'];
-  const dirs = String(env.PATH ?? '').split(win ? ';' : ':').filter(Boolean);
-  if (win && env.LOCALAPPDATA) {
-    const winget = path.join(env.LOCALAPPDATA, 'Microsoft', 'WinGet');
-    dirs.push(path.join(winget, 'Links'));
-    const packages = path.join(winget, 'Packages');
-    try { for (const e of fs.readdirSync(packages)) if (/sops/i.test(e)) dirs.push(path.join(packages, e)); } catch { /* none */ }
-  }
-  for (const dir of dirs) for (const n of names) { const f = path.join(dir, n); try { if (fs.statSync(f).isFile()) return f; } catch { /* next */ } }
-  return null;
-}
-
-/** Read test credential `name`: the local plaintext when present, else its committed `.enc` through sops. */
-export function testSecret(name, { repo, stack = 'dev', env = process.env, sops = null } = {}) {
-  const { plain, enc, rel } = testSecretPaths(name, { repo, stack });
-  if (fs.existsSync(plain)) return fs.readFileSync(plain, 'utf8').replace(/\r?\n$/, '');
-  if (!fs.existsSync(enc)) throw new Error(`test secret ${name} is not in .starcistacks/${rel}.enc; store it with \`${setCommand(name, stack)}\` in ${repo}`);
-  const bin = sops ?? resolveSops(env);
-  if (!bin) throw new Error('sops is not installed (Windows: winget install Mozilla.SOPS)');
-  const format = sopsFormatFor(plain);
-  const r = sopsDecrypt(bin, ['--decrypt', '--input-type', format, '--output-type', format, enc], { cwd: path.resolve(String(repo)), env, maxBuffer: 1024 * 1024 });
-  if (r.status !== 0) throw new Error(`test secret ${name}: sops could not decrypt .starcistacks/${rel}.enc (${String(r.stderr ?? r.error?.message ?? '').trim().split(/\r?\n/).pop()})`);
-  return String(r.stdout).replace(/\r?\n$/, '');
-}
-
-/** Every leaf outside the `sops` block is an ENC[...] value (or null); the block itself carries a mac. */
-const allEncrypted = (node) => {
-  if (node === null) return true;
-  if (Array.isArray(node)) return node.every(allEncrypted);
-  if (typeof node === 'object') return Object.values(node).every(allEncrypted);
-  return typeof node === 'string' && SOPS_VALUE.test(node);
-};
-const sopsTree = (doc) => !!doc && typeof doc === 'object' && !Array.isArray(doc) && !!doc.sops && typeof doc.sops === 'object'
-  && typeof doc.sops.mac === 'string' && SOPS_VALUE.test(doc.sops.mac)
-  && Object.keys(doc).length > 1 && Object.entries(doc).every(([k, v]) => k === 'sops' || allEncrypted(v));
-
-/**
- * True only for a sops-encrypted file with no plaintext value: binary/json form ({"data": ENC[...], "sops": {...}}),
- * yaml form (every value ENC[...] plus the sops block) or dotenv form (KEY=ENC[...] lines plus sops_* metadata).
- * The sops metadata must carry its mac. A key kept plaintext through `unencrypted_suffix` does not pass.
- */
-export function isSopsEnvelope(text) {
-  const src = String(text ?? '').replace(/^/, '');
-  if (!src.trim()) return false;
-  try { return sopsTree(JSON.parse(src)); } catch { /* not JSON */ }
-  const lines = src.split(/\r?\n/).filter((l) => l.trim() && !/^\s*#/.test(l));
-  if (lines.length && lines.every((l) => /^[A-Za-z_][A-Za-z0-9_]*=/.test(l))) {
-    const pairs = lines.map((l) => [l.slice(0, l.indexOf('=')), l.slice(l.indexOf('=') + 1)]);
-    const meta = pairs.filter(([k]) => k.startsWith('sops_'));
-    const vals = pairs.filter(([k]) => !k.startsWith('sops_'));
-    return vals.length > 0 && vals.every(([, v]) => SOPS_VALUE.test(v)) && meta.some(([k, v]) => k === 'sops_mac' && SOPS_VALUE.test(v));
-  }
-  try { return sopsTree(parseYaml(src)); } catch { return false; }
-}
-
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
-  const [cmd, name, ...rest] = process.argv.slice(2);
-  const opt = (f) => { const i = rest.indexOf(f); return i >= 0 ? rest[i + 1] : undefined; };
-  try {
-    if (cmd === 'get') {
-      const value = testSecret(name, { repo: opt('--repo'), stack: opt('--stack') ?? 'dev' });
-      if (rest.includes('--reveal')) process.stdout.write(`${value}\n`);
-    } else {
-      console.error(`usage: test-secrets.mjs get <name> --repo <path> [--stack dev] [--reveal]\nstore one with the product repo's own command: ${setCommand()}`);
-      process.exitCode = 2;
-    }
-  } catch (error) { console.error(String(error?.message ?? error)); process.exitCode = 1; }
-}

package/templates/fe/skeleton/apps/__app__/src/app/[locale]/layout.tsx

@@ -1,20 +0,0 @@
-import type { Metadata } from "next"
-import type { ReactNode } from "react"
-import { LocaleShell, localeMetadata } from "@/features/layouts/LocaleShell"
-import "../globals.css"
-
-type LayoutProps = {
-    readonly children: ReactNode
-    readonly params: Promise<{ readonly locale: string }>
-}
-
-/** The localized document title of this route segment. */
-export const generateMetadata = async (props: LayoutProps): Promise<Metadata> =>
-    localeMetadata((await props.params).locale)
-
-/** The locale segment's layout slot: it mounts the locale shell around the segment. */
-const Layout = async (props: LayoutProps) => (
-    <LocaleShell lang={(await props.params).locale}>{props.children}</LocaleShell>
-)
-
-export default Layout

package/templates/fe/skeleton/apps/__app__/src/app/[locale]/page.tsx

@@ -1,9 +0,0 @@
-import { HomePage, homeMetadata } from "@/features/pages/HomePage"
-
-/** The document title of this page, from the catalog of the requested locale. */
-export const generateMetadata = homeMetadata
-
-/** The locale root's page slot: it mounts the home page and nothing else. */
-const Page = () => <HomePage />
-
-export default Page

package/templates/fe/skeleton/apps/__app__/src/components/composites/FailureScreen/index.tsx

@@ -1,28 +0,0 @@
-import { Button, GrammarRoot, Heading, PageContainer, WorkspaceShell } from "@starci/grammar/common"
-
-/** Props for {@link FailureScreen}. */
-type FailureScreenProps = {
-    /** What failed, said to the reader. */
-    readonly title: string
-    /** The label of the one recovery action. */
-    readonly retryLabel: string
-    /** Runs the recovery: the boundary re-renders what failed. */
-    readonly onRetry: () => void
-}
-
-/** A whole-screen failure with its one recovery action: the drawing both error boundaries share. */
-export const FailureScreen = (props: FailureScreenProps) => (
-    <GrammarRoot>
-        <WorkspaceShell
-            primaryLabel={props.title}
-            primary={
-                <PageContainer measure="reading">
-                    <Heading level={1}>{props.title}</Heading>
-                    <Button variant="danger" onPress={props.onRetry}>
-                        {props.retryLabel}
-                    </Button>
-                </PageContainer>
-            }
-        />
-    </GrammarRoot>
-)

package/templates/fe/skeleton/apps/__app__/src/features/layouts/LocaleShell/index.tsx

@@ -1,35 +0,0 @@
-import type { Metadata } from "next"
-import { notFound } from "next/navigation"
-import { hasLocale, NextIntlClientProvider } from "next-intl"
-import { getMessages, getTranslations, setRequestLocale } from "next-intl/server"
-import type { ReactNode } from "react"
-import { siteUrl } from "@/modules/config"
-import { routing } from "@/modules/i18n"
-
-type LocaleShellProps = {
-    readonly lang: string
-    readonly children: ReactNode
-}
-
-/** The document title and the absolute base of every metadata URL, for the language in the address. */
-export const localeMetadata = async (lang: string): Promise<Metadata> => {
-    if (!hasLocale(routing.locales, lang)) notFound()
-    const t = await getTranslations({ locale: lang, namespace: "app" })
-    return { title: t("title"), metadataBase: new URL(siteUrl()) }
-}
-
-/** The document of one route language: `<html lang>` from the address and the catalog handed to client components. */
-export const LocaleShell = async (props: LocaleShellProps) => {
-    if (!hasLocale(routing.locales, props.lang)) notFound()
-    setRequestLocale(props.lang)
-    const messages = await getMessages()
-    return (
-        <html lang={props.lang}>
-            <body className="min-h-dvh">
-                <NextIntlClientProvider locale={props.lang} messages={messages}>
-                    {props.children}
-                </NextIntlClientProvider>
-            </body>
-        </html>
-    )
-}

package/templates/fe/skeleton/apps/__app__/src/features/pages/ErrorPage/component.tsx

@@ -1,19 +0,0 @@
-import { FailureScreen } from "@/components/composites/FailureScreen"
-
-/** Props for {@link ErrorPageBase}. */
-export type ErrorPageBaseProps = {
-    /** The words the failure shows. */
-    readonly props: {
-        readonly title: string
-        readonly retryLabel: string
-    }
-    /** What the surface reports upward. */
-    readonly on: {
-        readonly retry: () => void
-    }
-}
-
-/** Draw the failure of the locale segment with its one recovery action. */
-export const ErrorPageBase = (props: ErrorPageBaseProps) => (
-    <FailureScreen title={props.props.title} retryLabel={props.props.retryLabel} onRetry={props.on.retry} />
-)

package/templates/fe/skeleton/apps/__app__/src/features/pages/ErrorPage/index.tsx

@@ -1,11 +0,0 @@
-import { useTranslations } from "next-intl"
-import { ErrorPageBase } from "./component"
-
-/** The public props of the locale error page: the boundary hands it the retry. */
-type ErrorPageProps = { readonly onRetry: () => void }
-
-/** A render failure of the locale segment shows this instead of a blank page; retry re-renders the segment. */
-export const ErrorPage = (props: ErrorPageProps) => {
-    const t = useTranslations("errors.page")
-    return <ErrorPageBase props={{ title: t("title"), retryLabel: t("retry") }} on={{ retry: props.onRetry }} />
-}

package/templates/fe/skeleton/apps/__app__/src/features/pages/GlobalErrorPage/component.tsx

@@ -1,24 +0,0 @@
-import { FailureScreen } from "@/components/composites/FailureScreen"
-
-/** Props for {@link GlobalErrorPageBase}. */
-export type GlobalErrorPageBaseProps = {
-    /** The language of the document and the words the failure shows. */
-    readonly props: {
-        readonly lang: string
-        readonly title: string
-        readonly retryLabel: string
-    }
-    /** What the surface reports upward. */
-    readonly on: {
-        readonly retry: () => void
-    }
-}
-
-/** Draw the whole document, because this boundary replaces the root layout that would have drawn it. */
-export const GlobalErrorPageBase = (props: GlobalErrorPageBaseProps) => (
-    <html lang={props.props.lang}>
-        <body>
-            <FailureScreen title={props.props.title} retryLabel={props.props.retryLabel} onRetry={props.on.retry} />
-        </body>
-    </html>
-)

package/templates/fe/skeleton/apps/__app__/src/features/pages/GlobalErrorPage/index.tsx

@@ -1,14 +0,0 @@
-import { DEFAULT_LOCALE } from "@/modules/i18n"
-import messages from "@/modules/i18n/messages/vi.json"
-import { GlobalErrorPageBase } from "./component"
-
-/** The public props of the last-resort error page: the boundary hands it the retry. */
-type GlobalErrorPageProps = { readonly onRetry: () => void }
-
-/** The last-resort boundary above the locale layout: it has no provider, so it reads the default catalog directly. */
-export const GlobalErrorPage = (props: GlobalErrorPageProps) => (
-    <GlobalErrorPageBase
-        props={{ lang: DEFAULT_LOCALE, title: messages.errors.global.title, retryLabel: messages.errors.global.retry }}
-        on={{ retry: props.onRetry }}
-    />
-)

package/templates/fe/skeleton/apps/__app__/src/features/pages/HomePage/component.tsx

@@ -1,21 +0,0 @@
-import { GrammarRoot, Heading, PageContainer, WorkspaceShell } from "@starci/grammar/common"
-
-/** Props for {@link HomePageBase}. */
-export type HomePageBaseProps = {
-    /** The words the page shows. */
-    readonly props: { readonly title: string }
-}
-
-/** Draw the front door of the app. */
-export const HomePageBase = (props: HomePageBaseProps) => (
-    <GrammarRoot>
-        <WorkspaceShell
-            primaryLabel={props.props.title}
-            primary={
-                <PageContainer measure="reading">
-                    <Heading level={1}>{props.props.title}</Heading>
-                </PageContainer>
-            }
-        />
-    </GrammarRoot>
-)

package/templates/fe/skeleton/apps/__app__/src/features/pages/HomePage/index.tsx

@@ -1,15 +0,0 @@
-import type { Metadata } from "next"
-import { getTranslations } from "next-intl/server"
-import { HomePageBase } from "./component"
-
-/** The document title of the home page, from the catalog of the requested locale. */
-export const homeMetadata = async (): Promise<Metadata> => {
-    const t = await getTranslations("home")
-    return { title: t("title") }
-}
-
-/** The first page of the app: a server component, so no catalog is shipped for it. */
-export const HomePage = async () => {
-    const t = await getTranslations("home")
-    return <HomePageBase props={{ title: t("title") }} />
-}

package/templates/fe/skeleton/apps/__app__/src/features/pages/LoadingPage/component.tsx

@@ -1,23 +0,0 @@
-import { GrammarRoot, PageContainer, Text, WorkspaceShell } from "@starci/grammar/common"
-
-/** Props for {@link LoadingPageBase}. */
-export type LoadingPageBaseProps = {
-    /** The words the wait announces. */
-    readonly props: { readonly message: string }
-}
-
-/** Draw the wait as one politely announced line. */
-export const LoadingPageBase = (props: LoadingPageBaseProps) => (
-    <GrammarRoot>
-        <WorkspaceShell
-            primaryLabel={props.props.message}
-            primary={
-                <PageContainer measure="reading">
-                    <Text live="polite" tone="muted">
-                        {props.props.message}
-                    </Text>
-                </PageContainer>
-            }
-        />
-    </GrammarRoot>
-)

package/templates/fe/skeleton/apps/__app__/src/features/pages/LoadingPage/index.tsx

@@ -1,8 +0,0 @@
-import { getTranslations } from "next-intl/server"
-import { LoadingPageBase } from "./component"
-
-/** Shown while a route of the locale segment resolves. */
-export const LoadingPage = async () => {
-    const t = await getTranslations("loading")
-    return <LoadingPageBase props={{ message: t("message") }} />
-}

package/templates/fe/skeleton/apps/__app__/src/features/pages/NotFoundPage/component.tsx

@@ -1,28 +0,0 @@
-import { GrammarRoot, Heading, PageContainer, TextAction, WorkspaceShell } from "@starci/grammar/common"
-import { ROUTES } from "@/modules/routes"
-
-/** Props for {@link NotFoundPageBase}. */
-export type NotFoundPageBaseProps = {
-    /** The words the page shows. */
-    readonly props: {
-        readonly title: string
-        readonly homeLabel: string
-    }
-}
-
-/** Draw the missing-page message and the way back to the front door. */
-export const NotFoundPageBase = (props: NotFoundPageBaseProps) => (
-    <GrammarRoot>
-        <WorkspaceShell
-            primaryLabel={props.props.title}
-            primary={
-                <PageContainer measure="reading">
-                    <Heading level={1}>{props.props.title}</Heading>
-                    <TextAction appearance="inline" href={ROUTES.home}>
-                        {props.props.homeLabel}
-                    </TextAction>
-                </PageContainer>
-            }
-        />
-    </GrammarRoot>
-)