@starci/hfs 5.1.0 → 5.2.0

package/runtime/scripts/hfs/secret.mjs

@@ -24,6 +24,7 @@ import { setValues } from "./secret-prompt.mjs";
 import { stackContext } from "../../../stack/context.mjs";
 import { StackError } from "../../../stack/errors.mjs";
 import { serverKey } from "../../../stack/server-key.mjs";
+import { seedDevCustody } from "./secret-dev-init.mjs";
 export { envelopeOf, formatOf, plaintextOf } from "./secret-document.mjs";
 export { setSecretValues } from "./secret-store.mjs";
 /** The actions of `starci app secret`, in usage order. */
@@ -76,7 +77,7 @@ function parse(argv) {
 /** The operands and flags of one secret action, as the usage of `starci app secret` prints them. */
 export function secretUsage(verb) {
     if (verb === "init")
-        return "";
+        return "[--env <dev env> [--execute]]";
     if (verb === "set")
         return "--env <env> <slug> <KEY> [KEY ...] [--generate <bytes>] [--from-file KEY=path ...]";
     if (verb === "get")
@@ -100,8 +101,8 @@ export function secretUsage(verb) {
     return "--env <env>";
 }
 function editOptionsFor(verb, opts) {
-    if (opts.execute !== undefined && !EDIT_VERBS.has(verb) && !MOVE_VERBS.has(verb) && verb !== "server-key" && verb !== "recipients")
-        throw new SecretError("--execute is only valid for unset, rename, remove, recipients, migrate, split and server-key");
+    if (opts.execute !== undefined && !EDIT_VERBS.has(verb) && !MOVE_VERBS.has(verb) && verb !== "server-key" && verb !== "recipients" && verb !== "init")
+        throw new SecretError("--execute is only valid for init --env, unset, rename, remove, recipients, migrate, split and server-key");
     if (opts.execute !== undefined && verb === "recipients" && !opts.add && !opts.remove)
         throw new SecretError("--execute is only valid for recipients with --add or --remove");
     if ((opts.rotate !== undefined || opts.backup !== undefined || opts.restore !== undefined) && verb !== "server-key")
@@ -128,8 +129,8 @@ function outputOptionsFor(verb, opts) {
 }
 /** The environment leads the operands (`--env <env> <slug> ...` is checked and read as `<env> <slug> ...`); init takes none, audit may name one. */
 function environmentOf(verb, opts) {
-    if (verb === "init" && opts.env !== undefined)
-        throw new SecretError("--env is not valid for init");
+    if (verb === "init" && opts.env === undefined && opts.execute !== undefined)
+        throw new SecretError("--execute is only valid for init --env <dev env>");
     if (verb !== "init" && verb !== "audit" && opts.env === undefined)
         throw new SecretError(`usage: starci app secret ${verb} ${secretUsage(verb)}`);
     if (verb === "audit" && opts.positional.length)
@@ -141,7 +142,7 @@ function optionsFor(verb, opts) {
     environmentOf(verb, opts);
     const count = opts.positional.length;
     const bounds = {
-        init: [0, 0],
+        init: [0, 1],
         list: [1, 1],
         materialize: [1, 1],
         verify: [1, 1],
@@ -253,10 +254,12 @@ export async function secretMain(argv, { stdout = (s) => process.stdout.write(s)
     const [verb, ...rest] = argv;
     try {
         if (!VERBS.has(verb))
-            throw new SecretError("usage: starci app secret init | set --env <env> <slug> <KEY> [KEY ...] | get --env <env> <slug> [KEY] --to-file | unset --env <env> <slug> <KEY> | rename --env <env> <slug> <OLD> <NEW> | remove --env <env> <slug> | materialize --env <env> | list --env <env> | verify --env <env> | recipients --env <env> [--add|--remove ...] [--execute] | migrate --env <env> <slug> [--to <slug>] [--into-existing] | split --env <env> <slug> [--group KEY=member] [--group-file <yaml>] [--into-existing] | audit [--env <env>] | server-key --env <env> [--rotate | --backup github | --restore github] [--execute]");
+            throw new SecretError("usage: starci app secret init [--env <dev env> [--execute]] | set --env <env> <slug> <KEY> [KEY ...] | get --env <env> <slug> [KEY] --to-file | unset --env <env> <slug> <KEY> | rename --env <env> <slug> <OLD> <NEW> | remove --env <env> <slug> | materialize --env <env> | list --env <env> | verify --env <env> | recipients --env <env> [--add|--remove ...] [--execute] | migrate --env <env> <slug> [--to <slug>] [--into-existing] | split --env <env> <slug> [--group KEY=member] [--group-file <yaml>] [--into-existing] | audit [--env <env>] | server-key --env <env> [--rotate | --backup github | --restore github] [--execute]");
         const opts = parse(rest);
         optionsFor(verb, opts);
         const repoRoot = path.resolve(cwd, opts.cwd ?? ".");
+        if (verb === "init" && opts.env !== undefined)
+            return seedDevCustody(repoRoot, opts.env, { execute: opts.execute === true, sops: () => sops ?? defaultSops(env, repoRoot, platform, tools, hostIdentity), stdout, random });
         if (verb === "init")
             return publicStorage(() => initializeSecrets(repoRoot, { env, platform, tools, stdout, host: hostIdentity }));
         if (verb === "audit")

package/runtime/scripts/hfs/slots.mjs

@@ -232,7 +232,7 @@ export function readRepoDeclaration(manifest, repoRoot) {
 function createScopeResolver(manifest, repo) {
     const profile = repo.profile;
     const edition = repo.edition ?? 'full';
-    const slots = manifest.slots.filter((s) => s.profiles.includes(profile) && slotInEdition(manifest, s, edition)).map((s) => effectiveSlot(s, profile, edition));
+    const slots = manifest.slots.filter((s) => s.managedOnly !== true && s.profiles.includes(profile) && slotInEdition(manifest, s, edition)).map((s) => effectiveSlot(s, profile, edition));
     const scope = { manifest, repo, profile, slots, byId: new Map(slots.map((s) => [s.id, s])), variants: slots.flatMap(variantsOf), appKind: new Map(repo.apps.map((a) => [a.name, a.kind])) };
     const classifyPath = (input) => classifyIn(scope, input);
     /** tracked | ignored | external for the slot owning `p`, or null when no slot owns it. */

package/runtime/scripts/hfs/stack-local-config.d.mts

@@ -0,0 +1,101 @@
+import type { StackProblem } from './stack-config-kit.mjs';
+export declare const LOCAL_CONFIG_CODE = "STACKS_LOCAL_CONFIG";
+/** The generators `starci app secret init --env <env>` knows (PROJECT-STACKS-5: dev-only values, created once, never replaced). */
+export declare const GENERATORS: readonly string[];
+/** A key of a sealed member of the environment. */
+export interface CustodyRef {
+    member: string;
+    key: string;
+}
+/** A command the verbs run: an argv list (never a shell line), run from `cwd` (app-root relative). */
+export interface LocalCommand {
+    name: string;
+    argv: string[];
+    cwd: string;
+    heavy: 'install' | 'build' | 'none';
+    skipIfExists: string | null;
+    env: Record<string, string>;
+    files: string[];
+    /** Seed only: `migrate` runs it once the database is migrated, `ready` once the processes answer (a seed that signs up through the api). */
+    after: 'migrate' | 'ready';
+}
+/** A compose service the environment starts and how its readiness is observed. */
+export interface LocalService {
+    name: string;
+    wait: 'healthy' | 'started' | 'tcp';
+    port: string | null;
+}
+/** A native app process. */
+export interface LocalProcess extends LocalCommand {
+    port: string | null;
+    health: HttpProbe | null;
+}
+/** One HTTP probe: the readiness of a process, a `ready` row or a `verify` row. */
+export interface HttpProbe {
+    name: string;
+    url: string;
+    method: string;
+    status: number;
+    contains: string | null;
+}
+/** The per-environment database: its compose service, its own login role and where the app reads its URL. */
+export interface LocalDatabase {
+    service: string;
+    port: string;
+    name: string;
+    role: string;
+    urlEnv: string;
+    urlAs: 'env' | 'file';
+    adminUser: string;
+    password: CustodyRef;
+    adminPassword: CustodyRef;
+    appRole: string | null;
+    appPassword: CustodyRef | null;
+}
+/** One dev-only value the owner-armed `secret init` creates once. */
+export interface CustodyGenerator extends CustodyRef {
+    kind: string;
+    bytes: number;
+    publicKey: string | null;
+}
+/** The normalised `local` block of one environment. */
+export interface LocalBlock {
+    project: string;
+    ports: Record<string, number>;
+    services: LocalService[];
+    database: LocalDatabase | null;
+    composeEnv: Array<CustodyRef & {
+        name: string;
+    }>;
+    /** Least grants: the keys one compose service may read, mounted from `STACK_GRANT_<NAME>` (a directory holding only those keys). */
+    grants: Array<{
+        name: string;
+        keys: string[];
+    }>;
+    /** Data directories under the state base (`${data}/<name>`, `STACK_DATA_DIR`), created by `up` before anything starts: bind mounts and file stores of native processes. */
+    dirs: string[];
+    custody: CustodyGenerator[];
+    setup: LocalCommand[];
+    seed: LocalCommand[];
+    processes: LocalProcess[];
+    ready: HttpProbe[];
+    verify: HttpProbe[];
+    origins: Array<{
+        name: string;
+        url: string;
+    }>;
+    resources: {
+        diskGb: number;
+        ramMb: number;
+    };
+}
+/** The normalised `local` block, or the problems that stop it. `project` and `env` name the defaults (`<project>-<env>`, the role). */
+export declare function normalizeLocal(raw: unknown, { project, env }: {
+    project: string;
+    env: string;
+}): {
+    config: LocalBlock | null;
+    problems: StackProblem[];
+};
+/** Replaces `${port.<name>}` with the chosen host port. */
+export declare const expandPorts: (value: string, ports: Readonly<Record<string, number>>) => string;

package/runtime/scripts/hfs/stack-local-config.mjs

@@ -0,0 +1,320 @@
+// stack-local-config.mjs - reads and judges `environments.<env>.local`, the declaration of a dev environment (runtime docker-compose) that
+// `starci app stack up|down|doctor|prepare|status|logs|verify --env <env>` runs (PROJECT-STACKS-6). It holds names, ports, argv lists and
+// shapes only, never a value: custody keys are references into .starcistacks/<env>/secrets (PROJECT-STACKS-5). The authority for the fields is
+// this module; the same normaliser serves `starci app check` (rule R340) and the verbs, so a block the check passes is a block the verbs run.
+import path from 'node:path';
+import { isPlainObject as plain } from '../../engine/plain-object.mjs';
+import { closedFields, collector, patternField } from './stack-config-kit.mjs';
+export const LOCAL_CONFIG_CODE = 'STACKS_LOCAL_CONFIG';
+const NAME = /^[a-z][a-z0-9-]{0,40}$/u;
+const KEY = /^[A-Z][A-Z0-9_]{0,63}$/u;
+const PROJECT = /^[a-z0-9][a-z0-9_-]{0,62}$/u;
+const NAME_PATTERN = /^[a-z][a-z0-9-]{0,40}$/u;
+const SQL_NAME = /^[a-z][a-z0-9_]{0,62}$/u;
+/** The generators `starci app secret init --env <env>` knows (PROJECT-STACKS-5: dev-only values, created once, never replaced). */
+export const GENERATORS = Object.freeze(['hex', 'base64', 'password', 'uuid', 'rsa-pem', 'ec-pem', 'ed25519-pem']);
+const TOP = ['project', 'ports', 'services', 'database', 'composeEnv', 'grants', 'dirs', 'custody', 'setup', 'seed', 'processes', 'ready', 'verify', 'origins', 'resources'];
+const COMMAND = ['name', 'argv', 'cwd', 'heavy', 'skipIfExists', 'env', 'files'];
+const SEED = [...COMMAND, 'after'];
+const PROCESS = [...COMMAND, 'port', 'health'];
+const text = (value) => typeof value === 'string' && value.trim() !== '';
+/** A relative path inside the app root: no drive, no `..`, forward slashes. */
+function relative(c, at, value) {
+    if (typeof value !== 'string' || value === '' || path.posix.isAbsolute(value) || /^[A-Za-z]:/u.test(value) || value.includes('\\') || path.posix.normalize(value).split('/').includes('..')) {
+        c.problem(at, 'must be a relative path inside the app root');
+        return '.';
+    }
+    return value;
+}
+function ref(c, at, value) {
+    if (!closedFields(c, at, value, ['member', 'key'], 'local'))
+        return { member: '', key: '' };
+    const entry = value;
+    patternField(c, `${at}.member`, entry.member, /^[a-z0-9][a-z0-9-]*$/u);
+    patternField(c, `${at}.key`, entry.key, KEY);
+    return { member: String(entry.member), key: String(entry.key) };
+}
+function strings(c, at, value, pattern = null) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.some((item) => !text(item))) {
+        c.problem(at, 'must be a list of non-empty strings');
+        return [];
+    }
+    if (pattern)
+        value.forEach((item, index) => patternField(c, `${at}[${index}]`, item, pattern));
+    return value;
+}
+function command(c, at, value, allowed, names) {
+    const empty = { name: '', argv: [], cwd: '.', heavy: 'none', skipIfExists: null, env: {}, files: [], after: 'migrate' };
+    if (!closedFields(c, at, value, allowed, 'local'))
+        return empty;
+    const entry = value;
+    const name = String(entry.name ?? '');
+    if (patternField(c, `${at}.name`, entry.name, NAME)) {
+        if (names.has(name))
+            c.problem(`${at}.name`, `${name} is declared twice`);
+        names.add(name);
+    }
+    const argv = strings(c, `${at}.argv`, entry.argv);
+    if (argv.length === 0)
+        c.problem(`${at}.argv`, 'must hold the command and its arguments (an argv list, never a shell line)');
+    const heavy = entry.heavy ?? 'none';
+    if (!['install', 'build', 'none'].includes(String(heavy)))
+        c.problem(`${at}.heavy`, 'must be install, build or none (the heavy-command governor class of the command)');
+    let env = {};
+    if (entry.env !== undefined) {
+        if (!plain(entry.env))
+            c.problem(`${at}.env`, 'must be a mapping of non-secret values');
+        else {
+            env = entry.env;
+            for (const [key, item] of Object.entries(env)) {
+                patternField(c, `${at}.env.${key}`, key, KEY);
+                if (typeof item !== 'string')
+                    c.problem(`${at}.env.${key}`, 'must be a string');
+            }
+        }
+    }
+    return {
+        name, argv, cwd: entry.cwd === undefined ? '.' : relative(c, `${at}.cwd`, entry.cwd), heavy: heavy,
+        skipIfExists: entry.skipIfExists === undefined ? null : relative(c, `${at}.skipIfExists`, entry.skipIfExists), env,
+        files: strings(c, `${at}.files`, entry.files, KEY), after: afterOf(c, at, entry.after),
+    };
+}
+function afterOf(c, at, value) {
+    if (value === undefined)
+        return 'migrate';
+    if (value !== 'migrate' && value !== 'ready')
+        c.problem(`${at}.after`, 'must be migrate or ready');
+    return value === 'ready' ? 'ready' : 'migrate';
+}
+function probe(c, at, value) {
+    const empty = { name: '', url: '', method: 'GET', status: 200, contains: null };
+    if (!closedFields(c, at, value, ['name', 'url', 'method', 'status', 'contains'], 'local'))
+        return empty;
+    const entry = value;
+    patternField(c, `${at}.name`, entry.name, NAME);
+    const url = String(entry.url ?? '');
+    if (!/^http:\/\/(localhost|127\.0\.0\.1|[a-z0-9-]+\.localhost)(:\$\{port\.[a-z][a-z0-9-]*\}|:[0-9]+)?(\/.*)?$/u.test(url))
+        c.problem(`${at}.url`, 'must be an http URL on the loopback (localhost, 127.0.0.1 or *.localhost), its port a literal or ${port.<name>}');
+    const method = String(entry.method ?? 'GET');
+    if (!['GET', 'HEAD', 'POST'].includes(method))
+        c.problem(`${at}.method`, 'must be GET, HEAD or POST');
+    const status = entry.status === undefined ? 200 : entry.status;
+    if (!Number.isInteger(status) || status < 100 || status > 599)
+        c.problem(`${at}.status`, 'must be an HTTP status');
+    return { name: String(entry.name ?? ''), url, method, status: status, contains: text(entry.contains) ? entry.contains : null };
+}
+function portsOf(c, value) {
+    const ports = {};
+    if (!plain(value) || Object.keys(value).length === 0) {
+        c.problem('ports', 'must name at least one port: the host ports the environment publishes or listens on');
+        return ports;
+    }
+    const seen = new Map();
+    for (const [name, port] of Object.entries(value)) {
+        patternField(c, `ports.${name}`, name, NAME);
+        if (!Number.isInteger(port) || port < 1024 || port > 65535) {
+            c.problem(`ports.${name}`, 'must be a port from 1024 to 65535');
+            continue;
+        }
+        if (seen.has(port))
+            c.problem(`ports.${name}`, `is the port of ${seen.get(port)} too`);
+        seen.set(port, name);
+        ports[name] = port;
+    }
+    return ports;
+}
+function servicesOf(c, value, ports) {
+    if (!Array.isArray(value) || value.length === 0) {
+        c.problem('services', 'must list the compose services `up` starts, dependencies first');
+        return [];
+    }
+    return value.map((item, index) => {
+        const at = `services[${index}]`;
+        if (!closedFields(c, at, item, ['name', 'wait', 'port'], 'local'))
+            return { name: '', wait: 'started', port: null };
+        const entry = item;
+        patternField(c, `${at}.name`, entry.name, NAME);
+        const wait = String(entry.wait ?? 'healthy');
+        if (!['healthy', 'started', 'tcp'].includes(wait))
+            c.problem(`${at}.wait`, 'must be healthy (the compose healthcheck), tcp (the port accepts) or started');
+        const port = entry.port === undefined ? null : String(entry.port);
+        if (wait === 'tcp' && (port === null || !Object.hasOwn(ports, port)))
+            c.problem(`${at}.port`, 'must name a declared port when wait is tcp');
+        if (port !== null && !Object.hasOwn(ports, port))
+            c.problem(`${at}.port`, `${port} is not a declared port`);
+        return { name: String(entry.name ?? ''), wait: wait, port };
+    });
+}
+function databaseOf(c, value, ports, services, role) {
+    if (value === undefined)
+        return null;
+    if (!closedFields(c, 'database', value, ['service', 'port', 'name', 'role', 'urlEnv', 'urlAs', 'adminUser', 'password', 'adminPassword', 'appRole', 'appPassword'], 'local'))
+        return null;
+    const entry = value;
+    patternField(c, 'database.service', entry.service, NAME);
+    if (!services.some((service) => service.name === entry.service))
+        c.problem('database.service', 'must be one of the started services');
+    if (!Object.hasOwn(ports, String(entry.port)))
+        c.problem('database.port', 'must name a declared port');
+    const own = entry.role === undefined ? role : String(entry.role);
+    patternField(c, 'database.role', own, SQL_NAME);
+    const name = entry.name === undefined ? own : String(entry.name);
+    patternField(c, 'database.name', name, SQL_NAME);
+    patternField(c, 'database.urlEnv', entry.urlEnv, KEY);
+    const urlAs = String(entry.urlAs ?? 'file');
+    if (!['env', 'file'].includes(urlAs))
+        c.problem('database.urlAs', 'must be env (the URL in the process environment) or file (<KEY>_FILE, preferred)');
+    const adminUser = String(entry.adminUser ?? 'postgres');
+    patternField(c, 'database.adminUser', adminUser, SQL_NAME);
+    if (own === adminUser || own === 'postgres')
+        c.problem('database.role', 'must be a role of this environment alone, never the superuser and never a role another environment uses');
+    const appRole = entry.appRole === undefined ? null : String(entry.appRole);
+    if (appRole !== null)
+        patternField(c, 'database.appRole', appRole, SQL_NAME);
+    if ((appRole === null) !== (entry.appPassword === undefined))
+        c.problem('database.appPassword', 'is declared with appRole, both or neither: the app role the migrations create gets its own password per environment');
+    if (appRole !== null && (appRole === own || appRole === adminUser))
+        c.problem('database.appRole', 'must be a role other than the owner role and the superuser');
+    return {
+        appRole, appPassword: entry.appPassword === undefined ? null : ref(c, 'database.appPassword', entry.appPassword),
+        service: String(entry.service), port: String(entry.port), name, role: own, urlEnv: String(entry.urlEnv), urlAs: urlAs, adminUser,
+        password: ref(c, 'database.password', entry.password), adminPassword: ref(c, 'database.adminPassword', entry.adminPassword),
+    };
+}
+function custodyOf(c, value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value)) {
+        c.problem('custody', 'must be a list of generated dev values');
+        return [];
+    }
+    return value.map((item, index) => {
+        const at = `custody[${index}]`;
+        if (!closedFields(c, at, item, ['member', 'key', 'kind', 'bytes', 'publicKey'], 'local'))
+            return { member: '', key: '', kind: 'hex', bytes: 32, publicKey: null };
+        const entry = item;
+        const base = ref(c, at, { member: entry.member, key: entry.key });
+        if (!GENERATORS.includes(String(entry.kind)))
+            c.problem(`${at}.kind`, `must be one of ${GENERATORS.join(', ')}`);
+        const bytes = entry.bytes === undefined ? 32 : entry.bytes;
+        if (!Number.isInteger(bytes) || bytes < 8 || bytes > 1024)
+            c.problem(`${at}.bytes`, 'must be a whole byte count from 8 to 1024');
+        if (entry.publicKey !== undefined) {
+            if (entry.kind === 'rsa-pem' || entry.kind === 'ec-pem' || entry.kind === 'ed25519-pem')
+                patternField(c, `${at}.publicKey`, entry.publicKey, KEY);
+            else
+                c.problem(`${at}.publicKey`, 'is only for kind rsa-pem, ec-pem or ed25519-pem');
+        }
+        return { ...base, kind: String(entry.kind), bytes: bytes, publicKey: text(entry.publicKey) ? entry.publicKey : null };
+    });
+}
+function listOf(c, at, value, each) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value)) {
+        c.problem(at, 'must be a list');
+        return [];
+    }
+    return value.map((item, index) => each(item, index));
+}
+function referencedPorts(c, block) {
+    const known = new Set(Object.keys(block.ports));
+    const check = (at, value) => {
+        for (const match of value.matchAll(/\$\{port\.([a-z][a-z0-9-]*)\}/gu))
+            if (!known.has(match[1]))
+                c.problem(at, `names the undeclared port ${match[1]}`);
+    };
+    for (const item of [...block.ready, ...block.verify])
+        check(`url of ${item.name}`, item.url);
+    for (const origin of block.origins)
+        check(`origin ${origin.name}`, origin.url);
+    for (const run of [...block.setup, ...block.seed, ...block.processes]) {
+        for (const part of run.argv)
+            check(`argv of ${run.name}`, part);
+        for (const value of Object.values(run.env))
+            check(`env of ${run.name}`, value);
+    }
+    for (const process of block.processes) {
+        if (process.port !== null && !known.has(process.port))
+            c.problem(`processes.${process.name}.port`, `${process.port} is not a declared port`);
+        if (process.health)
+            check(`health of ${process.name}`, process.health.url);
+    }
+}
+/** The normalised `local` block, or the problems that stop it. `project` and `env` name the defaults (`<project>-<env>`, the role). */
+export function normalizeLocal(raw, { project, env }) {
+    const c = collector();
+    if (!closedFields(c, 'local', raw, TOP, 'local'))
+        return { config: null, problems: c.problems };
+    const entry = raw;
+    const compose = String(entry.project ?? `${project}-${env}`).toLowerCase().replaceAll(/[^a-z0-9_-]+/gu, '-');
+    patternField(c, 'project', compose, PROJECT);
+    const ports = portsOf(c, entry.ports);
+    const services = servicesOf(c, entry.services, ports);
+    const role = `${project}_${env}`.toLowerCase().replaceAll(/[^a-z0-9]+/gu, '_').replace(/^[^a-z]+/u, 'a');
+    const names = new Set();
+    const block = {
+        project: compose, ports, services,
+        database: databaseOf(c, entry.database, ports, services, role),
+        composeEnv: listOf(c, 'composeEnv', entry.composeEnv, (item, index) => {
+            const at = `composeEnv[${index}]`;
+            if (!closedFields(c, at, item, ['name', 'member', 'key'], 'local'))
+                return { name: '', member: '', key: '' };
+            const value = item;
+            patternField(c, `${at}.name`, value.name, KEY);
+            return { name: String(value.name), ...ref(c, at, { member: value.member, key: value.key }) };
+        }),
+        grants: listOf(c, 'grants', entry.grants, (item, index) => {
+            const at = `grants[${index}]`;
+            if (!closedFields(c, at, item, ['name', 'keys'], 'local'))
+                return { name: '', keys: [] };
+            const value = item;
+            patternField(c, `${at}.name`, value.name, NAME);
+            const keys = strings(c, `${at}.keys`, value.keys, KEY);
+            if (keys.length === 0)
+                c.problem(`${at}.keys`, 'must list the keys the service reads');
+            return { name: String(value.name), keys };
+        }),
+        dirs: strings(c, 'dirs', entry.dirs, NAME_PATTERN),
+        custody: custodyOf(c, entry.custody),
+        setup: listOf(c, 'setup', entry.setup, (item, index) => command(c, `setup[${index}]`, item, COMMAND, names)),
+        seed: listOf(c, 'seed', entry.seed, (item, index) => command(c, `seed[${index}]`, item, SEED, names)),
+        processes: listOf(c, 'processes', entry.processes, (item, index) => {
+            const at = `processes[${index}]`;
+            const base = command(c, at, item, PROCESS, names);
+            const value = plain(item) ? item : {};
+            return { ...base, port: value.port === undefined ? null : String(value.port), health: value.health === undefined ? null : probe(c, `${at}.health`, { name: base.name || 'health', ...value.health }) };
+        }),
+        ready: listOf(c, 'ready', entry.ready, (item, index) => probe(c, `ready[${index}]`, item)),
+        verify: listOf(c, 'verify', entry.verify, (item, index) => probe(c, `verify[${index}]`, item)),
+        origins: listOf(c, 'origins', entry.origins, (item, index) => {
+            const at = `origins[${index}]`;
+            if (!closedFields(c, at, item, ['name', 'url'], 'local'))
+                return { name: '', url: '' };
+            const value = item;
+            patternField(c, `${at}.name`, value.name, NAME);
+            return { name: String(value.name), url: String(value.url ?? '') };
+        }),
+        resources: { diskGb: 10, ramMb: 4096 },
+    };
+    if (entry.resources !== undefined && closedFields(c, 'resources', entry.resources, ['diskGb', 'ramMb'], 'local')) {
+        const value = entry.resources;
+        for (const [key, floor] of [['diskGb', 1], ['ramMb', 512]]) {
+            if (value[key] === undefined)
+                continue;
+            if (!Number.isInteger(value[key]) || value[key] < floor)
+                c.problem(`resources.${key}`, `must be a whole number from ${floor}`);
+            else
+                block.resources[key] = value[key];
+        }
+    }
+    referencedPorts(c, block);
+    const generated = new Set(block.custody.flatMap((item) => [`${item.member}/${item.key}`, ...(item.publicKey ? [`${item.member}/${item.publicKey}`] : [])]));
+    if (generated.size < block.custody.length)
+        c.problem('custody', 'declares a key twice');
+    return c.problems.length === 0 ? { config: block, problems: [] } : { config: null, problems: c.problems };
+}
+/** Replaces `${port.<name>}` with the chosen host port. */
+export const expandPorts = (value, ports) => value.replaceAll(/\$\{port\.([a-z][a-z0-9-]*)\}/gu, (_whole, name) => String(ports[name] ?? ''));

package/runtime/scripts/hfs/stacks-gate.mjs

@@ -535,7 +535,7 @@ const checkStacksManifest = (manifest, model, { stacksRoot, environment, root, r
     const lite = repo.edition === 'lite';
     checkStacksTree({ stacksRoot, manifest, environmentNames, add, lite });
     checkKubernetesDeclaration(manifest, add);
-    for (const issue of swarmInventoryIssues({ components: manifest.components, lite }))
+    for (const issue of swarmInventoryIssues({ components: manifest.components, lite, swarm: new Set(Object.values(object(manifest.environments) ? manifest.environments : {}).filter((spec) => spec?.runtime === 'docker-swarm').flatMap((spec) => Object.keys(object(spec.components) ? spec.components : {}))) }))
         add('HFS_STACKS_SHAPE', issue.at, issue.message);
     checkSelectedEnvironment({ environment, environmentNames, environments, stacksRoot, ids, root, model, manifest, lite, repo, add });
 };

package/runtime/scripts/lib/swarm-stack.d.mts

@@ -10,9 +10,10 @@ export declare function composeIncludePaths(doc: Mapping): {
     errors: string[];
 };
 /** Inventory rules are independent of a selected environment or rendered deployment model. */
-export declare function swarmInventoryIssues({ components, lite }: {
+export declare function swarmInventoryIssues({ components, lite, swarm }: {
     components: unknown;
     lite?: boolean;
+    swarm?: ReadonlySet<string>;
 }): SwarmIssue[];
 /** Validate the same deployment model in HFS and the deployment evidence gate. */
 export declare function swarmModelIssues({ model, components, bindings, lite }: {

package/runtime/scripts/lib/swarm-stack.mjs

@@ -49,12 +49,12 @@ function jobDeclarationIssues(id, component, components, add) {
         add(`components.${id}.schedule`, 'replicated-job must declare its cron schedule');
 }
 /** Inventory rules are independent of a selected environment or rendered deployment model. */
-export function swarmInventoryIssues({ components, lite = false }) {
+export function swarmInventoryIssues({ components, lite = false, swarm }) {
     const errors = [], catalog = mapping(components);
     const add = (at, message) => { errors.push({ at, message }); };
     for (const [id, entry] of Object.entries(catalog)) {
         const component = mapping(entry);
-        if (lite && present(component.image) && BACKING_IMAGE.test(repositoryOf(component.image)))
+        if (lite && (swarm === undefined || swarm.has(id)) && present(component.image) && BACKING_IMAGE.test(repositoryOf(component.image)))
             add(`components.${id}.image`, 'lite runs no backing image; its db component runs the image .starcistacks/images/db/Dockerfile builds, storage is the external S3 endpoint, identity the API');
         jobDeclarationIssues(id, component, catalog, add);
     }

package/scaffold/add-module.d.mts

@@ -0,0 +1,16 @@
+/** What a module verb answers: every app-relative path it wrote, rewrote or deleted. */
+export interface ModuleResult {
+    readonly created: string[];
+    readonly updated: string[];
+    readonly removed: string[];
+}
+/** Adds the module package `name`, registers it and re-renders the registry. Refused when the app has no agent SDK package or the module exists. */
+export declare function addModule({ root, name }: {
+    root: string;
+    name: string;
+}): ModuleResult;
+/** Removes the module package `name`, its registrations and its entry in the registry; the last module takes the registry package with it. */
+export declare function removeModule({ root, name }: {
+    root: string;
+    name: string;
+}): ModuleResult;