@starci/hfs 4.11.21 → 4.12.0

package/runtime/scripts/hfs/declaration-shape.d.mts

@@ -0,0 +1,3 @@
+import type { Parsed } from './manifest-shape.mjs';
+/** Shape problems of a parsed hfs.json, in the words of modules/schemas/hfs-repo.schema.yaml. */
+export declare function declarationShapeProblems(declaration: Parsed, profiles: Parsed): string[];

package/runtime/scripts/hfs/declaration-shape.mjs

@@ -1,142 +1,179 @@
-// declaration-shape.mjs - the dependency-free hfs.json shape validation used by the HFS slot loader. Semantic checks
-// against a loaded manifest remain in slots.mjs; this module mirrors modules/schemas/hfs-repo.schema.yaml only.
 import { isPlainObject } from '../../engine/plain-object.mjs';
 import { APP_KIND, connectionShapeProblems, NAME, PACKAGE_NAME, RUNTIME_KIND, SLOT_ID } from './manifest-shape.mjs';
 import { dbFunctionsOk } from './rule-params-shape.mjs';
 import { kindShapeProblems, patternShapeProblems } from './declaration-slots.mjs';
 import { byCodeUnit } from '../lib/list.mjs';
-
 /** Shape problems of the optional hfs.json `db` block of a lite app: the environment variable naming its database, its image, forced RLS and its application role. */
 const isStringList = (value) => Array.isArray(value) && value.every((entry) => typeof entry === 'string' && entry.trim());
-
 function dbBlockProblems(block) {
-  if (block === undefined) return [];
-  if (!isPlainObject(block)) return ['db must be an object'];
-  const bad = [];
-  for (const key of Object.keys(block)) if (!['urlEnv', 'image', 'forceRls', 'forceRlsExemptions', 'appRole'].includes(key)) bad.push(`db has unknown key ${key}`);
-  if (block.urlEnv !== undefined && (typeof block.urlEnv !== 'string' || !/^[A-Z][A-Z0-9_]*$/.test(block.urlEnv))) bad.push('db.urlEnv must name an UPPER_CASE environment variable');
-  if (block.image !== undefined && (typeof block.image !== 'string' || !/@sha256:[0-9a-f]{64}$/.test(block.image))) bad.push('db.image must be a digest-pinned image reference');
-  if (block.forceRls !== undefined && !isStringList(block.forceRls)) bad.push('db.forceRls must be a list of strings');
-  if (block.appRole !== undefined && (typeof block.appRole !== 'string' || !/^[a-z][a-z0-9_]*$/.test(block.appRole))) bad.push('db.appRole must name a role');
-  if (block.forceRlsExemptions !== undefined && !Array.isArray(block.forceRlsExemptions)) bad.push('db.forceRlsExemptions must be a list of { table, reason }');
-  return bad;
+    if (block === undefined)
+        return [];
+    if (!isPlainObject(block))
+        return ['db must be an object'];
+    const bad = [];
+    for (const key of Object.keys(block))
+        if (!['urlEnv', 'image', 'forceRls', 'forceRlsExemptions', 'appRole'].includes(key))
+            bad.push(`db has unknown key ${key}`);
+    if (block.urlEnv !== undefined && (typeof block.urlEnv !== 'string' || !/^[A-Z][A-Z0-9_]*$/.test(block.urlEnv)))
+        bad.push('db.urlEnv must name an UPPER_CASE environment variable');
+    if (block.image !== undefined && (typeof block.image !== 'string' || !/@sha256:[0-9a-f]{64}$/.test(block.image)))
+        bad.push('db.image must be a digest-pinned image reference');
+    if (block.forceRls !== undefined && !isStringList(block.forceRls))
+        bad.push('db.forceRls must be a list of strings');
+    if (block.appRole !== undefined && (typeof block.appRole !== 'string' || !/^[a-z][a-z0-9_]*$/.test(block.appRole)))
+        bad.push('db.appRole must name a role');
+    if (block.forceRlsExemptions !== undefined && !Array.isArray(block.forceRlsExemptions))
+        bad.push('db.forceRlsExemptions must be a list of { table, reason }');
+    return bad;
 }
-
 function appShapeProblems(apps, at, side, names) {
-  const bad = [];
-  if (!Array.isArray(apps) || !apps.length) {
-    bad.push(`${at}.apps must list every ${side}/apps/<name> with its kind`);
+    const bad = [];
+    if (!Array.isArray(apps) || !apps.length) {
+        bad.push(`${at}.apps must list every ${side}/apps/<name> with its kind`);
+        return bad;
+    }
+    apps.forEach((app, index) => {
+        if (!isPlainObject(app) || !NAME.test(String(app.name)) || !NAME.test(String(app.kind)) || Object.keys(app).some((key) => key !== 'name' && key !== 'kind'))
+            bad.push(`${at}.apps[${index}] must be {name, kind}`);
+        else if (names.has(app.name))
+            bad.push(`app ${app.name} is declared twice (${names.get(app.name)} and ${side})`);
+        else
+            names.set(app.name, side);
+    });
     return bad;
-  }
-  apps.forEach((app, index) => {
-    if (!isPlainObject(app) || !NAME.test(String(app.name)) || !NAME.test(String(app.kind)) || Object.keys(app).some((key) => key !== 'name' && key !== 'kind')) bad.push(`${at}.apps[${index}] must be {name, kind}`);
-    else if (names.has(app.name)) bad.push(`app ${app.name} is declared twice (${names.get(app.name)} and ${side})`);
-    else names.set(app.name, side);
-  });
-  return bad;
 }
-
 function connectionProblems(side, value) {
-  const bad = [];
-  if (side !== 'be') {
-    bad.push('connections belong to the be side');
-    return bad;
-  }
-  const list = Array.isArray(value.connections) ? value.connections : null;
-  const shape = connectionShapeProblems(list, value.apps);
-  if (shape.length) {
-    bad.push(...shape);
+    const bad = [];
+    if (side !== 'be') {
+        bad.push('connections belong to the be side');
+        return bad;
+    }
+    const list = Array.isArray(value.connections) ? value.connections : null;
+    const shape = connectionShapeProblems(list, value.apps);
+    if (shape.length) {
+        bad.push(...shape);
+        return bad;
+    }
+    if (new Set(list.map((connection) => connection.name)).size !== list.length)
+        bad.push('connections names must be unique');
+    for (const a of list)
+        for (const b of list)
+            if (a !== b && `${b.envPrefix}_`.startsWith(`${a.envPrefix}_`))
+                bad.push(`connections ${a.name} and ${b.name} share env keys (${a.envPrefix}_ covers ${b.envPrefix}_)`);
     return bad;
-  }
-  if (new Set(list.map((connection) => connection.name)).size !== list.length) bad.push('connections names must be unique');
-  for (const a of list) for (const b of list) if (a !== b && `${b.envPrefix}_`.startsWith(`${a.envPrefix}_`)) bad.push(`connections ${a.name} and ${b.name} share env keys (${a.envPrefix}_ covers ${b.envPrefix}_)`);
-  return bad;
 }
-
 /** Whether a declared list is present but not a list of distinct entries that all satisfy `valid`. */
 const isBadUniqueList = (list, valid) => list !== undefined && (!Array.isArray(list) || !list.every((entry) => valid(entry)) || new Set(list).size !== list.length);
-
 function validExtraPackage(entry) {
-  return isPlainObject(entry) && Object.keys(entry).every(key => key === 'name' || key === 'reason')
-    && typeof entry.name === 'string' && entry.name.length <= 214 && PACKAGE_NAME.test(entry.name)
-    && typeof entry.reason === 'string' && entry.reason.trim().length > 0;
+    return isPlainObject(entry) && Object.keys(entry).every(key => key === 'name' || key === 'reason')
+        && typeof entry.name === 'string' && entry.name.length <= 214 && PACKAGE_NAME.test(entry.name)
+        && typeof entry.reason === 'string' && entry.reason.trim().length > 0;
 }
-
 function extraPackageProblems(side, entries) {
-  if (entries === undefined) return [];
-  if (side !== 'fe') return ['extraPackages belong to the fe side'];
-  if (!Array.isArray(entries) || !entries.every(validExtraPackage)) return ['sides.fe.extraPackages must be a list of {name, reason} with a package name and a nonempty reason'];
-  return [];
+    if (entries === undefined)
+        return [];
+    if (side !== 'fe')
+        return ['extraPackages belong to the fe side'];
+    if (!Array.isArray(entries) || !entries.every(validExtraPackage))
+        return ['sides.fe.extraPackages must be a list of {name, reason} with a package name and a nonempty reason'];
+    return [];
 }
-
 function grammarProblems(side, grammar) {
-  if (grammar === undefined) return [];
-  if (side !== 'fe') return ['grammar belongs to the fe side'];
-  return typeof grammar === 'string' && NAME.test(grammar) ? [] : ['sides.fe.grammar must name a Grammar family'];
+    if (grammar === undefined)
+        return [];
+    if (side !== 'fe')
+        return ['grammar belongs to the fe side'];
+    return typeof grammar === 'string' && NAME.test(grammar) ? [] : ['sides.fe.grammar must name a Grammar family'];
 }
-
 function declarationSideProblems(side, value, names) {
-  const bad = [];
-  const at = `sides.${side}`;
-  if (!isPlainObject(value)) return [`${at} must be an object`];
-  for (const key of Object.keys(value)) if (!['apps', 'optionalSlots', 'patterns', 'kinds', 'connections', 'reads', 'extraPackages', 'grammar', 'backing', 'dbFunctions'].includes(key)) bad.push(`${at} has unknown key ${key}`);
-  if (value.dbFunctions !== undefined && (side !== 'be' || !dbFunctionsOk(value.dbFunctions, { bare: true }))) bad.push(`${at}.dbFunctions belongs to the be side and lists {name, reason} database functions, each schema-qualified (schema.name, never pg_catalog) or a bare pg built-in of the canon's list, with unique names`);
-  bad.push(...appShapeProblems(value.apps, at, side, names));
-  if (isBadUniqueList(value.optionalSlots, (slot) => SLOT_ID.test(String(slot)))) bad.push(`${at}.optionalSlots must be a unique list of slot ids`);
-  if (value.backing !== undefined && side !== 'be') bad.push('backing belongs to the be side');
-  else if (isBadUniqueList(value.backing, (name) => NAME.test(String(name)))) bad.push(`${at}.backing must be a unique list of backing service names`);
-  bad.push(...patternShapeProblems(value, at, NAME), ...kindShapeProblems(value, at, NAME));
-  if (isBadUniqueList(value.reads, (read) => typeof read === 'string' && read.length > 0)) bad.push(`${at}.reads must be a unique list of paths`);
-  if (value.connections !== undefined) bad.push(...connectionProblems(side, value));
-  bad.push(...extraPackageProblems(side, value.extraPackages), ...grammarProblems(side, value.grammar));
-  return bad;
+    const bad = [];
+    const at = `sides.${side}`;
+    if (!isPlainObject(value))
+        return [`${at} must be an object`];
+    for (const key of Object.keys(value))
+        if (!['apps', 'optionalSlots', 'patterns', 'kinds', 'connections', 'reads', 'extraPackages', 'grammar', 'backing', 'dbFunctions'].includes(key))
+            bad.push(`${at} has unknown key ${key}`);
+    if (value.dbFunctions !== undefined && (side !== 'be' || !dbFunctionsOk(value.dbFunctions, { bare: true })))
+        bad.push(`${at}.dbFunctions belongs to the be side and lists {name, reason} database functions, each schema-qualified (schema.name, never pg_catalog) or a bare pg built-in of the canon's list, with unique names`);
+    bad.push(...appShapeProblems(value.apps, at, side, names));
+    if (isBadUniqueList(value.optionalSlots, (slot) => SLOT_ID.test(String(slot))))
+        bad.push(`${at}.optionalSlots must be a unique list of slot ids`);
+    if (value.backing !== undefined && side !== 'be')
+        bad.push('backing belongs to the be side');
+    else if (isBadUniqueList(value.backing, (name) => NAME.test(String(name))))
+        bad.push(`${at}.backing must be a unique list of backing service names`);
+    bad.push(...patternShapeProblems(value, at, NAME), ...kindShapeProblems(value, at, NAME));
+    if (isBadUniqueList(value.reads, (read) => typeof read === 'string' && read.length > 0))
+        bad.push(`${at}.reads must be a unique list of paths`);
+    if (value.connections !== undefined)
+        bad.push(...connectionProblems(side, value));
+    bad.push(...extraPackageProblems(side, value.extraPackages), ...grammarProblems(side, value.grammar));
+    return bad;
 }
-
 /** Product vocabulary is a declaration, never a switch for a rule. */
 function lexiconBlockProblems(lexicon) {
-  if (lexicon === undefined) return [];
-  if (!isPlainObject(lexicon)) return ['lexicon must be an object'];
-  const bad = [];
-  for (const key of Object.keys(lexicon)) if (key !== 'removed') bad.push(`lexicon has unknown key ${key}`);
-  if (isBadUniqueList(lexicon.removed, (word) => typeof word === 'string' && word.trim().length > 0)) bad.push('lexicon.removed must be a unique list of nonempty words');
-  return bad;
+    if (lexicon === undefined)
+        return [];
+    if (!isPlainObject(lexicon))
+        return ['lexicon must be an object'];
+    const bad = [];
+    for (const key of Object.keys(lexicon))
+        if (key !== 'removed')
+            bad.push(`lexicon has unknown key ${key}`);
+    if (isBadUniqueList(lexicon.removed, (word) => typeof word === 'string' && word.trim().length > 0))
+        bad.push('lexicon.removed must be a unique list of nonempty words');
+    return bad;
 }
-
 /** Front-end error reporting remains optional in both editions. */
 function observeBlockProblems(observe) {
-  if (observe === undefined) return [];
-  if (!isPlainObject(observe)) return ['observe must be an object'];
-  const bad = [];
-  for (const key of Object.keys(observe)) if (key !== 'reporter') bad.push(`observe has unknown key ${key}`);
-  if (observe.reporter !== undefined && (typeof observe.reporter !== 'string' || !observe.reporter.trim())) bad.push('observe.reporter must name the optional error reporter');
-  return bad;
+    if (observe === undefined)
+        return [];
+    if (!isPlainObject(observe))
+        return ['observe must be an object'];
+    const bad = [];
+    for (const key of Object.keys(observe))
+        if (key !== 'reporter')
+            bad.push(`observe has unknown key ${key}`);
+    if (observe.reporter !== undefined && (typeof observe.reporter !== 'string' || !observe.reporter.trim()))
+        bad.push('observe.reporter must name the optional error reporter');
+    return bad;
 }
-
 const DECLARATION_KEYS = new Set(['hfs', 'kind', 'project', 'edition', 'db', 'sides', 'browser', 'lexicon', 'observe']);
 const RUNTIME_DECLARATION_KEYS = new Set(['hfs', 'kind', 'project']);
-
 function productDeclarationProblems(declaration, profiles) {
-  const bad = [];
-  for (const key of Object.keys(declaration)) if (!DECLARATION_KEYS.has(key)) bad.push(`unknown key ${key}`);
-  bad.push(...dbBlockProblems(declaration.db), ...lexiconBlockProblems(declaration.lexicon), ...observeBlockProblems(declaration.observe));
-  if (declaration.browser !== undefined && declaration.browser !== true) bad.push('browser is `true` when the app has a browser journey (slot app.browser), and is left out otherwise');
-  if (declaration.kind !== APP_KIND) bad.push(`kind must be ${APP_KIND} (a product is one app repository with a be and an fe side) or ${RUNTIME_KIND} (the StarCi runtime repository)`);
-  if (!isPlainObject(declaration.sides) || Object.keys(declaration.sides).sort(byCodeUnit).join() !== profiles.join()) { bad.push('sides must declare exactly be and fe'); return bad; }
-  const names = new Map();
-  for (const side of profiles) bad.push(...declarationSideProblems(side, declaration.sides[side], names));
-  return bad;
+    const bad = [];
+    for (const key of Object.keys(declaration))
+        if (!DECLARATION_KEYS.has(key))
+            bad.push(`unknown key ${key}`);
+    bad.push(...dbBlockProblems(declaration.db), ...lexiconBlockProblems(declaration.lexicon), ...observeBlockProblems(declaration.observe));
+    if (declaration.browser !== undefined && declaration.browser !== true)
+        bad.push('browser is `true` when the app has a browser journey (slot app.browser), and is left out otherwise');
+    if (declaration.kind !== APP_KIND)
+        bad.push(`kind must be ${APP_KIND} (a product is one app repository with a be and an fe side) or ${RUNTIME_KIND} (the StarCi runtime repository)`);
+    if (!isPlainObject(declaration.sides) || Object.keys(declaration.sides).sort(byCodeUnit).join() !== profiles.join()) {
+        bad.push('sides must declare exactly be and fe');
+        return bad;
+    }
+    const names = new Map();
+    for (const side of profiles)
+        bad.push(...declarationSideProblems(side, declaration.sides[side], names));
+    return bad;
 }
-
 /** Shape problems of a parsed hfs.json, in the words of modules/schemas/hfs-repo.schema.yaml. */
 export function declarationShapeProblems(declaration, profiles) {
-  const bad = [];
-  if (!isPlainObject(declaration)) return ['hfs.json is not an object'];
-  if (!(Number.isInteger(declaration.hfs) && declaration.hfs >= 1)) bad.push('hfs must be the pinned manifest major (an integer, 1 or more)');
-  if (!NAME.test(String(declaration.project))) bad.push('project must be a project name');
-  if (declaration.kind === RUNTIME_KIND) {
-    for (const key of Object.keys(declaration)) if (!RUNTIME_DECLARATION_KEYS.has(key)) bad.push(`unknown key ${key} (a runtime declaration is {hfs, kind, project})`);
+    const bad = [];
+    if (!isPlainObject(declaration))
+        return ['hfs.json is not an object'];
+    if (!(Number.isInteger(declaration.hfs) && declaration.hfs >= 1))
+        bad.push('hfs must be the pinned manifest major (an integer, 1 or more)');
+    if (!NAME.test(String(declaration.project)))
+        bad.push('project must be a project name');
+    if (declaration.kind === RUNTIME_KIND) {
+        for (const key of Object.keys(declaration))
+            if (!RUNTIME_DECLARATION_KEYS.has(key))
+                bad.push(`unknown key ${key} (a runtime declaration is {hfs, kind, project})`);
+        return bad;
+    }
+    bad.push(...productDeclarationProblems(declaration, profiles));
     return bad;
-  }
-  bad.push(...productDeclarationProblems(declaration, profiles));
-  return bad;
 }

package/runtime/scripts/hfs/declaration-slots.d.mts

@@ -0,0 +1,18 @@
+import type { Parsed, Slot } from './manifest-shape.mjs';
+import type { RepoView } from './slots.mjs';
+/** The problems of a side's `optionalSlots` and `patterns` against the manifest. */
+export declare function optionalSlotProblems(manifest: Parsed, side: Parsed, s: Parsed): string[];
+/** The problems of a side's `backing` list: every name is admitted by ruleParams.be.backing in this edition. */
+export declare function backingProblems(manifest: Parsed, side: string, s: Parsed, edition?: string): string[];
+/** The problems of the shape of a side's `patterns` list (a unique list of pattern names). */
+export declare function patternShapeProblems(s: Parsed, at: Parsed, namePattern: Parsed): string[];
+/** The problems of the shape of a side's `kinds` list (a unique list of trigger kind names). */
+export declare function kindShapeProblems(s: Parsed, at: Parsed, namePattern: Parsed): string[];
+/** The problems of `ruleParams.be.kindPatterns` (trigger kind -> patterns) and `ruleParams.be.addKinds` (starci app add noun -> {topic, variable, patterns, trigger?, needs?, also?, defaults?, wire?}). */
+export declare function kindParamProblems(be: Parsed, triggerKinds: Parsed): string[];
+/** The problems of `ruleParams.be.patternScenarios`: a pattern name to a non-empty list of unique kebab-case scenario ids. */
+export declare function scenarioProblem(scenarios: Parsed): string[];
+/** The problems of the `trigger` of a slot against the manifest's `triggerKinds`: a known kind, on a feature-tier slot only. */
+export declare function triggerProblems(slot: Parsed, triggerKinds: Parsed): string[];
+/** Whether an opt-in slot is enabled for the repository: by its app kind, by a connection's provider, by name in optionalSlots, or by its declared pattern. */
+export declare function declaredSlotEnabled(slot: Pick<Slot, 'id' | 'appKind' | 'provider' | 'pattern'>, repo: Pick<RepoView, 'apps' | 'optionalSlots' | 'providers' | 'connections' | 'patterns'>): boolean;

package/runtime/scripts/hfs/declaration-slots.mjs

@@ -1,86 +1,89 @@
-// declaration-slots.mjs - how an app declaration (hfs.json) switches on the opt-in slots of a side: by name (`optionalSlots`), by app kind
-// (a slot with `appKind`) and by declared pattern (a slot with `pattern: <name>` is enabled by `sides.<side>.patterns: [<name>]`, one
-// mechanism for pattern slots). A cross-cutting pattern can instead be owned by the side's canonical proof scenario catalog.
-// slots.mjs asks this file to judge a side's lists and to say whether a slot is enabled for a repository.
 import { judgedInEdition } from './edition-slots.mjs';
-
 /** The problems of a side's `optionalSlots` and `patterns` against the manifest. */
 export function optionalSlotProblems(manifest, side, s) {
-  const bad = [];
-  for (const id of s.optionalSlots ?? []) {
-    const slot = manifest.slots.find((candidate) => candidate.id === id);
-    if (!slot?.profiles.includes(side)) bad.push(`sides.${side}.optionalSlots names ${id}, which is not a ${side} slot`);
-    else if (slot.presence !== 'opt-in') bad.push(`sides.${side}.optionalSlots names ${id}, which is ${slot.presence}, not opt-in`);
-    else if (slot.appKind !== undefined) bad.push(`sides.${side}.optionalSlots names ${id}; an app of kind ${slot.appKind} enables it`);
-  }
-  for (const name of s.patterns ?? []) {
-    const ownsSlot = manifest.slots.some((slot) => slot.profiles.includes(side) && slot.pattern === name);
-    const ownsProof = Object.hasOwn(manifest.ruleParams?.[side]?.patternScenarios ?? {}, name);
-    if (!ownsSlot && !ownsProof) bad.push(`sides.${side}.patterns names ${name}, which neither a ${side} slot nor its proof scenario catalog declares`);
-  }
-  if (s.kinds !== undefined && side !== 'be') bad.push(`sides.${side}.kinds belongs to the be side`);
-  for (const kind of s.kinds ?? []) {
-    if (!(manifest.triggerKinds ?? []).includes(kind)) bad.push(`sides.${side}.kinds names ${kind}, which is not one of triggerKinds (${(manifest.triggerKinds ?? []).join(', ')})`);
-  }
-  return bad;
+    const bad = [];
+    for (const id of s.optionalSlots ?? []) {
+        const slot = manifest.slots.find((candidate) => candidate.id === id);
+        if (!slot?.profiles.includes(side))
+            bad.push(`sides.${side}.optionalSlots names ${id}, which is not a ${side} slot`);
+        else if (slot.presence !== 'opt-in')
+            bad.push(`sides.${side}.optionalSlots names ${id}, which is ${slot.presence}, not opt-in`);
+        else if (slot.appKind !== undefined)
+            bad.push(`sides.${side}.optionalSlots names ${id}; an app of kind ${slot.appKind} enables it`);
+    }
+    for (const name of s.patterns ?? []) {
+        const ownsSlot = manifest.slots.some((slot) => slot.profiles.includes(side) && slot.pattern === name);
+        const ownsProof = Object.hasOwn(manifest.ruleParams?.[side]?.patternScenarios ?? {}, name);
+        if (!ownsSlot && !ownsProof)
+            bad.push(`sides.${side}.patterns names ${name}, which neither a ${side} slot nor its proof scenario catalog declares`);
+    }
+    if (s.kinds !== undefined && side !== 'be')
+        bad.push(`sides.${side}.kinds belongs to the be side`);
+    for (const kind of s.kinds ?? []) {
+        if (!(manifest.triggerKinds ?? []).includes(kind))
+            bad.push(`sides.${side}.kinds names ${kind}, which is not one of triggerKinds (${(manifest.triggerKinds ?? []).join(', ')})`);
+    }
+    return bad;
 }
-
 /** The problems of a side's `backing` list: every name is admitted by ruleParams.be.backing in this edition. */
 export function backingProblems(manifest, side, s, edition = 'full') {
-  const services = Object.entries(manifest.ruleParams?.be?.backing ?? {})
-    .filter(([, entry]) => judgedInEdition(entry, edition)).map(([name]) => name);
-  return (s.backing ?? []).filter((name) => !services.includes(name))
-    .map((name) => `sides.${side}.backing names ${name}, which is not admitted in edition ${edition} by ruleParams.be.backing (${services.join(', ')})`);
+    const services = Object.entries(manifest.ruleParams?.be?.backing ?? {})
+        .filter(([, entry]) => judgedInEdition(entry, edition)).map(([name]) => name);
+    return (s.backing ?? []).filter((name) => !services.includes(name))
+        .map((name) => `sides.${side}.backing names ${name}, which is not admitted in edition ${edition} by ruleParams.be.backing (${services.join(', ')})`);
 }
-
 /** The problems of the shape of a side's `patterns` list (a unique list of pattern names). */
 export function patternShapeProblems(s, at, namePattern) {
-  const list = s.patterns;
-  if (list === undefined) return [];
-  return Array.isArray(list) && list.every((value) => namePattern.test(String(value))) && new Set(list).size === list.length ? [] : [`${at}.patterns must be a unique list of pattern names`];
+    const list = s.patterns;
+    if (list === undefined)
+        return [];
+    return Array.isArray(list) && list.every((value) => namePattern.test(String(value))) && new Set(list).size === list.length ? [] : [`${at}.patterns must be a unique list of pattern names`];
 }
-
 /** The problems of the shape of a side's `kinds` list (a unique list of trigger kind names). */
 export function kindShapeProblems(s, at, namePattern) {
-  const list = s.kinds;
-  if (list === undefined) return [];
-  return Array.isArray(list) && list.every((value) => namePattern.test(String(value))) && new Set(list).size === list.length ? [] : [`${at}.kinds must be a unique list of trigger kind names`];
+    const list = s.kinds;
+    if (list === undefined)
+        return [];
+    return Array.isArray(list) && list.every((value) => namePattern.test(String(value))) && new Set(list).size === list.length ? [] : [`${at}.kinds must be a unique list of trigger kind names`];
 }
-
 /** The problems of `ruleParams.be.kindPatterns` (trigger kind -> patterns) and `ruleParams.be.addKinds` (starci app add noun -> {topic, variable, patterns, trigger?, needs?, also?, defaults?, wire?}). */
 export function kindParamProblems(be, triggerKinds) {
-  const kebab = /^[a-z][a-z0-9-]*$/;
-  const names = (list) => Array.isArray(list) && list.every((value) => kebab.test(String(value))) && new Set(list).size === list.length;
-  const bad = [];
-  const patterns = be.kindPatterns;
-  if (patterns === null || typeof patterns !== 'object' || Array.isArray(patterns) || !Object.entries(patterns).every(([kind, list]) => (triggerKinds ?? []).includes(kind) && names(list))) bad.push('ruleParams.be.kindPatterns must map a trigger kind to a unique list of pattern names');
-  const nouns = be.addKinds;
-  const nounOk = (spec) => spec !== null && typeof spec === 'object' && kebab.test(String(spec.topic)) && kebab.test(String(spec.variable)) && names(spec.patterns) && (spec.trigger === undefined || kebab.test(String(spec.trigger))) && (spec.needs === undefined || names(spec.needs)) && (spec.also === undefined || names(spec.also)) && (spec.defaults === undefined || (typeof spec.defaults === 'object' && !Array.isArray(spec.defaults))) && (spec.wire === undefined || (spec.wire !== null && typeof spec.wire === 'object' && ['file', 'import', 'symbol'].every((key) => typeof spec.wire[key] === 'string' && spec.wire[key] !== '')));
-  if (nouns === null || typeof nouns !== 'object' || Array.isArray(nouns) || !Object.entries(nouns).every(([noun, spec]) => kebab.test(noun) && nounOk(spec))) bad.push('ruleParams.be.addKinds must map a noun to {topic, variable, patterns, trigger?, needs?, also?, defaults?}');
-  return bad;
+    const kebab = /^[a-z][a-z0-9-]*$/;
+    const names = (list) => Array.isArray(list) && list.every((value) => kebab.test(String(value))) && new Set(list).size === list.length;
+    const bad = [];
+    const patterns = be.kindPatterns;
+    if (patterns === null || typeof patterns !== 'object' || Array.isArray(patterns) || !Object.entries(patterns).every(([kind, list]) => (triggerKinds ?? []).includes(kind) && names(list)))
+        bad.push('ruleParams.be.kindPatterns must map a trigger kind to a unique list of pattern names');
+    const nouns = be.addKinds;
+    const nounOk = (spec) => spec !== null && typeof spec === 'object' && kebab.test(String(spec.topic)) && kebab.test(String(spec.variable)) && names(spec.patterns) && (spec.trigger === undefined || kebab.test(String(spec.trigger))) && (spec.needs === undefined || names(spec.needs)) && (spec.also === undefined || names(spec.also)) && (spec.defaults === undefined || (typeof spec.defaults === 'object' && !Array.isArray(spec.defaults))) && (spec.wire === undefined || (spec.wire !== null && typeof spec.wire === 'object' && ['file', 'import', 'symbol'].every((key) => typeof spec.wire[key] === 'string' && spec.wire[key] !== '')));
+    if (nouns === null || typeof nouns !== 'object' || Array.isArray(nouns) || !Object.entries(nouns).every(([noun, spec]) => kebab.test(noun) && nounOk(spec)))
+        bad.push('ruleParams.be.addKinds must map a noun to {topic, variable, patterns, trigger?, needs?, also?, defaults?}');
+    return bad;
 }
-
 /** The problems of `ruleParams.be.patternScenarios`: a pattern name to a non-empty list of unique kebab-case scenario ids. */
 export function scenarioProblem(scenarios) {
-  const kebab = /^[a-z][a-z0-9-]*$/;
-  const ok = scenarios !== null && typeof scenarios === 'object' && !Array.isArray(scenarios) && Object.entries(scenarios).every(([name, list]) => kebab.test(name) && Array.isArray(list) && list.length > 0 && list.every((id) => kebab.test(String(id))) && new Set(list).size === list.length);
-  return ok ? [] : ['ruleParams.be.patternScenarios must map a pattern name to a non-empty list of unique kebab-case scenario ids'];
+    const kebab = /^[a-z][a-z0-9-]*$/;
+    const ok = scenarios !== null && typeof scenarios === 'object' && !Array.isArray(scenarios) && Object.entries(scenarios).every(([name, list]) => kebab.test(name) && Array.isArray(list) && list.length > 0 && list.every((id) => kebab.test(String(id))) && new Set(list).size === list.length);
+    return ok ? [] : ['ruleParams.be.patternScenarios must map a pattern name to a non-empty list of unique kebab-case scenario ids'];
 }
-
 /** The problems of the `trigger` of a slot against the manifest's `triggerKinds`: a known kind, on a feature-tier slot only. */
 export function triggerProblems(slot, triggerKinds) {
-  if (slot.trigger === undefined) return [];
-  const bad = [];
-  if (!(triggerKinds ?? []).includes(slot.trigger)) bad.push(`slot ${slot.id}: trigger ${slot.trigger} is not one of triggerKinds`);
-  if (slot.tier !== 'feature') bad.push(`slot ${slot.id}: a trigger belongs to a feature-tier slot`);
-  return bad;
+    if (slot.trigger === undefined)
+        return [];
+    const bad = [];
+    if (!(triggerKinds ?? []).includes(slot.trigger))
+        bad.push(`slot ${slot.id}: trigger ${slot.trigger} is not one of triggerKinds`);
+    if (slot.tier !== 'feature')
+        bad.push(`slot ${slot.id}: a trigger belongs to a feature-tier slot`);
+    return bad;
 }
-
 /** Whether an opt-in slot is enabled for the repository: by its app kind, by a connection's provider, by name in optionalSlots, or by its declared pattern. */
 export function declaredSlotEnabled(slot, repo) {
-  if (slot.appKind !== undefined) return repo.apps.some((app) => app.kind === slot.appKind);
-  // A provider declared on any connection (be owns them all today) enables the provider slots of every profile: repo.providers
-  // is the app-wide union the declaration resolver computed; a hand-built repo falls back to its own connections.
-  if (slot.provider !== undefined) return (repo.providers ?? (repo.connections ?? []).map((connection) => connection.provider)).includes(slot.provider);
-  return repo.optionalSlots.includes(slot.id) || (slot.pattern !== undefined && (repo.patterns ?? []).includes(slot.pattern));
+    if (slot.appKind !== undefined)
+        return repo.apps.some((app) => app.kind === slot.appKind);
+    // A provider declared on any connection (be owns them all today) enables the provider slots of every profile: repo.providers
+    // is the app-wide union the declaration resolver computed; a hand-built repo falls back to its own connections.
+    if (slot.provider !== undefined)
+        return (repo.providers ?? (repo.connections ?? []).map((connection) => connection.provider)).includes(slot.provider);
+    return repo.optionalSlots.includes(slot.id) || (slot.pattern !== undefined && (repo.patterns ?? []).includes(slot.pattern));
 }

package/runtime/scripts/hfs/doc-commands.d.mts

@@ -0,0 +1,71 @@
+import { type CommandToken } from '../lib/command-tokens.mjs';
+/** One starci command occurrence in a text: `bounded` runs to the end of its span, `prose` keeps only the flags that follow the verb. */
+export interface CommandOccurrence {
+    line: number;
+    mode: 'bounded' | 'prose';
+    preceded: string;
+    text: string;
+}
+/** A whitespace token of a command (the command tokenizer's output). */
+export type { CommandToken };
+/** A declared flag of the command catalog. */
+export interface CatalogFlag {
+    name: string;
+    type: string;
+    enum?: string[];
+    [key: string]: unknown;
+}
+/** A declared positional of a verb. */
+export interface CatalogPositional {
+    name: string;
+    enum?: string[];
+    [key: string]: unknown;
+}
+/** A verb of the command catalog. */
+export interface CatalogVerb {
+    flags?: CatalogFlag[];
+    positional?: CatalogPositional[];
+    [key: string]: unknown;
+}
+/** A group of the command catalog; `self` is set when the group word is itself the whole command. */
+export interface CatalogGroup {
+    self?: CatalogVerb;
+    verbs: Record<string, CatalogVerb>;
+}
+/** The command catalog checkCommand reads. */
+export interface CommandCatalog {
+    global: CatalogFlag[];
+    groups: Record<string, CatalogGroup>;
+}
+/** The generated catalog's loaded form: { global: { flags }, groups: [{ group, verbs: [{ verb }] }] }. */
+export interface LoadedCatalog {
+    global: {
+        flags: CatalogFlag[];
+    };
+    groups: {
+        group: string;
+        verbs: ({
+            verb: string;
+        } & CatalogVerb)[];
+    }[];
+}
+/** The options of checkCommand, extractCommands. */
+export interface ExtractOptions {
+    kind?: string;
+    skipLine?: ((line: string) => boolean) | null;
+}
+/**
+ * Every starci command occurrence in one text.
+ * `bounded` occurrences (inside a code span, a fenced line, or a script string literal span) run to the end of that
+ * span; `prose` occurrences inside running text only keep the flags and values that follow the verb.
+ */
+export declare function extractCommands(text: string, { kind, skipLine }?: ExtractOptions): CommandOccurrence[];
+/**
+ * Returns [] when the command is a valid call (or a fragment of one), else the reasons it is not.
+ * `strictProse` holds a mention inside running text to the same group and verb as a span.
+ */
+export declare function checkCommand(occurrence: CommandOccurrence, catalog: CommandCatalog, { strictProse }?: {
+    strictProse?: boolean;
+}): string[];
+/** A catalog of the { global: { flags }, groups: [{ group, verbs: [{ verb }] }] } form in the shape checkCommand reads (packages/cli/src/catalog.generated.mjs already is). */
+export declare const commandCatalogOf: (loaded: LoadedCatalog) => CommandCatalog;