@starci/hfs 5.1.0 → 5.2.0

package/stack/local-ports.mjs

@@ -0,0 +1,39 @@
+// local-ports.mjs - free-port checks of a dev environment and the name of whatever holds a port that is not free.
+import net from 'node:net';
+import { firstLine, lines as splitLines } from './context.mjs';
+/** True when nothing listens on the loopback `port` (a bind attempt, so a wildcard listener counts too). */
+export const bindFree = (port) => new Promise((resolve) => {
+    const server = net.createServer();
+    server.once('error', () => resolve(false));
+    server.listen(port, '127.0.0.1', () => server.close(() => resolve(true)));
+});
+/** True when something accepts a TCP connection on the loopback `port`. */
+export const tcpOpen = (port) => new Promise((resolve) => {
+    const socket = net.connect({ port, host: '127.0.0.1' });
+    socket.setTimeout(1000);
+    socket.once('connect', () => { socket.destroy(); resolve(true); });
+    socket.once('timeout', () => { socket.destroy(); resolve(false); });
+    socket.once('error', () => resolve(false));
+});
+/** What holds `port`: a docker container (by published port), else the process (netstat/tasklist on Windows, lsof elsewhere), else "an unknown process". */
+export function holderOf(ctx, port) {
+    const container = ctx.spawn('docker', ['ps', '--filter', `publish=${port}`, '--format', '{{.Names}}']);
+    const name = firstLine(container.stdout);
+    if (container.status === 0 && name)
+        return `container ${name}`;
+    if (ctx.platform === 'win32') {
+        const table = ctx.spawn('netstat', ['-ano', '-p', 'tcp']);
+        const row = splitLines(table.stdout).map((line) => line.trim().split(/\s+/u)).find((cells) => cells[3] === 'LISTENING' && cells[1]?.endsWith(`:${port}`));
+        const pid = row?.[4];
+        if (pid) {
+            const task = ctx.spawn('tasklist', ['/FI', `PID eq ${pid}`, '/FO', 'CSV', '/NH']);
+            const image = /^"([^"]+)"/u.exec(firstLine(task.stdout))?.[1];
+            return image ? `process ${image} (pid ${pid})` : `process pid ${pid}`;
+        }
+        return 'an unknown process';
+    }
+    const listing = ctx.spawn('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-Fpc']);
+    const pid = /^p(\d+)/mu.exec(listing.stdout)?.[1];
+    const command = /^c(.+)$/mu.exec(listing.stdout)?.[1];
+    return pid ? `process ${command ?? 'unknown'} (pid ${pid})` : 'an unknown process';
+}

package/stack/local-prepare.d.mts

@@ -0,0 +1,22 @@
+import type { StackContext } from './context.mjs';
+import type { ActionResult } from './remote.mjs';
+import type { LocalConfig } from './local-config.mjs';
+import type { Custody } from './local-custody.mjs';
+import type { Prerequisite } from './local-host.mjs';
+import type { LocalDeps } from './local-run.mjs';
+/** The prerequisite table of the environment as rows and printed lines. */
+export declare function preflight(ctx: StackContext, local: LocalConfig, deps: LocalDeps): Promise<{
+    rows: Prerequisite[];
+    lines: string[];
+    ok: boolean;
+}>;
+/** The refusal result of a failed preflight: the table with its owner steps, then the code. */
+export declare const hostRefusal: (lines: string[]) => ActionResult;
+/** Runs the setup commands (install, codegen); a command with `skipIfExists` that finds its marker is skipped. */
+export declare function runSetup(ctx: StackContext, local: LocalConfig, custody: Custody | null): Promise<string[]>;
+/** Builds the images that have a build context and pulls the rest. */
+export declare function prepareImages(ctx: StackContext, local: LocalConfig, custody: Custody | null): Promise<string[]>;
+/** `prepare` for a dev environment. */
+export declare function prepareLocal(ctx: StackContext, local: LocalConfig, { execute }?: {
+    execute?: boolean;
+}, deps?: LocalDeps): Promise<ActionResult>;

package/stack/local-prepare.mjs

@@ -0,0 +1,62 @@
+// local-prepare.mjs - `starci app stack prepare --env <dev env> [--execute]` (PROJECT-STACKS-6): checks the host, opens the dev custody, runs the
+// declared setup commands (install, codegen) and builds or pulls the compose images. A dry run reports the table and the plan and changes nothing.
+// It refuses on a missing prerequisite, a held port, a missing sealed value or an identity this machine lacks, and never generates a replacement.
+import fs from 'node:fs';
+import path from 'node:path';
+import { StackError } from './errors.mjs';
+import { missingKeys, missingStep, neededKeys, openCustody } from './local-custody.mjs';
+import { hostPrerequisites, tableLines } from './local-host.mjs';
+import { commandDigest, compose, composeValues, runCommand, runEnvironment, stateOf } from './local-run.mjs';
+import { readRecord, writeRecord } from './local-state.mjs';
+/** The prerequisite table of the environment as rows and printed lines. */
+export async function preflight(ctx, local, deps) {
+    const rows = await hostPrerequisites(ctx, local, { repoRoot: local.repoRoot, stateDir: stateOf(ctx, local), secretsDir: local.secretsDir }, deps);
+    return { rows, lines: tableLines(rows), ok: rows.every((row) => row.ok) };
+}
+/** The refusal result of a failed preflight: the table with its owner steps, then the code. */
+export const hostRefusal = (lines) => ({ ok: false, lines, refused: { code: 'STACK_LOCAL_HOST', message: 'this machine is missing what the environment needs; run the owner steps above, then retry' } });
+/** Runs the setup commands (install, codegen); a command with `skipIfExists` that finds its marker is skipped. */
+export async function runSetup(ctx, local, custody) {
+    const out = [];
+    const dir = stateOf(ctx, local);
+    const record = readRecord(dir);
+    for (const run of local.setup) {
+        if (run.skipIfExists && fs.existsSync(path.join(local.repoRoot, run.cwd, run.skipIfExists))) {
+            out.push(`setup ${run.name}: skipped (${run.skipIfExists} exists)`);
+            continue;
+        }
+        await runCommand(ctx, local, run, runEnvironment(ctx, local, run, custody, null));
+        record.receipts.setup[run.name] = { at: new Date(ctx.now()).toISOString(), digest: commandDigest(run) };
+        out.push(`setup ${run.name}: done`);
+    }
+    writeRecord(dir, record);
+    return out;
+}
+/** Builds the images that have a build context and pulls the rest. */
+export async function prepareImages(ctx, local, custody) {
+    const values = composeValues(local, custody);
+    const build = await compose(ctx, local, ['build'], { values, heavy: true, label: 'compose build' });
+    const pull = await compose(ctx, local, ['pull', '--ignore-buildable', '--quiet'], { values, heavy: true, label: 'compose pull' });
+    const lines = [build.status === 0 ? 'images: built' : `images: build failed (${(build.stderr.trim().split(/\r?\n/u)[0] ?? '').slice(0, 160)})`];
+    lines.push(pull.status === 0 ? 'images: pulled' : `images: pull failed (${(pull.stderr.trim().split(/\r?\n/u)[0] ?? '').slice(0, 160)})`);
+    if (build.status !== 0 || pull.status !== 0)
+        throw new StackError('STACK_LOCAL_IMAGES', lines.join('; '), 1);
+    return lines;
+}
+/** `prepare` for a dev environment. */
+export async function prepareLocal(ctx, local, { execute = false } = {}, deps = {}) {
+    const host = await preflight(ctx, local, deps);
+    if (!host.ok)
+        return hostRefusal(host.lines);
+    const lines = [...host.lines];
+    const missing = missingKeys(local);
+    lines.push(`custody: ${neededKeys(local).length} key(s) read from ${local.env}${missing.length ? `; missing ${missing.join(', ')} (${missingStep(local, missing)})` : ', all sealed'}`);
+    if (!execute) {
+        lines.push(...local.setup.map((run) => `plan setup ${run.name}: ${run.argv.join(' ')}`), 'plan images: docker compose build and pull', 'dry run: nothing was changed; arm it with --execute');
+        return { ok: missing.length === 0, lines, data: { rows: host.rows } };
+    }
+    const custody = openCustody(ctx, local);
+    lines.push(`custody: ${custody.values.size} key file(s) written to the host-local directory`);
+    lines.push(...await runSetup(ctx, local, custody), ...await prepareImages(ctx, local, custody));
+    return { ok: true, lines, data: { rows: host.rows } };
+}

package/stack/local-run.d.mts

@@ -0,0 +1,71 @@
+import type { RunResult, StackContext } from './context.mjs';
+import type { LocalConfig } from './local-config.mjs';
+import type { Custody } from './local-custody.mjs';
+import { hostTool } from './local-host.mjs';
+import type { HostDeps } from './local-host.mjs';
+import type { HttpProbe, LocalCommand } from '../runtime/scripts/hfs/stack-local-config.mjs';
+/** The seams a spec replaces besides the context's own. */
+export interface LocalDeps extends HostDeps {
+    alive?: ((pid: number) => boolean) | undefined;
+    kill?: ((pid: number) => void) | undefined;
+    tcpOpen?: ((port: number) => Promise<boolean>) | undefined;
+    migrate?: ((urlEnv: string, env: NodeJS.ProcessEnv, cwd: string) => Promise<number>) | undefined;
+}
+export declare const DEFAULT_TIMEOUT_SECONDS = 180;
+export declare const stateOf: (ctx: StackContext, local: LocalConfig) => string;
+/** The data directory of the environment under its state directory (`${data}` in a declared value, `STACK_DATA_DIR` in compose). */
+export declare const dataOf: (ctx: StackContext, local: LocalConfig) => string;
+/** Expands `${port.<name>}` and `${data}` in a declared value. */
+export declare const expand: (ctx: StackContext, local: LocalConfig, value: string) => string;
+/** Creates the declared data directories. */
+export declare function makeDataDirectories(ctx: StackContext, local: LocalConfig): void;
+/** `STACK_PORT_<NAME>` for every declared port: the names compose files interpolate (`127.0.0.1:${STACK_PORT_DB}:5432`). */
+export declare const portEnvironment: (ports: Readonly<Record<string, number>>) => Record<string, string>;
+/** `STACK_GRANT_<NAME>` for every least grant: the private directory a compose service mounts to read only its own keys. */
+export declare function grantEnvironment(ctx: StackContext, local: LocalConfig): Record<string, string>;
+/** The docker compose argv of the environment's project and files. */
+export declare const composeArgs: (local: LocalConfig, args: readonly string[]) => string[];
+/** Runs one docker compose command; `values` are the compose-interpolated custody values, passed in memory only. */
+export declare function compose(ctx: StackContext, local: LocalConfig, args: readonly string[], { values, heavy, label, input }?: {
+    values?: Record<string, string>;
+    heavy?: boolean;
+    label?: string;
+    input?: string;
+}): Promise<RunResult>;
+/** The compose-interpolated values of the environment (the keys `composeEnv` maps), from the opened custody. */
+export declare function composeValues(local: LocalConfig, custody: Custody | null): Record<string, string>;
+/** The environment a command or process runs with: ports expanded, custody as `<KEY>_FILE`, the database URL as the environment declares. */
+export declare function runEnvironment(ctx: StackContext, local: LocalConfig, run: LocalCommand, custody: Custody | null, role: 'owner' | 'app' | null): NodeJS.ProcessEnv;
+/** The loopback connection string of the environment's own database role, built in memory from custody. */
+export declare function databaseUrl(local: LocalConfig, custody: Custody, role?: 'owner' | 'app'): string | null;
+/** Runs one setup or seed command to its end, through the governor when its class is heavy. A non-zero exit is a failure naming the command and its first error line. */
+export declare function runCommand(ctx: StackContext, local: LocalConfig, run: LocalCommand, env: NodeJS.ProcessEnv): Promise<void>;
+/** The digest of a command's argv and cwd: the key of its receipt. */
+export declare const commandDigest: (run: LocalCommand) => string;
+/** True when `pid` is alive. */
+export declare const isAlive: (pid: number) => boolean;
+/** Starts a native process detached from this command, its output in the environment's log. Returns the pid. */
+export declare function startProcess(ctx: StackContext, local: LocalConfig, run: LocalCommand, env: NodeJS.ProcessEnv): number;
+/** Ends a native process and its children. */
+export declare function stopProcess(ctx: Pick<StackContext, 'spawn' | 'platform'>, pid: number, deps?: LocalDeps): void;
+/** One HTTP probe against its expanded URL; the verdict and a detail line. */
+export declare function probe(ctx: StackContext, local: LocalConfig, row: HttpProbe): Promise<{
+    ok: boolean;
+    detail: string;
+}>;
+/** Polls a probe until it passes or the deadline passes. */
+export declare function waitFor(ctx: StackContext, deadline: number, attempt: () => Promise<{
+    ok: boolean;
+    detail: string;
+}>): Promise<{
+    ok: boolean;
+    detail: string;
+}>;
+/** The per-service readiness the environment declares: compose health, an open port, or just started. */
+export declare function serviceReady(ctx: StackContext, local: LocalConfig, name: string, deadline: number, deps?: LocalDeps): Promise<{
+    ok: boolean;
+    detail: string;
+}>;
+/** Masks the value of anything that reads like a credential assignment, so a log tail never carries one. */
+export declare const redact: (line: string) => string;
+export { hostTool };

package/stack/local-run.mjs

@@ -0,0 +1,200 @@
+// local-run.mjs - what the dev verbs share: the compose command line of an environment, governed heavy runs, native process control,
+// HTTP probes and the redaction of logs. Nothing here prints a value; every command is an argv list run without a shell.
+import fs from 'node:fs';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { firstLine } from './context.mjs';
+import { materializedDirectory } from '../runtime/scripts/hfs/secret-files.mjs';
+import { failure, refusal } from './errors.mjs';
+import { fileEnvironment, grantDirectory } from './local-custody.mjs';
+import { hostTool, launch } from './local-host.mjs';
+import { tcpOpen } from './local-ports.mjs';
+import { logFile, stateDirectory } from './local-state.mjs';
+import { expandPorts } from '../runtime/scripts/hfs/stack-local-config.mjs';
+export const DEFAULT_TIMEOUT_SECONDS = 180;
+export const stateOf = (ctx, local) => stateDirectory(ctx.env, local.project, local.env);
+/** The data directory of the environment under its state directory (`${data}` in a declared value, `STACK_DATA_DIR` in compose). */
+export const dataOf = (ctx, local) => path.join(stateOf(ctx, local), 'data');
+/** Expands `${port.<name>}` and `${data}` in a declared value. */
+export const expand = (ctx, local, value) => expandPorts(value, local.ports).replaceAll('${data}', dataOf(ctx, local).replaceAll('\\', '/'));
+/** Creates the declared data directories. */
+export function makeDataDirectories(ctx, local) {
+    for (const name of local.dirs)
+        fs.mkdirSync(path.join(dataOf(ctx, local), name), { recursive: true });
+}
+/** `STACK_PORT_<NAME>` for every declared port: the names compose files interpolate (`127.0.0.1:${STACK_PORT_DB}:5432`). */
+export const portEnvironment = (ports) => Object.fromEntries(Object.entries(ports).map(([name, port]) => [`STACK_PORT_${name.toUpperCase().replaceAll('-', '_')}`, String(port)]));
+/** `STACK_GRANT_<NAME>` for every least grant: the private directory a compose service mounts to read only its own keys. */
+export function grantEnvironment(ctx, local) {
+    if (local.grants.length === 0)
+        return {};
+    const directory = materializedDirectory(local.repoRoot, local.env, ctx.env, ctx.platform);
+    return Object.fromEntries(local.grants.map((grant) => [`STACK_GRANT_${grant.name.toUpperCase().replaceAll('-', '_')}`, grantDirectory(directory, grant.name).replaceAll('\\', '/')]));
+}
+/** The docker compose argv of the environment's project and files. */
+export const composeArgs = (local, args) => ['compose', '-p', local.project, ...local.composeFiles.flatMap((file) => ['-f', file]), ...args];
+/** Runs one docker compose command; `values` are the compose-interpolated custody values, passed in memory only. */
+export async function compose(ctx, local, args, { values = {}, heavy = false, label = `compose ${args[0]}`, input } = {}) {
+    const bare = local.composeEnv.filter((item) => !Object.hasOwn(values, item.name)).map((item) => item.name);
+    // A command that creates or enters a container needs the real values; the others only interpolate the file, where a placeholder does.
+    if (bare.length && ['up', 'exec', 'run', 'create', 'start', 'restart'].includes(String(args[0])))
+        throw refusal('STACK_LOCAL_COMPOSE_VALUES', `docker compose ${String(args[0])} needs the custody values of ${bare.join(', ')}`);
+    const env = { ...ctx.env, ...portEnvironment(local.ports), ...grantEnvironment(ctx, local), STACK_DATA_DIR: dataOf(ctx, local).replaceAll('\\', '/'), ...Object.fromEntries(bare.map((name) => [name, 'placeholder'])), ...values };
+    const argv = composeArgs(local, args);
+    if (heavy && ctx.heavy)
+        return ctx.heavy({ kind: 'build', label: `${local.project} ${label}`, cwd: local.repoRoot, argv: ['docker', ...argv], env });
+    return ctx.spawn('docker', argv, { cwd: local.repoRoot, env, ...(input === undefined ? {} : { input }) });
+}
+/** The compose-interpolated values of the environment (the keys `composeEnv` maps), from the opened custody. */
+export function composeValues(local, custody) {
+    const values = {};
+    for (const item of local.composeEnv) {
+        const value = custody?.values.get(item.key);
+        if (value !== undefined)
+            values[item.name] = value;
+    }
+    return values;
+}
+/** The environment a command or process runs with: ports expanded, custody as `<KEY>_FILE`, the database URL as the environment declares. */
+export function runEnvironment(ctx, local, run, custody, role) {
+    const env = { ...ctx.env, ...portEnvironment(local.ports) };
+    for (const [key, value] of Object.entries(run.env))
+        env[key] = expand(ctx, local, value);
+    if (custody)
+        Object.assign(env, fileEnvironment(custody, run.files));
+    const url = custody && role ? databaseUrl(local, custody, role) : null;
+    if (local.database && url !== null && custody) {
+        if (local.database.urlAs === 'env')
+            env[local.database.urlEnv] = url;
+        else {
+            const file = path.join(custody.directory, local.database.urlEnv);
+            fs.writeFileSync(file, url, { mode: 0o600 });
+            env[`${local.database.urlEnv}_FILE`] = file;
+        }
+    }
+    return env;
+}
+/** The loopback connection string of the environment's own database role, built in memory from custody. */
+export function databaseUrl(local, custody, role = 'owner') {
+    const database = local.database;
+    if (!database)
+        return null;
+    const app = role === 'app' && database.appRole !== null && database.appPassword !== null;
+    const user = app ? database.appRole : database.role;
+    const password = custody.values.get(app ? database.appPassword.key : database.password.key);
+    if (!password)
+        return null;
+    return `postgresql://${user}:${encodeURIComponent(password)}@127.0.0.1:${local.ports[database.port]}/${database.name}`;
+}
+const launcher = (ctx, argv) => launch(ctx.platform, argv[0] ?? '', argv.slice(1));
+/** Runs one setup or seed command to its end, through the governor when its class is heavy. A non-zero exit is a failure naming the command and its first error line. */
+export async function runCommand(ctx, local, run, env) {
+    const cwd = path.join(local.repoRoot, run.cwd);
+    const [command, args] = launcher(ctx, run.argv.map((part) => expand(ctx, local, part)));
+    const result = run.heavy !== 'none' && ctx.heavy
+        ? await ctx.heavy({ kind: run.heavy, label: `${local.project} ${run.name}`, cwd, argv: [command, ...args], env })
+        : ctx.spawn(command, args, { cwd, env });
+    if (result.error || result.status !== 0)
+        throw failure('STACK_LOCAL_COMMAND', `${run.name} (${run.argv.join(' ')}) failed: ${firstLine(result.stderr) || firstLine(result.stdout) || result.error?.message || `exit ${result.status}`}`);
+}
+/** The digest of a command's argv and cwd: the key of its receipt. */
+export const commandDigest = (run) => createHash('sha256').update(JSON.stringify([run.argv, run.cwd, run.env])).digest('hex').slice(0, 16);
+/** True when `pid` is alive. */
+export const isAlive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+};
+/** Starts a native process detached from this command, its output in the environment's log. Returns the pid. */
+export function startProcess(ctx, local, run, env) {
+    const dir = stateOf(ctx, local);
+    const log = logFile(dir, run.name);
+    fs.mkdirSync(path.dirname(log), { recursive: true });
+    const descriptor = fs.openSync(log, 'a');
+    try {
+        const [command, args] = launcher(ctx, run.argv.map((part) => expand(ctx, local, part)));
+        const child = ctx.spawn(command, args, { background: true, detached: true, cwd: path.join(local.repoRoot, run.cwd), env, stdio: ['ignore', descriptor, descriptor], windowsHide: true });
+        const pid = child.pid;
+        if (typeof pid !== 'number')
+            throw failure('STACK_LOCAL_COMMAND', `${run.name} did not start: ${child.spawnError?.message ?? 'no process id'}`);
+        child.unref?.();
+        return pid;
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+}
+/** Ends a native process and its children. */
+export function stopProcess(ctx, pid, deps = {}) {
+    if (deps.kill) {
+        deps.kill(pid);
+        return;
+    }
+    if (ctx.platform === 'win32') {
+        ctx.spawn('taskkill', ['/PID', String(pid), '/T', '/F']);
+        return;
+    }
+    try {
+        process.kill(-pid, 'SIGTERM');
+    }
+    catch {
+        try {
+            process.kill(pid, 'SIGTERM');
+        }
+        catch { /* already gone */ }
+    }
+}
+/** One HTTP probe against its expanded URL; the verdict and a detail line. */
+export async function probe(ctx, local, row) {
+    const url = expand(ctx, local, row.url);
+    try {
+        const response = await ctx.fetch(url, { method: row.method, redirect: 'manual', signal: AbortSignal.timeout(5000) });
+        if (response.status !== row.status)
+            return { ok: false, detail: `${row.name}: ${url} answered ${response.status}, ${row.status} expected` };
+        if (row.contains !== null && !(await response.text()).includes(row.contains))
+            return { ok: false, detail: `${row.name}: ${url} answered without the expected text` };
+        return { ok: true, detail: `${row.name}: ${url} answered ${response.status}` };
+    }
+    catch (error) {
+        return { ok: false, detail: `${row.name}: ${url} does not answer (${error.message})` };
+    }
+}
+/** Polls a probe until it passes or the deadline passes. */
+export async function waitFor(ctx, deadline, attempt) {
+    let last = await attempt();
+    while (!last.ok && ctx.now() < deadline) {
+        await ctx.sleep(1000);
+        last = await attempt();
+    }
+    return last;
+}
+/** The per-service readiness the environment declares: compose health, an open port, or just started. */
+export async function serviceReady(ctx, local, name, deadline, deps = {}) {
+    const service = local.services.find((item) => item.name === name);
+    if (!service)
+        return { ok: false, detail: `${name} is not a declared service` };
+    return waitFor(ctx, deadline, async () => {
+        const ids = await compose(ctx, local, ['ps', '-q', name]);
+        const id = firstLine(ids.stdout);
+        if (!id)
+            return { ok: false, detail: `${name}: no container` };
+        if (service.wait === 'tcp')
+            return (await (deps.tcpOpen ?? tcpOpen)(local.ports[service.port])) ? { ok: true, detail: `${name}: port ${local.ports[service.port]} accepts` } : { ok: false, detail: `${name}: port ${local.ports[service.port]} does not accept yet` };
+        const inspected = ctx.spawn('docker', ['inspect', '-f', '{{.State.Status}} {{if .State.Health}}{{.State.Health.Status}}{{else}}nohealth{{end}}', id]);
+        const [state, health] = firstLine(inspected.stdout).split(' ');
+        if (state !== 'running')
+            return { ok: false, detail: `${name}: ${state ?? 'unknown'}` };
+        if (service.wait === 'started')
+            return { ok: true, detail: `${name}: running` };
+        if (health === 'nohealth')
+            throw refusal('STACK_LOCAL_NO_HEALTHCHECK', `${name} declares wait: healthy but its compose service has no healthcheck: add one to the compose file, or declare wait: tcp or started`);
+        return health === 'healthy' ? { ok: true, detail: `${name}: healthy` } : { ok: false, detail: `${name}: ${health}` };
+    });
+}
+/** Masks the value of anything that reads like a credential assignment, so a log tail never carries one. */
+export const redact = (line) => line.replaceAll(/((?:pass(?:word)?|secret|token|credential|private[_-]?key|api[_-]?key|authorization)[\w-]*["']?\s*[=:]\s*(?:Bearer\s+)?)[^\s"',;]+/giu, '$1[redacted]');
+export { hostTool };

package/stack/local-state.d.mts

@@ -0,0 +1,35 @@
+/** What the environment recorded about itself. */
+export interface LocalRecord {
+    processes: Record<string, {
+        pid: number;
+        startedAt: string;
+        port: number | null;
+    }>;
+    ports: Record<string, number>;
+    receipts: {
+        migrate?: {
+            at: string;
+            digest: string;
+        };
+        seed: Record<string, {
+            at: string;
+            digest: string;
+        }>;
+        setup: Record<string, {
+            at: string;
+            digest: string;
+        }>;
+        database?: {
+            at: string;
+            role: string;
+        };
+    };
+}
+/** The directory of one environment's state: `<state base>/stack/<project>/<env>`. */
+export declare const stateDirectory: (env: NodeJS.ProcessEnv, project: string, environment: string) => string;
+/** The log file of one process or service. */
+export declare const logFile: (dir: string, name: string) => string;
+/** Reads the record; an absent or damaged file is an empty record (the environment then reads as not started). */
+export declare function readRecord(dir: string): LocalRecord;
+/** Writes the record atomically; it holds ids, ports and digests, never a value. */
+export declare function writeRecord(dir: string, record: LocalRecord): void;

package/stack/local-state.mjs

@@ -0,0 +1,29 @@
+// local-state.mjs - where a dev environment keeps what it started: process ids, logs and receipts, under the per-host state base
+// (STARCI_LOCAL_ROOT, else the runtime's .runtime), never in the app's checkout (README "Harness state lives in the runtime").
+import fs from 'node:fs';
+import path from 'node:path';
+import { starciLocalRoot } from '../runtime/engine/runtime-root.mjs';
+const empty = () => ({ processes: {}, ports: {}, receipts: { seed: {}, setup: {} } });
+/** The directory of one environment's state: `<state base>/stack/<project>/<env>`. */
+export const stateDirectory = (env, project, environment) => path.join(starciLocalRoot(env), 'stack', project, environment);
+/** The log file of one process or service. */
+export const logFile = (dir, name) => path.join(dir, 'logs', `${name}.log`);
+/** Reads the record; an absent or damaged file is an empty record (the environment then reads as not started). */
+export function readRecord(dir) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(dir, 'state.json'), 'utf8'));
+        const base = empty();
+        return { processes: parsed.processes ?? base.processes, ports: parsed.ports ?? base.ports, receipts: { ...base.receipts, ...parsed.receipts } };
+    }
+    catch {
+        return empty();
+    }
+}
+/** Writes the record atomically; it holds ids, ports and digests, never a value. */
+export function writeRecord(dir, record) {
+    fs.mkdirSync(path.join(dir, 'logs'), { recursive: true });
+    const target = path.join(dir, 'state.json');
+    const temporary = `${target}.${process.pid}.tmp`;
+    fs.writeFileSync(temporary, `${JSON.stringify(record, null, 2)}\n`);
+    fs.renameSync(temporary, target);
+}

package/stack/local-status.d.mts

@@ -0,0 +1,6 @@
+import type { StackContext } from './context.mjs';
+import type { ActionResult } from './remote.mjs';
+import type { LocalConfig } from './local-config.mjs';
+import type { LocalDeps } from './local-run.mjs';
+/** `status` for a dev environment. */
+export declare function statusLocal(ctx: StackContext, local: LocalConfig, _options?: Record<string, unknown>, deps?: LocalDeps): Promise<ActionResult>;

package/stack/local-status.mjs

@@ -0,0 +1,36 @@
+import { firstLine } from './context.mjs';
+import { migrationsDigest } from './local-up.mjs';
+import { compose, isAlive, probe, stateOf } from './local-run.mjs';
+import { readRecord } from './local-state.mjs';
+/** `status` for a dev environment. */
+export async function statusLocal(ctx, local, _options = {}, deps = {}) {
+    const record = readRecord(stateOf(ctx, local));
+    const lines = [];
+    let ok = true;
+    const mark = (good, text) => { ok &&= good; lines.push(`${good ? 'ok    ' : 'FAIL  '}${text}`); };
+    for (const service of local.services) {
+        const id = firstLine((await compose(ctx, local, ['ps', '-q', service.name])).stdout);
+        if (!id) {
+            mark(false, `service ${service.name}: not created`);
+            continue;
+        }
+        const inspected = ctx.spawn('docker', ['inspect', '-f', '{{.State.Status}} {{if .State.Health}}{{.State.Health.Status}}{{else}}nohealth{{end}}', id]);
+        const [state, health] = firstLine(inspected.stdout).split(' ');
+        mark(state === 'running' && (service.wait !== 'healthy' || health === 'healthy'), `service ${service.name}: ${state}${health === 'nohealth' ? '' : `, ${health}`}`);
+    }
+    const alive = deps.alive ?? isAlive;
+    for (const run of local.processes) {
+        const entry = record.processes[run.name];
+        mark(entry !== undefined && alive(entry.pid), entry ? `process ${run.name}: pid ${entry.pid} ${alive(entry.pid) ? 'alive' : 'gone'}` : `process ${run.name}: not started`);
+    }
+    if (local.database) {
+        const receipt = record.receipts.migrate;
+        const current = migrationsDigest(local.repoRoot);
+        mark(receipt?.digest === current, receipt ? `migrations: receipt ${receipt.digest} ${receipt.digest === current ? 'is current' : `is stale, the folder is ${current}`}` : 'migrations: no receipt');
+    }
+    for (const row of local.ready) {
+        const result = await probe(ctx, local, row);
+        mark(result.ok, `ready ${result.detail}`);
+    }
+    return { ok, lines, data: { processes: record.processes } };
+}

package/stack/local-up.d.mts

@@ -0,0 +1,11 @@
+import type { StackContext } from './context.mjs';
+import type { ActionResult } from './remote.mjs';
+import type { LocalConfig } from './local-config.mjs';
+import type { LocalDeps } from './local-run.mjs';
+/** The digest of the migration folder (names and contents): what a migrate receipt records. */
+export declare function migrationsDigest(repoRoot: string): string;
+/** `up` for a dev environment. */
+export declare function upLocal(ctx: StackContext, local: LocalConfig, { execute, timeoutSeconds }?: {
+    execute?: boolean;
+    timeoutSeconds?: number;
+}, deps?: LocalDeps): Promise<ActionResult>;