@starci/hfs 5.1.0 → 5.3.0

package/runtime/scripts/hfs/view.d.mts

@@ -43,3 +43,26 @@ export declare const declaredHfsView: ({ runtimeRoot, declaration, repoRoot, sid
     repoRoot: string;
     side: string;
 }) => HfsView;
+/**
+ * The view of the root packages of the app at `repoRoot` (the app root, where the root `eslint.config.mjs` lives), for the laws of `side`.
+ *
+ * @param {{ runtimeRoot: string, repoRoot: string, side: string }} input - Where the manifest copy lives, the app root, and the side whose laws apply.
+ * @returns {object} The frozen view.
+ */
+export declare const openPackagesHfsView: ({ runtimeRoot, repoRoot, side }: {
+    runtimeRoot: string;
+    repoRoot: string;
+    side: "be" | "fe";
+}) => HfsView;
+/**
+ * The view of the root packages of an in-memory app declaration (rule tests): no file is read except the manifest.
+ *
+ * @param {{ runtimeRoot: string, declaration: object, repoRoot: string, side: string }} input - Manifest root, the app hfs.json object, the app root and the side.
+ * @returns {object} The frozen view.
+ */
+export declare const declaredPackagesHfsView: ({ runtimeRoot, declaration, repoRoot, side }: {
+    runtimeRoot: string;
+    declaration: Parsed;
+    repoRoot: string;
+    side: "be" | "fe";
+}) => HfsView;

package/runtime/scripts/hfs/view.mjs

@@ -5,6 +5,7 @@
 import path from 'node:path';
 import { allowsFile } from './allows.mjs';
 import { openHfs } from './slots.mjs';
+import { ROOT_PACKAGE_SLOTS } from './architecture/root-packages.mjs';
 const posix = (p) => String(p).replaceAll('\\', '/');
 const isAbsoluteAny = (text) => path.isAbsolute(text) || /^[A-Za-z]:\//.test(text);
 /**
@@ -69,3 +70,70 @@ export const openHfsView = ({ runtimeRoot, repoRoot }) => hfsView(openHfs({ root
  * @returns {object} The frozen view.
  */
 export const declaredHfsView = ({ runtimeRoot, declaration, repoRoot, side }) => hfsView(openHfs({ root: runtimeRoot, declaration, side }), repoRoot);
+/**
+ * The view of the root workspace packages of an app (`packages/<pkg>/src/**`, slots app.packages and app.module-registry), as the lint of one
+ * side sees them: the rule parameters, the apps and the Grammar of `side` (a package is judged by the laws of the side whose subpath a file
+ * sits in), and the paths of the APP ROOT (`repoRoot` is the app root, not a side folder). The slots answer for the root paths; a file of a
+ * package is of the tier `package` and has no owner: the owner laws (one `index.ts` per owner root) are the module folders', a package's public
+ * surface being the `exports` of its manifest.
+ *
+ * @param {object} opened - The result of `openHfs` for the app root (profile app, both sides resolved).
+ * @param {string} repoRoot - The absolute app root.
+ * @param {string} side - `be` or `fe`: the side whose laws the file is judged by.
+ * @returns {object} The frozen view: the profile of the side over the paths of the app root.
+ */
+function packagesView(opened, repoRoot, side) {
+    const scope = opened.sides?.[side];
+    const sideRepo = opened.repo.sides?.[side];
+    if (scope === undefined || sideRepo === undefined)
+        throw new Error('the view of the root packages needs the declaration of an app with both sides');
+    const rel = (file) => {
+        const text = posix(file);
+        return isAbsoluteAny(text) ? posix(path.relative(repoRoot, file)) : text.replace(/^\.\//, '');
+    };
+    const cache = new Map();
+    const classify = (file) => {
+        const key = rel(file);
+        if (!cache.has(key))
+            cache.set(key, opened.classifyPath(key));
+        return cache.get(key);
+    };
+    const packageOf = (file) => {
+        const slot = classify(file).slot;
+        const relative = rel(file);
+        return slot !== undefined && ROOT_PACKAGE_SLOTS.has(slot) ? relative.split('/').slice(0, 2).join('/') : null;
+    };
+    return Object.freeze({
+        repoRoot,
+        profile: side,
+        side,
+        edition: opened.repo.edition ?? 'full',
+        ...(sideRepo.grammar === undefined ? {} : { grammar: sideRepo.grammar }),
+        apps: sideRepo.apps,
+        connections: sideRepo.connections,
+        patterns: Object.freeze([...(sideRepo.patterns ?? [])]),
+        ruleParams: scope.ruleParams(),
+        relative: rel,
+        classify,
+        slotOf: (file) => classify(file).slot ?? null,
+        tierOf: (file) => (packageOf(file) === null ? null : 'package'),
+        // A package is no owner of the module laws (one index.ts at the owner root): its public surface is the `exports` of its manifest, so no file of it has an owner.
+        ownerOf: () => null,
+        allows: (file) => allowsFile(opened, rel(file)),
+        slot: (id) => opened.slot(id),
+    });
+}
+/**
+ * The view of the root packages of the app at `repoRoot` (the app root, where the root `eslint.config.mjs` lives), for the laws of `side`.
+ *
+ * @param {{ runtimeRoot: string, repoRoot: string, side: string }} input - Where the manifest copy lives, the app root, and the side whose laws apply.
+ * @returns {object} The frozen view.
+ */
+export const openPackagesHfsView = ({ runtimeRoot, repoRoot, side }) => packagesView(openHfs({ root: runtimeRoot, repoRoot }), repoRoot, side);
+/**
+ * The view of the root packages of an in-memory app declaration (rule tests): no file is read except the manifest.
+ *
+ * @param {{ runtimeRoot: string, declaration: object, repoRoot: string, side: string }} input - Manifest root, the app hfs.json object, the app root and the side.
+ * @returns {object} The frozen view.
+ */
+export const declaredPackagesHfsView = ({ runtimeRoot, declaration, repoRoot, side }) => packagesView(openHfs({ root: runtimeRoot, declaration }), repoRoot, side);

package/runtime/scripts/lib/declaration-surface.d.mts

@@ -26,6 +26,10 @@ export declare const DECLARATION: RegExp;
 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 package whose module-definition helpers return a type they state in their own declaration (R368 accepts a destructured export of their call). */
+export declare const STATED_SURFACE_PACKAGE = "@starci/nest-kit";
+/** The helpers of that package: each is called with the options type as a type argument and returns the explicitly typed definition. */
+export declare const STATED_SURFACE_HELPERS: ReadonlySet<string>;
 /**
  * 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

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

@@ -55,6 +55,52 @@ function returnsOnlyJsx(ts, source, start) {
     ts.forEachChild(fn.body, visit);
     return only;
 }
+/** The package whose module-definition helpers return a type they state in their own declaration (R368 accepts a destructured export of their call). */
+export const STATED_SURFACE_PACKAGE = '@starci/nest-kit';
+/** The helpers of that package: each is called with the options type as a type argument and returns the explicitly typed definition. */
+export const STATED_SURFACE_HELPERS = new Set(['defineConfigurableModule', 'defineCapabilityModule']);
+/** The local names under which `source` imports a stated-surface helper from its package (`import { defineConfigurableModule as define }` gives `define`). */
+function statedHelperNames(ts, source) {
+    const names = new Set();
+    for (const statement of source.statements) {
+        if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier) || statement.moduleSpecifier.text !== STATED_SURFACE_PACKAGE)
+            continue;
+        const bindings = statement.importClause?.namedBindings;
+        if (bindings === undefined || !ts.isNamedImports(bindings))
+            continue;
+        for (const element of bindings.elements)
+            if (STATED_SURFACE_HELPERS.has((element.propertyName ?? element.name).text))
+                names.add(element.name.text);
+    }
+    return names;
+}
+/**
+ * Whether the destructured export the diagnostic at `start` points at is `export const { A, B } = helper<Options>()` for a stated-surface helper:
+ * each name has the type the helper's declaration gives it, written there, so the file states its surface by naming the helper and the options
+ * type, exactly as `export const A: Host["A"] = built.A` states it through `Host`.
+ */
+function statesSurfaceThroughHelper(ts, source, start) {
+    const helpers = statedHelperNames(ts, source);
+    if (helpers.size === 0)
+        return null;
+    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.isVariableDeclaration(node))
+            continue;
+        const call = node.initializer;
+        const stated = ts.isObjectBindingPattern(node.name) && call !== undefined && ts.isCallExpression(call) && ts.isIdentifier(call.expression) && helpers.has(call.expression.text)
+            && (call.typeArguments?.length ?? 0) > 0 && node.name.elements.every((element) => ts.isIdentifier(element.name) && element.dotDotDotToken === undefined);
+        return stated && call !== undefined ? call.getText(source) : null;
+    }
+    return null;
+}
 /** 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'],
@@ -98,7 +144,14 @@ export function declarationSurface(ts, file, text, module) {
         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 = [];
+    // The emit writes `any` for a destructured export; the call that states its type joins the digest, so a change of the options type reaches the importers.
+    const stated = new Set();
     for (const diagnostic of diagnostics) {
+        const call = diagnostic.code === 9019 && diagnostic.start !== undefined ? statesSurfaceThroughHelper(ts, source, diagnostic.start) : null;
+        if (call !== null) {
+            stated.add(call);
+            continue;
+        }
         const exempt = (diagnostic.code === 9007 || diagnostic.code === 9008) && diagnostic.start !== undefined && returnsOnlyJsx(ts, source, diagnostic.start);
         if (exempt)
             continue;
@@ -108,5 +161,6 @@ export function declarationSurface(ts, file, text, module) {
             reason: ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n').split('\n')[0] ?? '',
         });
     }
-    return { outputText: declared.outputText, problems };
+    const outputText = stated.size === 0 ? declared.outputText : `${declared.outputText}${[...stated].sort().map((call) => `// stated by ${call}\n`).join('')}`;
+    return { outputText, problems };
 }

package/runtime/scripts/lib/secret-records.d.mts

@@ -0,0 +1,13 @@
+/** The cache folder of the secrets family, relative to the cache directory. */
+export declare const SECRETS_FOLDER = "check/secrets";
+/** A file of the secrets folder in a tracked tree: `.starcistacks/cache/check/secrets/<area>.jsonl` (an area is a folder path, so the file may sit in subfolders), at the app root or below one. */
+export declare const SECRETS_CACHE_FILE: RegExp;
+/** The finding codes of the secrets family: plaintext secrets, sealed custody, untracked secret files. */
+export declare const SECRET_CODES: ReadonlySet<string>;
+/** The stored form of a finding message: the digest of the message. A message already in that form is kept. */
+export declare function messageDigest(message: string): string;
+/**
+ * The faults of the text of a file of the secrets folder: every line is a record that holds codes, paths, positions and digests, and nothing
+ * else. An empty list means the file carries no secret material by construction.
+ */
+export declare function secretRecordFaults(text: string): string[];

package/runtime/scripts/lib/secret-records.mjs

@@ -0,0 +1,83 @@
+// secret-records.mjs - the contract of the secrets family's records in the committed check cache (contexts/project/check-cache.md, "The secrets
+// records"). The cache is committed, so what the secrets family writes may never be secret material: a record holds codes, paths, positions
+// and hashes. The finding's rule is one of the family's codes, its message is the sha256 prefix of the message the run printed (the identity
+// the new / known / fixed comparison needs), and the record carries no `data`. The cache writer (hfs cache/secret-records.mjs) projects its
+// records to this form; the secret judgement of R06 (scripts/hfs/rules/secrets.mjs, shared by `starci app check` and the commit hook) judges a
+// staged or tracked file of the folder by `secretRecordFaults`, so the file is accepted by what it holds and never by where it sits.
+import { createHash } from 'node:crypto';
+/** The cache folder of the secrets family, relative to the cache directory. */
+export const SECRETS_FOLDER = 'check/secrets';
+/** A file of the secrets folder in a tracked tree: `.starcistacks/cache/check/secrets/<area>.jsonl` (an area is a folder path, so the file may sit in subfolders), at the app root or below one. */
+export const SECRETS_CACHE_FILE = /(?:^|\/)\.starcistacks\/cache\/check\/secrets\/.+\.jsonl$/;
+/** The finding codes of the secrets family: plaintext secrets, sealed custody, untracked secret files. */
+export const SECRET_CODES = new Set([
+    'HFS_PLAINTEXT_SECRET', 'HFS_SECRET_PLAINTEXT_FILE', 'HFS_SECRET_OUTSIDE_ENC', 'HFS_SCRIPT_PLAINTEXT_LOAD', 'HFS_LITE_SECRET_CUSTODY', 'HFS_IDENTITY_CUSTODY',
+    'HFS_AGE_KEY_CUSTODY', 'RT_SECRET_TRACKED', 'STACKS_SECRET_ENV_LITERAL', 'STACKS_SECRET_NOT_EXTERNAL', 'STACKS_SECRET_UNVERSIONED', 'SEALED_CUSTODY_LOCATION',
+    'APP_SECRET_IN_CI', 'CI_SECRET_SEALED', 'BE_LOG_SECRET', 'BE_SECRET_DEFAULT', 'HFS_DOCKER_SECRETS',
+]);
+/** The form a stored message takes: `sha256:` and the first 16 hex digits of the sha256 of the message. */
+const DIGEST = /^sha256:[0-9a-f]{16}$/;
+/** A path a record may name: a relative posix path without control characters, backslashes or colons, never absolute and never leaving the app. */
+const SAFE_PATH = /^(?!\/)(?!(?:.*\/)?\.\.(?:\/|$))[^\u0000-\u001f\\:]*$/u;
+/** The stored form of a finding message: the digest of the message. A message already in that form is kept. */
+export function messageDigest(message) {
+    return DIGEST.test(message) ? message : `sha256:${createHash('sha256').update(message).digest('hex').slice(0, 16)}`;
+}
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const isPath = (value) => typeof value === 'string' && SAFE_PATH.test(value);
+/** The faults of one parsed record of the secrets folder; an empty list is a record that carries no secret material. */
+function recordFaults(value, at) {
+    if (!isObject(value))
+        return [`${at} is not a record`];
+    const faults = [];
+    const extra = Object.keys(value).filter((key) => !['path', 'step', 'hash', 'findings'].includes(key));
+    if (extra.length > 0)
+        faults.push(`${at} carries ${extra.join(', ')}; a secrets record holds path, step, hash and findings only`);
+    if (!isPath(value['path']))
+        faults.push(`${at} path is not a relative posix path`);
+    if (value['step'] !== 'secrets')
+        faults.push(`${at} step is not "secrets"`);
+    if (typeof value['hash'] !== 'string' || !/^(?:[0-9a-f]{64}|absent)$/.test(value['hash']))
+        faults.push(`${at} hash is not a sha256`);
+    const findings = value['findings'];
+    if (!Array.isArray(findings))
+        return [...faults, `${at} findings is not a list`];
+    for (const finding of findings) {
+        if (!isObject(finding)) {
+            faults.push(`${at} holds a finding that is not an object`);
+            continue;
+        }
+        const keys = Object.keys(finding).sort().join(',');
+        if (keys !== 'column,line,message,path,rule')
+            faults.push(`${at} holds a finding with the keys ${keys}; a finding holds path, line, column, rule and message only`);
+        if (typeof finding['rule'] !== 'string' || !SECRET_CODES.has(finding['rule']))
+            faults.push(`${at} holds a finding whose rule is not a code of the secrets family`);
+        if (typeof finding['message'] !== 'string' || !DIGEST.test(finding['message']))
+            faults.push(`${at} holds a finding whose message is not a digest (sha256:<16 hex>)`);
+        if (!isPath(finding['path']))
+            faults.push(`${at} holds a finding whose path is not a relative posix path`);
+        if (!Number.isInteger(finding['line']) || !Number.isInteger(finding['column']))
+            faults.push(`${at} holds a finding whose position is not a pair of integers`);
+    }
+    return faults;
+}
+/**
+ * The faults of the text of a file of the secrets folder: every line is a record that holds codes, paths, positions and digests, and nothing
+ * else. An empty list means the file carries no secret material by construction.
+ */
+export function secretRecordFaults(text) {
+    const faults = [];
+    text.split('\n').forEach((raw, index) => {
+        const line = raw.endsWith('\r') ? raw.slice(0, -1) : raw;
+        if (line.trim() === '')
+            return;
+        const at = `line ${index + 1}`;
+        try {
+            faults.push(...recordFaults(JSON.parse(line), at));
+        }
+        catch {
+            faults.push(`${at} is not JSON`);
+        }
+    });
+    return faults;
+}

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-inbox-lite.mjs

@@ -218,8 +218,8 @@ export function addLiteWebhookInbox({ root, repo, noun, provider, values, now =
     const hasHandoffStorage = migrations.some((file) => /create\s+function\s+public\.event_bus_send\b/i.test(fs.readFileSync(path.join(migrationsDir, file), "utf8")));
     if (!hasHandoffStorage)
         planned[0].text = `${template("platform/migration.sql.tpl", renderValues)}\n${template("platform/client-operation-outcomes.sql.tpl", renderValues)}\n${planned[0].text}`; // the migration is the first planned file
-    // The sql tag and the database-function call (with its spec) the inbox and the event bus use; the lite starter leaves them out.
-    for (const file of ["database.sql.ts", "database.client.ts", "database.client.spec.ts"]) {
+    // The sql tag the inbox and the event bus use; the lite starter leaves it out.
+    for (const file of ["database.sql.ts"]) {
         const relative = `be/src/modules/platform/database/${file}`;
         if (fs.existsSync(path.join(root, ...relative.split("/"))))
             continue;

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;

package/scaffold/add-module.mjs

@@ -0,0 +1,232 @@
+// starci app add module <name> / starci app remove module <name> - a module package of the product's agent SDK and its registry.
+//
+// A module is a workspace package `packages/module-<name>` (`@<project>/module-<name>`) built on the product's agent SDK (`packages/agent-sdk`): its
+// template and workbench declaration (React-free, for the back end), and its workbench (drawn with Grammar alone). `add` writes the package from
+// templates/app/module, registers it (root `workspaces`, the app dependencies on the registry and the module) and re-renders the managed registry
+// package `packages/modules` (module-registry.mts, the same render `starci app sync` checks); `remove` reverses every one of those steps.
+import fs from 'node:fs';
+import path from 'node:path';
+import { TEMPLATES_DIR } from '../sync/index.mjs';
+import { readRepoDeclaration, loadSlotManifest } from '../runtime/scripts/hfs/slots.mjs';
+import { byCodeUnit } from '../report/order.mjs';
+import { ScaffoldError, pascalOf, camelOf } from './service.mjs';
+import { packageJsonText } from './app.mjs';
+import { MODULE_PREFIX, REGISTRY_DIR, SDK_DIR, moduleNames, registryFiles, upperOf } from './module-registry.mjs';
+const NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const TEMPLATE_DIR = path.join(TEMPLATES_DIR, 'app', 'module');
+const WORKSPACE_GLOB = 'packages/*';
+const read = (file) => JSON.parse(fs.readFileSync(file, 'utf8'));
+const sortedDependencies = (dependencies) => Object.fromEntries(Object.entries(dependencies).sort(([left], [right]) => byCodeUnit(left, right)));
+const listFiles = (dir, base = dir) => fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    const full = path.join(dir, entry.name);
+    return entry.isDirectory() ? listFiles(full, base) : [path.relative(base, full).split(path.sep).join('/')];
+});
+/** A template's text with `{{project}}`, `{{name}}`, `{{pascal}}`, `{{camel}}` and `{{upper}}` filled; any other placeholder is a defect of the template. */
+function fill(text, values, file) {
+    return text.replace(/\{\{([A-Za-z]\w*)\}\}/g, (whole, key) => {
+        const value = values[key];
+        if (value === undefined)
+            throw new ScaffoldError('HFS_ADD_PLACEHOLDER_UNKNOWN', `module template ${file} uses ${whole}, which add module does not provide`);
+        return value;
+    }).replace(/\r\n/g, '\n');
+}
+/** The package files written from code: the manifests are never template files. */
+function manifests(project, name, versions) {
+    const sdk = `@${project}/agent-sdk`;
+    const exports = {
+        '.': { types: './dist/index.d.ts', default: './dist/index.js' },
+        './template': { types: './dist/template/index.d.ts', default: './dist/template/index.js' },
+        './manifest': { types: './dist/manifest/index.d.ts', default: './dist/manifest/index.js' },
+        './workbench': { types: './dist/esm/workbench/index.d.ts', default: './dist/esm/workbench/index.js' },
+        './public': { types: './dist/esm/public/index.d.ts', default: './dist/esm/public/index.js' },
+    };
+    const packageJson = {
+        name: `@${project}/${MODULE_PREFIX}${name}`,
+        version: '0.0.0',
+        private: true,
+        description: `The ${pascalOf(name)} module on the ${project} agent SDK: its template (./template) and workbench declaration (./manifest), both React-free for the back end, its Grammar-only workbench (./workbench) and its public face (./public) for the front end.`,
+        exports,
+        scripts: { build: 'tsc -p tsconfig.build.json && tsc -p tsconfig.build.workbench.json', typecheck: 'tsc --noEmit --pretty false', test: 'jest --coverage' },
+        dependencies: { [sdk]: '*' },
+        peerDependencies: { '@starci/grammar': versions['@starci/grammar'], react: versions['react'] },
+        devDependencies: sortedDependencies({ '@types/jest': versions['@types/jest'] ?? '', '@types/react': versions['@types/react'] ?? '', jest: versions['jest'] ?? '', 'ts-jest': versions['ts-jest'] ?? '', typescript: versions['typescript'] ?? '' }),
+    };
+    const build = { rootDir: 'src', noEmit: false, declaration: true, types: [] };
+    return [
+        { relative: 'package.json', body: packageJsonText(packageJson) },
+        { relative: 'tsconfig.json', body: packageJsonText({ extends: '@starci/tsconfig/next.json', compilerOptions: { incremental: false, types: ['jest', 'node'] }, include: ['src/**/*.ts', 'src/**/*.tsx', 'src/**/*.json'], exclude: ['node_modules', 'dist'] }) },
+        { relative: 'tsconfig.build.json', body: packageJsonText({ extends: './tsconfig.json', compilerOptions: { ...build, outDir: 'dist', module: 'node16', moduleResolution: 'node16' }, exclude: ['node_modules', 'dist', 'src/**/*.spec.ts', 'src/workbench/**', 'src/public/**'] }) },
+        { relative: 'tsconfig.build.workbench.json', body: packageJsonText({ extends: './tsconfig.json', compilerOptions: { ...build, outDir: 'dist/esm' }, include: ['src/**/*.ts', 'src/**/*.tsx', 'src/**/*.json'], exclude: ['node_modules', 'dist', 'src/**/*.spec.ts'] }) },
+    ];
+}
+/** The versions a module package declares, read from the app's own manifests so it installs the one version of each. */
+function versionsOf(root, feAppFiles) {
+    const rootPackage = read(path.join(root, 'package.json'));
+    const all = { ...rootPackage.devDependencies, ...rootPackage.dependencies };
+    for (const file of feAppFiles)
+        Object.assign(all, read(file).dependencies);
+    const wanted = ['@starci/grammar', 'react', '@types/jest', '@types/react', 'jest', 'ts-jest', 'typescript'];
+    const missing = wanted.filter((name) => all[name] === undefined);
+    if (missing.length > 0)
+        throw new ScaffoldError('HFS_ADD_MODULE_PINS', `add module reads the versions of ${missing.join(', ')} from the app's manifests, which declare none of them`);
+    return Object.fromEntries(wanted.map((name) => [name, all[name]]));
+}
+/** The package.json of every front-end Next app of the app. */
+const feManifests = (root) => {
+    const apps = path.join(root, 'fe', 'apps');
+    if (!fs.existsSync(apps))
+        return [];
+    return fs.readdirSync(apps, { withFileTypes: true }).filter((entry) => entry.isDirectory() && fs.existsSync(path.join(apps, entry.name, 'package.json'))).map((entry) => path.join(apps, entry.name, 'package.json')).sort(byCodeUnit);
+};
+/** Everything a verb changes, snapshotted first so a failure leaves the tree as it was. */
+class Transaction {
+    before = new Map();
+    root;
+    constructor(root) { this.root = root; }
+    write(relative, body) {
+        const file = path.join(this.root, ...relative.split('/'));
+        if (!this.before.has(file))
+            this.before.set(file, fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, body);
+    }
+    remove(relative) {
+        const file = path.join(this.root, ...relative.split('/'));
+        if (!fs.existsSync(file))
+            return;
+        for (const inner of fs.statSync(file).isDirectory() ? listFiles(file).map((name) => path.join(file, ...name.split('/'))) : [file])
+            this.before.set(inner, fs.readFileSync(inner, 'utf8'));
+        fs.rmSync(file, { recursive: true, force: true });
+    }
+    rollback() {
+        for (const [file, text] of this.before) {
+            if (text === null)
+                fs.rmSync(file, { force: true });
+            else {
+                fs.mkdirSync(path.dirname(file), { recursive: true });
+                fs.writeFileSync(file, text);
+            }
+        }
+    }
+}
+function context(root, name) {
+    if (!NAME.test(String(name)))
+        throw new ScaffoldError('HFS_ADD_NAME_INVALID', `module name ${name} must be kebab-case (letters, digits and single dashes)`);
+    const declarationFile = path.join(root, 'hfs.json');
+    const packageFile = path.join(root, 'package.json');
+    if (!fs.existsSync(declarationFile) || !fs.existsSync(packageFile))
+        throw new ScaffoldError('HFS_ADD_NOT_AN_APP', 'a module verb runs at the app root containing hfs.json and package.json');
+    const repo = readRepoDeclaration(loadSlotManifest(), root);
+    return { project: repo.project, declarationFile, packageFile };
+}
+/** Sets or deletes one dependency of a manifest file, keeping the section sorted; answers whether the text changed. */
+function setDependency(tx, root, file, name, version) {
+    const manifest = read(file);
+    const current = manifest.dependencies ?? {};
+    if ((version === null && current[name] === undefined) || current[name] === version)
+        return false;
+    const next = { ...current };
+    if (version === null)
+        Reflect.deleteProperty(next, name);
+    else
+        next[name] = version;
+    manifest.dependencies = sortedDependencies(next);
+    tx.write(path.relative(root, file).split(path.sep).join('/'), packageJsonText(manifest));
+    return true;
+}
+/** Registers the modules on the app: the workspace glob, and the registry and module dependencies of the back end (the root manifest) and every front-end app. */
+function register(tx, root, project, packageFile, names, changed) {
+    const rootPackage = read(packageFile);
+    const workspaces = new Set(rootPackage.workspaces ?? []);
+    const others = fs.existsSync(path.join(root, 'packages')) && fs.readdirSync(path.join(root, 'packages')).some((entry) => !entry.startsWith(MODULE_PREFIX) && entry !== 'modules');
+    if (names.length > 0)
+        workspaces.add(WORKSPACE_GLOB);
+    else if (!others)
+        workspaces.delete(WORKSPACE_GLOB);
+    if ([...workspaces].join('|') !== (rootPackage.workspaces ?? []).join('|')) {
+        rootPackage.workspaces = [...workspaces];
+        tx.write('package.json', packageJsonText(rootPackage));
+        changed.push('package.json');
+    }
+    const registry = `@${project}/modules`;
+    if (setDependency(tx, root, packageFile, registry, names.length > 0 ? '*' : null))
+        changed.push('package.json');
+    for (const file of feManifests(root)) {
+        let touched = setDependency(tx, root, file, registry, names.length > 0 ? '*' : null);
+        const present = Object.keys(read(file).dependencies ?? {}).filter((dependency) => dependency.startsWith(`@${project}/${MODULE_PREFIX}`));
+        for (const dependency of present)
+            if (!names.some((name) => `@${project}/${MODULE_PREFIX}${name}` === dependency))
+                touched = setDependency(tx, root, file, dependency, null) || touched;
+        for (const name of names)
+            touched = setDependency(tx, root, file, `@${project}/${MODULE_PREFIX}${name}`, '*') || touched;
+        if (touched)
+            changed.push(path.relative(root, file).split(path.sep).join('/'));
+    }
+}
+/** Replaces the registry package by the render of `names`: files written, and a registry of no module deleted. */
+function writeRegistry(tx, root, project, names, result) {
+    const files = registryFiles(project, names);
+    if (files.length === 0) {
+        if (fs.existsSync(path.join(root, REGISTRY_DIR))) {
+            tx.remove(REGISTRY_DIR);
+            result.removed.push(REGISTRY_DIR);
+        }
+        return;
+    }
+    for (const file of files) {
+        (fs.existsSync(path.join(root, file.path)) ? result.updated : result.created).push(file.path);
+        tx.write(file.path, file.content);
+    }
+}
+/** 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 function addModule({ root, name }) {
+    const { project, packageFile } = context(root, name);
+    if (!fs.existsSync(path.join(root, SDK_DIR, 'package.json')))
+        throw new ScaffoldError('HFS_ADD_MODULE_SDK_MISSING', `a module is built on the product's agent SDK, which must exist as ${SDK_DIR}/ (a workspace package named @${project}/agent-sdk)`);
+    const folder = `packages/${MODULE_PREFIX}${name}`;
+    if (fs.existsSync(path.join(root, folder)))
+        throw new ScaffoldError('HFS_ADD_EXISTS', `module ${name} already exists: ${folder}`);
+    const values = { project, name, pascal: pascalOf(name), camel: camelOf(name), upper: upperOf(name) };
+    const planned = [
+        ...manifests(project, name, versionsOf(root, feManifests(root))),
+        ...listFiles(TEMPLATE_DIR).map((file) => ({
+            relative: file.replace(/\.tpl$/, '').split('/').map((segment) => segment.replace('__name__', name).replace('__pascal__', values.pascal)).join('/'),
+            body: fill(fs.readFileSync(path.join(TEMPLATE_DIR, ...file.split('/')), 'utf8'), values, file),
+        })),
+    ];
+    const result = { created: planned.map((file) => `${folder}/${file.relative}`), updated: [], removed: [] };
+    const tx = new Transaction(root);
+    try {
+        for (const file of planned)
+            tx.write(`${folder}/${file.relative}`, file.body);
+        const names = moduleNames(root);
+        register(tx, root, project, packageFile, names, result.updated);
+        writeRegistry(tx, root, project, names, result);
+    }
+    catch (error) {
+        tx.rollback();
+        fs.rmSync(path.join(root, folder), { recursive: true, force: true });
+        throw error;
+    }
+    return result;
+}
+/** Removes the module package `name`, its registrations and its entry in the registry; the last module takes the registry package with it. */
+export function removeModule({ root, name }) {
+    const { project, packageFile } = context(root, name);
+    const folder = `packages/${MODULE_PREFIX}${name}`;
+    if (!fs.existsSync(path.join(root, folder)))
+        throw new ScaffoldError('HFS_REMOVE_NOT_FOUND', `module ${name} does not exist: ${folder}`);
+    const result = { created: [], updated: [], removed: [folder] };
+    const tx = new Transaction(root);
+    try {
+        tx.remove(folder);
+        const names = moduleNames(root);
+        register(tx, root, project, packageFile, names, result.updated);
+        writeRegistry(tx, root, project, names, result);
+    }
+    catch (error) {
+        tx.rollback();
+        throw error;
+    }
+    return result;
+}