@starci/hfs 4.11.22 → 4.12.0

package/sync/hygiene.mjs

@@ -1,4 +1,12 @@
-// starci app hygiene: the guard for the two trees an app tracks besides source. A file under the app root's .starciwork must be
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// starci app check --staged: the guard for the two trees an app tracks besides source. A file under the app root's .starciwork must be
 // product content (the .starciwork/.gitignore allowlist admits it, so agent output is refused), and a file under the app root's
 // .starcistacks must not be a plaintext secret (only *.enc is sealed). It is also the secrets guard of the commit: every staged file, in
 // any tree, is read from the index and judged with the one secret judgement of `starci app check` (scripts/hfs/rules/secrets.mjs: a secret by
@@ -24,146 +32,152 @@ import { bypassesIn } from '../runtime/scripts/lib/bypass-markers.mjs';
 import { loadSlotManifest } from '../runtime/scripts/hfs/slots.mjs';
 import { runGit } from '../runtime/scripts/api/git/lib.mjs';
 import { loadTypescript } from '../runtime/scripts/lib/package-at.mjs';
-
 // One git call through the runtime's git owner (scripts/api/git/lib.mjs): stdout, or the failure thrown the way execFileSync threw it (error.status carries the exit code). The caller's own env is passed on unchanged: a hook runs with GIT_INDEX_FILE set, which the staged reads must keep seeing.
 const git = (cwd, args, options = {}) => {
-  const run = runGit(args, { cwd, env: process.env, ...options });
-  if (run.error) throw run.error;
-  if (run.status !== 0) throw Object.assign(new Error(`git ${args[0]} exited ${run.status}`), { status: run.status });
-  return run.stdout;
+    const run = runGit(args, { cwd, env: process.env, ...options });
+    if (run.error)
+        throw run.error;
+    if (run.status !== 0)
+        throw Object.assign(new Error(`git ${args[0]} exited ${run.status}`), { status: run.status });
+    return run.stdout;
 };
-
 const PLAINTEXT_NAME = /(^|\/)(\.env(\..*)?|[^/]*\.(pem|key|identity|age))$/;
-/** The app root's work tree and stack tree, app-relative (`starci app hygiene` runs at the app root). */
+/** The app root's work tree and stack tree, app-relative (`starci app check --staged` runs at the app root). */
 const WORK = '.starciwork/';
 const STACKS = '.starcistacks/';
-const GUARDED = file => file.startsWith(WORK) || file.startsWith(STACKS);
-
+const GUARDED = (file) => file.startsWith(WORK) || file.startsWith(STACKS);
 /** The subset of `files` git ignores (as if untracked), asked in one call: a Set of paths. */
 function ignoredAmong(cwd, files) {
-  if (files.length === 0) return new Set();
-  try {
-    const out = git(cwd, ['check-ignore', '--no-index', '-z', '--stdin'], { input: files.join('\0'), maxBuffer: 64 * 1024 * 1024 });
-    return new Set(out.split('\0').filter(Boolean));
-  } catch (error) {
-    if (error.status === 1) return new Set();
-    throw error;
-  }
+    if (files.length === 0)
+        return new Set();
+    try {
+        const out = git(cwd, ['check-ignore', '--no-index', '-z', '--stdin'], { input: files.join('\0'), maxBuffer: 64 * 1024 * 1024 });
+        return new Set(out.split('\0').filter(Boolean));
+    }
+    catch (error) {
+        if (error.status === 1)
+            return new Set();
+        throw error;
+    }
 }
-
 /** Violations among `files` (repository-relative, '/'-separated): [{ file, code, message }]. `ignored` is a Set of ignored paths. */
 export function hygieneFindings(files, ignored) {
-  const findings = [];
-  for (const file of files) {
-    if (file.startsWith(WORK) && ignored.has(file)) {
-      findings.push({ file, code: 'HFS_WORK_AGENT_DATA', message: 'is agent output, which .starciwork/.gitignore refuses; keep it in the scratchpad or the blob store' });
+    const findings = [];
+    for (const file of files) {
+        if (file.startsWith(WORK) && ignored.has(file)) {
+            findings.push({ file, code: 'HFS_WORK_AGENT_DATA', message: 'is agent output, which .starciwork/.gitignore refuses; keep it in the scratchpad or the blob store' });
+        }
+        if (file.startsWith(STACKS) && !/\.enc(?:\.yaml)?$/.test(file) && !file.endsWith('.env.example') && !file.endsWith('/secrets/.gitkeep')) {
+            if (file.includes('/secrets/'))
+                findings.push({ file, code: 'HFS_PLAINTEXT_SECRET', message: 'sits under secrets/ but is not sealed; only <slug>.enc may be tracked' });
+            else if (PLAINTEXT_NAME.test(file))
+                findings.push({ file, code: 'HFS_PLAINTEXT_SECRET', message: 'is a plaintext secret; seal it to .starcistacks/<env>/secrets/<slug>.enc' });
+        }
     }
-    if (file.startsWith(STACKS) && !/\.enc(?:\.yaml)?$/.test(file) && !file.endsWith('.env.example') && !file.endsWith('/secrets/.gitkeep')) {
-      if (file.includes('/secrets/')) findings.push({ file, code: 'HFS_PLAINTEXT_SECRET', message: 'sits under secrets/ but is not sealed; only <slug>.enc may be tracked' });
-      else if (PLAINTEXT_NAME.test(file)) findings.push({ file, code: 'HFS_PLAINTEXT_SECRET', message: 'is a plaintext secret; seal it to .starcistacks/<env>/secrets/<slug>.enc' });
-    }
-  }
-  return findings;
+    return findings;
 }
-
 const gitList = (cwd, args) => git(cwd, args, { maxBuffer: 64 * 1024 * 1024 }).split('\0').filter(Boolean);
-
 /** Files staged for the next commit (added, copied, modified, renamed). */
-export const stagedFiles = cwd => gitList(cwd, ['diff', '--cached', '--name-only', '--diff-filter=ACMR', '-z']);
-
+export const stagedFiles = (cwd) => gitList(cwd, ['diff', '--cached', '--name-only', '--diff-filter=ACMR', '-z']);
 /** Every tracked file. */
-export const trackedFiles = cwd => gitList(cwd, ['ls-files', '-z']);
-
+export const trackedFiles = (cwd) => gitList(cwd, ['ls-files', '-z']);
 /** Files the index adds for the next commit. */
-const addedFiles = cwd => gitList(cwd, ['diff', '--cached', '--name-only', '--diff-filter=A', '-z']);
-
+const addedFiles = (cwd) => gitList(cwd, ['diff', '--cached', '--name-only', '--diff-filter=A', '-z']);
 /** The new back-end logic files staged without their unit spec, at an HFS app root only (a repository without hfs.json has no slots). */
 function missingSpecFindings(cwd, { added = addedFiles(cwd), indexed, manifest } = {}) {
-  if (!fs.existsSync(path.join(cwd, 'hfs.json')) || !added.some(file => file.startsWith('be/'))) return [];
-  const staged = (file) => {
-    try { return git(cwd, ['show', `:${file}`]); } catch { return null; }
-  };
-  let ts = null;
-  try { ts = loadTypescript(cwd, import.meta.dirname); } catch { ts = null; }
-  return stagedSpecFindings(manifest ?? loadSlotManifest(), added, indexed ?? new Set(trackedFiles(cwd)), { ts, staged });
+    if (!fs.existsSync(path.join(cwd, 'hfs.json')) || !added.some(file => file.startsWith('be/')))
+        return [];
+    const staged = (file) => {
+        try {
+            return git(cwd, ['show', `:${file}`]);
+        }
+        catch {
+            return null;
+        }
+    };
+    let ts = null;
+    try {
+        ts = loadTypescript(cwd, import.meta.dirname);
+    }
+    catch {
+        ts = null;
+    }
+    return stagedSpecFindings(manifest ?? loadSlotManifest(), added, indexed ?? new Set(trackedFiles(cwd)), { ts, staged });
 }
-
 const MAX_STAGED_BYTES = 1024 * 1024;
-
 /** The text of `file` as the index holds it (what the commit would record), or null when it is absent, binary or over 1 MB. */
 function stagedText(cwd, file) {
-  try {
-    const blob = git(cwd, ['show', `:${file}`], { encoding: 'buffer', maxBuffer: MAX_STAGED_BYTES * 2 });
-    return blob.length > MAX_STAGED_BYTES || blob.includes(0) ? null : blob.toString('utf8');
-  } catch {
-    return null;
-  }
+    try {
+        const blob = git(cwd, ['show', `:${file}`], { encoding: 'buffer', maxBuffer: MAX_STAGED_BYTES * 2 });
+        return blob.length > MAX_STAGED_BYTES || blob.includes(0) ? null : blob.toString('utf8');
+    }
+    catch {
+        return null;
+    }
 }
-
 /** The secret findings of `files` read from the index, as {file, code, message}; a file the name check already refused is not reported twice. */
 function secretGuardFindings(cwd, files, alreadyRefused = new Set()) {
-  return files.filter(file => !alreadyRefused.has(file)).flatMap(file => {
-    const manifestText = /(?:^|\/)README\.md$/.test(file) ? stagedText(cwd, path.posix.join(path.posix.dirname(file), '.starcistacks/application-stacks.yaml')) ?? undefined : undefined;
-    return secretFileFindings({ file, text: stagedText(cwd, file), manifestText }).map(finding => ({ file, code: finding.code, message: finding.message }));
-  });
+    return files.filter(file => !alreadyRefused.has(file)).flatMap((file) => {
+        const manifestText = /(?:^|\/)README\.md$/.test(file) ? stagedText(cwd, path.posix.join(path.posix.dirname(file), '.starcistacks/application-stacks.yaml')) ?? undefined : undefined;
+        return secretFileFindings({ file, text: stagedText(cwd, file), manifestText }).map((finding) => ({ file, code: finding.code, message: finding.message }));
+    });
 }
-
 /** The bypass markers (R303) of `files` read from the index: an inline disable, a type-check escape, a skipped test or a swallowed failure fails at the commit. */
 function bypassGuardFindings(cwd, files) {
-  return files.flatMap(file => {
-    const text = stagedText(cwd, file);
-    return text === null ? [] : bypassesIn(file, text).map(hit => ({ file, code: HFS_BYPASS_MARKER, message: bypassMessage(file, hit) }));
-  });
+    return files.flatMap((file) => {
+        const text = stagedText(cwd, file);
+        return text === null ? [] : bypassesIn(file, text).map((hit) => ({ file, code: HFS_BYPASS_MARKER, message: bypassMessage(file, hit) }));
+    });
 }
-
 /** Findings for `files`: the guarded trees, then the secret guard and the bypass guard over every file. */
 export function judge(cwd, files) {
-  const guarded = files.filter(GUARDED);
-  const findings = hygieneFindings(guarded, ignoredAmong(cwd, guarded.filter(file => file.startsWith(WORK))));
-  const refused = new Set(findings.filter(finding => finding.code === 'HFS_PLAINTEXT_SECRET').map(finding => finding.file));
-  return { checked: files.length, findings: [...findings, ...secretGuardFindings(cwd, files, refused), ...bypassGuardFindings(cwd, files)] };
+    const guarded = files.filter(GUARDED);
+    const findings = hygieneFindings(guarded, ignoredAmong(cwd, guarded.filter(file => file.startsWith(WORK))));
+    const refused = new Set(findings.filter(finding => finding.code === 'HFS_PLAINTEXT_SECRET').map(finding => finding.file));
+    return { checked: files.length, findings: [...findings, ...secretGuardFindings(cwd, files, refused), ...bypassGuardFindings(cwd, files)] };
 }
-
 // The scripts/housekeeping/ledger-hygiene.mjs of the checkout under judgment: the root git names for `cwd`, which carries
 // that script only when the repository IS a full StarCi runtime checkout (packages/hfs/sync/ sits 3 directories
 // under such a root). A product repository — or a
 // bare repo — has no such file, so the section is silently absent wherever this module happens to be installed.
-const ledgerHygieneScript = cwd => {
-  try {
-    const root = git(cwd, ['rev-parse', '--show-toplevel']).trim();
-    return path.join(root, 'scripts', 'housekeeping', 'ledger-hygiene.mjs');
-  } catch {
-    return null;
-  }
+const ledgerHygieneScript = (cwd) => {
+    try {
+        const root = git(cwd, ['rev-parse', '--show-toplevel']).trim();
+        return path.join(root, 'scripts', 'housekeeping', 'ledger-hygiene.mjs');
+    }
+    catch {
+        return null;
+    }
 };
-
 /**
  * The state-root ledger findings (LEDGER_ORPHAN_STATE_ROOT) of the checkout containing
  * `cwd`, as {code, file, message} entries; [] when that checkout carries no ledger-hygiene script. Never throws: a
- * report failure is one HFS_LEDGER_HYGIENE_UNAVAILABLE finding, not a crash of `starci app hygiene`.
+ * report failure is one HFS_LEDGER_HYGIENE_UNAVAILABLE finding, not a crash of `starci app check --staged`.
  */
 async function ledgerHygieneFindings(cwd = process.cwd()) {
-  const script = ledgerHygieneScript(cwd);
-  if (!script || !fs.existsSync(script)) return [];
-  try {
-    const { ledgerHygieneReport } = await import(pathToFileURL(script).href);
-    const report = await ledgerHygieneReport({ apply: false });
-    return [
-      ...report.orphans.map(o => ({ code: o.code, file: o.ledgerId, message: `ledger ${o.name ?? o.ledgerId} - ${o.reason}; source roots: ${o.sourceRoots.join(', ') || '(none)'}` })),
-    ];
-  } catch (error) {
-    return [{ code: 'HFS_LEDGER_HYGIENE_UNAVAILABLE', file: script, message: `could not run: ${String(error?.message ?? error).slice(0, 200)}` }];
-  }
+    const script = ledgerHygieneScript(cwd);
+    if (!script || !fs.existsSync(script))
+        return [];
+    try {
+        const { ledgerHygieneReport } = await import(__rewriteRelativeImportExtension(pathToFileURL(script).href));
+        const report = await ledgerHygieneReport({ apply: false });
+        return [
+            ...report.orphans.map((o) => ({ code: o.code, file: o.ledgerId, message: `ledger ${o.name ?? o.ledgerId} - ${o.reason}; source roots: ${o.sourceRoots.join(', ') || '(none)'}` })),
+        ];
+    }
+    catch (error) {
+        return [{ code: 'HFS_LEDGER_HYGIENE_UNAVAILABLE', file: script, message: `could not run: ${String(error?.message ?? error).slice(0, 200)}` }];
+    }
 }
-
-/** `starci app hygiene`: checks staged files (for the staged run also the new logic files without a spec) plus state-root ledger findings when reachable; returns the exit code. */
-export async function runWorkHygiene({ cwd = process.cwd(), out = line => process.stdout.write(`${line}\n`), files } = {}) {
-  const judged = judge(cwd, files ?? stagedFiles(cwd));
-  const { checked } = judged;
-  const findings = [...judged.findings, ...(files ? [] : missingSpecFindings(cwd))];
-  const ledgerFindings = await ledgerHygieneFindings(cwd);
-  const all = [...findings, ...ledgerFindings];
-  for (const finding of all) out(`${finding.code} ${finding.file} ${finding.message}`);
-  out(`starci app hygiene: ${checked} staged file(s) checked, ${findings.length} finding(s), ${ledgerFindings.length} ledger finding(s)`);
-  return all.length ? 1 : 0;
+/** `starci app check --staged`: checks staged files (for the staged run also the new logic files without a spec) plus state-root ledger findings when reachable; returns the exit code. */
+export async function runWorkHygiene({ cwd = process.cwd(), out = (line) => process.stdout.write(`${line}\n`), files } = {}) {
+    const judged = judge(cwd, files ?? stagedFiles(cwd));
+    const { checked } = judged;
+    const findings = [...judged.findings, ...(files ? [] : missingSpecFindings(cwd))];
+    const ledgerFindings = await ledgerHygieneFindings(cwd);
+    const all = [...findings, ...ledgerFindings];
+    for (const finding of all)
+        out(`${finding.code} ${finding.file} ${finding.message}`);
+    out(`starci app check --staged: ${checked} staged file(s) checked, ${findings.length} finding(s), ${ledgerFindings.length} ledger finding(s)`);
+    return all.length ? 1 : 0;
 }

package/sync/index.d.mts

@@ -0,0 +1,237 @@
+import { type RepoView } from '../runtime/scripts/hfs/slots.mjs';
+import type { AppRepo } from '../runtime/scripts/hfs/slot-app-view.mjs';
+import type { Slot, SlotManifest } from '../runtime/scripts/hfs/manifest-shape.mjs';
+export declare const TEMPLATES_DIR: string;
+/** The scopes a target is rendered for: the app root, then each side. */
+export declare const SCOPES: readonly string[];
+export declare class SyncError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
+/** A side of the app (be or fe) as the resolved hfs.json declares it. */
+export type AppSide = RepoView;
+/** The app declaration hfs.json resolves to (resolveRepoDeclaration): the project, the edition, the optional slots and both sides. */
+export type ResolvedApp = AppRepo;
+/** A slot of the slot manifest (knowledge/hfs/slots.yaml). */
+type ManifestSlot = Slot;
+export type { SlotManifest };
+/** A file sync manages, before it is rendered: its path (relative to its scope), template and mode. */
+export interface Target {
+    path: string;
+    template: string;
+    mode: string;
+    slot?: string;
+    markdown?: boolean;
+}
+/** The markers around a managed block. */
+export interface Markers {
+    begin: string;
+    end: string;
+}
+/** A rendered target: its path (app-relative), scope, mode, content and hash, with the parsed scripts of a scripts target. */
+export interface RenderedTarget {
+    path: string;
+    scope: string;
+    mode: string;
+    content: string;
+    hash: string;
+    scripts?: Record<string, unknown>;
+    markdown?: boolean | undefined;
+    markers?: Markers;
+}
+/** What comparing a rendered target with the disk answers. */
+export interface TargetCheck {
+    path: string;
+    status: 'ok' | 'missing' | 'drift';
+    expectedHash: string;
+    actualHash?: string;
+    difference?: {
+        line: number;
+        expected: string;
+        actual: string;
+    } | null;
+}
+/** What sync reads from the jest preset: the Sonar exclusions. */
+export interface Presets {
+    sonarExclusions: string;
+}
+type ParseYaml = (text: string) => any;
+/** The app's source facts sync renders from (appSource). */
+export interface AppSourceFacts {
+    runtimeExample: boolean;
+    files: string[];
+    read: (file: string) => string;
+    workPresent: boolean;
+    hasImage: (file: string) => boolean;
+    stack: any;
+    quality: any;
+    badges: string;
+    qualityDeclared: boolean;
+}
+/**
+ * Every target of `scope` (app, be or fe), its path relative to that scope's folder: the files the manifest's managedBy slots
+ * list, then (app root) the unlisted ones. A slot that names managedBy lists literal files only, and each has a template under
+ * its scope or under common. `enabled(slot)` decides an opt-in slot (renderTargets passes the declaration's); without it every slot
+ * counts, which is what an inventory of the templates needs.
+ */
+export declare function targetsOf(scope: string, { edition, manifest, hasTemplate, enabled }?: {
+    edition?: string;
+    manifest?: SlotManifest;
+    hasTemplate?: (name: string) => boolean;
+    enabled?: (slot: ManifestSlot) => boolean;
+}): Target[];
+export declare const hashOf: (text: string) => string;
+/**
+ * The hfs.json sync reads: an app declaration valid for the manifest it pins (both sides, their apps, connections, optional slots,
+ * reads). Sync never renders configs for a declaration the eslint canons and starci app check would refuse, so a pin bump cannot leave
+ * lint unable to start. Answers the resolved app.
+ */
+export declare function validateHfs(hfs: unknown, manifest?: SlotManifest): ResolvedApp;
+/**
+ * Fill `{{name}}` from vars and expand `{{> partial}}` lines. A partial line may be written as a line comment (`// {{> partial}}`)
+ * so a JavaScript template stays valid source before rendering. Variable-only lines may also use a line comment;
+ * empty variable-only lines disappear and an unknown name is an error.
+ */
+export declare function render(text: string, vars: Record<string, string>, readTemplate?: (name: string) => string): string;
+/**
+ * The base image of a lite app's managed .starcistacks/images/db/Dockerfile (contexts/stack/pins.yaml images postgres, ruling:lite-official-postgres-image): the
+ * Docker Official postgres image by digest, to which the Dockerfile adds PGVECTOR_PACKAGE from PGDG and the PGMQ release.
+ */
+export declare const DB_BASE_IMAGE = "postgres:17.11@sha256:31ba9c94a03ada9988f2bb493a22a75eef3a185884533e5cdbcd498ea835b08f";
+/** The PGDG package of pgvector at the exact version the db image installs (the one extension the image does not ship). */
+export declare const PGVECTOR_PACKAGE = "postgresql-17-pgvector=0.8.7-1.pgdg13+1";
+/**
+ * The pgmq release the db image installs for the event bus (ruling:lite-pgmq-bus-bullmq-jobs): its source tarball, verified by sha256
+ * when Docker adds it. PGDG does not package pgmq; it is SQL objects only, so the Dockerfile copies its control and script files.
+ */
+export declare const PGMQ: Readonly<{
+    version: "1.13.1";
+    source: "https://github.com/pgmq/pgmq/archive/refs/tags/v1.13.1.tar.gz";
+    sha256: "67221f288f42f95c002a64df40f7d660e765e32df8ada0f2672ba915a14827f7";
+}>;
+/** The local tag the development db container and the drift scratch database run, built from the app's .starcistacks/images/db/Dockerfile. */
+export declare const dbLocalImage: (project: string) => string;
+/** The digest-pinned image of a lite app's declared Redis, in every environment that runs it (ruling:R212/case-10). */
+export declare const REDIS_IMAGE = "redis:7@sha256:c6eabf748fc7a61dbb5a705c78bcf3d6377b1127a97d0ce965c11c44ba46896f";
+/** The development scripts of a lite app's declared Redis (create once, then start and stop it), as a scripts object. */
+export declare const redisDevScripts: (project: string) => Record<string, string>;
+/** What the app's sync reads from the jest preset it installs for its be side: the Sonar exclusions ({ sonarExclusions }); both editions install it (a lite back end keeps full's unit run, ruling:R212/case-1, amended by ruling:R212/case-4). */
+export declare function loadPresets(root: string): Promise<Presets>;
+/** The presets ({ sonarExclusions }) of the jest preset version this @starci/hfs pins, read from its bundled copy. */
+export declare function bundledPresets(): Presets;
+/**
+ * The entries Sonar's copy-paste detection leaves out: every `cpd-exclusions` entry the design truths
+ * (knowledge/hfs/design-truths.yaml) allow, today the message catalogs (ruling message-catalogs-not-duplicate-code): a catalog
+ * holds one block per language with the same keys, which CPD reads as duplicated code. They are still sources: linted, analysed
+ * and held to every other rule. The rendered properties carry them inside the generated Sonar block, and `starci check loosening`
+ * accepts the block only as this manifest derives it.
+ */
+export declare const SONAR_CPD_EXCLUSIONS: readonly string[];
+/**
+ * The Sonar scope of the jest preset's exclusions (presets.sonarExclusions): its file patterns are the tests, which
+ * `sonar.test.inclusions` takes and `sonar.exclusions` moves out of the sources (`sonar.tests` names every source folder, so the
+ * two sets stay disjoint and each test is analysed as a test, never dropped); its folder patterns (`/**`) and the front end's
+ * build and dependency folders are no source at all. Nothing else is excluded: a generated file is analysed like any other.
+ */
+export declare function sonarScope(presets: Presets | null | undefined): {
+    tests: string[];
+    exclusions: string[];
+};
+/**
+ * The be source of the app at `root` the coverage components read: { files, read }, `files` be-relative posix paths of every `*.ts` file under
+ * be/apps and be/src (build output and dependencies skipped) and `read` their text. `workPresent` records whether the optional
+ * lite brand tree exists, so sync can preserve its absence. `hasImage` identifies authored optional Dockerfiles without reading
+ * their content. An app with no be folder has no source files.
+ */
+export declare function appSource(root: string, { parseYaml, notices }?: {
+    parseYaml?: ParseYaml | undefined;
+    notices?: string[] | undefined;
+}): AppSourceFacts;
+/**
+ * The Codecov `individual_components` entries of components [{ id, name, paths }]: one `component_id` block each, `prefix` ahead of every path
+ * (the app folder in the runtime repository) and `ids` mapping a component id to its name there.
+ */
+export declare function componentsYaml(components: readonly {
+    id: string;
+    name: string;
+    paths: readonly string[];
+}[], { prefix, ids }?: {
+    prefix?: string;
+    ids?: (id: string) => string;
+}): string;
+/** The managed be/jest.config.js option text of a coverage scope { roots, roles, files, excludes }, laid out exactly as prettier lays it out (width 120, indent 4). */
+export declare function jestCoverageSource(coverage: {
+    roots: string[];
+    roles: string[];
+    files: string[];
+    excludes: string[];
+}): string;
+/**
+ * The script lines the apps add to the root package.json, each ending with a comma (the template puts them mid-object). A be
+ * script runs from be/ (`cd be && ...`, the folder its tsconfig and jest configuration are relative to) or runs the built app; an
+ * fe script runs the fe app's workspace (@<project>/<app>): through turbo for dev (so the packages it imports are built first) and
+ * through npm `-w` for start. be: `dev:be` runs the one api app from source and restarts it on change (`dev:be:<app>` each, with
+ * several), `start:<app>` runs a built api or worker app, `cli` the built cli app (`npm run cli -- <group> <command>`) and, when the
+ * back end declares a connection, `migrate` its migrate command (`cli migrate run`). fe: `dev:fe` runs the one Next app in
+ * development (`dev:fe:<app>` each, with several), `start:<app>` serves a built one. Images:
+ * `docker:build:<app>` builds the image of one app (the exact command its Dockerfile header states, tag `<project>/<app>:dev`) and
+ * `docker:build` builds every image, one after the other, never pushing.
+ */
+export declare function appScripts(app: ResolvedApp, source: Partial<Pick<AppSourceFacts, 'hasImage'>> | undefined): string;
+/** The stylesheets of the fe side the CSS canon judges, relative to fe/: every app and every workspace package (slot fe.route, fe.package.*). */
+export declare const STYLE_GLOB = "{apps,packages}/*/src/**/*.css";
+/**
+ * The build matrix of the images workflow: one entry per declared app (be then fe, then a lite app's db image), each with the image name and its Dockerfile. The workflow
+ * runs on the release tag, so every image is built there; no path filter narrows it. A YAML block mapping per entry, indented for
+ * `strategy.matrix.include`.
+ */
+export declare function imageMatrix(app: ResolvedApp, source: Partial<Pick<AppSourceFacts, 'hasImage'>> | undefined): string;
+/**
+ * The Dockerfile of every declared app, [{ path, content }] (app-relative): written once by starci app scaffold from templates/<side>/image/<kind>
+ * and then the app's own, judged by the docker rules (R187-R191). A Next image copies the fe packages only when the fe side opts into
+ * them and the be contracts only when the fe side reads them, so each COPY names a folder the app has.
+ */
+export declare function imageFiles(app: ResolvedApp, source?: Partial<Pick<AppSourceFacts, 'hasImage'>>): {
+    path: string;
+    content: string;
+}[];
+/** Every value a template of `scope` can name, derived from hfs.json and the presets. */
+export declare function variables(app: ResolvedApp, scope: string, presets: Presets | null | undefined, sonarKey: string | null | undefined, manifest?: SlotManifest, source?: Pick<AppSourceFacts, 'files' | 'read'> & Partial<AppSourceFacts>): Record<string, string>;
+/**
+ * The managed content of every target of the app: [{ path, mode, content, hash, scope }], paths app-relative (a side's targets under
+ * its folder); a scripts target also carries `scripts`, the parsed block. `sonarKey` is the key the be side's stack declaration
+ * names; without one the key is the project.
+ */
+export declare function renderTargets(hfs: unknown, presets: Presets | null | undefined, { sonarKey, readTemplate, manifest, source }?: {
+    sonarKey?: string | null | undefined;
+    readTemplate?: (name: string) => string;
+    manifest?: SlotManifest;
+    source?: AppSourceFacts | undefined;
+}): RenderedTarget[];
+/** Compare every rendered target with the disk: [{ path, status: ok | missing | drift, expectedHash, actualHash?, difference? }]. */
+export declare function checkTargets(root: string, targets: readonly RenderedTarget[]): TargetCheck[];
+/** Apply exactly one target to its whole file while preserving content outside the managed block or scripts. */
+export declare function writtenContent(target: RenderedTarget, existing: string | undefined): string;
+export declare function writeTargets(root: string, targets: readonly RenderedTarget[]): string[];
+/** The hfs.json object of the app at `root` (validated), or a SyncError. */
+export declare function loadHfs(root: string, manifest?: SlotManifest): Record<string, any>;
+/** The rendered targets of the app at `root`: its hfs.json, the Sonar key the be side's stack declaration names, the presets it installs. */
+export declare function renderRepo(root: string, { presets, parseYaml, notices, manifest }?: {
+    presets?: Presets | undefined;
+    parseYaml?: ParseYaml | undefined;
+    notices?: string[] | undefined;
+    manifest?: SlotManifest;
+}): Promise<{
+    hfs: Record<string, any>;
+    targets: RenderedTarget[];
+}>;
+/** The app-relative files of the retired folders that still exist under `root` of a lite app; sync --execute deletes them, the dry run reports them. */
+export declare function retiredFiles(root: string, hfs: {
+    edition?: string;
+} | null | undefined): string[];
+export declare function runSync(argv: string[], { cwd, out, presets, parseYaml }?: {
+    cwd?: string;
+    out?: (line: string) => unknown;
+    presets?: Presets | undefined;
+    parseYaml?: ParseYaml | undefined;
+}): Promise<number>;