@starci/hfs 5.1.0 → 5.3.0

package/stack/local-host.mjs

@@ -0,0 +1,163 @@
+// local-host.mjs - the host prerequisites of a dev environment, one row each: what is needed, whether this machine has it, and the exact
+// install step the owner runs when it does not (winget on Windows, brew on macOS, apt on Linux). Read-only: it probes tools through the spawn
+// seam, reads sizes and the app's declared ports, and installs nothing (rules.md rules 5 and 8; the owner runs the printed steps).
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { firstLine } from './context.mjs';
+import { bindFree, holderOf } from './local-ports.mjs';
+import { readRecord } from './local-state.mjs';
+const INSTALL = {
+    node: { win32: 'winget install OpenJS.NodeJS.LTS', darwin: 'brew install node', linux: 'sudo apt install nodejs npm, or nvm install <version>' },
+    npm: { win32: 'winget install OpenJS.NodeJS.LTS (npm ships with Node)', darwin: 'brew install node (npm ships with Node)', linux: 'sudo apt install npm' },
+    git: { win32: 'winget install Git.Git', darwin: 'brew install git', linux: 'sudo apt install git' },
+    docker: { win32: 'winget install Docker.DockerDesktop, then start Docker Desktop and wait for the engine', darwin: 'brew install --cask docker, then open Docker', linux: 'sudo apt install docker.io, then sudo systemctl enable --now docker and add your user to the docker group' },
+    compose: { win32: 'update Docker Desktop (it ships Compose v2): winget upgrade Docker.DockerDesktop', darwin: 'brew upgrade --cask docker', linux: 'sudo apt install docker-compose-v2' },
+    wsl: { win32: 'wsl --install (an administrator terminal), then restart', darwin: 'not needed', linux: 'not needed' },
+    sops: { win32: 'winget install Mozilla.SOPS', darwin: 'brew install sops', linux: 'download the sops release for your CPU from https://github.com/getsops/sops/releases and put it on PATH' },
+    age: { win32: 'winget install FiloSottile.age', darwin: 'brew install age', linux: 'sudo apt install age' },
+};
+const platformOf = (ctx) => (ctx.platform === 'win32' || ctx.platform === 'darwin' ? ctx.platform : 'linux');
+const NPM_SHIMS = new Set(['npm', 'npx']);
+/**
+ * How to start `command` on this platform without a shell. npm and npx are `.cmd` shims on Windows, which cannot be spawned directly: they run as
+ * `node <npm-cli.js>` from the Node install beside this node when it is there, else through `cmd.exe /d /s /c`.
+ */
+export function launch(platform, command, args, exists = fs.existsSync) {
+    if (platform !== 'win32' || !NPM_SHIMS.has(command))
+        return [command, [...args]];
+    const cli = path.join(path.dirname(process.execPath), 'node_modules', 'npm', 'bin', `${command}-cli.js`);
+    return exists(cli) ? [process.execPath, [cli, ...args]] : ['cmd.exe', ['/d', '/s', '/c', command, ...args]];
+}
+/** Runs a host tool without a shell (see launch). */
+export function hostTool(ctx, command, args, options = {}) {
+    const [file, argv] = launch(ctx.platform, command, args);
+    return ctx.spawn(file, argv, options);
+}
+const present = (run) => run.error === undefined && run.status === 0;
+const versionOf = (text) => /(\d+)\.(\d+)(?:\.(\d+))?/u.exec(text)?.[0] ?? null;
+const wantedOf = (text) => /\d+(?:\.\d+){0,2}/u.exec(text)?.[0] ?? null;
+const atLeast = (have, need) => {
+    const [a = 0, b = 0, c = 0] = have.split('.').map(Number);
+    const [x = 0, y = 0, z = 0] = need.split('.').map(Number);
+    if (a !== x)
+        return a > x;
+    return b !== y ? b > y : c >= z;
+};
+/** The Node version the app asks for: `.nvmrc`, else the first version of `engines.node`; null when it asks for none. */
+export function wantedNode(repoRoot) {
+    try {
+        return wantedOf(fs.readFileSync(path.join(repoRoot, '.nvmrc'), 'utf8'));
+    }
+    catch { /* no .nvmrc */ }
+    try {
+        return wantedOf(String(JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8')).engines?.node ?? ''));
+    }
+    catch {
+        return null;
+    }
+}
+const diskFree = (dir) => {
+    let at = dir;
+    while (!fs.existsSync(at) && path.dirname(at) !== at)
+        at = path.dirname(at);
+    try {
+        const stat = fs.statfsSync(at);
+        return Math.floor((stat.bavail * stat.bsize) / 1024 ** 3);
+    }
+    catch {
+        return null;
+    }
+};
+function tool(ctx, id, row) {
+    const run = hostTool(ctx, row.command, row.args);
+    if (!present(run))
+        return { id, ok: false, detail: `${row.label} not found on PATH`, fix: INSTALL[id]?.[platformOf(ctx)] ?? null };
+    return { id, ok: true, detail: `${row.label} ${versionOf(`${run.stdout} ${run.stderr}`) ?? firstLine(run.stdout)}`, fix: null };
+}
+function docker(ctx) {
+    const platform = platformOf(ctx);
+    const cli = hostTool(ctx, 'docker', ['--version']);
+    if (!present(cli))
+        return [{ id: 'docker', ok: false, detail: 'docker not found on PATH', fix: INSTALL.docker?.[platform] ?? null }, { id: 'compose', ok: false, detail: 'needs docker first', fix: INSTALL.compose?.[platform] ?? null }];
+    const info = ctx.spawn('docker', ['info', '--format', '{{.ServerVersion}} {{.OSType}}']);
+    const [server, kind] = firstLine(info.stdout).split(' ');
+    const rows = [];
+    if (!present(info) || !server)
+        rows.push({ id: 'docker', ok: false, detail: 'the docker engine does not answer', fix: platform === 'linux' ? 'sudo systemctl start docker' : 'start Docker Desktop and wait until it reports the engine running' });
+    else if (kind !== 'linux')
+        rows.push({ id: 'docker', ok: false, detail: `docker serves ${kind} containers`, fix: 'switch Docker Desktop to Linux containers' });
+    else
+        rows.push({ id: 'docker', ok: true, detail: `docker engine ${server} (linux containers)`, fix: null });
+    const compose = ctx.spawn('docker', ['compose', 'version', '--short']);
+    const have = versionOf(compose.stdout);
+    if (!present(compose) || !have)
+        rows.push({ id: 'compose', ok: false, detail: 'docker compose v2 not found', fix: INSTALL.compose?.[platform] ?? null });
+    else if (!atLeast(have, '2.20'))
+        rows.push({ id: 'compose', ok: false, detail: `docker compose ${have} found, 2.20 or newer wanted`, fix: INSTALL.compose?.[platform] ?? null });
+    else
+        rows.push({ id: 'compose', ok: true, detail: `docker compose ${have}`, fix: null });
+    return rows;
+}
+/** True when the environment's secrets folder holds a sealed member. */
+export const hasSealedMembers = (secretsDir) => {
+    try {
+        return fs.readdirSync(secretsDir).some((name) => /\.enc(\.yaml)?$/u.test(name));
+    }
+    catch {
+        return false;
+    }
+};
+/** One row per declared port: free, or held by this environment's own record, or held by someone else (named). */
+export async function portRows(ctx, local, stateDir, deps = {}) {
+    const free = deps.portFree ?? bindFree;
+    const own = new Set(Object.values(readRecord(stateDir).ports));
+    const rows = [];
+    for (const [name, port] of Object.entries(local.ports)) {
+        if (await free(port))
+            rows.push({ id: `port ${name}`, ok: true, detail: `${port} is free`, fix: null });
+        else if (own.has(port))
+            rows.push({ id: `port ${name}`, ok: true, detail: `${port} is held by this environment`, fix: null });
+        else if (holderOf(ctx, port).startsWith(`container ${local.project}-`))
+            rows.push({ id: `port ${name}`, ok: true, detail: `${port} is held by this environment's container`, fix: null });
+        else
+            rows.push({ id: `port ${name}`, ok: false, detail: `${port} is held by ${holderOf(ctx, port)}`, fix: `stop that holder, or change ports.${name} in .starcistacks/application-stacks.yaml` });
+    }
+    return rows;
+}
+function nodeRow(ctx, repoRoot) {
+    const want = wantedNode(repoRoot);
+    const node = ctx.spawn('node', ['--version']);
+    const have = versionOf(node.stdout);
+    if (present(node) && have && (!want || atLeast(have, want)))
+        return { id: 'node', ok: true, detail: `node ${have}${want ? ` (the app wants ${want} or newer)` : ''}`, fix: null };
+    return { id: 'node', ok: false, detail: present(node) ? `node ${have} found, ${want} or newer wanted by .nvmrc or engines.node` : 'node not found on PATH', fix: INSTALL.node?.[platformOf(ctx)] ?? null };
+}
+function resourceRows(local, stateDir, deps) {
+    const disk = (deps.diskFreeGb ?? diskFree)(stateDir);
+    const memory = (deps.memoryMb ?? (() => ({ free: Math.floor(os.freemem() / 1024 ** 2), total: Math.floor(os.totalmem() / 1024 ** 2) })))();
+    return [
+        disk === null || disk >= local.resources.diskGb
+            ? { id: 'disk', ok: true, detail: disk === null ? 'free disk not readable here' : `${disk} GB free (${local.resources.diskGb} GB wanted)`, fix: null }
+            : { id: 'disk', ok: false, detail: `${disk} GB free, ${local.resources.diskGb} GB wanted`, fix: 'free disk space, or prune unused images with docker image prune (an owner step)' },
+        memory.total >= local.resources.ramMb
+            ? { id: 'memory', ok: true, detail: `${memory.total} MB RAM (${memory.free} MB free, ${local.resources.ramMb} MB wanted)`, fix: null }
+            : { id: 'memory', ok: false, detail: `${memory.total} MB RAM, ${local.resources.ramMb} MB wanted`, fix: 'close other work or use a machine with more memory' },
+    ];
+}
+/** The whole table for one environment: tools, engine, resources, then the declared ports. */
+export async function hostPrerequisites(ctx, local, where, deps = {}) {
+    const rows = [nodeRow(ctx, where.repoRoot), tool(ctx, 'npm', { command: 'npm', args: ['--version'], label: 'npm' }), tool(ctx, 'git', { command: 'git', args: ['--version'], label: 'git' }), ...docker(ctx)];
+    if (ctx.platform === 'win32') {
+        const wsl = ctx.spawn('wsl.exe', ['--status']);
+        rows.push(present(wsl) ? { id: 'wsl', ok: true, detail: 'WSL2 is installed', fix: null } : { id: 'wsl', ok: false, detail: 'WSL2 is not available (Docker Desktop runs Linux containers on it)', fix: INSTALL.wsl?.win32 ?? null });
+    }
+    if (hasSealedMembers(where.secretsDir))
+        rows.push(tool(ctx, 'sops', { command: 'sops', args: ['--version'], label: 'sops' }), tool(ctx, 'age', { command: 'age', args: ['--version'], label: 'age' }));
+    rows.push(...resourceRows(local, where.stateDir, deps), ...await portRows(ctx, local, where.stateDir, deps));
+    return rows;
+}
+/** The table as printed lines: `ok    ` and `FAIL  ` rows, each failure followed by its owner-run step. */
+export function tableLines(rows) {
+    return rows.flatMap((row) => [`${row.ok ? 'ok    ' : 'FAIL  '}${row.id}: ${row.detail}`, ...(row.ok || !row.fix ? [] : [`      owner step: ${row.fix}`])]);
+}

package/stack/local-logs.d.mts

@@ -0,0 +1,8 @@
+import type { StackContext } from './context.mjs';
+import type { ActionResult } from './remote.mjs';
+import type { LocalConfig } from './local-config.mjs';
+/** `logs` for a dev environment. */
+export declare function logsLocal(ctx: StackContext, local: LocalConfig, { service, lines }?: {
+    service?: string | undefined;
+    lines?: number;
+}): Promise<ActionResult>;

package/stack/local-logs.mjs

@@ -0,0 +1,32 @@
+// local-logs.mjs - `starci app stack logs --env <dev env> --service <name> [--lines N]` (PROJECT-STACKS-6): one named process or compose service,
+// bounded in lines, redacted; never the environment or the credentials.
+import fs from 'node:fs';
+import { lines as splitLines } from './context.mjs';
+import { refusal } from './errors.mjs';
+import { compose, redact, stateOf } from './local-run.mjs';
+import { logFile } from './local-state.mjs';
+const DEFAULT_LINES = 200;
+const MAX_LINES = 2000;
+/** `logs` for a dev environment. */
+export async function logsLocal(ctx, local, { service, lines = DEFAULT_LINES } = {}) {
+    if (!service)
+        throw refusal('STACK_LOCAL_LOGS_SERVICE', `name one process or service with --service: ${[...local.processes.map((run) => run.name), ...local.services.map((item) => item.name)].join(', ')}`);
+    if (!Number.isInteger(lines) || lines < 1 || lines > MAX_LINES)
+        throw refusal('STACK_LOCAL_LOGS_LINES', `--lines is a whole number from 1 to ${MAX_LINES}`);
+    let text;
+    if (local.processes.some((run) => run.name === service)) {
+        try {
+            text = fs.readFileSync(logFile(stateOf(ctx, local), service), 'utf8');
+        }
+        catch {
+            text = '';
+        }
+    }
+    else if (local.services.some((item) => item.name === service)) {
+        text = (await compose(ctx, local, ['logs', '--no-color', '--tail', String(lines), service])).stdout;
+    }
+    else
+        throw refusal('STACK_LOCAL_LOGS_SERVICE', `${service} is neither a process nor a service of ${local.env}`);
+    const tail = splitLines(text).slice(-lines).map(redact);
+    return { ok: true, lines: tail.length ? tail : [`${service}: no log lines yet`], data: { service, count: tail.length } };
+}

package/stack/local-ports.d.mts

@@ -0,0 +1,7 @@
+import type { StackContext } from './context.mjs';
+/** True when nothing listens on the loopback `port` (a bind attempt, so a wildcard listener counts too). */
+export declare const bindFree: (port: number) => Promise<boolean>;
+/** True when something accepts a TCP connection on the loopback `port`. */
+export declare const tcpOpen: (port: number) => Promise<boolean>;
+/** What holds `port`: a docker container (by published port), else the process (netstat/tasklist on Windows, lsof elsewhere), else "an unknown process". */
+export declare function holderOf(ctx: Pick<StackContext, 'spawn' | 'platform'>, port: number): string;

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 };