@starci/hfs 4.13.0 → 4.15.0

package/src/stack-records-double.d.mts

@@ -1,6 +1,6 @@
 import type { ReleaseStore, StoredRelease } from '../stack/release-store.mjs';
 /** The records half of a ReleaseStore, plus what it kept. */
-export interface RecordsDouble extends Pick<ReleaseStore, 'read' | 'tryLock' | 'refreshLock' | 'unlock' | 'journal'> {
+export interface RecordsDouble extends Pick<ReleaseStore, 'read' | 'tryLock' | 'refreshLock' | 'unlock' | 'journal' | 'journals'> {
     /** The latest document of each attempt, as the journal wrote it (a copy at each write). */
     documents: Map<string, Record<string, unknown>>;
     /** Every write of every document, in order: the phase boundaries a cancelled job would have left. */
@@ -25,6 +25,8 @@ export interface RecordsOptions {
         freeAfterTries?: number;
     } | undefined;
     failJournal?: boolean | undefined;
+    /** The attempt documents the journal already holds (what journals() answers): the evidence of the manual rollback guard. */
+    history?: Record<string, unknown>[] | undefined;
     /** The journal accepts this many document writes and fails every later one (a manager that drops mid-deploy). */
     failJournalAfter?: number | undefined;
 }

package/stack/ci-key.d.mts

@@ -0,0 +1,11 @@
+import type { DeployConfig } from './config.mjs';
+import type { StackContext } from './context.mjs';
+import type { ActionResult } from './remote.mjs';
+/** What the verb takes. */
+export interface CiKeyOptions {
+    publicKey?: string | null | undefined;
+    printAuthorizedKeys?: boolean | undefined;
+    printGate?: boolean | undefined;
+}
+/** Prints the gate, the authorized_keys line or the install steps (see the top of the file). */
+export declare function ciKey(_ctx: StackContext, config: DeployConfig, options?: CiKeyOptions): Promise<ActionResult>;

package/stack/ci-key.mjs

@@ -0,0 +1,44 @@
+// ci-key.mjs - `starci app stack ci-key`: the owner-run side of the forced-command gate of the CI SSH key (ssh-gate.mts).
+//   --print-gate              prints the text of starci-ssh-gate, to install executable as /usr/local/bin/starci-ssh-gate on the manager
+//   --print-authorized-keys   prints the authorized_keys line of the CI key from its PUBLIC key file (--public-key <file>)
+// Both print only their text, so they pipe straight into the owner's ssh. Nothing here reaches a server, reads a sealed member or touches a private
+// key: creating, installing and rotating the key stay owner-run steps. Without a flag the verb prints the install steps.
+import fs from 'node:fs';
+import { refusal } from './errors.mjs';
+import { GATE_PATH, authorizedKeysLine, gateScript } from './ssh-gate.mjs';
+const lineOf = (file) => {
+    if (!file)
+        throw refusal('STACK_USAGE', '--print-authorized-keys needs --public-key <the .pub file of the CI key>');
+    let text;
+    try {
+        text = fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        throw refusal('STACK_CI_KEY_PUBLIC', `cannot read the public key file ${file}`);
+    }
+    return authorizedKeysLine(text);
+};
+/** Prints the gate, the authorized_keys line or the install steps (see the top of the file). */
+export async function ciKey(_ctx, config, options = {}) {
+    if (options.printGate === true && options.printAuthorizedKeys === true)
+        throw refusal('STACK_USAGE', 'print the gate or the authorized_keys line, one at a time');
+    if (options.printGate === true)
+        return { ok: true, lines: [gateScript().trimEnd()], data: { gatePath: GATE_PATH } };
+    if (options.printAuthorizedKeys === true) {
+        const line = lineOf(options.publicKey);
+        return { ok: true, lines: [line], data: { authorizedKeys: line } };
+    }
+    const env = config.env;
+    return {
+        ok: true,
+        lines: [
+            'the CI key reaches Docker, which is root on the manager: its authorized_keys line forces starci-ssh-gate, which admits docker system dial-stdio and the release store\'s named operations only.',
+            'owner-run steps on the manager (as root; <ops> is your own ssh access):',
+            `  1. starci app stack ci-key --env ${env} --print-gate | ssh <ops> 'install -m 0755 -o root -g root /dev/stdin ${GATE_PATH}'`,
+            `  2. starci app stack ci-key --env ${env} --public-key <ci-key.pub> --print-authorized-keys | ssh <ops> 'cat >> ~<ci-account>/.ssh/authorized_keys'`,
+            '  3. seal VPS_GATE=1 in the vps-ci member of the environment, so `stack connect` tells the deploy to use the gate (STARCI_SSH_GATE=1); remove it to go back.',
+            'not yet admitted by the gate: the post-deploy tasks and the manager backup/decrypt of a stack database run free commands; keep those environments on an ungated key until they are named operations.',
+        ],
+        data: { gatePath: GATE_PATH },
+    };
+}

package/stack/cli.d.mts

@@ -15,6 +15,10 @@ export interface Flags {
     urgent?: boolean;
     'first-start'?: boolean;
     redeploy?: boolean;
+    'data-acknowledged'?: boolean;
+    'print-authorized-keys'?: boolean;
+    'print-gate'?: boolean;
+    'public-key'?: string;
     image?: string[];
     keep?: string[];
     'extra-compose'?: string[];
@@ -36,7 +40,7 @@ export interface Flags {
     remote?: string;
     'ci-run'?: string;
 }
-export declare const ACTIONS: readonly ["prepare", "connect", "disconnect", "build-args", "render", "deploy", "converge", "verify", "rollback", "prune", "backup", "jobs", "task", "ingress", "retire", "build", "accept", "status"];
+export declare const ACTIONS: readonly ["prepare", "connect", "disconnect", "build-args", "render", "deploy", "converge", "verify", "rollback", "prune", "backup", "jobs", "task", "ingress", "retire", "build", "accept", "status", "ci-key"];
 /** One action of `starci app stack`. */
 export type Action = (typeof ACTIONS)[number];
 /** True when `value` names one action of `starci app stack`. */

package/stack/cli.mjs

@@ -20,11 +20,11 @@ import { parseTargetBinding, bindStackTarget, nativeToolEnvironment } from './ta
 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', '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']);
+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', '--redeploy']);
-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']);
+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'];
@@ -41,7 +41,7 @@ export const FLAGS = Object.freeze({
     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],
@@ -51,11 +51,12 @@ export const FLAGS = Object.freeze({
     build: ['--push', '--execute'],
     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', 'status']);
+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]]);
@@ -137,13 +138,14 @@ const OPTIONS = {
     }),
     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'), 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 }),
@@ -160,6 +162,7 @@ const MODULES = {
     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;
@@ -172,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/deploy.d.mts

@@ -41,6 +41,7 @@ export interface RollbackOptions {
     timeoutSeconds?: number | undefined;
     sshCmd?: string | null | undefined;
     lockWaitSeconds?: number | undefined;
+    dataAcknowledged?: boolean | undefined;
 }
 /** What an accept takes. */
 export interface AcceptOptions {
@@ -70,7 +71,9 @@ export interface DeployDeps {
         keepFiles: string[];
         execute: boolean;
     }) => Promise<ActionResult>;
-    releaseStore: (config: DeployConfig, ssh: Runner) => ReleaseStore;
+    releaseStore: (config: DeployConfig, ssh: Runner, options?: {
+        gated?: boolean | undefined;
+    }) => ReleaseStore;
     observedServices: (ctx: StackContext, config: DeployConfig) => ObservedService[];
     ssh: (ctx: StackContext, config: DeployConfig, options: SshOptions) => Runner | Promise<Runner>;
     floor: Partial<FloorDeps>;

package/stack/deploy.mjs

@@ -42,6 +42,8 @@ import { pruneStack } from './prune.mjs';
 import { compareWithRelease, observedServices, stackImages } from './status.mjs';
 import { parseYaml } from '../runtime/engine/yaml.mjs';
 import { createReleaseStore } from './release-store.mjs';
+import { contractFinding, enforceContractGuard } from './rollback-guard.mjs';
+import { gateIsOn } from './ssh-gate.mjs';
 import { urgentDeploy } from './urgent-floor.mjs';
 import { verifyStack } from './verify.mjs';
 /** Loads `file` (relative to this module). Split out so a spec can load a real sibling module through `lazy`. */
@@ -163,7 +165,7 @@ async function openRunner(ctx, config, options, d, cleanups) {
     cleanups.push(() => run.cleanup?.());
     return run;
 }
-const openStore = async (ctx, config, options, d, cleanups) => d.releaseStore(config, await openRunner(ctx, config, options, d, cleanups));
+const openStore = async (ctx, config, options, d, cleanups) => d.releaseStore(config, await openRunner(ctx, config, options, d, cleanups), { gated: gateIsOn(ctx.env) });
 /** Redeploys a stored release after a failed deploy: fetch, stack deploy, converge. Returns the lines to print. */
 async function redeployStored(ctx, config, d, store, previous, out, steps, rec) {
     const dir = path.join(out, 'previous');
@@ -352,7 +354,7 @@ async function deployExecute(ctx, config, options, d, out, seams) {
         const contract = phase && !first ? await rec.phase('contract', () => contractPhase(phase), (done) => done.ok) : null;
         if (contract) {
             lines.push(...contract.lines);
-            rec.note({ migrations: [...(data.migrations?.applied ?? []), ...contract.applied] });
+            rec.note({ migrations: [...(data.migrations?.applied ?? []), ...contract.applied], contract: contract.applied });
             steps.push({ step: 'contract', ok: contract.ok });
             data.migrations = { ...data.migrations, contractApplied: contract.applied };
         }
@@ -413,7 +415,7 @@ export async function deployRelease(ctx, config, options = {}, deps = {}) {
         if (options.urgent !== true)
             await render();
         const run = await openRunner(ctx, config, options, d, cleanups);
-        const store = d.releaseStore(config, run);
+        const store = d.releaseStore(config, run, { gated: gateIsOn(ctx.env) });
         const meta = {
             kind: 'deploy', trigger: triggerOf(options), sourceSha: options.sourceSha, ciRun: options.ciRun,
             urgent: options.urgent === true ? { role: ctx.env.STARCI_ROLE ?? 'unknown', reason: options.reason ?? '' } : undefined,
@@ -457,8 +459,10 @@ export async function rollbackRelease(ctx, config, options = {}, deps = {}) {
         const target = release ?? await store.previous();
         if (!target)
             throw refusal('STACK_ROLLBACK_NO_TARGET', 'no previous accepted release is recorded; name one with --release');
+        // A manual rollback to a release older than an applied contract migration is refused unless the owner acknowledges the data effect.
+        const notice = enforceContractGuard(contractFinding(await store.journals(), target), options.dataAcknowledged === true);
         if (options.execute !== true)
-            return { ok: true, lines: [`dry run: would redeploy release ${target}`], data: { release: target, executed: false } };
+            return { ok: true, lines: [...notice, `dry run: would redeploy release ${target}`], data: { release: target, executed: false } };
         return await recordedAttempt(ctx, config, store, { kind: 'rollback', trigger: 'dispatch' }, { waitSeconds: options.lockWaitSeconds }, async (rec) => {
             const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'stack-rollback-'));
             try {
@@ -475,6 +479,7 @@ export async function rollbackRelease(ctx, config, options = {}, deps = {}) {
                     ['verify', () => d.verifyStack(ctx, config, { retrySeconds: 180, stackFile })],
                     ['accept', async () => { await acceptObserved(ctx, config, d, store, rec, { out: scratch, releaseId: target }); return { ok: true, lines: [] }; }],
                 ], lines, steps, rec);
+                lines.unshift(...notice);
                 lines.push(failed ? `rollback to ${target} failed at ${failed}` : `rolled back to release ${target}; a rollback cannot undo data effects`);
                 return { ok: !failed, lines, data: { release: target, executed: true, steps } };
             }
@@ -525,7 +530,7 @@ export async function acceptRelease(ctx, config, options = {}, deps = {}) {
             const contract = database ? await rec.phase('contract', () => contractPhase({ ctx, config, database, f: { ...FLOOR_DEPS, ...d.floor }, run: null, dbUrlEnv: options.dbUrlEnv }), (done) => done.ok) : null;
             if (contract) {
                 lines.push(...contract.lines);
-                rec.note({ migrations: contract.applied });
+                rec.note({ migrations: contract.applied, contract: contract.applied });
             }
             if (contract && !contract.ok)
                 return { ok: false, lines: [...lines, `release ${release} is accepted and serving; its contract migration is red: the owner decides`], data: { release, accepted: true, executed: true, contractFailed: true } };

package/stack/journal.d.mts

@@ -47,6 +47,8 @@ export interface AttemptDocument {
     backup: Record<string, unknown> | null;
     /** Reserved for the migrate and contract phases: the names of the migrations that were applied. */
     migrations: string[];
+    /** The contract migrations this attempt applied (the marker the manual rollback guard reads); empty when it applied none. */
+    contract: string[];
     /** `docker service inspect` snapshots by moment: `converge`, `rollback`, `accept`. */
     observed: Record<string, ObservedService[]>;
     outcome: Outcome;
@@ -55,6 +57,20 @@ export interface AttemptDocument {
         message: string;
     } | null;
 }
+/** The facts of a finished attempt that a notification carries: names, digests and codes, never a message text or a value. */
+export interface AttemptSummary {
+    attempt: string;
+    kind: AttemptKind;
+    stack: string;
+    env: string;
+    outcome: Outcome;
+    trigger: Trigger;
+    sourceSha: string | null;
+    tag: string | null;
+    releaseId: string | null;
+    ciUrl: string | null;
+    errorCode: string | null;
+}
 /** What an attempt is told about itself when it opens. */
 export interface AttemptMeta {
     kind: AttemptKind;
@@ -74,6 +90,7 @@ export interface Note {
     previous?: string | null;
     backup?: Record<string, unknown> | null;
     migrations?: string[];
+    contract?: string[];
     urgent?: {
         role: string;
         reason: string;
@@ -95,6 +112,8 @@ export interface Recorder {
         code: string;
         message: string;
     } | null): Promise<void>;
+    /** The facts of the attempt as it stands (call after `finish` for a notification). */
+    summary(): AttemptSummary;
 }
 /** A new attempt id: the UTC time and 8 random hex characters. */
 export declare const newAttemptId: (ctx: Pick<StackContext, "now">) => string;

package/stack/journal.mjs

@@ -11,6 +11,7 @@
 import { randomBytes } from 'node:crypto';
 import { firstLine } from './context.mjs';
 import { StackError, refusal } from './errors.mjs';
+import { notifyOutcome } from './notify.mjs';
 const REASON_MAX = 500;
 const SAFE = /[^A-Za-z0-9._/:@ -]/gu;
 const isoOf = (ctx) => new Date(ctx.now()).toISOString();
@@ -39,7 +40,7 @@ export async function openAttempt(ctx, config, store, meta) {
         schema: 'starci/stack-deploy-attempt@1', attempt: id, kind: meta.kind, stack: config.stack, env: config.env, startedAt: isoOf(ctx), endedAt: null,
         trigger: meta.trigger, sourceSha: meta.sourceSha ?? null, tag: facts.tag, ci: facts.ci,
         urgent: meta.urgent ? { role: clean(meta.urgent.role, 40), reason: meta.urgent.reason.slice(0, REASON_MAX), tag: meta.urgent.tag ?? null } : null,
-        releaseId: null, previous: null, phases: [], backup: null, migrations: [], observed: {}, outcome: 'running', error: null,
+        releaseId: null, previous: null, phases: [], backup: null, migrations: [], contract: [], observed: {}, outcome: 'running', error: null,
     };
     const warnings = [];
     let beat = async () => { };
@@ -70,6 +71,8 @@ export async function openAttempt(ctx, config, store, meta) {
                 document.backup = found.backup;
             if (found.migrations !== undefined)
                 document.migrations = found.migrations;
+            if (found.contract !== undefined)
+                document.contract = found.contract;
             if (found.urgent)
                 document.urgent = { role: clean(found.urgent.role, 40), reason: found.urgent.reason.slice(0, REASON_MAX), tag: found.urgent.tag ?? null };
         },
@@ -93,6 +96,10 @@ export async function openAttempt(ctx, config, store, meta) {
             }
         },
         snapshot(moment, services) { document.observed[moment] = services; },
+        summary: () => ({
+            attempt: id, kind: document.kind, stack: document.stack, env: document.env, outcome: document.outcome, trigger: document.trigger,
+            sourceSha: document.sourceSha, tag: document.tag, releaseId: document.releaseId, ciUrl: document.ci?.url ?? null, errorCode: document.error?.code ?? null,
+        }),
         async finish(outcome, error = null) {
             document.outcome = outcome;
             document.endedAt = isoOf(ctx);
@@ -165,10 +172,12 @@ export async function recordedAttempt(ctx, config, store, meta, wait, body) {
         });
         const result = await body(recorder);
         await recorder.finish(outcomeOf(result, meta.kind), result.refused ? { code: result.refused.code, message: result.refused.message.slice(0, 300) } : null);
-        return { ...result, lines: [...result.lines, ...recorder.warnings], data: { ...result.data, attempt: recorder.id } };
+        const notice = await notifyOutcome(ctx, config, recorder.summary());
+        return { ...result, lines: [...result.lines, ...recorder.warnings, ...notice], data: { ...result.data, attempt: recorder.id } };
     }
     catch (error) {
         await recorder.finish('refused', errorOf(error));
+        await notifyOutcome(ctx, config, recorder.summary());
         throw error;
     }
     finally {

package/stack/notify.d.mts

@@ -0,0 +1,9 @@
+import type { DeployConfig } from './config.mjs';
+import type { StackContext } from './context.mjs';
+import type { AttemptSummary } from './journal.mjs';
+/** The one-line text a chat webhook shows. */
+export declare function notifyText(summary: AttemptSummary): string;
+/** The JSON body: `text` (Slack style) and `content` (Discord style) carry the line, the rest is the same facts as fields. */
+export declare function notifyBody(summary: AttemptSummary): Record<string, unknown>;
+/** Sends the message for a finished attempt when `deploy.notify` is declared and lists its outcome; returns the lines to print (empty when nothing was sent or it went well). */
+export declare function notifyOutcome(ctx: StackContext, config: Pick<DeployConfig, 'notify' | 'secretsDir'>, summary: AttemptSummary): Promise<string[]>;

package/stack/notify.mjs

@@ -0,0 +1,32 @@
+import { openMember } from './sealed.mjs';
+const TIMEOUT_MS = 10_000;
+const HTTPS_URL = /^https:\/\/[^\s]+$/u;
+/** The one-line text a chat webhook shows. */
+export function notifyText(summary) {
+    const commit = summary.sourceSha ? ` of ${summary.sourceSha.slice(0, 10)}` : '';
+    const tag = summary.tag ? ` (${summary.tag})` : '';
+    const release = summary.releaseId ? `, release ${summary.releaseId}` : '';
+    const failure = summary.errorCode ? `, ${summary.errorCode}` : '';
+    return `[${summary.stack}/${summary.env}] ${summary.kind} ${summary.outcome}${commit}${tag}${release}${failure}`;
+}
+/** The JSON body: `text` (Slack style) and `content` (Discord style) carry the line, the rest is the same facts as fields. */
+export function notifyBody(summary) {
+    const text = notifyText(summary);
+    return { text, content: text, ...summary };
+}
+/** Sends the message for a finished attempt when `deploy.notify` is declared and lists its outcome; returns the lines to print (empty when nothing was sent or it went well). */
+export async function notifyOutcome(ctx, config, summary) {
+    const declared = config.notify;
+    if (!declared || !declared.on.includes(summary.outcome))
+        return [];
+    try {
+        const url = openMember(ctx, config, declared.webhook.member)[declared.webhook.key];
+        if (typeof url !== 'string' || !HTTPS_URL.test(url))
+            return [`notify: the sealed ${declared.webhook.member} holds no https URL under ${declared.webhook.key}; nothing was sent`];
+        const response = await ctx.fetch(url, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(notifyBody(summary)), redirect: 'error', signal: AbortSignal.timeout(TIMEOUT_MS) });
+        return response.ok ? [] : [`notify: the webhook answered HTTP ${response.status}; the deploy outcome stands`];
+    }
+    catch (error) {
+        return [`notify: the message was not sent (${error.name === 'TimeoutError' ? 'timed out' : 'the webhook could not be reached'}); the deploy outcome stands`];
+    }
+}

package/stack/release-store.d.mts

@@ -48,20 +48,22 @@ export interface ReleaseStore {
     unlock(token: string): Promise<boolean>;
     /** The journal of one attempt under /srv/<stack>/deploys. */
     journal(attempt: string): AttemptJournal;
+    /** The newest attempt documents (at most 500), oldest first; a document that is not a JSON object is left out. */
+    journals(): Promise<Record<string, unknown>[]>;
 }
 /** A lock nobody refreshed for this long (its holder died without releasing it) is taken over by the next try. Phases refresh it. */
 export declare const LOCK_TTL_SECONDS = 3600;
 /** An attempt id: UTC compact time and 8 random hex. */
 export declare const ATTEMPT_ID: RegExp;
 /**
- * The remote script of one try at the deploy lock: `mkdir` is the atomic claim, the owner file (token, trigger, epoch) is replaced by rename, a lock
- * unrefreshed for `ttl` seconds is moved aside (one rename wins) and claimed anew. Prints `acquired` or `busy <trigger> <age>`. Composed only from
- * a validated base, token and trigger.
+ * The remote command of one try at the deploy lock (ssh-gate.mts holds the body): `mkdir` is the atomic claim, the owner file (token, trigger, epoch) is
+ * replaced by rename, a lock unrefreshed for `ttl` seconds is moved aside (one rename wins) and claimed anew. Prints `acquired` or `busy <trigger> <age>`.
+ * Composed only from a validated base, token and trigger.
  */
 export declare const lockAcquireScript: (base: string, token: string, trigger: string, ttl?: number) => string;
-/** The remote script that marks the lock alive when `token` owns it: prints `held` or `lost`. */
+/** The remote command that marks the lock alive when `token` owns it: prints `held` or `lost`. */
 export declare const lockRefreshScript: (base: string, token: string) => string;
-/** The remote script that removes the lock when `token` owns it: prints `released` or `lost`. */
+/** The remote command that removes the lock when `token` owns it: prints `released` or `lost`. */
 export declare const lockReleaseScript: (base: string, token: string) => string;
 /** Removes every carriage return: a snippet from a Windows checkout must never reach a remote shell with CRLF. */
 export declare const lfOnly: (text: unknown) => string;
@@ -69,4 +71,6 @@ export declare const lfOnly: (text: unknown) => string;
  * The release store of one stack. `ssh` is the runner; the returned API is async:
  *   store(dir, id) accept(id) current() previous() fetch(id, targetDir) list()
  */
-export declare function createReleaseStore(config: Pick<DeployConfig, 'remote' | 'stack'>, ssh: StoreSsh): ReleaseStore;
+export declare function createReleaseStore(config: Pick<DeployConfig, 'remote' | 'stack'>, ssh: StoreSsh, options?: {
+    gated?: boolean | undefined;
+}): ReleaseStore;

package/stack/release-store.mjs

@@ -8,7 +8,7 @@ import path from 'node:path';
 import { firstLine, lines as splitLines } from './context.mjs';
 import { isReleaseId } from './digest.mjs';
 import { failure, refusal } from './errors.mjs';
-import { releaseListScript, releasePointerScript } from './remote.mjs';
+import { gatedCommand, inlineCommand } from './ssh-gate.mjs';
 /** A lock nobody refreshed for this long (its holder died without releasing it) is taken over by the next try. Phases refresh it. */
 export const LOCK_TTL_SECONDS = 3600;
 const TOKEN = /^[0-9a-f]{32}$/u;
@@ -30,27 +30,16 @@ const checkedAttempt = (attempt) => {
         throw refusal('STACK_ATTEMPT_ID', 'an attempt id is a UTC compact time and 8 lowercase hex characters');
     return attempt;
 };
-const OWNER_READ = (lock) => `if [ -r "${lock}/owner" ]; then read -r held_token held_trigger held_stamp < "${lock}/owner"; else held_token=none; held_trigger=unknown; held_stamp=$(stat -c %Y "${lock}" 2>/dev/null) || held_stamp=0; fi; case "$held_stamp" in ''|*[!0-9]*) held_stamp=0;; esac`;
 /**
- * The remote script of one try at the deploy lock: `mkdir` is the atomic claim, the owner file (token, trigger, epoch) is replaced by rename, a lock
- * unrefreshed for `ttl` seconds is moved aside (one rename wins) and claimed anew. Prints `acquired` or `busy <trigger> <age>`. Composed only from
- * a validated base, token and trigger.
+ * The remote command of one try at the deploy lock (ssh-gate.mts holds the body): `mkdir` is the atomic claim, the owner file (token, trigger, epoch) is
+ * replaced by rename, a lock unrefreshed for `ttl` seconds is moved aside (one rename wins) and claimed anew. Prints `acquired` or `busy <trigger> <age>`.
+ * Composed only from a validated base, token and trigger.
  */
-export const lockAcquireScript = (base, token, trigger, ttl = LOCK_TTL_SECONDS) => {
-    const lock = `${base}/deploy.lock`;
-    return [
-        `b="${base}"; l="${lock}"; now=$(date +%s); mkdir -p "$b" || exit 1`,
-        `claim() { printf '%s %s %s\\n' '${checkedToken(token)}' '${checkedTrigger(trigger)}' "$now" > "$l/owner.new" && mv -f "$l/owner.new" "$l/owner" && echo acquired && exit 0; exit 1; }`,
-        'if mkdir "$l" 2>/dev/null; then claim; fi',
-        OWNER_READ('$l'),
-        `age=$((now - held_stamp)); if [ "$age" -gt ${Math.trunc(ttl)} ]; then if mv "$l" "$l.stale.${token}" 2>/dev/null; then rm -rf "$l.stale.${token}"; if mkdir "$l" 2>/dev/null; then claim; fi; fi; fi`,
-        'case "$held_trigger" in ci|dispatch|urgent) ;; *) held_trigger=unknown;; esac; echo "busy $held_trigger $age"',
-    ].join('; ');
-};
-/** The remote script that marks the lock alive when `token` owns it: prints `held` or `lost`. */
-export const lockRefreshScript = (base, token) => `l="${base}/deploy.lock"; now=$(date +%s); if [ -r "$l/owner" ]; then read -r t g s < "$l/owner"; if [ "$t" = '${checkedToken(token)}' ]; then printf '%s %s %s\\n' "$t" "$g" "$now" > "$l/owner.new" && mv -f "$l/owner.new" "$l/owner" && echo held; else echo lost; fi; else echo lost; fi`;
-/** The remote script that removes the lock when `token` owns it: prints `released` or `lost`. */
-export const lockReleaseScript = (base, token) => `l="${base}/deploy.lock"; if [ -r "$l/owner" ]; then read -r t g s < "$l/owner"; if [ "$t" = '${checkedToken(token)}' ]; then rm -rf "$l" && echo released; else echo lost; fi; else echo lost; fi`;
+export const lockAcquireScript = (base, token, trigger, ttl = LOCK_TTL_SECONDS) => inlineCommand('lock-acquire', [base, checkedToken(token), checkedTrigger(trigger), String(Math.trunc(ttl))]);
+/** The remote command that marks the lock alive when `token` owns it: prints `held` or `lost`. */
+export const lockRefreshScript = (base, token) => inlineCommand('lock-refresh', [base, checkedToken(token)]);
+/** The remote command that removes the lock when `token` owns it: prints `released` or `lost`. */
+export const lockReleaseScript = (base, token) => inlineCommand('lock-release', [base, checkedToken(token)]);
 const BASE = /^\/[A-Za-z0-9._/-]+$/u;
 const FILES = ['stack.yaml', 'release.json'];
 /** Removes every carriage return: a snippet from a Windows checkout must never reach a remote shell with CRLF. */
@@ -62,7 +51,7 @@ const checkedId = (id) => {
 };
 const checkedBase = (config) => {
     const base = config.remote?.releasesBase ?? `/srv/${config.stack}`;
-    if (!BASE.test(base) || base.split('/').includes('..'))
+    if (!BASE.test(base) || base.includes('..'))
         throw refusal('STACK_RELEASE_BASE', `the releases base ${base} must be an absolute path without ..`);
     return base;
 };
@@ -70,10 +59,11 @@ const checkedBase = (config) => {
  * The release store of one stack. `ssh` is the runner; the returned API is async:
  *   store(dir, id) accept(id) current() previous() fetch(id, targetDir) list()
  */
-export function createReleaseStore(config, ssh) {
+export function createReleaseStore(config, ssh, options = {}) {
     const base = checkedBase(config);
-    const dirOf = (id) => `${base}/releases/${checkedId(id)}`;
-    async function run(command, input) {
+    /** Runs the named operation: through the forced-command gate (`starci-op <name> <args>`) when the key has one, else as the same body under `sh -c`. */
+    async function run(name, args, input) {
+        const command = options.gated === true ? gatedCommand(name, args) : inlineCommand(name, args);
         const answer = await ssh(lfOnly(command), { input });
         if (answer.status !== 0)
             throw failure('STACK_RELEASE_SSH', `remote command failed: ${firstLine(answer.stderr)}`);
@@ -88,14 +78,13 @@ export function createReleaseStore(config, ssh) {
         }
     }
     async function pointer(name) {
-        const out = await run(releasePointerScript(`"${base}"`, name));
+        const out = await run('pointer', [base, name]);
         const id = out.trim();
         return isReleaseId(id) ? id : '';
     }
     /** Both files of a stored release as [name, text] pairs, framed as base64 lines. */
     async function readFiles(id) {
-        const source = dirOf(id);
-        const out = await run(`set -e; for f in stack.yaml release.json; do test -r "${source}/$f"; base64 < "${source}/$f" | tr -d '\\n'; printf '\\n'; done`);
+        const out = await run('read', [base, checkedId(id)]);
         const frames = out.split('\n');
         if (frames.length !== 3 || frames[2] !== '' || frames.slice(0, 2).some((frame) => !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(frame)))
             throw failure('STACK_RELEASE_SSH', 'invalid release response framing');
@@ -104,15 +93,15 @@ export function createReleaseStore(config, ssh) {
     return {
         /** Uploads stack.yaml and release.json of a rendered release as text; read-only afterwards. */
         async store(dir, id) {
-            const target = dirOf(id);
+            checkedId(id);
             const contents = FILES.map((name) => [name, readLocal(dir, name)]);
             const input = contents.map(([, text]) => Buffer.from(text, 'utf8').toString('base64')).join('\n') + '\n';
-            await run(`set -e; d="${target}"; if [ -d "$d" ]; then chmod -R u+w "$d"; else mkdir -p "$d"; fi; IFS= read -r stack; IFS= read -r release; printf '%s' "$stack" | base64 -d > "$d/stack.yaml"; printf '%s' "$release" | base64 -d > "$d/release.json"; chmod 440 "$d/stack.yaml" "$d/release.json"; chmod 550 "$d"`, input);
+            await run('store', [base, checkedId(id)], input);
         },
         /** The release was verified: previous := current, current := id. */
         async accept(id) {
             checkedId(id);
-            await run(`set -e; cd "${base}"; test -d "releases/${id}"; if [ -L current ] && [ "$(basename "$(readlink current)")" != "${id}" ]; then ln -sfn "$(readlink current)" previous; fi; ln -sfn "releases/${id}" current.new; mv -Tf current.new current`);
+            await run('accept', [base, id]);
         },
         /** The accepted release id, '' when none. */
         current: () => pointer('current'),
@@ -139,7 +128,7 @@ export function createReleaseStore(config, ssh) {
             return { stackYaml: stack[1], release: record !== null && typeof record === 'object' && !Array.isArray(record) ? record : {} };
         },
         async tryLock(token, trigger) {
-            const answer = (await run(lockAcquireScript(base, token, trigger))).trim();
+            const answer = (await run('lock-acquire', [base, checkedToken(token), checkedTrigger(trigger), String(LOCK_TTL_SECONDS)])).trim();
             if (answer === 'acquired')
                 return { acquired: true };
             const busy = /^busy ([a-z]+) (-?[0-9]+)$/u.exec(answer);
@@ -147,25 +136,39 @@ export function createReleaseStore(config, ssh) {
                 throw failure('STACK_RELEASE_SSH', 'the deploy lock script answered something else than acquired or busy');
             return { acquired: false, holder: busy[1], ageSeconds: Number(busy[2]) };
         },
-        async refreshLock(token) { return (await run(lockRefreshScript(base, token))).trim() === 'held'; },
-        async unlock(token) { return (await run(lockReleaseScript(base, token))).trim() === 'released'; },
+        async refreshLock(token) { return (await run('lock-refresh', [base, checkedToken(token)])).trim() === 'held'; },
+        async unlock(token) { return (await run('lock-release', [base, checkedToken(token)])).trim() === 'released'; },
         journal(attempt) {
             const id = checkedAttempt(attempt);
-            const file = `${base}/deploys/${id}.json`;
             const encoded = (value) => `${Buffer.from(JSON.stringify(value), 'utf8').toString('base64')}
 `;
             return {
                 async write(document) {
-                    await run(`set -e; d="${base}/deploys"; mkdir -p "$d"; IFS= read -r doc; printf '%s' "$doc" | base64 -d > "$d/.${id}.tmp"; mv -f "$d/.${id}.tmp" "${file}"`, encoded(document));
+                    await run('journal-write', [base, id], encoded(document));
                 },
                 async index(entry) {
-                    await run(`set -e; mkdir -p "${base}/deploys"; IFS= read -r line; printf '%s\\n' "$(printf '%s' "$line" | base64 -d)" >> "${base}/deploys.jsonl"`, encoded(entry));
+                    await run('journal-index', [base], encoded(entry));
                 },
             };
         },
+        /** The attempt documents the journal keeps, oldest first. */
+        async journals() {
+            const documents = [];
+            for (const frame of (await run('journal-read', [base])).split('\n')) {
+                if (frame === '')
+                    continue;
+                try {
+                    const parsed = JSON.parse(Buffer.from(frame, 'base64').toString('utf8'));
+                    if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed))
+                        documents.push(parsed);
+                }
+                catch { /* a document that cannot be read is no evidence either way */ }
+            }
+            return documents;
+        },
         /** The stored releases, newest first: [{ id, current, previous }]. */
         async list() {
-            const response = await run(`${releasePointerScript(`"${base}"`, 'current')}; ${releasePointerScript(`"${base}"`, 'previous')}; ${releaseListScript(`"${base}"`)}`);
+            const response = await run('list', [base]);
             const [current, previous, ...entries] = response.split('\n');
             const now = isReleaseId(current) ? current : '';
             const before = isReleaseId(previous) ? previous : '';