@starci/hfs 5.0.8 → 5.2.0

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/declaration-surface.d.mts

@@ -0,0 +1,35 @@
+import type { TypeScript } from './ts-ast.mjs';
+/** What the declaration emit cannot write without reading other files, and where: one export (or one part of it) the author must annotate. */
+export interface SurfaceProblem {
+    /** The TypeScript diagnostic code (9007: function without a return type, 9010: variable without a type, ...). */
+    code: number;
+    /** The offset and length of the offending span in the file's text. */
+    start: number;
+    length: number;
+    /** The name of the export (or member) the span sits in, or `default export`. */
+    name: string;
+    /** What to annotate: `return type`, `variable type`, `parameter type`, `property type`, `accessor type`, `destructured export` or `exported value`. */
+    annotate: string;
+    /** TypeScript's own reason, one sentence. */
+    reason: string;
+}
+/** The declaration emit of one file: its text (the digest of the type surface) and the exports it could not write explicitly. */
+export interface DeclarationSurface {
+    outputText: string;
+    problems: SurfaceProblem[];
+}
+/** A script file (`.js`, `.mjs`, `.cjs`, `.jsx`): it has no declaration emit and stands for its content. */
+export declare const SCRIPT: RegExp;
+/** A declaration file: it is its own surface. */
+export declare const DECLARATION: RegExp;
+/** A TypeScript source file whose surface the declaration emit writes. */
+export declare const TYPESCRIPT: RegExp;
+/** Whether `file` is a TypeScript source (not a declaration file) the declaration emit reads. */
+export declare const isEmittableSource: (file: string) => boolean;
+/**
+ * The declaration emit of one TypeScript source and the exports it could not write explicitly (a type inferred from bodies and other files), or null
+ * when the compiler has no `transpileDeclaration` (before TypeScript 5.5). A declaration whose only diagnostics are components returning JSX has the
+ * surface its emit shows. `module` is the side's `module` compiler option, which the emit reads. A throw from the compiler propagates: the caller
+ * decides what an unreadable file means.
+ */
+export declare function declarationSurface(ts: TypeScript, file: string, text: string, module?: number): DeclarationSurface | null;

package/runtime/scripts/lib/declaration-surface.mjs

@@ -0,0 +1,112 @@
+/** A script file (`.js`, `.mjs`, `.cjs`, `.jsx`): it has no declaration emit and stands for its content. */
+export const SCRIPT = /\.(?:[cm]?jsx?)$/;
+/** A declaration file: it is its own surface. */
+export const DECLARATION = /\.d\.[cm]?ts$/;
+/** A TypeScript source file whose surface the declaration emit writes. */
+export const TYPESCRIPT = /\.(?:[cm]?tsx?)$/;
+/** Whether `file` is a TypeScript source (not a declaration file) the declaration emit reads. */
+export const isEmittableSource = (file) => TYPESCRIPT.test(file) && !DECLARATION.test(file);
+/** Whether `expression` is a JSX element, fragment, `null` or `undefined`, or a conditional of those: its type does not depend on any other file. */
+function isJsxValue(ts, expression) {
+    if (expression === undefined)
+        return false;
+    let node = expression;
+    while (ts.isParenthesizedExpression(node))
+        node = node.expression;
+    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxFragment(node) || node.kind === ts.SyntaxKind.NullKeyword)
+        return true;
+    if (ts.isIdentifier(node))
+        return node.text === 'undefined';
+    return ts.isConditionalExpression(node) && isJsxValue(ts, node.whenTrue) && isJsxValue(ts, node.whenFalse);
+}
+/**
+ * Whether the function (or method) the declaration diagnostic at `start` points at has the type `JSX.Element | null | undefined` whatever its body
+ * reads: not async, not a generator, and every `return` of its own (and its concise body) a JSX value. A React component written without a return
+ * type is the common case; its inferred type is one the JSX namespace of the installed packages gives, which a lockfile change dirties as a whole.
+ */
+function returnsOnlyJsx(ts, source, start) {
+    let found;
+    const find = (node) => {
+        if (found !== undefined || start < node.getFullStart() || start >= node.end)
+            return;
+        const named = (ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node)) && node.name !== undefined && node.name.getStart(source) === start;
+        if (named || ((ts.isArrowFunction(node) || ts.isFunctionExpression(node)) && node.getStart(source) === start)) {
+            found = node;
+            return;
+        }
+        ts.forEachChild(node, find);
+    };
+    find(source);
+    const fn = found;
+    if (fn === undefined || fn.type !== undefined || fn.body === undefined)
+        return false;
+    if (fn.asteriskToken !== undefined || (ts.getCombinedModifierFlags(fn) & ts.ModifierFlags.Async) !== 0)
+        return false;
+    if (!ts.isBlock(fn.body))
+        return isJsxValue(ts, fn.body);
+    let only = true;
+    const visit = (node) => {
+        if (!only || ts.isFunctionLike(node) || ts.isClassLike(node))
+            return;
+        if (ts.isReturnStatement(node) && node.expression !== undefined && !isJsxValue(ts, node.expression))
+            only = false;
+        ts.forEachChild(node, visit);
+    };
+    ts.forEachChild(fn.body, visit);
+    return only;
+}
+/** What to annotate for each isolated-declaration diagnostic code; any other code asks for the exported value's type. */
+const ANNOTATE = new Map([
+    [9007, 'return type'], [9008, 'return type'], [9009, 'accessor type'], [9010, 'variable type'], [9011, 'parameter type'], [9012, 'property type'],
+    [9019, 'destructured export'], [9025, 'parameter type'],
+]);
+/** The declaration kinds whose name labels the export a diagnostic sits in, innermost first. */
+function nameOf(ts, source, start) {
+    let innermost = source;
+    const descend = (node) => {
+        if (start < node.getFullStart() || start >= node.end)
+            return;
+        innermost = node;
+        ts.forEachChild(node, descend);
+    };
+    ts.forEachChild(source, descend);
+    for (let node = innermost; node !== undefined && node !== source; node = node.parent) {
+        if (ts.isExportAssignment(node))
+            return 'default export';
+        if (ts.isBindingElement(node) && ts.isIdentifier(node.name))
+            return node.name.text;
+        if ((ts.isVariableDeclaration(node) || ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node) || ts.isMethodDeclaration(node) || ts.isPropertyDeclaration(node) || ts.isPropertyAssignment(node) || ts.isGetAccessorDeclaration(node)) && node.name !== undefined && ts.isIdentifier(node.name))
+            return node.name.text;
+        if (ts.isFunctionDeclaration(node) && (ts.getCombinedModifierFlags(node) & ts.ModifierFlags.Default) !== 0)
+            return 'default export';
+    }
+    return 'default export';
+}
+/**
+ * The declaration emit of one TypeScript source and the exports it could not write explicitly (a type inferred from bodies and other files), or null
+ * when the compiler has no `transpileDeclaration` (before TypeScript 5.5). A declaration whose only diagnostics are components returning JSX has the
+ * surface its emit shows. `module` is the side's `module` compiler option, which the emit reads. A throw from the compiler propagates: the caller
+ * decides what an unreadable file means.
+ */
+export function declarationSurface(ts, file, text, module) {
+    const emit = ts.transpileDeclaration;
+    if (emit === undefined)
+        return null;
+    const declared = emit.call(ts, text, { compilerOptions: { jsx: ts.JsxEmit.Preserve, target: ts.ScriptTarget.Latest, ...(module === undefined ? {} : { module }) }, fileName: file, reportDiagnostics: true });
+    const diagnostics = (declared.diagnostics ?? []);
+    if (diagnostics.length === 0)
+        return { outputText: declared.outputText, problems: [] };
+    const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, file.endsWith('x') ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+    const problems = [];
+    for (const diagnostic of diagnostics) {
+        const exempt = (diagnostic.code === 9007 || diagnostic.code === 9008) && diagnostic.start !== undefined && returnsOnlyJsx(ts, source, diagnostic.start);
+        if (exempt)
+            continue;
+        const start = diagnostic.start ?? 0;
+        problems.push({
+            code: diagnostic.code, start, length: diagnostic.length ?? 0, name: nameOf(ts, source, start), annotate: ANNOTATE.get(diagnostic.code) ?? 'exported value',
+            reason: ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n').split('\n')[0] ?? '',
+        });
+    }
+    return { outputText: declared.outputText, problems };
+}

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;