@starci/hfs 5.1.0 → 5.2.0

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[];

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;