@starci/hfs 4.12.2 → 4.13.2

package/stack/cli.mjs

@@ -9,7 +9,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 // cli.mjs - `starci app stack <action>` for the Swarm deploy tooling: flags, dry run versus --execute, dispatch, text and --json output.
 //   starci app stack <action> --env <env> [the action's FLAGS]     (only the READ_ONLY actions default --env to production)
 // Each action takes only its own flags: a flag of another action is a refusal, never ignored.
-// (up, down and status are the test-world verbs and are dispatched by packages/hfs/src/main.mjs.)
+// (`starci app world <up|down|status>` is the test world's, dispatched by packages/hfs/src/main.mjs; `stack status` below is the deploy's drift report.)
 // Every action module exports one async function (ctx, config, options) -> { ok, lines, data }; a refusal throws StackError.
 import path from 'node:path';
 import { stackContext } from './context.mjs';
@@ -19,12 +19,12 @@ import { StackError, EXIT, refusal } from './errors.mjs';
 import { parseTargetBinding, bindStackTarget, nativeToolEnvironment } from './target-binding.mjs';
 import { oneCommand, prepareUrgentRelease } from './urgent-release.mjs';
 /** The actions that drive the docker CLI of the operator machine (pointed at the manager by docker-transport.mjs when the key is sealed). */
-const DOCKER_ACTIONS = new Set(['deploy', 'accept', 'converge', 'verify', 'rollback', 'prune']);
-export const ACTIONS = Object.freeze(['prepare', 'connect', 'disconnect', 'build-args', 'render', 'deploy', 'converge', 'verify', 'rollback', 'prune', 'backup', 'jobs', 'task', 'ingress', 'retire', 'build', 'accept']);
+const DOCKER_ACTIONS = new Set(['deploy', 'accept', 'converge', 'verify', 'rollback', 'prune', 'status']);
+export const ACTIONS = Object.freeze(['prepare', 'connect', 'disconnect', 'build-args', 'render', 'deploy', 'converge', 'verify', 'rollback', 'prune', 'backup', 'jobs', 'task', 'ingress', 'retire', 'build', 'accept', 'status', 'ci-key']);
 /** True when `value` names one action of `starci app stack`. */
 export const isAction = (value) => ACTIONS.includes(value);
-export const BOOLEAN = new Set(['--execute', '--json', '--swarm-state', '--init-swarm', '--owner-approved', '--fix-live-restore', '--skip-public', '--skip-internal', '--allow-unpinned', '--push', '--urgent', '--first-start']);
-export const VALUE = new Set(['--env', '--image', '--sha', '--previous', '--out', '--release', '--since', '--timeout', '--retry', '--keep', '--app', '--ssh-cmd', '--extra-compose', '--project', '--target-binding', '--db-url-env', '--backup-out', '--db-service', '--reason', '--remote']);
+export const BOOLEAN = new Set(['--execute', '--json', '--swarm-state', '--init-swarm', '--owner-approved', '--fix-live-restore', '--skip-public', '--skip-internal', '--allow-unpinned', '--push', '--urgent', '--first-start', '--redeploy', '--data-acknowledged', '--print-authorized-keys', '--print-gate']);
+export const VALUE = new Set(['--env', '--image', '--sha', '--previous', '--out', '--release', '--since', '--timeout', '--retry', '--keep', '--app', '--ssh-cmd', '--extra-compose', '--project', '--target-binding', '--db-url-env', '--backup-out', '--db-service', '--reason', '--remote', '--ci-run', '--public-key']);
 export const REPEAT = new Set(['--image', '--keep', '--extra-compose', '--project']);
 /** `--ssh-cmd` replaces the configured alias for an action whose module (or the Docker transport) reaches the manager over SSH. */
 const SSH = ['--ssh-cmd'];
@@ -38,10 +38,10 @@ export const FLAGS = Object.freeze({
     disconnect: ['--execute'],
     'build-args': ['--app'],
     render: ['--image', '--sha', '--previous', '--out', '--allow-unpinned', '--extra-compose'],
-    deploy: ['--image', '--sha', '--execute', '--out', '--timeout', '--retry', '--skip-public', '--target-binding', '--urgent', '--reason', '--remote', '--db-url-env', '--backup-out', '--first-start', '--db-service', ...SSH],
+    deploy: ['--image', '--sha', '--execute', '--out', '--timeout', '--retry', '--skip-public', '--target-binding', '--urgent', '--reason', '--remote', '--db-url-env', '--backup-out', '--first-start', '--db-service', '--ci-run', '--redeploy', ...SSH],
     converge: ['--since', '--timeout', ...SSH],
     verify: ['--retry', '--skip-public', '--skip-internal', '--target-binding', ...SSH],
-    rollback: ['--release', '--execute', '--timeout', ...SSH],
+    rollback: ['--release', '--execute', '--timeout', '--data-acknowledged', ...SSH],
     prune: ['--keep', '--execute', ...SSH],
     backup: ['--swarm-state', '--execute', ...SSH],
     jobs: ['--execute', ...SSH],
@@ -49,12 +49,14 @@ export const FLAGS = Object.freeze({
     ingress: ['--execute', ...SSH],
     retire: ['--project', '--execute', ...SSH],
     build: ['--push', '--execute'],
-    accept: ['--release', '--execute', '--retry', ...SSH],
+    accept: ['--release', '--execute', '--retry', '--db-url-env', ...SSH],
+    status: [...SSH],
+    'ci-key': ['--public-key', '--print-authorized-keys', '--print-gate'],
 });
 /** The operands of the actions that take any, as the usage prints them. */
 export const OPERANDS = Object.freeze({ jobs: '<action> [<arg>...]', task: '<name> [<arg>...]', ingress: '<action> [<arg>...]' });
 /** The read-only actions, whose `--env` defaults to production. Every action with an effect names its environment, so none reaches production by omission. */
-export const READ_ONLY = Object.freeze(['build-args', 'render', 'verify']);
+export const READ_ONLY = Object.freeze(['build-args', 'render', 'verify', 'status', 'ci-key']);
 /** Splits argv into { flags, positional }; an unknown flag, a flag of another action or a flag without its value is a refusal. */
 function parseFlags(action, argv) {
     const own = new Set(['--env', '--json', ...FLAGS[action]]);
@@ -91,8 +93,10 @@ function checkDeployForm(flags) {
     }
     if (!flags.urgent && (flags['first-start'] || flags['db-service']))
         throw refusal('STACK_USAGE', '--first-start and --db-service are the first start of an empty database under the urgent floor: add --urgent');
-    if (!flags.urgent && (flags['db-url-env'] || flags['backup-out']))
-        throw refusal('STACK_USAGE', '--db-url-env and --backup-out choose the urgent floor\'s database and backup folder: add --urgent');
+    if (flags.urgent && flags['ci-run'])
+        throw refusal('STACK_USAGE', '--ci-run names the CI run that deploys; an urgent deploy runs no CI (the CI run of its tag is the back-fill)');
+    if (flags['ci-run'] !== undefined && !/^[0-9]{1,20}$/u.test(flags['ci-run']))
+        throw refusal('STACK_USAGE', '--ci-run takes the numeric id of the CI run');
 }
 /** `--image api=ghcr.io/o/x@sha256:...` (repeatable or comma separated) -> { api: 'ghcr.io/o/x@sha256:...' }. */
 function parseImages(values = []) {
@@ -130,15 +134,18 @@ const OPTIONS = {
         out: flags.out ? path.resolve(cwd, flags.out) : null, timeoutSeconds: number(flags, 'timeout'), retrySeconds: number(flags, 'retry'), skipPublic: flags['skip-public'] === true,
         urgent: flags.urgent === true, dbUrlEnv: flags['db-url-env'], backupOut: flags['backup-out'] ? path.resolve(cwd, flags['backup-out']) : undefined,
         firstStart: flags['first-start'] === true, dbService: flags['db-service'], reason: flags.reason, remote: flags.remote,
+        ciRun: flags['ci-run'], redeploy: flags.redeploy === true,
     }),
     converge: ({ flags }) => ({ since: flags.since, timeoutSeconds: number(flags, 'timeout') }),
     verify: ({ flags }) => ({ retrySeconds: number(flags, 'retry'), skipPublic: flags['skip-public'] === true, skipInternal: flags['skip-internal'] === true }),
-    rollback: ({ flags }) => ({ release: flags.release ?? null, execute: flags.execute === true, timeoutSeconds: number(flags, 'timeout') }),
+    rollback: ({ flags }) => ({ release: flags.release ?? null, execute: flags.execute === true, timeoutSeconds: number(flags, 'timeout'), dataAcknowledged: flags['data-acknowledged'] === true }),
     prune: ({ flags, cwd }) => ({ keepFiles: (flags.keep ?? []).map((file) => path.resolve(cwd, file)), execute: flags.execute === true }),
     backup: ({ flags }) => ({ swarmState: flags['swarm-state'] === true, execute: flags.execute === true }),
     ingress: ({ flags, positional }) => ({ action: positional[0], execute: flags.execute === true, args: positional.slice(1) }),
     build: ({ flags }) => ({ push: flags.push === true, execute: flags.execute === true }),
-    accept: ({ flags }) => ({ release: flags.release ?? null, execute: flags.execute === true, retrySeconds: number(flags, 'retry') }),
+    accept: ({ flags }) => ({ release: flags.release ?? null, execute: flags.execute === true, retrySeconds: number(flags, 'retry'), dbUrlEnv: flags['db-url-env'] }),
+    status: () => ({}),
+    'ci-key': ({ flags, cwd }) => ({ publicKey: flags['public-key'] ? path.resolve(cwd, flags['public-key']) : null, printAuthorizedKeys: flags['print-authorized-keys'] === true, printGate: flags['print-gate'] === true }),
     retire: ({ flags }) => ({ projects: flags.project ?? [], execute: flags.execute === true }),
     jobs: ({ flags, positional }) => ({ action: positional[0], args: positional.slice(1), execute: flags.execute === true }),
     task: ({ flags, positional }) => ({ name: positional[0], args: positional.slice(1), execute: flags.execute === true }),
@@ -154,6 +161,8 @@ const MODULES = {
     retire: ['./retire.mjs', 'retireCompose'],
     build: ['./build.mjs', 'buildImages'],
     accept: ['./deploy.mjs', 'acceptRelease'],
+    status: ['./status.mjs', 'statusStack'],
+    'ci-key': ['./ci-key.mjs', 'ciKey'],
 };
 async function handlerOf(action, importer) {
     const [file, name] = MODULES[action];

package/stack/config.d.mts

@@ -84,6 +84,14 @@ export interface BackupBlock {
     dir: string | null;
     volumes: BackupVolume[];
 }
+/** The normalised `deploy.notify` block: the sealed webhook URL and the outcomes announced. */
+export interface NotifyBlock {
+    webhook: {
+        member: string;
+        key: string;
+    };
+    on: string[];
+}
 export interface RegistryBlock {
     host: string;
     visibility: string;
@@ -158,6 +166,12 @@ export interface DeployBlock {
     environment: Record<string, ServiceEnvironment>;
     configs: ConfigEntry[];
     passEnv: string[];
+    /** deploy.auto: a green release tag deploys here by itself (the CI workflow reads it; the verbs do not). */
+    auto: boolean;
+    /** deploy.approval: none, or reviewers set on the GitHub Environment. */
+    approval: 'none' | 'reviewers';
+    /** deploy.platforms: the platforms the images are built for (default linux/amd64). */
+    platforms: string[];
     verify: {
         http: HttpCheck[];
         exec: ExecCheck[];
@@ -166,6 +180,7 @@ export interface DeployBlock {
     tasks: Record<string, TaskEntry>;
     postDeploy: string[];
     backup: BackupBlock | null;
+    notify: NotifyBlock | null;
     ingress: IngressConfig | null;
     registry: RegistryBlock;
 }

package/stack/converge.d.mts

@@ -2,6 +2,8 @@ import type { DeployConfig } from './config.mjs';
 import type { StackContext } from './context.mjs';
 import type { ActionResult } from './remote.mjs';
 type Ctx = Pick<StackContext, 'spawn' | 'now' | 'sleep'>;
+/** The JSON text with object keys sorted at every depth, so two equal specs compare equal whatever the key order. */
+export declare function canonical(value: unknown): string;
 /**
  * Waits until the stack converged. `since` is the ISO instant the deploy began (required). Returns { ok, lines, data: { services, failed, pending } };
  * on failure the lines name the service and the Swarm task error text.

package/stack/converge.mjs

@@ -13,7 +13,7 @@ const TAB = String.fromCodePoint(9);
 const TASK_FORMAT = `{{.DesiredState}}|{{.Status.State}}|{{.Status.Timestamp}}|{{.Status.Err}}${TAB}{{json .Spec}}`;
 const docker = (ctx, args) => toolOutput(ctx, 'docker', args);
 /** The JSON text with object keys sorted at every depth, so two equal specs compare equal whatever the key order. */
-function canonical(value) {
+export function canonical(value) {
     if (Array.isArray(value))
         return `[${value.map(canonical).join(',')}]`;
     if (value !== null && typeof value === 'object')

package/stack/db-phases.d.mts

@@ -0,0 +1,185 @@
+import type { DbTarget as PostgresTarget } from '../db/postgres.mjs';
+import type { DatabaseDecl, DatabaseTarget, MigrationPhase } from '../db/migrate.mjs';
+import type { DeployConfig } from './config.mjs';
+import type { StackContext } from './context.mjs';
+import type { ArchiveFacts, ManagerBackup } from './manager-backup.mjs';
+import type { ActionResult, Runner } from './remote.mjs';
+/** The receipt of a database backup (db/backup-receipt.mjs). */
+export interface BackupReceipt {
+    schemaOnly: boolean;
+    at: string;
+    file: string;
+    bytes: number;
+    sha256: string;
+    parts: string[];
+}
+/** What a backup hands back: where the receipt is and what it says. */
+export interface BackupData {
+    receiptPath: string;
+    receipt?: BackupReceipt | undefined;
+}
+/** The database a floor step reaches (db/postgres.mjs): `{ urlEnv }`, `{}` or `{ target }`, spread into the migrate options. */
+export type DbTarget = Record<string, unknown>;
+/** The verdict of one migrate pass; `data` is migrate's (`done`, `push`, `pushFiles`, `pushed`). */
+export interface MigrateResult {
+    ok: boolean;
+    lines?: string[] | undefined;
+    data?: Record<string, unknown> | undefined;
+}
+/** Whether the database is empty, and why not. */
+export interface Emptiness {
+    empty: boolean;
+    history: boolean;
+    publicTables: number;
+}
+/** The outcome of the `first-start` step. */
+export interface FirstStartStepResult {
+    ok: boolean;
+    code?: string;
+    lines: string[];
+}
+/** The collaborators of the database steps, each defaulting to the app's own db verbs; a spec injects stubs. */
+export interface FloorDeps {
+    backup: (ctx: StackContext, args: {
+        target: DbTarget;
+        out: string;
+    }) => Promise<BackupData>;
+    decrypt: (ctx: StackContext, args: {
+        archive: string;
+        identity: string | null;
+        parts: string[];
+    }) => Promise<{
+        parts: string[];
+    }>;
+    migrate: (ctx: StackContext, args: {
+        target: DbTarget;
+        execute: boolean;
+        phase?: MigrationPhase | undefined;
+    }) => Promise<MigrateResult>;
+    dbContainer: (ctx: StackContext, config: DeployConfig, args: {
+        service: string;
+        seconds: number;
+    }) => Promise<string | undefined>;
+    emptiness: (ctx: StackContext, target: PostgresTarget) => Promise<Emptiness>;
+    /** The database of a running container, reached with the credentials that container holds. */
+    containerTarget: (ctx: StackContext, container: string) => PostgresTarget;
+    /** The encrypted dump of a `stack` database, made and kept on the manager. */
+    managerBackup: (ctx: StackContext, config: DeployConfig, args: {
+        run: Runner;
+        container: string;
+        url: string;
+        recipients: string[];
+        at: string;
+    }) => Promise<ManagerBackup>;
+    /** The test decrypt of that dump on the manager with its own identity: the parts it lists. */
+    managerDecrypt: (ctx: StackContext, args: {
+        run: Runner;
+        archive: string;
+    }) => Promise<string[]>;
+}
+/** The code or message of a thrown value, for a refusal line. */
+export declare const reasonOf: (error: unknown) => string;
+/** The message of a thrown value. */
+export declare const messageOf: (error: unknown) => string;
+/** A refused step: the lines so far and the code; the CLI prints both and exits 2. */
+export declare const refused: (lines: string[], code: string, message: string, data?: Record<string, unknown>) => ActionResult;
+export declare const AGE_HEADER = "age-encryption.org/v1\n";
+/** Problems of a backup receipt against the facts measured on its archive: a full backup written by this run, size, age header and sha256 equal. */
+export declare function backupProblems(receipt: BackupReceipt | undefined, facts: ArchiveFacts, startedMs: number): string[];
+/** How long a first start waits for the database service's container to accept connections. */
+export declare const FIRST_START_WAIT_SECONDS = 180;
+/** How long a deploy of a running stack waits for the database service's container to accept connections. */
+export declare const DB_WAIT_SECONDS = 60;
+export declare const FLOOR_DEPS: Readonly<FloorDeps>;
+/**
+ * The `first-start` step of a first start's deploy (between the hold deploy and the real one): the database container, the proof it is empty,
+ * migrate preview then execute (every migration, contract ones included: no release runs yet) inside it. `targetFor` reaches the container's
+ * database; `hint` ends the not-empty message with what the operator does next. Returns { ok, lines, code } where code names the failure.
+ */
+export declare function firstStartStep(ctx: StackContext, config: DeployConfig, input: {
+    service: string;
+    targetFor: (container: string) => PostgresTarget;
+    hint: string;
+}, f: FloorDeps): Promise<FirstStartStepResult>;
+/** The database a deploy migrates: the `database:` block of application-stacks.yaml. */
+export interface DeployDatabase {
+    decl: DatabaseDecl;
+    target: DatabaseTarget;
+    service: string;
+}
+/** The `database:` block of the app, or null when it declares none (then a deploy has no database phase at all). */
+export declare function declaredDatabase(ctx: Pick<StackContext, 'cwd'>, config: Pick<DeployConfig, 'repoRoot'>): Promise<DeployDatabase | null>;
+/** What the phases of one deploy are given. */
+export interface PhaseInput {
+    ctx: StackContext;
+    config: DeployConfig;
+    database: DeployDatabase;
+    f: FloorDeps;
+    /** The manager's runner (a `stack` database's backup is made and kept there). */
+    run: Runner | null;
+    dbUrlEnv?: string | undefined;
+    backupOut?: string | undefined;
+}
+/**
+ * A `stack` database must be a service of the stack the deploy renders: an app whose `database:` block exists but whose database is not one of its
+ * services declares `target: external`. Returns the refusal, or null when the service is there (or the stack's services are not known).
+ */
+export declare function unknownDatabaseService(config: Pick<DeployConfig, 'stack' | 'services'>, database: DeployDatabase): {
+    code: string;
+    message: string;
+} | null;
+/** One recorded step of a deploy. */
+export interface PhaseStep {
+    step: string;
+    ok: boolean;
+}
+/** What the deploy keeps of its migrations (the deploy result's `data.migrations`; WP1's journal records it). */
+export interface MigrationRecord {
+    /** Something was pending before the deploy. */
+    pending: boolean;
+    /** The file names of the expand and of the contract migrations that were pending. */
+    expand: string[];
+    contract: string[];
+    /** The verified backup taken because something was pending, else null (nothing pending: no backup). */
+    backup: {
+        receiptPath: string;
+        file: string;
+        bytes: number;
+        sha256: string;
+        where: 'manager' | 'local';
+    } | null;
+    /** The versions the expand pass and the contract pass applied. */
+    applied: string[];
+    contractApplied: string[];
+}
+/** The result of a phase: ok, or the refusal that stopped it; the steps it ran and the lines it printed either way. */
+export interface PhaseResult {
+    ok: boolean;
+    refused?: {
+        code: string;
+        message: string;
+    } | undefined;
+    lines: string[];
+    steps: PhaseStep[];
+    record: MigrationRecord;
+}
+/**
+ * Before the stack deploy: preview, backup only when something is pending, then the expand migrations. Any refusal leaves the services untouched
+ * and carries its code; the migrations an execute applied before failing stay (the backup is their way back).
+ */
+export declare function expandPhase(p: PhaseInput): Promise<PhaseResult>;
+/**
+ * After the accept: the `*_contract_*` migrations. A red contract leaves the release accepted (it is serving and verified); the caller reports a
+ * red job and the owner decides. Nothing pending is a green no-op without a database call beyond the preview.
+ */
+export declare function contractPhase(p: PhaseInput): Promise<{
+    ok: boolean;
+    lines: string[];
+    applied: string[];
+    skipped: boolean;
+}>;
+/** The first-start hooks of a `stack` database on an environment with no accepted release (the deploy's `deploy-hold` and `first-start` steps). */
+export declare function firstStartHooks(p: PhaseInput): {
+    step: () => Promise<FirstStartStepResult>;
+    service: string;
+};