@starci/hfs 4.11.21 → 4.12.0

package/coverage/cli.d.mts

@@ -0,0 +1,28 @@
+/** The preset's merge: shard coverage maps in, one lcov out. */
+type MergeCoverage = (args: {
+    inputs: string[];
+    outDir: string;
+}) => {
+    reports: number;
+    files: number;
+};
+/** The coverage proof (runtime/scripts/hfs/coverage-from.mjs). */
+type Prove = (args: {
+    repoRoot: string;
+    coverageFrom: string;
+}) => {
+    ok: boolean;
+};
+export declare const USAGE = "usage: starci app coverage merge --out <lcov> <coverage-final.json-or-dir>... [--cwd <dir>] | starci app coverage verify <lcov> [--cwd <dir>]";
+/**
+ * Exit 0 merged or proved, 1 a refused proof, 2 bad usage, no preset or no report found. `merge` replaces the installed preset merge and
+ * `prove` the coverage proof in a spec.
+ */
+export declare function coverageMain(argv: string[], { cwd: baseCwd, stdout, stderr, merge, prove }?: {
+    cwd?: string;
+    stdout?: (text: string) => unknown;
+    stderr?: (text: string) => unknown;
+    merge?: MergeCoverage;
+    prove?: Prove;
+}): Promise<number>;
+export {};

package/coverage/cli.mjs

@@ -9,69 +9,83 @@
 import path from 'node:path';
 import { createRequire } from 'node:module';
 import { coverageFrom, formatCoverageReport } from '../runtime/scripts/hfs/coverage-from.mjs';
-
-const USAGE = 'usage: starci app coverage merge --out <lcov> <coverage-final.json-or-dir>... [--cwd <dir>] | starci app coverage verify <lcov> [--cwd <dir>]';
-
+export const USAGE = 'usage: starci app coverage merge --out <lcov> <coverage-final.json-or-dir>... [--cwd <dir>] | starci app coverage verify <lcov> [--cwd <dir>]';
 function parse(argv) {
-  const [action, ...rest] = argv;
-  if (action !== 'merge' && action !== 'verify') throw new Error(USAGE);
-  const opts = { inputs: [] };
-  for (let index = 0; index < rest.length; index += 1) {
-    const arg = rest[index];
-    if (arg === '--out' || arg === '--cwd') {
-      const value = rest[index + 1];
-      if (!value || value.startsWith('--')) throw new Error(`${arg} needs a value; ${USAGE}`);
-      opts[arg.slice(2)] = value;
-      index += 1;
-    } else if (arg.startsWith('--')) throw new Error(`unknown flag ${arg}; ${USAGE}`);
-    else opts.inputs.push(arg);
-  }
-  opts.action = action;
-  if (action === 'verify') {
-    if (opts.out !== undefined || opts.inputs.length !== 1) throw new Error(USAGE);
+    const [action, ...rest] = argv;
+    if (action !== 'merge' && action !== 'verify')
+        throw new Error(USAGE);
+    const opts = { action, inputs: [] };
+    for (let index = 0; index < rest.length; index += 1) {
+        const arg = rest[index];
+        if (arg === '--out' || arg === '--cwd') {
+            const value = rest[index + 1];
+            if (!value || value.startsWith('--'))
+                throw new Error(`${arg} needs a value; ${USAGE}`);
+            opts[arg.slice(2)] = value;
+            index += 1;
+        }
+        else if (arg.startsWith('--'))
+            throw new Error(`unknown flag ${arg}; ${USAGE}`);
+        else
+            opts.inputs.push(arg);
+    }
+    if (action === 'verify') {
+        if (opts.out !== undefined || opts.inputs.length !== 1)
+            throw new Error(USAGE);
+        return opts;
+    }
+    if (!opts.out || !opts.inputs.length)
+        throw new Error(USAGE);
+    if (path.basename(opts.out) !== 'lcov.info')
+        throw new Error(`--out names the lcov.info the coverage proof reads; ${USAGE}`);
     return opts;
-  }
-  if (!opts.out || !opts.inputs.length) throw new Error(USAGE);
-  if (path.basename(opts.out) !== 'lcov.info') throw new Error(`--out names the lcov.info the coverage proof reads; ${USAGE}`);
-  return opts;
 }
-
 /** The app's installed preset merge (resolved from the app root, like the presets `starci app sync` loads). */
 function installedMerge(cwd) {
-  try { return createRequire(path.join(cwd, 'package.json'))('@starci/jest-preset/merge').mergeCoverage; } catch (error) {
-    throw new Error(`@starci/jest-preset/merge is not installed under ${cwd} (${error.code ?? error.message}); install the canon @starci/jest-preset`);
-  }
+    try {
+        return createRequire(path.join(cwd, 'package.json'))('@starci/jest-preset/merge').mergeCoverage;
+    }
+    catch (error) {
+        throw new Error(`@starci/jest-preset/merge is not installed under ${cwd} (${error.code ?? error.message}); install the canon @starci/jest-preset`);
+    }
 }
-
 /** The coverage proof of the app at `cwd` over the lcov `report`: exit 0 proved, 1 refused, 2 when the proof cannot run. */
 function verifyCoverage(cwd, report, { stdout, stderr, prove }) {
-  try {
-    const result = prove({ repoRoot: cwd, coverageFrom: report });
-    stdout(formatCoverageReport(result));
-    return result.ok ? 0 : 1;
-  } catch (error) {
-    stderr(`starci app coverage verify: ${String(error?.message ?? error).split('\n')[0]}\n`);
-    return 2;
-  }
+    try {
+        const result = prove({ repoRoot: cwd, coverageFrom: report });
+        stdout(formatCoverageReport(result));
+        return result.ok ? 0 : 1;
+    }
+    catch (error) {
+        stderr(`starci app coverage verify: ${String(error?.message ?? error).split('\n')[0]}\n`);
+        return 2;
+    }
 }
-
 /**
  * Exit 0 merged or proved, 1 a refused proof, 2 bad usage, no preset or no report found. `merge` replaces the installed preset merge and
  * `prove` the coverage proof in a spec.
  */
 export async function coverageMain(argv, { cwd: baseCwd = process.cwd(), stdout = (s) => process.stdout.write(s), stderr = (s) => process.stderr.write(s), merge, prove = coverageFrom } = {}) {
-  let opts;
-  try { opts = parse(argv); } catch (error) { stderr(`starci app coverage: ${error.message}\n`); return 2; }
-  const cwd = path.resolve(baseCwd, opts.cwd ?? '.');
-  if (opts.action === 'verify') return verifyCoverage(cwd, opts.inputs[0], { stdout, stderr, prove });
-  try {
-    const run = merge ?? installedMerge(cwd);
-    const outDir = path.dirname(path.resolve(cwd, opts.out));
-    const result = run({ inputs: opts.inputs.map((input) => path.resolve(cwd, input)), outDir });
-    stdout(`starci app coverage merge: ${result.reports} shard report(s), ${result.files} source file(s) -> ${path.relative(cwd, path.join(outDir, 'lcov.info')).replaceAll('\\', '/')}\n`);
-    return 0;
-  } catch (error) {
-    stderr(`starci app coverage: ${error.message}\n`);
-    return 2;
-  }
+    let opts;
+    try {
+        opts = parse(argv);
+    }
+    catch (error) {
+        stderr(`starci app coverage: ${error.message}\n`);
+        return 2;
+    }
+    const cwd = path.resolve(baseCwd, opts.cwd ?? '.');
+    if (opts.action === 'verify')
+        return verifyCoverage(cwd, opts.inputs[0], { stdout, stderr, prove });
+    try {
+        const run = merge ?? installedMerge(cwd);
+        const outDir = path.dirname(path.resolve(cwd, opts.out));
+        const result = run({ inputs: opts.inputs.map((input) => path.resolve(cwd, input)), outDir });
+        stdout(`starci app coverage merge: ${result.reports} shard report(s), ${result.files} source file(s) -> ${path.relative(cwd, path.join(outDir, 'lcov.info')).replaceAll('\\', '/')}\n`);
+        return 0;
+    }
+    catch (error) {
+        stderr(`starci app coverage: ${error.message}\n`);
+        return 2;
+    }
 }

package/db/backup-receipt.d.mts

@@ -0,0 +1,28 @@
+import { dbTarget } from './postgres.mjs';
+import type { SpawnResult, VerbContext } from '../release/index.mjs';
+export declare const RECEIPT_SCHEMA = "starci/db-backup@1";
+export declare function sha256(file: string): string;
+/** A database session a backup runs in: the context, the target and the project name the archive carries. */
+export interface BackupSession {
+    ctx: VerbContext;
+    target: ReturnType<typeof dbTarget>;
+    project: string;
+}
+/** Backup SQL can hold row values, so a client tool's stderr is withheld whole. */
+export declare function runPgTool(session: BackupSession, command: string, args: readonly string[]): {
+    stdout: string;
+    text: string;
+};
+/** Resolves existing ancestors before checking containment, including symlinked output directories and Git worktree marker files. */
+export declare function outsideRepository(root: string, output: string): string;
+/** The database of `--db-url-env` (default DATABASE_URL) and the project name the archive carries. */
+export declare function backupSession(ctx: VerbContext, options: {
+    urlEnv?: string | undefined;
+}): BackupSession;
+/** One read-only query through psql; failures and malformed output are withheld. */
+export declare function queryRows(session: BackupSession, sql: string): Record<string, any>[];
+/** Executes local tar/age through ctx.spawn, the same seam used by the stack's age installer; never relays tool errors containing data. */
+export declare function backupTool(ctx: VerbContext, command: string, args: readonly string[], options?: Record<string, unknown>): SpawnResult;
+/** Reads public recipients only from creation_rules age fields, including nested SOPS key_groups. */
+export declare function backupRecipients(root: string): string[];
+export declare function encryptFile(ctx: VerbContext, input: string, output: string, recipients: readonly string[]): number;

package/db/backup-receipt.mjs

@@ -5,88 +5,108 @@ import { createHash } from 'node:crypto';
 import { parseYaml } from '../runtime/engine/yaml.mjs';
 import { failure, refusal } from '../stack/errors.mjs';
 import { DEFAULT_DB_URL_ENV, dbTarget, pgTool, queryRows as psqlRows } from './postgres.mjs';
-
 export const RECEIPT_SCHEMA = 'starci/db-backup@1';
 export function sha256(file) {
-  const hash = createHash('sha256');
-  const fd = fs.openSync(file, 'r');
-  const chunk = Buffer.alloc(1024 * 1024);
-  try {
-    let bytes;
-    while ((bytes = fs.readSync(fd, chunk, 0, chunk.length, null)) > 0) hash.update(chunk.subarray(0, bytes));
-  } finally { fs.closeSync(fd); }
-  return hash.digest('hex');
+    const hash = createHash('sha256');
+    const fd = fs.openSync(file, 'r');
+    const chunk = Buffer.alloc(1024 * 1024);
+    try {
+        let bytes;
+        while ((bytes = fs.readSync(fd, chunk, 0, chunk.length, null)) > 0)
+            hash.update(chunk.subarray(0, bytes));
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    return hash.digest('hex');
 }
 const inside = (root, file) => { const rel = path.relative(root, file); return rel === '' || (!rel.startsWith(`..${path.sep}`) && rel !== '..' && !path.isAbsolute(rel)); };
-
 /** Backup SQL can hold row values, so a client tool's stderr is withheld whole. */
 export function runPgTool(session, command, args) {
-  return pgTool(session.ctx, session.target, command, args, { withhold: true, code: 'DB_BACKUP_CLI_FAILED' });
+    return pgTool(session.ctx, session.target, command, args, { withhold: true, code: 'DB_BACKUP_CLI_FAILED' });
 }
-
 /** Resolves existing ancestors before checking containment, including symlinked output directories and Git worktree marker files. */
 export function outsideRepository(root, output) {
-  let ancestor = path.resolve(output);
-  const tail = [];
-  while (!fs.existsSync(ancestor)) { tail.unshift(path.basename(ancestor)); ancestor = path.dirname(ancestor); }
-  const resolved = path.join(fs.realpathSync(ancestor), ...tail);
-  if (inside(fs.realpathSync(root), resolved)) throw refusal('DB_DUMP_INSIDE_REPO', '--out must be outside the app repository and every Git worktree');
-  for (let dir = resolved; ; dir = path.dirname(dir)) {
-    if (fs.existsSync(path.join(dir, '.git'))) throw refusal('DB_DUMP_INSIDE_REPO', '--out must be outside every Git worktree');
-    if (dir === path.dirname(dir)) break;
-  }
-  return resolved;
+    let ancestor = path.resolve(output);
+    const tail = [];
+    while (!fs.existsSync(ancestor)) {
+        tail.unshift(path.basename(ancestor));
+        ancestor = path.dirname(ancestor);
+    }
+    const resolved = path.join(fs.realpathSync(ancestor), ...tail);
+    if (inside(fs.realpathSync(root), resolved))
+        throw refusal('DB_DUMP_INSIDE_REPO', '--out must be outside the app repository and every Git worktree');
+    for (let dir = resolved;; dir = path.dirname(dir)) {
+        if (fs.existsSync(path.join(dir, '.git')))
+            throw refusal('DB_DUMP_INSIDE_REPO', '--out must be outside every Git worktree');
+        if (dir === path.dirname(dir))
+            break;
+    }
+    return resolved;
 }
-
-/** The database of `--url-env` (default DATABASE_URL) and the project name the archive carries. */
+/** The database of `--db-url-env` (default DATABASE_URL) and the project name the archive carries. */
 export function backupSession(ctx, options) {
-  const target = dbTarget(ctx, options.urlEnv ?? DEFAULT_DB_URL_ENV);
-  const project = path.basename(ctx.cwd).replace(/[^A-Za-z0-9_-]/gu, '-') || 'database';
-  return { ctx, target, project };
+    const target = dbTarget(ctx, options.urlEnv ?? DEFAULT_DB_URL_ENV);
+    const project = path.basename(ctx.cwd).replace(/[^A-Za-z0-9_-]/gu, '-') || 'database';
+    return { ctx, target, project };
 }
-
 /** One read-only query through psql; failures and malformed output are withheld. */
 export function queryRows(session, sql) {
-  try { return psqlRows(session.ctx, session.target, sql, { withhold: true }); }
-  catch { throw failure('DB_BACKUP_QUERY_FAILED', 'database inventory query failed; output withheld'); }
+    try {
+        return psqlRows(session.ctx, session.target, sql, { withhold: true });
+    }
+    catch {
+        throw failure('DB_BACKUP_QUERY_FAILED', 'database inventory query failed; output withheld');
+    }
 }
-
 /** Executes local tar/age through ctx.spawn, the same seam used by the stack's age installer; never relays tool errors containing data. */
 export function backupTool(ctx, command, args, options = {}) {
-  const result = ctx.spawn(command, args, { cwd: ctx.cwd, env: ctx.env, ...options });
-  if (result.error || result.status !== 0) throw failure('DB_BACKUP_TOOL_FAILED', `${command} failed; output withheld`);
-  return result;
+    const result = ctx.spawn(command, args, { cwd: ctx.cwd, env: ctx.env, ...options });
+    if (result.error || result.status !== 0)
+        throw failure('DB_BACKUP_TOOL_FAILED', `${command} failed; output withheld`);
+    return result;
 }
-
 /** Reads public recipients only from creation_rules age fields, including nested SOPS key_groups. */
 export function backupRecipients(root) {
-  let rules;
-  try { rules = parseYaml(fs.readFileSync(path.join(root, '.sops.yaml'), 'utf8')).creation_rules; } catch { rules = []; }
-  const found = [];
-  const visit = (value) => {
-    if (!value || typeof value !== 'object') return;
-    for (const [key, item] of Object.entries(value)) {
-      if (key === 'age') found.push(...(JSON.stringify(item).match(/age1[0-9a-z]{50,}/gu) ?? []));
-      else if (typeof item === 'object') visit(item);
+    let rules;
+    try {
+        rules = parseYaml(fs.readFileSync(path.join(root, '.sops.yaml'), 'utf8')).creation_rules;
+    }
+    catch {
+        rules = [];
     }
-  };
-  visit(rules);
-  if (!found.length) throw refusal('DB_BACKUP_NO_RECIPIENT', 'no age recipient in .sops.yaml creation_rules');
-  return [...new Set(found)];
+    const found = [];
+    const visit = (value) => {
+        if (!value || typeof value !== 'object')
+            return;
+        for (const [key, item] of Object.entries(value)) {
+            if (key === 'age')
+                found.push(...(JSON.stringify(item).match(/age1[0-9a-z]{50,}/gu) ?? []));
+            else if (typeof item === 'object')
+                visit(item);
+        }
+    };
+    visit(rules);
+    if (!found.length)
+        throw refusal('DB_BACKUP_NO_RECIPIENT', 'no age recipient in .sops.yaml creation_rules');
+    return [...new Set(found)];
 }
-
 /** Header and size checks prove an age envelope exists; proving decryption requires the owner's identity separately. */
 function checkArchive(file) {
-  const size = fs.statSync(file).size;
-  const fd = fs.openSync(file, 'r');
-  const header = Buffer.alloc(22);
-  try { fs.readSync(fd, header, 0, header.length, 0); } finally { fs.closeSync(fd); }
-  if (size < 100 || !header.toString('ascii').startsWith('age-encryption.org/v1\n')) throw failure('DB_BACKUP_ARCHIVE_INVALID', 'encrypted archive has no valid age header or payload');
-  return size;
+    const size = fs.statSync(file).size;
+    const fd = fs.openSync(file, 'r');
+    const header = Buffer.alloc(22);
+    try {
+        fs.readSync(fd, header, 0, header.length, 0);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    if (size < 100 || !header.toString('ascii').startsWith('age-encryption.org/v1\n'))
+        throw failure('DB_BACKUP_ARCHIVE_INVALID', 'encrypted archive has no valid age header or payload');
+    return size;
 }
-
 export function encryptFile(ctx, input, output, recipients) {
-  backupTool(ctx, 'age', [...recipients.flatMap((recipient) => ['-r', recipient]), '-o', output, input]);
-  return checkArchive(output);
+    backupTool(ctx, 'age', [...recipients.flatMap((recipient) => ['-r', recipient]), '-o', output, input]);
+    return checkArchive(output);
 }
-

package/db/drift.d.mts

@@ -0,0 +1,86 @@
+import type { FlagSpec, VerbContext, VerbIo, VerbResult } from '../release/index.mjs';
+import { BOOTSTRAP_FILE } from '../runtime/scripts/hfs/rules/database-constants.mjs';
+export { BOOTSTRAP_FILE };
+export declare const DRIFT_CODE = "BE_ENTITY_SCHEMA_DRIFT";
+export declare const MIGRATIONS_DIR = "db/migrations";
+/** One entity column as the comparison reads it. */
+export interface EntityColumn {
+    entity: string;
+    schema: string;
+    table: string;
+    column: string;
+    type: string;
+    enumName: string | null;
+    nullable: boolean;
+    view: boolean;
+}
+/** One column of the migrated schema, as SCHEMA_SQL answers it. */
+export interface SchemaColumn {
+    schema: string;
+    table: string;
+    column: string;
+    type: string;
+    enumName: string | null;
+    nullable: boolean;
+    view: boolean;
+}
+/** One drift finding. */
+export interface DriftFinding {
+    code: string;
+    level: 'error';
+    kind: string;
+    entity: string;
+    schema: string;
+    table: string;
+    column: string;
+    message: string;
+    expected?: unknown;
+    actual?: unknown;
+}
+/**
+ * The columns of every entity the app's entity list names, from TypeORM's own metadata: a postgres DataSource with synchronize false is
+ * built and its metadata derived (buildMetadatas), never initialized, so no connection is opened. typeorm, its pg driver and typescript are
+ * the app's (resolved from be/); an app without them gets no verdict.
+ */
+export declare function loadEntityColumns(appRoot: string): Promise<EntityColumn[]>;
+/** Every column of the scratch schema with its format_type spelling (enums as `enum`, domains as their base type) and nullability. */
+export declare const SCHEMA_SQL = "select c.table_schema as \"schema\", c.table_name as \"table\", c.column_name as \"column\", c.is_nullable = 'YES' as \"nullable\",\n  case when t.typtype = 'e' then 'enum' when e.typtype = 'e' then 'enum[]' when t.typtype = 'd' then pg_catalog.format_type(t.typbasetype, null)\n    else pg_catalog.format_type(a.atttypid, null) end as \"type\",\n  case when t.typtype = 'e' then t.typname when e.typtype = 'e' then e.typname end as \"enumName\",\n  cl.relkind in ('v', 'm') as \"view\"\nfrom information_schema.columns c\njoin pg_catalog.pg_namespace n on n.nspname = c.table_schema\njoin pg_catalog.pg_class cl on cl.relnamespace = n.oid and cl.relname = c.table_name\njoin pg_catalog.pg_attribute a on a.attrelid = cl.oid and a.attname = c.column_name and a.attnum > 0 and not a.attisdropped\njoin pg_catalog.pg_type t on t.oid = a.atttypid\nleft join pg_catalog.pg_type e on e.oid = t.typelem and t.typcategory = 'A'\nwhere c.table_schema not in ('pg_catalog', 'information_schema')";
+/** The SQL files the scratch database receives, in order: db/bootstrap.sql when present, then the active migrations by stamp. */
+export declare function migrationFiles(root: string): string[];
+/**
+ * The columns of the migrated schema: a scratch database (a container of the app's db image, or the empty database `urlEnv` names) receives
+ * db/bootstrap.sql and every active migration, each file in one transaction, then is read with SCHEMA_SQL. A file that does not apply to an
+ * empty database is a red result of its own (DB_DRIFT_MIGRATION_FAILED). The container is removed in every case.
+ */
+export declare function migratedSchema(ctx: VerbContext, appRoot: string, { urlEnv }?: {
+    urlEnv?: string | undefined;
+}): Promise<{
+    columns: SchemaColumn[];
+    files: string[];
+    how: string;
+}>;
+/**
+ * The drift findings of `entityColumns` against `schemaColumns` ({schema, table, column, type, enumName, nullable, view} each): a missing
+ * table once per entity, then per column a missing column, a type mismatch (an enum matches an enum, by name when the entity names one) and,
+ * outside views, a nullability mismatch. Schema columns no entity maps are not findings.
+ */
+export declare function compareSchema(entityColumns: readonly EntityColumn[], schemaColumns: readonly SchemaColumn[]): DriftFinding[];
+/**
+ * `starci app db drift`. options: { urlEnv, entityColumns(root), schema(ctx, root, { urlEnv }) }, the last two seams for specs. An app with
+ * no entity list is green with nothing to compare.
+ */
+export declare function driftCheck(ctx: VerbContext, options?: {
+    urlEnv?: string | undefined;
+    entityColumns?: (root: string) => Promise<EntityColumn[]> | EntityColumn[];
+    schema?: (ctx: VerbContext, root: string, flags: {
+        urlEnv?: string | undefined;
+    }) => Promise<{
+        columns: SchemaColumn[];
+        files?: string[];
+        how?: string;
+    }>;
+}): Promise<VerbResult>;
+/** Entry of the verb: `starci app db drift [--db-url-env NAME] [--json] [--cwd <dir>]`. */
+/** The flags of `starci app db drift`; the parser refuses every other. */
+export declare const SPEC: FlagSpec;
+export declare function dbDriftMain(argv: string[], io?: VerbIo): Promise<number>;