@starci/hfs 5.1.0 → 5.3.0

package/stack/images/openclaw-runtime/openclaw-init.mjs

@@ -0,0 +1,101 @@
+// Writes the gateway settings the StarCi runtime layer relies on into openclaw.json before the gateway starts (idempotent merge: other keys,
+// agents and plugins that OpenClaw or an operator added are kept). Loopback bind + token auth: the gateway is reached only through the relay.
+//
+// The contract an app image relies on (images/README.md "The OpenClaw runtime layer"):
+//   STARCI_PLUGINS_DIR   the plugin directory (default /opt/starci/plugins): every subfolder holding an openclaw.plugin.json is added to
+//                        plugins.load.paths and enabled as plugins.entries.<folder name>
+//   AI_BASE_URL + STARCI_AI_KEY  one OpenAI-compatible custom provider (name OPENCLAW_PROVIDER, default "starci-ai"; chat model AI_CHAT_MODEL,
+//                        default "work"); the key stays a reference openclaw resolves from the gateway process environment
+//   OPENCLAW_MODEL       the primary model of the agents; OPENCLAW_MODEL_REASONING=off switches the model's reasoning off
+import fs from "node:fs"
+import path from "node:path"
+
+const file = "/home/node/.openclaw/openclaw.json"
+let config = {}
+try {
+    config = JSON.parse(fs.readFileSync(file, "utf8"))
+} catch {
+    config = {}
+}
+// The app writes each agent workspace itself: no first-run ritual.
+config.agents = config.agents || {}
+config.agents.defaults = { ...(config.agents.defaults || {}), skipBootstrap: true }
+// The app owns every trigger and schedule: OpenClaw runs one turn when asked and nothing in the background. `cron.enabled: false` stops its cron
+// scheduler; a `defaults.heartbeat` block makes every agent resolve its heartbeat from it, and `every: "0m"` gives each no interval.
+config.cron = { ...(config.cron || {}), enabled: false }
+config.agents.defaults.heartbeat = { ...(config.agents.defaults.heartbeat || {}), every: "0m" }
+// Plugins: every folder of the plugin directory that holds an openclaw.plugin.json is loaded and enabled; other paths and entries are kept.
+const pluginsDir = process.env.STARCI_PLUGINS_DIR || "/opt/starci/plugins"
+const found = fs.existsSync(pluginsDir)
+    ? fs.readdirSync(pluginsDir, { withFileTypes: true })
+          .filter((entry) => entry.isDirectory() && fs.existsSync(path.join(pluginsDir, entry.name, "openclaw.plugin.json")))
+          .map((entry) => entry.name)
+          .sort()
+    : []
+const plugins = config.plugins || {}
+const load = plugins.load || {}
+const paths = Array.isArray(load.paths) ? load.paths : []
+const entries = { ...(plugins.entries || {}) }
+for (const name of found) entries[name] = { ...(entries[name] || {}), enabled: true }
+config.plugins = {
+    ...plugins,
+    load: { ...load, paths: [...paths, ...found.map((name) => path.join(pluginsDir, name)).filter((folder) => !paths.includes(folder))] },
+    entries,
+}
+config.session = {
+    ...(config.session || {}),
+    maintenance: {
+        ...((config.session || {}).maintenance || {}),
+        mode: "enforce",
+        pruneAfter: "7d",
+        maxEntries: 400,
+        maxDiskBytes: "400mb",
+    },
+}
+config.gateway = {
+    ...(config.gateway || {}),
+    mode: "local",
+    bind: "loopback",
+    port: 18789,
+    auth: {
+        ...((config.gateway || {}).auth || {}),
+        mode: "token",
+        token: fs.readFileSync(process.env.OPENCLAW_GATEWAY_TOKEN_FILE, "utf8"),
+    },
+}
+// Language models come only from the AI gateway the app hosts: one OpenAI-compatible custom provider with the virtual key it shares with the app.
+if (process.env.AI_BASE_URL && process.env.STARCI_AI_KEY) {
+    const chat = process.env.AI_CHAT_MODEL || "work"
+    const provider = process.env.OPENCLAW_PROVIDER || "starci-ai"
+    config.models = {
+        ...(config.models || {}),
+        mode: "merge",
+        providers: {
+            ...((config.models || {}).providers || {}),
+            [provider]: {
+                baseUrl: process.env.AI_BASE_URL,
+                apiKey: "${STARCI_AI_KEY}",
+                api: "openai-completions",
+                models: [{ id: chat, name: chat, input: ["text", "image"] }],
+            },
+        },
+    }
+}
+const model = process.env.OPENCLAW_MODEL
+if (model) {
+    config.agents.defaults.model = { ...(config.agents.defaults.model || {}), primary: model }
+    if (process.env.OPENCLAW_MODEL_REASONING === "off") {
+        const models = (config.agents.defaults.models = config.agents.defaults.models || {})
+        const previous = models[model] || {}
+        models[model] = {
+            ...previous,
+            params: {
+                ...(previous.params || {}),
+                extra_body: { ...((previous.params || {}).extra_body || {}), reasoning: { enabled: false } },
+            },
+        }
+    }
+}
+fs.mkdirSync("/home/node/.openclaw", { recursive: true })
+fs.writeFileSync(file, JSON.stringify(config, null, 2), { mode: 0o600 })
+console.log("openclaw.json ready (gateway local/loopback/token, " + found.length + " plugin" + (found.length === 1 ? "" : "s") + (model ? ", model " + model : "") + ")")

package/stack/images/openclaw-runtime/openclaw-relay.mjs

@@ -0,0 +1,25 @@
+// A byte-for-byte TCP relay inside the OpenClaw task: it listens on the overlay address and forwards every connection to the loopback-only
+// gateway (127.0.0.1:18789), so the gateway sees a loopback peer and honours the scopes a client declares. It adds no header and reads no frame.
+import net from "node:net"
+
+const listenPort = Number(process.env.OPENCLAW_RELAY_PORT || 18790)
+const gatewayPort = 18789
+
+const server = net.createServer((client) => {
+    const gateway = net.connect({ host: "127.0.0.1", port: gatewayPort })
+    const close = () => {
+        client.destroy()
+        gateway.destroy()
+    }
+    client.on("error", close)
+    gateway.on("error", close)
+    client.on("close", close)
+    gateway.on("close", close)
+    client.pipe(gateway)
+    gateway.pipe(client)
+})
+server.on("error", (error) => {
+    console.error("openclaw relay failed: " + error.message)
+    process.exit(1)
+})
+server.listen(listenPort, "0.0.0.0", () => console.log("openclaw relay " + listenPort + " -> 127.0.0.1:" + gatewayPort))

package/stack/local-cli.d.mts

@@ -0,0 +1,25 @@
+import { isLocalEnvironment } from './local-config.mjs';
+import type { StackContext } from './context.mjs';
+import type { LocalDeps } from './local-run.mjs';
+/** The actions that exist only for a dev environment. */
+export declare const LOCAL_ONLY: readonly ["doctor", "up", "down", "logs"];
+/** The actions a swarm environment already has, which a docker-compose environment answers with its dev implementation. */
+export declare const LOCAL_SHARED: readonly ["prepare", "status", "verify"];
+/** True when `value` is an action only a dev environment has. */
+export declare const isLocalOnly: (value: unknown) => boolean;
+/** True when `value` is an action both kinds have. */
+export declare const isLocalShared: (value: unknown) => boolean;
+/** The parsed flags of a dev action. */
+export interface LocalFlags {
+    env?: string;
+    json: boolean;
+    execute: boolean;
+    timeout?: string;
+    service?: string;
+    lines?: string;
+}
+/** Parses the flags of one dev action; a flag of another action, an unknown flag and a missing value are refusals. */
+export declare function parseLocalFlags(action: string, argv: readonly string[]): LocalFlags;
+/** Runs one dev action and returns the exit code. */
+export declare function runLocal(ctx: StackContext, action: string, argv: readonly string[], deps?: LocalDeps): Promise<number>;
+export { isLocalEnvironment };

package/stack/local-cli.mjs

@@ -0,0 +1,89 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// local-cli.mjs - the dev actions of `starci app stack` (PROJECT-STACKS-6): doctor, up, down and logs, and prepare, status and verify when the
+// named environment runs docker-compose. Each takes only its own flags; effects (up, down, prepare) are dry runs until --execute.
+//   starci app stack doctor  --env <env>
+//   starci app stack prepare --env <env> [--execute]
+//   starci app stack up      --env <env> [--execute] [--timeout <seconds>]
+//   starci app stack status  --env <env>
+//   starci app stack logs    --env <env> --service <name> [--lines <n>]
+//   starci app stack verify  --env <env>
+//   starci app stack down    --env <env> [--execute]
+import { loadLocalConfig, isLocalEnvironment } from './local-config.mjs';
+import { EXIT, refusal } from './errors.mjs';
+/** The actions that exist only for a dev environment. */
+export const LOCAL_ONLY = Object.freeze(['doctor', 'up', 'down', 'logs']);
+/** The actions a swarm environment already has, which a docker-compose environment answers with its dev implementation. */
+export const LOCAL_SHARED = Object.freeze(['prepare', 'status', 'verify']);
+/** True when `value` is an action only a dev environment has. */
+export const isLocalOnly = (value) => LOCAL_ONLY.includes(value);
+/** True when `value` is an action both kinds have. */
+export const isLocalShared = (value) => LOCAL_SHARED.includes(value);
+const FLAGS = Object.freeze({
+    doctor: [], up: ['--execute', '--timeout'], down: ['--execute'], logs: ['--service', '--lines'], prepare: ['--execute'], status: [], verify: [],
+});
+const VALUES = new Set(['--env', '--timeout', '--service', '--lines']);
+/** Parses the flags of one dev action; a flag of another action, an unknown flag and a missing value are refusals. */
+export function parseLocalFlags(action, argv) {
+    const own = new Set(['--env', '--json', ...(FLAGS[action] ?? [])]);
+    const flags = { json: false, execute: false };
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (!arg.startsWith('--'))
+            throw refusal('STACK_USAGE', `stack ${action} takes no operand (got ${arg})`);
+        if (!own.has(arg))
+            throw refusal('STACK_USAGE', `stack ${action} takes no ${arg}: its flags are ${[...own].join(', ')}`);
+        if (arg === '--json')
+            flags.json = true;
+        else if (arg === '--execute')
+            flags.execute = true;
+        else if (VALUES.has(arg)) {
+            const value = argv[index + 1];
+            if (value === undefined || value.startsWith('--'))
+                throw refusal('STACK_USAGE', `${arg} needs a value`);
+            index += 1;
+            flags[arg.slice(2)] = value;
+        }
+    }
+    if (flags.env === undefined)
+        throw refusal('STACK_USAGE', `stack ${action} names its environment with --env <env>`);
+    return flags;
+}
+const whole = (value, name, fallback) => {
+    if (value === undefined)
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1)
+        throw refusal('STACK_USAGE', `${name} must be a whole number`);
+    return parsed;
+};
+/** The module of each dev action. */
+const MODULES = {
+    doctor: ['./local-doctor.mjs', 'doctorLocal'], prepare: ['./local-prepare.mjs', 'prepareLocal'], up: ['./local-up.mjs', 'upLocal'], status: ['./local-status.mjs', 'statusLocal'],
+    logs: ['./local-logs.mjs', 'logsLocal'], verify: ['./local-verify.mjs', 'verifyLocal'], down: ['./local-down.mjs', 'downLocal'],
+};
+/** Runs one dev action and returns the exit code. */
+export async function runLocal(ctx, action, argv, deps = {}) {
+    const flags = parseLocalFlags(action, argv);
+    const local = loadLocalConfig({ repoRoot: ctx.cwd, env: flags.env });
+    const [file, name] = MODULES[action];
+    const handler = (await import(__rewriteRelativeImportExtension(file)))[name];
+    const result = await handler(ctx, local, { execute: flags.execute, timeoutSeconds: whole(flags.timeout, '--timeout', 180), service: flags.service, lines: whole(flags.lines, '--lines', 200) }, deps);
+    if (flags.json)
+        ctx.stdout(`${JSON.stringify({ verb: action, ok: result.ok, ...result.data }, null, 2)}\n`);
+    else
+        for (const line of result.lines)
+            ctx.stdout(`${line}\n`);
+    if (result.refused) {
+        ctx.stderr(`starci app stack: ${result.refused.code}: ${result.refused.message}\n`);
+        return EXIT.refused;
+    }
+    return result.ok ? EXIT.ok : EXIT.failed;
+}
+export { isLocalEnvironment };

package/stack/local-config.d.mts

@@ -0,0 +1,17 @@
+import type { LocalBlock } from '../runtime/scripts/hfs/stack-local-config.mjs';
+/** The dev configuration of one environment, with absolute paths. */
+export interface LocalConfig extends LocalBlock {
+    env: string;
+    appProject: string;
+    repoRoot: string;
+    envDir: string;
+    composeFiles: string[];
+    secretsDir: string;
+}
+/** True when the environment is declared and runs docker-compose (the dev kind); false for a swarm or an unknown one. */
+export declare function isLocalEnvironment(repoRoot: string, env: string): boolean;
+/** The normalised dev configuration; a refusal names every problem when the block is missing or invalid. */
+export declare function loadLocalConfig({ repoRoot, env }: {
+    repoRoot: string;
+    env: string;
+}): LocalConfig;

package/stack/local-config.mjs

@@ -0,0 +1,37 @@
+// local-config.mjs - loads `environments.<env>.local` of .starcistacks/application-stacks.yaml for the dev verbs of `starci app stack`.
+// The block is read and judged by the module `starci app check` uses (runtime/scripts/hfs/stack-local-config.mjs).
+import fs from 'node:fs';
+import path from 'node:path';
+import { normalizeLocal, LOCAL_CONFIG_CODE } from '../runtime/scripts/hfs/stack-local-config.mjs';
+import { readYaml, STACKS_DIR, STACKS_FILE } from './config.mjs';
+import { refusal } from './errors.mjs';
+/** True when the environment is declared and runs docker-compose (the dev kind); false for a swarm or an unknown one. */
+export function isLocalEnvironment(repoRoot, env) {
+    try {
+        const declaration = readYaml(path.join(repoRoot, STACKS_DIR, STACKS_FILE), STACKS_FILE);
+        return declaration?.environments?.[env]?.runtime === 'docker-compose';
+    }
+    catch {
+        return false;
+    }
+}
+/** The normalised dev configuration; a refusal names every problem when the block is missing or invalid. */
+export function loadLocalConfig({ repoRoot, env }) {
+    const declaration = readYaml(path.join(repoRoot, STACKS_DIR, STACKS_FILE), STACKS_FILE);
+    const environment = declaration?.environments?.[env];
+    if (!environment)
+        throw refusal('STACKS_DEPLOY_ENV_UNKNOWN', `${STACKS_FILE} declares no environment ${env}`);
+    if (environment.runtime !== 'docker-compose')
+        throw refusal('STACK_LOCAL_NOT_DEV', `environment ${env} runs ${environment.runtime}; up, down, doctor and logs run a docker-compose dev environment`);
+    if (environment.local === undefined)
+        throw refusal('STACK_LOCAL_UNDECLARED', `environment ${env} has no local block in ${STACKS_FILE}: declare the ports, services, processes and probes the dev environment runs (PROJECT-STACKS-6)`);
+    const appProject = String(JSON.parse(fs.readFileSync(path.join(repoRoot, 'hfs.json'), 'utf8')).project);
+    const { config, problems } = normalizeLocal(environment.local, { project: appProject, env });
+    if (!config) {
+        const first = problems.slice(0, 6).map((item) => `${item.at}: ${item.message}`).join('; ');
+        throw refusal(LOCAL_CONFIG_CODE, `${problems.length} problem${problems.length === 1 ? '' : 's'} in environments.${env}.local: ${first}`);
+    }
+    const envDir = path.join(repoRoot, STACKS_DIR, env);
+    const composeFiles = (environment.composeFiles ?? []).map((file) => path.join(envDir, file));
+    return { ...config, env, appProject, repoRoot, envDir, composeFiles, secretsDir: path.join(envDir, 'secrets') };
+}

package/stack/local-custody.d.mts

@@ -0,0 +1,24 @@
+import type { StackContext } from './context.mjs';
+import type { LocalConfig } from './local-config.mjs';
+/** The opened custody: the directory of the host-local `<KEY>` files and the values, in memory only. */
+export interface Custody {
+    directory: string;
+    values: Map<string, string>;
+}
+/** Every key the environment's commands, processes, database and compose read. */
+export declare function neededKeys(local: LocalConfig): string[];
+/** Which sealed member holds each key, read from the cleartext key names (no identity needed). */
+export declare function holders(secretsDir: string): Map<string, string>;
+/** The keys needed that no sealed member holds. */
+export declare const missingKeys: (local: LocalConfig) => string[];
+/** The owner step for keys no member holds: init when the environment generates them, else set. */
+export declare function missingStep(local: LocalConfig, missing: readonly string[]): string;
+/**
+ * Decrypts the needed keys in memory and writes each to its own private file outside the checkout. A key no member holds, or a member the
+ * machine's identity cannot open, is a refusal that names the owner step; nothing is generated here.
+ */
+export declare function openCustody(ctx: StackContext, local: LocalConfig): Custody;
+/** The directory of one least grant inside the host-local custody directory (created private; it holds only the keys the grant names). */
+export declare function grantDirectory(directory: string, name: string): string;
+/** The `<KEY>_FILE` environment of the keys a command reads: each points at the host-local file. */
+export declare const fileEnvironment: (custody: Custody, keys: readonly string[]) => Record<string, string>;

package/stack/local-custody.mjs

@@ -0,0 +1,109 @@
+// local-custody.mjs - the dev custody of a dev environment: which keys the environment reads, whether they are sealed, and their host-local
+// files (PROJECT-STACKS-5). Opening a member needs the owner identity; a machine without it is refused with the exact owner step, and a missing
+// value is never answered by minting a replacement (only the owner-armed `starci app secret init --env <env>` creates dev values, once).
+import fs from 'node:fs';
+import path from 'node:path';
+import { envelopeOf } from '../runtime/scripts/hfs/secret-document.mjs';
+import { materializedDirectory, writeSecretFile } from '../runtime/scripts/hfs/secret-files.mjs';
+import { isSealedName, memberOfName } from '../runtime/scripts/lib/sealed-member.mjs';
+import { refusal } from './errors.mjs';
+/** Every key the environment's commands, processes, database and compose read. */
+export function neededKeys(local) {
+    const keys = new Set();
+    for (const run of [...local.setup, ...local.seed, ...local.processes])
+        for (const key of run.files)
+            if (key !== local.database?.urlEnv)
+                keys.add(key);
+    for (const item of local.composeEnv)
+        keys.add(item.key);
+    for (const grant of local.grants)
+        for (const key of grant.keys)
+            keys.add(key);
+    if (local.database) {
+        keys.add(local.database.password.key);
+        keys.add(local.database.adminPassword.key);
+        if (local.database.appPassword)
+            keys.add(local.database.appPassword.key);
+    }
+    return [...keys].sort();
+}
+/** Which sealed member holds each key, read from the cleartext key names (no identity needed). */
+export function holders(secretsDir) {
+    const held = new Map();
+    let names = [];
+    try {
+        names = fs.readdirSync(secretsDir).filter(isSealedName).sort();
+    }
+    catch {
+        return held;
+    }
+    for (const name of names) {
+        try {
+            for (const key of envelopeOf(fs.readFileSync(path.join(secretsDir, name), 'utf8')).keys)
+                if (!held.has(key))
+                    held.set(key, name);
+        }
+        catch { /* an unreadable member is judged when it is opened */ }
+    }
+    return held;
+}
+/** The keys needed that no sealed member holds. */
+export const missingKeys = (local) => {
+    const held = holders(local.secretsDir);
+    return neededKeys(local).filter((key) => !held.has(key));
+};
+/** The owner step for keys no member holds: init when the environment generates them, else set. */
+export function missingStep(local, missing) {
+    const generated = new Set(local.custody.flatMap((item) => [item.key, ...(item.publicKey ? [item.publicKey] : [])]));
+    const create = missing.filter((key) => generated.has(key));
+    const set = missing.filter((key) => !generated.has(key));
+    return [
+        create.length ? `the owner arms "starci app secret init --env ${local.env} --execute" to create ${create.join(', ')} once` : '',
+        set.length ? `the owner seals ${set.join(', ')} with "starci app secret set --env ${local.env} <slug> <KEY>"` : '',
+    ].filter(Boolean).join('; ');
+}
+/**
+ * Decrypts the needed keys in memory and writes each to its own private file outside the checkout. A key no member holds, or a member the
+ * machine's identity cannot open, is a refusal that names the owner step; nothing is generated here.
+ */
+export function openCustody(ctx, local) {
+    const needed = neededKeys(local);
+    const held = holders(local.secretsDir);
+    const missing = needed.filter((key) => !held.has(key));
+    if (missing.length)
+        throw refusal('STACK_LOCAL_CUSTODY_MISSING', `no sealed member of ${local.env} holds ${missing.join(', ')}: ${missingStep(local, missing)}`);
+    const values = new Map();
+    const members = [...new Set(needed.map((key) => held.get(key)))];
+    for (const name of members) {
+        const file = path.join(local.secretsDir, name);
+        try {
+            ctx.sops.requireIdentity?.(file);
+            const map = ctx.sops.decrypt(file, envelopeOf(fs.readFileSync(file, 'utf8')).format);
+            for (const key of needed)
+                if (held.get(key) === name && typeof map[key] === 'string')
+                    values.set(key, map[key]);
+        }
+        catch (error) {
+            const why = String(error.message ?? error).split(/\r?\n/u)[0];
+            throw refusal('STACK_LOCAL_IDENTITY_MISSING', `${memberOfName(name)} (${local.env}) cannot be opened on this machine: ${why}. The owner step: put the age identity that ${local.env} is sealed to in SOPS_AGE_KEY of the harness secret.env (or .claude/secret.env of the app), obtained from the owner; a replacement is never generated for an existing sealed value (PROJECT-STACKS-5)`);
+        }
+    }
+    const directory = materializedDirectory(local.repoRoot, local.env, ctx.env, ctx.platform);
+    for (const [key, value] of values)
+        writeSecretFile(directory, key, value);
+    for (const grant of local.grants) {
+        const target = grantDirectory(directory, grant.name);
+        for (const key of grant.keys)
+            if (values.has(key))
+                writeSecretFile(target, key, values.get(key));
+    }
+    return { directory, values };
+}
+/** The directory of one least grant inside the host-local custody directory (created private; it holds only the keys the grant names). */
+export function grantDirectory(directory, name) {
+    const target = path.join(directory, 'grants', name);
+    fs.mkdirSync(target, { recursive: true, mode: 0o700 });
+    return target;
+}
+/** The `<KEY>_FILE` environment of the keys a command reads: each points at the host-local file. */
+export const fileEnvironment = (custody, keys) => Object.fromEntries(keys.filter((key) => custody.values.has(key)).map((key) => [`${key}_FILE`, path.join(custody.directory, key)]));

package/stack/local-doctor.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';
+/** `doctor` for a dev environment. */
+export declare function doctorLocal(ctx: StackContext, local: LocalConfig, _options?: Record<string, unknown>, deps?: LocalDeps): Promise<ActionResult>;

package/stack/local-doctor.mjs

@@ -0,0 +1,49 @@
+// local-doctor.mjs - `starci app stack doctor --env <dev env>` (PROJECT-STACKS-6): the read-only inspection of a dev environment and of the machine
+// it runs on. The prerequisite table (tools, engine, resources, ports) names the owner-run install step per OS for each missing one; then
+// the custody (which keys are sealed, whether this machine's identity opens the members), the compose render, the volumes and the recorded
+// processes. It changes nothing and never prints a value.
+import fs from 'node:fs';
+import path from 'node:path';
+import { firstLine, lines as splitLines } from './context.mjs';
+import { holders, missingKeys, missingStep, neededKeys } from './local-custody.mjs';
+import { tableLines } from './local-host.mjs';
+import { preflight } from './local-prepare.mjs';
+import { compose, isAlive, stateOf } from './local-run.mjs';
+import { readRecord } from './local-state.mjs';
+function custodyRows(ctx, local) {
+    const needed = neededKeys(local);
+    const missing = missingKeys(local);
+    const rows = [{ id: 'custody', ok: missing.length === 0, detail: missing.length ? `${missing.join(', ')} sealed in no member of ${local.env}` : `${needed.length} key(s) sealed`, fix: missing.length ? missingStep(local, missing) : null }];
+    const held = holders(local.secretsDir);
+    const members = [...new Set(needed.map((key) => held.get(key)).filter((name) => name !== undefined))];
+    for (const name of members) {
+        try {
+            ctx.sops.requireIdentity?.(path.join(local.secretsDir, name));
+            rows.push({ id: `identity ${name}`, ok: true, detail: 'this machine holds an identity the member is sealed to', fix: null });
+        }
+        catch (error) {
+            rows.push({ id: `identity ${name}`, ok: false, detail: String(error.message).split(/\r?\n/u)[0] ?? 'no identity', fix: 'obtain the age identity of the environment from the owner into SOPS_AGE_KEY of the harness secret.env; a replacement is never generated for an existing sealed value' });
+        }
+    }
+    return rows;
+}
+/** `doctor` for a dev environment. */
+export async function doctorLocal(ctx, local, _options = {}, deps = {}) {
+    const host = await preflight(ctx, local, deps);
+    const rows = [...custodyRows(ctx, local)];
+    const lines = [...host.lines, ...tableLines(rows)];
+    const dockerOk = host.rows.filter((row) => row.id === 'docker' || row.id === 'compose').every((row) => row.ok);
+    if (dockerOk) {
+        const placeholders = Object.fromEntries(local.composeEnv.map((item) => [item.name, 'placeholder']));
+        const render = await compose(ctx, local, ['config', '-q'], { values: placeholders });
+        rows.push({ id: 'compose files', ok: render.status === 0, detail: render.status === 0 ? `${local.composeFiles.length} file(s) render` : firstLine(render.stderr) || 'do not render', fix: render.status === 0 ? null : 'fix the compose files named above' });
+        lines.push(...tableLines(rows.slice(-1)));
+        const volumes = splitLines(ctx.spawn('docker', ['volume', 'ls', '--filter', `label=com.docker.compose.project=${local.project}`, '--format', '{{.Name}}']).stdout);
+        lines.push(`volumes: ${volumes.join(', ') || 'none yet'}`);
+    }
+    const record = readRecord(stateOf(ctx, local));
+    const alive = deps.alive ?? isAlive;
+    const recorded = Object.entries(record.processes).map(([name, entry]) => `${name} pid ${entry.pid} ${alive(entry.pid) ? 'alive' : 'gone'}`);
+    lines.push(`processes: ${recorded.join(', ') || 'none recorded'}`, `state: ${fs.existsSync(stateOf(ctx, local)) ? stateOf(ctx, local) : 'none yet'}`);
+    return { ok: host.ok && rows.every((row) => row.ok), lines, data: { rows: [...host.rows, ...rows] } };
+}

package/stack/local-down.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';
+import type { LocalDeps } from './local-run.mjs';
+/** `down` for a dev environment. */
+export declare function downLocal(ctx: StackContext, local: LocalConfig, { execute }?: {
+    execute?: boolean;
+}, deps?: LocalDeps): Promise<ActionResult>;

package/stack/local-down.mjs

@@ -0,0 +1,20 @@
+import { compose, isAlive, stateOf, stopProcess } from './local-run.mjs';
+import { readRecord, writeRecord } from './local-state.mjs';
+/** `down` for a dev environment. */
+export async function downLocal(ctx, local, { execute = false } = {}, deps = {}) {
+    const dir = stateOf(ctx, local);
+    const record = readRecord(dir);
+    const alive = deps.alive ?? isAlive;
+    const running = Object.entries(record.processes).filter(([, entry]) => alive(entry.pid));
+    const lines = [`processes to end: ${running.map(([name, entry]) => `${name} (pid ${entry.pid})`).join(', ') || 'none'}`, `compose project to stop: ${local.project} (volumes and images stay)`];
+    if (!execute)
+        return { ok: true, lines: [...lines, 'dry run: nothing was stopped; arm it with --execute'], data: { processes: running.map(([name]) => name) } };
+    for (const [name, entry] of running) {
+        stopProcess(ctx, entry.pid, deps);
+        lines.push(`process ${name}: ended`);
+    }
+    writeRecord(dir, { ...record, processes: {} });
+    const stopped = await compose(ctx, local, ['down'], { label: 'compose down' });
+    lines.push(stopped.status === 0 ? `compose ${local.project}: stopped, volumes kept` : `compose ${local.project}: down failed (${(stopped.stderr.trim().split(/\r?\n/u)[0] ?? '').slice(0, 160)})`);
+    return { ok: stopped.status === 0, lines, data: { processes: running.map(([name]) => name) } };
+}

package/stack/local-host.d.mts

@@ -0,0 +1,42 @@
+import type { RunResult, StackContext } from './context.mjs';
+import type { LocalBlock } from '../runtime/scripts/hfs/stack-local-config.mjs';
+/** One row of the prerequisite table. */
+export interface Prerequisite {
+    id: string;
+    ok: boolean;
+    detail: string;
+    fix: string | null;
+}
+/** The seams of the host probes a spec replaces. */
+export interface HostDeps {
+    portFree?: ((port: number) => Promise<boolean>) | undefined;
+    diskFreeGb?: ((dir: string) => number | null) | undefined;
+    memoryMb?: (() => {
+        free: number;
+        total: number;
+    }) | undefined;
+}
+/**
+ * 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 declare function launch(platform: NodeJS.Platform, command: string, args: readonly string[], exists?: (file: string) => boolean): [string, string[]];
+/** Runs a host tool without a shell (see launch). */
+export declare function hostTool(ctx: Pick<StackContext, 'spawn' | 'platform'>, command: string, args: readonly string[], options?: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}): RunResult;
+/** The Node version the app asks for: `.nvmrc`, else the first version of `engines.node`; null when it asks for none. */
+export declare function wantedNode(repoRoot: string): string | null;
+/** True when the environment's secrets folder holds a sealed member. */
+export declare const hasSealedMembers: (secretsDir: string) => boolean;
+/** One row per declared port: free, or held by this environment's own record, or held by someone else (named). */
+export declare function portRows(ctx: StackContext, local: LocalBlock, stateDir: string, deps?: HostDeps): Promise<Prerequisite[]>;
+/** The whole table for one environment: tools, engine, resources, then the declared ports. */
+export declare function hostPrerequisites(ctx: StackContext, local: LocalBlock, where: {
+    repoRoot: string;
+    stateDir: string;
+    secretsDir: string;
+}, deps?: HostDeps): Promise<Prerequisite[]>;
+/** The table as printed lines: `ok    ` and `FAIL  ` rows, each failure followed by its owner-run step. */
+export declare function tableLines(rows: readonly Prerequisite[]): string[];