@starci/hfs 4.11.22 → 4.12.0

package/scaffold/add-compose.mjs

@@ -2,81 +2,81 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { TEMPLATES_DIR } from '../sync/index.mjs';
 import { ScaffoldError } from './service.mjs';
-
 /** Adds `importLine` and one `symbol` entry of the `imports` array of a module file's lines, once. */
 export function addModuleImport(lines, { importLine, entry, relative, noun }) {
-  const active = compositionCode(lines.join('\n')).split('\n');
-  const imported = active.some(line => line.replace(/;\s*$/, '') === importLine);
-  // An area group spread once is registered whatever its argument (the lite root passes `tokens.verify` to domainModules).
-  const group = /^\.\.\.(\w+Modules)\(/.exec(entry)?.[1];
-  const registered = active.some(line => line.trim() === `${entry},` ||
-    (group !== undefined && line.includes(`...${group}(`)) ||
-    (/\bimports:\s*\[/.test(line) && !line.trim().startsWith('//') && line.replace(/\s+/g, '').includes(entry.replace(/\s+/g, ''))));
-  const lastImport = active.reduce((last, line, index) => line.startsWith('import ') ? index : last, -1);
-  const importsLine = line => /\bimports:\s*\[/.test(line) && !line.trim().startsWith('//');
-  if (lastImport < 0 || active.findIndex(importsLine) < 0) throw new ScaffoldError('HFS_ADD_WIRE_INVALID', `add ${noun} could not find the imports array in ${relative}`);
-  if (imported && registered) return;
-  if (!imported) lines.splice(lastImport + 1, 0, importLine);
-  if (registered) return;
-  const imports = compositionCode(lines.join('\n')).split('\n').findIndex(importsLine);
-  const indent = /^(\s*)/.exec(lines[imports])?.[1] ?? '';
-  if (/^\s*imports: \[$/.test(lines[imports])) lines.splice(imports + 1, 0, `${indent}    ${entry},`);
-  else lines[imports] = lines[imports].replace(/(\bimports:\s*\[)\s*/, `$1${entry}, `);
+    const active = compositionCode(lines.join('\n')).split('\n');
+    const imported = active.some(line => line.replace(/;\s*$/, '') === importLine);
+    // An area group spread once is registered whatever its argument (the lite root passes `tokens.verify` to domainModules).
+    const group = /^\.\.\.(\w+Modules)\(/.exec(entry)?.[1];
+    const registered = active.some(line => line.trim() === `${entry},` ||
+        (group !== undefined && line.includes(`...${group}(`)) ||
+        (/\bimports:\s*\[/.test(line) && !line.trim().startsWith('//') && line.replace(/\s+/g, '').includes(entry.replace(/\s+/g, ''))));
+    const lastImport = active.reduce((last, line, index) => line.startsWith('import ') ? index : last, -1);
+    const importsLine = (line) => /\bimports:\s*\[/.test(line) && !line.trim().startsWith('//');
+    if (lastImport < 0 || active.findIndex(importsLine) < 0)
+        throw new ScaffoldError('HFS_ADD_WIRE_INVALID', `add ${noun} could not find the imports array in ${relative}`);
+    if (imported && registered)
+        return;
+    if (!imported)
+        lines.splice(lastImport + 1, 0, importLine);
+    if (registered)
+        return;
+    const imports = compositionCode(lines.join('\n')).split('\n').findIndex(importsLine);
+    const indent = /^(\s*)/.exec(lines[imports])?.[1] ?? '';
+    if (/^\s*imports: \[$/.test(lines[imports]))
+        lines.splice(imports + 1, 0, `${indent}    ${entry},`);
+    else
+        lines[imports] = lines[imports].replace(/(\bimports:\s*\[)\s*/, `$1${entry}, `);
 }
-
 /** Masks comments without changing offsets or treating quoted module specifiers as comments. */
 export function compositionCode(text) {
-  return text.replace(/"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|`(?:\\.|[^`\\])*`|\/\*[\s\S]*?\*\/|\/\/[^\n]*/g,
-    value => value.startsWith('/') ? value.replace(/[^\r\n]/g, ' ') : value);
+    return text.replace(/"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|`(?:\\.|[^`\\])*`|\/\*[\s\S]*?\*\/|\/\/[^\n]*/g, (value) => value.startsWith('/') ? value.replace(/[^\r\n]/g, ' ') : value);
 }
-
-
 /** Reads the explicitly typed expression body of a group without treating comments as active declarations. */
 export function readComposeGroup({ repoRoot, repo, app, area, noun }) {
-  const relative = `be/apps/${app}/src/compose/${area}.ts`;
-  const file = path.join(repoRoot, ...relative.split('/'));
-  const exists = fs.existsSync(file);
-  const skeleton = repo.edition === 'lite' ? 'skeleton-lite/apps/api' : 'skeleton/apps/__app__';
-  const template = path.join(TEMPLATES_DIR, 'be', ...skeleton.split('/'), 'src', 'compose', `${area}.ts`);
-  const text = fs.readFileSync(exists ? file : template, 'utf8').replace(/\r\n/g, '\n');
-  const argument = area === 'domain' && repo.edition === 'lite' ? 'verifyAccessToken: VerifyAccessToken' : '';
-  const marker = `export const ${area}Modules = (${argument}): Array<Type<unknown> | DynamicModule> => [`;
-  const declarationAt = compositionCode(text).indexOf(`\n${marker}`);
-  const active = declarationAt >= 0;
-  const tail = active ? text.slice(declarationAt + 1 + marker.length).trimEnd().replace(/;$/, '').trimEnd() : '';
-  const body = tail.endsWith(']') ? tail.slice(0, -1) : undefined;
-  if (body === undefined) throw new ScaffoldError('HFS_ADD_WIRE_INVALID', `add ${noun} needs the typed ${area}Modules group in ${relative}`);
-  return { relative, file, exists, text, marker, body };
+    const relative = `be/apps/${app}/src/compose/${area}.ts`;
+    const file = path.join(repoRoot, ...relative.split('/'));
+    const exists = fs.existsSync(file);
+    const skeleton = repo.edition === 'lite' ? 'skeleton-lite/apps/api' : 'skeleton/apps/__app__';
+    const template = path.join(TEMPLATES_DIR, 'be', ...skeleton.split('/'), 'src', 'compose', `${area}.ts`);
+    const text = fs.readFileSync(exists ? file : template, 'utf8').replace(/\r\n/g, '\n');
+    const argument = area === 'domain' && repo.edition === 'lite' ? 'verifyAccessToken: VerifyAccessToken' : '';
+    const marker = `export const ${area}Modules = (${argument}): Array<Type<unknown> | DynamicModule> => [`;
+    const declarationAt = compositionCode(text).indexOf(`\n${marker}`);
+    const active = declarationAt >= 0;
+    const tail = active ? text.slice(declarationAt + 1 + marker.length).trimEnd().replace(/;$/, '').trimEnd() : '';
+    const body = tail.endsWith(']') ? tail.slice(0, -1) : undefined;
+    if (body === undefined)
+        throw new ScaffoldError('HFS_ADD_WIRE_INVALID', `add ${noun} needs the typed ${area}Modules group in ${relative}`);
+    return { relative, file, exists, text, marker, body };
 }
-
 /** Creates a typed group from the edition's template, or adds members without duplicating inline registrations or semicolon imports. */
 export function planComposeGroup(input) {
-  const { relative, file, exists, marker, body, text: original } = readComposeGroup(input);
-  let text = original;
-  let compactBody = compositionCode(body).replace(/\s+/g, '');
-  for (const { importLine, entry } of input.entries) {
-    const lines = text.split('\n');
-    if (!lines.some(line => line.replace(/;\s*$/, '') === importLine)) {
-      const lastImport = lines.reduce((last, line, index) => line.startsWith('import ') ? index : last, -1);
-      lines.splice(lastImport + 1, 0, importLine);
-      text = lines.join('\n');
+    const { relative, file, exists, marker, body, text: original } = readComposeGroup(input);
+    let text = original;
+    let compactBody = compositionCode(body).replace(/\s+/g, '');
+    for (const { importLine, entry } of input.entries) {
+        const lines = text.split('\n');
+        if (!lines.some(line => line.replace(/;\s*$/, '') === importLine)) {
+            const lastImport = lines.reduce((last, line, index) => line.startsWith('import ') ? index : last, -1);
+            lines.splice(lastImport + 1, 0, importLine);
+            text = lines.join('\n');
+        }
+        const compactEntry = entry.replace(/\s+/g, '');
+        const members = `,${compactBody},`;
+        if (!members.includes(`,${compactEntry},`)) {
+            const afterMarker = compositionCode(text).indexOf(marker) + marker.length;
+            const empty = text.slice(afterMarker).startsWith(']');
+            text = `${text.slice(0, afterMarker)}\n    ${entry},${empty ? '\n' : ''}${text.slice(afterMarker)}`;
+            compactBody = `${compactEntry},${compactBody}`;
+        }
     }
-    const compactEntry = entry.replace(/\s+/g, '');
-    const members = `,${compactBody},`;
-    if (!members.includes(`,${compactEntry},`)) {
-      const afterMarker = compositionCode(text).indexOf(marker) + marker.length;
-      const empty = text.slice(afterMarker).startsWith(']');
-      text = `${text.slice(0, afterMarker)}\n    ${entry},${empty ? '\n' : ''}${text.slice(afterMarker)}`;
-      compactBody = `${compactEntry},${compactBody}`;
-    }
-  }
-  return { relative, file, exists, text };
+    return { relative, file, exists, text };
 }
-
 /** Writes the planned group and reports a newly created composition file. */
 export function writeComposeGroup(input) {
-  const { relative, file, exists, text } = planComposeGroup(input);
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(file, text);
-  return exists ? [] : [relative];
+    const { relative, file, exists, text } = planComposeGroup(input);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, text);
+    return exists ? [] : [relative];
 }

package/scaffold/add-database-lite.d.mts

@@ -0,0 +1,2 @@
+/** Enables the lazy SQL identifier guard's error family when a lite generator installs database.sql.ts. */
+export declare function withSqlIdentifierError(text: string): string;

package/scaffold/add-database-lite.mjs

@@ -1,14 +1,14 @@
 import { ScaffoldError } from './service.mjs';
-
 /** Enables the lazy SQL identifier guard's error family when a lite generator installs database.sql.ts. */
 export function withSqlIdentifierError(text) {
-  const code = '    IdentifierRejected = "DATABASE_IDENTIFIER_REJECTED",';
-  if (text.includes(code)) return text;
-  const enumMarker = 'export enum DatabaseErrorCode {';
-  const kindsMarker = 'export const DATABASE_ERROR_KINDS: Record<DatabaseErrorCode, ErrorKind> = {';
-  if (!text.includes(enumMarker) || !text.includes(kindsMarker)) {
-    throw new ScaffoldError('HFS_ADD_DATABASE_ERROR', 'platform/database has an unknown error-family shape');
-  }
-  return text.replace(enumMarker, enumMarker + '\n    /** A dynamic SQL identifier was not on the names its caller allows. */\n' + code)
-    .replace(kindsMarker, kindsMarker + '\n    [DatabaseErrorCode.IdentifierRejected]: "internal",');
+    const code = '    IdentifierRejected = "DATABASE_IDENTIFIER_REJECTED",';
+    if (text.includes(code))
+        return text;
+    const enumMarker = 'export enum DatabaseErrorCode {';
+    const kindsMarker = 'export const DATABASE_ERROR_KINDS: Record<DatabaseErrorCode, ErrorKind> = {';
+    if (!text.includes(enumMarker) || !text.includes(kindsMarker)) {
+        throw new ScaffoldError('HFS_ADD_DATABASE_ERROR', 'platform/database has an unknown error-family shape');
+    }
+    return text.replace(enumMarker, enumMarker + '\n    /** A dynamic SQL identifier was not on the names its caller allows. */\n' + code)
+        .replace(kindsMarker, kindsMarker + '\n    [DatabaseErrorCode.IdentifierRejected]: "internal",');
 }

package/scaffold/add-fe-layout.d.mts

@@ -0,0 +1,16 @@
+/**
+ * Generates one route-segment layout in the app at `repoRoot`.
+ *
+ * @param {{ repoRoot: string, segment: string, options?: { app?: string, blocks?: string } }} input - The app root, the segment under [locale] and the options.
+ * @returns {{ created: string[] }} The files written, relative to the app root.
+ */
+export declare function addFeLayout({ repoRoot, segment, options }: {
+    repoRoot: string;
+    segment: string;
+    options?: {
+        app?: string | undefined;
+        blocks?: string | undefined;
+    };
+}): {
+    created: string[];
+};

package/scaffold/add-fe-layout.mjs

@@ -13,7 +13,6 @@ import path from 'node:path';
 import { ScaffoldError, pascalOf } from './service.mjs';
 import { appOf, declarationOf, fill, writeNew } from './add-fe-unit.mjs';
 import { blockParts, blocksOf, routeSegmentsOf } from './add-fe-page.mjs';
-
 /**
  * Generates one route-segment layout in the app at `repoRoot`.
  *
@@ -21,26 +20,27 @@ import { blockParts, blocksOf, routeSegmentsOf } from './add-fe-page.mjs';
  * @returns {{ created: string[] }} The files written, relative to the app root.
  */
 export function addFeLayout({ repoRoot, segment, options = {} }) {
-  const segments = routeSegmentsOf(segment);
-  const appBase = `fe/apps/${appOf(declarationOf(repoRoot), options.app)}`;
-  const Name = `${pascalOf(segments.join('-'))}Layout`;
-  const route = `${appBase}/src/app/[locale]/${segments.join('/')}/layout.tsx`;
-  const owner = `${appBase}/src/features/layouts/${Name}`;
-  for (const relative of [route, owner]) {
-    if (fs.existsSync(path.join(repoRoot, ...relative.split('/')))) throw new ScaffoldError('HFS_ADD_EXISTS', `${relative} already exists; starci app add never overwrites a unit`);
-  }
-  const blocks = blocksOf(repoRoot, appBase, options.blocks);
-  const parts = blockParts(blocks, '                ');
-  const vars = {
-    Name, segment: segments.join('/'),
-    blockImports: parts.imports,
-    railDoc: blocks.length === 0 ? 'leaves its rail empty until a block fills it' : `fills its rail with ${blocks.join(', ')}`,
-    frame: blocks.length === 0
-      ? '<PrimaryRailLayout primary={props.content} />'
-      : ['(', '    <PrimaryRailLayout', '        primary={props.content}', '        rail={', '            <>', parts.jsx, '            </>', '        }', '    />', ')'].join('\n'),
-  };
-  const created = [];
-  writeNew(created, repoRoot, route, fill('layout/route-layout.tsx.tpl', vars));
-  writeNew(created, repoRoot, `${owner}/index.tsx`, fill('layout/index.tsx.tpl', vars));
-  return { created };
+    const segments = routeSegmentsOf(segment);
+    const appBase = `fe/apps/${appOf(declarationOf(repoRoot), options.app)}`;
+    const Name = `${pascalOf(segments.join('-'))}Layout`;
+    const route = `${appBase}/src/app/[locale]/${segments.join('/')}/layout.tsx`;
+    const owner = `${appBase}/src/features/layouts/${Name}`;
+    for (const relative of [route, owner]) {
+        if (fs.existsSync(path.join(repoRoot, ...relative.split('/'))))
+            throw new ScaffoldError('HFS_ADD_EXISTS', `${relative} already exists; starci app add never overwrites a unit`);
+    }
+    const blocks = blocksOf(repoRoot, appBase, options.blocks);
+    const parts = blockParts(blocks, '                ');
+    const vars = {
+        Name, segment: segments.join('/'),
+        blockImports: parts.imports,
+        railDoc: blocks.length === 0 ? 'leaves its rail empty until a block fills it' : `fills its rail with ${blocks.join(', ')}`,
+        frame: blocks.length === 0
+            ? '<PrimaryRailLayout primary={props.content} />'
+            : ['(', '    <PrimaryRailLayout', '        primary={props.content}', '        rail={', '            <>', parts.jsx, '            </>', '        }', '    />', ')'].join('\n'),
+    };
+    const created = [];
+    writeNew(created, repoRoot, route, fill('layout/route-layout.tsx.tpl', vars));
+    writeNew(created, repoRoot, `${owner}/index.tsx`, fill('layout/index.tsx.tpl', vars));
+    return { created };
 }

package/scaffold/add-fe-overlay.d.mts

@@ -0,0 +1,17 @@
+/**
+ * Generates one overlay owner in the app at `repoRoot`.
+ *
+ * @param {{ repoRoot: string, name: string, options?: { app?: string, kind?: string, form?: boolean } }} input - The app root, the overlay name and the options.
+ * @returns {{ created: string[] }} The files written or extended, relative to the app root.
+ */
+export declare function addFeOverlay({ repoRoot, name, options }: {
+    repoRoot: string;
+    name: string;
+    options?: {
+        app?: string | undefined;
+        kind?: string | undefined;
+        form?: boolean | undefined;
+    };
+}): {
+    created: string[];
+};

package/scaffold/add-fe-overlay.mjs

@@ -13,73 +13,68 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { ScaffoldError, camelOf, pascalOf } from './service.mjs';
 import { addCatalogNamespaces, appOf, declarationOf, fill, humanOf, words, writeNew } from './add-fe-unit.mjs';
-
 /** The shells an overlay may be: `--kind` to Grammar component. */
 const SHELLS = Object.freeze({ modal: 'Dialog', drawer: 'Drawer' });
-
-/** The copy of a new overlay, by catalog locale; any other locale takes the English words. */
 const OVERLAY_COPY = Object.freeze({
-  en: { open: 'Open', cancel: 'Cancel', submit: 'Save', description: 'Describe the task this overlay holds.', name: 'Name' },
-  vi: { open: 'Mở', cancel: 'Hủy', submit: 'Lưu', description: 'Mô tả việc mà lớp phủ này đảm nhận.', name: 'Tên' },
+    en: { open: 'Open', cancel: 'Cancel', submit: 'Save', description: 'Describe the task this overlay holds.', name: 'Name' },
+    vi: { open: 'Mở', cancel: 'Hủy', submit: 'Lưu', description: 'Mô tả việc mà lớp phủ này đảm nhận.', name: 'Tên' },
 });
-
 /** The variables of the overlay templates for one shell, with or without a form. */
-function overlayVars({ Name, nameKebab, shell, form }) {
-  const decision = (indent, cancel, commit) => [
-    `${indent}<Button intent="dismiss" onPress={${cancel}}>`,
-    `${indent}    {props.props.cancelLabel}`,
-    `${indent}</Button>`,
-    `${indent}${commit}`,
-    `${indent}    {props.props.submitLabel}`,
-    `${indent}</Button>`,
-  ].join('\n');
-  const shellAttributes = shell === 'Drawer' ? '        placement="right"\n' : '';
-  /** The shell's footer: the decision group, the way out first and the commit last. */
-  const footer = (commit) => [
-    '        footer={(close) => (',
-    '            <>',
-    decision('                ', 'close', commit),
-    '            </>',
-    '        )}',
-    '',
-  ].join('\n');
-  if (form) {
-    const formId = `${nameKebab}-form`;
+function overlayVars({ nameKebab, shell, form }) {
+    const decision = (indent, cancel, commit) => [
+        `${indent}<Button intent="dismiss" onPress={${cancel}}>`,
+        `${indent}    {props.props.cancelLabel}`,
+        `${indent}</Button>`,
+        `${indent}${commit}`,
+        `${indent}    {props.props.submitLabel}`,
+        `${indent}</Button>`,
+    ].join('\n');
+    const shellAttributes = shell === 'Drawer' ? '        placement="right"\n' : '';
+    /** The shell's footer: the decision group, the way out first and the commit last. */
+    const footer = (commit) => [
+        '        footer={(close) => (',
+        '            <>',
+        decision('                ', 'close', commit),
+        '            </>',
+        '        )}',
+        '',
+    ].join('\n');
+    if (form) {
+        const formId = `${nameKebab}-form`;
+        return {
+            grammarImports: ['Button', shell, 'Form', 'FormGrid', 'Input'].sort().join(', '),
+            labelMembers: '        readonly nameLabel: string\n',
+            labelsResolved: '                nameLabel: t("name"),\n',
+            labelsFixture: '    nameLabel: "Name",\n',
+            submitMember: '        readonly submit: (input: FormData) => void\n',
+            submitHandler: 'submit: () => setIsOpen(false)',
+            submitFixture: 'submit: () => undefined',
+            doc: `The ${shell} holding one form: its fields in one column in the body, the footer's way out first and the submit, which names the form, last.`,
+            shellAttributes,
+            footer: footer(`<Button type="submit" form="${formId}" intent="commit">`),
+            body: [
+                `        <Form id="${formId}" label={props.props.title} onSubmit={props.on.submit}>`,
+                '            <FormGrid columns={1}>',
+                `                <Input id="${nameKebab}-name" name="name" label={props.props.nameLabel} isRequired />`,
+                '            </FormGrid>',
+                '        </Form>',
+            ].join('\n'),
+        };
+    }
     return {
-      grammarImports: ['Button', shell, 'Form', 'FormGrid', 'Input'].sort().join(', '),
-      labelMembers: '        readonly nameLabel: string\n',
-      labelsResolved: '                nameLabel: t("name"),\n',
-      labelsFixture: '    nameLabel: "Name",\n',
-      submitMember: '        readonly submit: (input: FormData) => void\n',
-      submitHandler: 'submit: () => setIsOpen(false)',
-      submitFixture: 'submit: () => undefined',
-      doc: `The ${shell} holding one form: its fields in one column in the body, the footer's way out first and the submit, which names the form, last.`,
-      shellAttributes,
-      footer: footer(`<Button type="submit" form="${formId}" intent="commit">`),
-      body: [
-        `        <Form id="${formId}" label={props.props.title} onSubmit={props.on.submit}>`,
-        '            <FormGrid columns={1}>',
-        `                <Input id="${nameKebab}-name" name="name" label={props.props.nameLabel} isRequired />`,
-        '            </FormGrid>',
-        '        </Form>',
-      ].join('\n'),
+        grammarImports: ['Button', shell, 'Text'].sort().join(', '),
+        labelMembers: '        readonly description: string\n',
+        labelsResolved: '                description: t("description"),\n',
+        labelsFixture: '    description: "Describe the task this overlay holds.",\n',
+        submitMember: '        readonly confirm: () => void\n',
+        submitHandler: 'confirm: () => setIsOpen(false)',
+        submitFixture: 'confirm: () => undefined',
+        doc: `The ${shell} of one task: its sentence, and the footer's way out first and commit last.`,
+        shellAttributes,
+        footer: footer('<Button intent="commit" onPress={props.on.confirm}>'),
+        body: '        <Text>{props.props.description}</Text>',
     };
-  }
-  return {
-    grammarImports: ['Button', shell, 'Text'].sort().join(', '),
-    labelMembers: '        readonly description: string\n',
-    labelsResolved: '                description: t("description"),\n',
-    labelsFixture: '    description: "Describe the task this overlay holds.",\n',
-    submitMember: '        readonly confirm: () => void\n',
-    submitHandler: 'confirm: () => setIsOpen(false)',
-    submitFixture: 'confirm: () => undefined',
-    doc: `The ${shell} of one task: its sentence, and the footer's way out first and commit last.`,
-    shellAttributes,
-    footer: footer('<Button intent="commit" onPress={props.on.confirm}>'),
-    body: '        <Text>{props.props.description}</Text>',
-  };
 }
-
 /**
  * Generates one overlay owner in the app at `repoRoot`.
  *
@@ -87,23 +82,26 @@ function overlayVars({ Name, nameKebab, shell, form }) {
  * @returns {{ created: string[] }} The files written or extended, relative to the app root.
  */
 export function addFeOverlay({ repoRoot, name, options = {} }) {
-  const shell = SHELLS[options.kind];
-  if (shell === undefined) throw new ScaffoldError('HFS_ADD_OVERLAY_KIND', `an overlay names its shell with --kind ${Object.keys(SHELLS).join('|')}; those are the only two`);
-  const base = pascalOf(name);
-  if (!/^[A-Z][A-Za-z0-9]*$/.test(base)) throw new ScaffoldError('HFS_ADD_NAME_INVALID', `${name} is not a unit name`);
-  const Name = base.endsWith('Overlay') ? base : `${base}Overlay`;
-  const appBase = `fe/apps/${appOf(declarationOf(repoRoot), options.app)}`;
-  const folder = `${appBase}/src/features/overlays/${Name}`;
-  if (fs.existsSync(path.join(repoRoot, ...folder.split('/')))) throw new ScaffoldError('HFS_ADD_EXISTS', `${folder} already exists; starci app add never overwrites a unit`);
-  const form = options.form === true;
-  const vars = { Name, shell, nameCamel: camelOf(Name), title: humanOf(words(base).join('-')), ...overlayVars({ Name, nameKebab: words(Name).join('-'), shell, form }) };
-  const created = [];
-  writeNew(created, repoRoot, `${folder}/index.tsx`, fill('overlay/index.tsx.tpl', vars));
-  writeNew(created, repoRoot, `${folder}/component.tsx`, fill('overlay/component.tsx.tpl', vars));
-  writeNew(created, repoRoot, `${appBase}/stories/overlays/${Name}.stories.tsx`, fill('overlay/stories.tsx.tpl', vars));
-  addCatalogNamespaces(created, { repoRoot, appBase }, (locale) => {
-    const copy = OVERLAY_COPY[locale] ?? OVERLAY_COPY.en;
-    return { [vars.nameCamel]: { title: vars.title, open: copy.open, ...(form ? { name: copy.name } : { description: copy.description }), cancel: copy.cancel, submit: copy.submit } };
-  });
-  return { created };
+    const shell = options.kind === undefined ? undefined : SHELLS[options.kind];
+    if (shell === undefined)
+        throw new ScaffoldError('HFS_ADD_OVERLAY_KIND', `an overlay names its shell with --kind ${Object.keys(SHELLS).join('|')}; those are the only two`);
+    const base = pascalOf(name);
+    if (!/^[A-Z][A-Za-z0-9]*$/.test(base))
+        throw new ScaffoldError('HFS_ADD_NAME_INVALID', `${name} is not a unit name`);
+    const Name = base.endsWith('Overlay') ? base : `${base}Overlay`;
+    const appBase = `fe/apps/${appOf(declarationOf(repoRoot), options.app)}`;
+    const folder = `${appBase}/src/features/overlays/${Name}`;
+    if (fs.existsSync(path.join(repoRoot, ...folder.split('/'))))
+        throw new ScaffoldError('HFS_ADD_EXISTS', `${folder} already exists; starci app add never overwrites a unit`);
+    const form = options.form === true;
+    const vars = { Name, shell, nameCamel: camelOf(Name), title: humanOf(words(base).join('-')), ...overlayVars({ nameKebab: words(Name).join('-'), shell, form }) };
+    const created = [];
+    writeNew(created, repoRoot, `${folder}/index.tsx`, fill('overlay/index.tsx.tpl', vars));
+    writeNew(created, repoRoot, `${folder}/component.tsx`, fill('overlay/component.tsx.tpl', vars));
+    writeNew(created, repoRoot, `${appBase}/stories/overlays/${Name}.stories.tsx`, fill('overlay/stories.tsx.tpl', vars));
+    addCatalogNamespaces(created, { repoRoot, appBase }, (locale) => {
+        const copy = OVERLAY_COPY[locale] ?? OVERLAY_COPY.en;
+        return { [vars.nameCamel]: { title: vars.title, open: copy.open, ...(form ? { name: copy.name } : { description: copy.description }), cancel: copy.cancel, submit: copy.submit } };
+    });
+    return { created };
 }

package/scaffold/add-fe-page.d.mts

@@ -0,0 +1,41 @@
+/** A page tab: its id, catalog key, label and route. */
+export interface PageTab {
+    readonly id: string;
+    readonly key: string;
+    readonly label: string;
+    readonly href: string;
+}
+/** The static segments of `<route>` (`settings/billing`); a dynamic or grouped segment is the author's to write. */
+export declare function routeSegmentsOf(route: string): string[];
+/**
+ * The blocks of `--blocks a,b`, as their PascalCase names: each an existing block of the app whose connected half takes no input
+ * (`export const X = () =>`), since a generated owner has no value to hand one; a block that takes input is composed by hand.
+ */
+export declare function blocksOf(repoRoot: string, appBase: string, option?: string | undefined): string[];
+/**
+ * The page tabs of `--tabs a,b`: two or more distinct kebab-case ids, each with its catalog key and its route. The first tab is
+ * the page's own route, every other one the sub-route `<route>/<id>`.
+ */
+export declare function tabsOf(route: string, option?: string | undefined): PageTab[];
+/** The imports and the JSX lines of the blocks a page or layout composes. */
+export declare const blockParts: (blocks: readonly string[], indent: string) => {
+    imports: string;
+    jsx: string;
+};
+/**
+ * Generates one route page in the app at `repoRoot`.
+ *
+ * @param {{ repoRoot: string, route: string, options?: { app?: string, blocks?: string, tabs?: string } }} input - The app root, the route under [locale] and the options.
+ * @returns {{ created: string[] }} The files written or extended, relative to the app root.
+ */
+export declare function addFePage({ repoRoot, route, options }: {
+    repoRoot: string;
+    route: string;
+    options?: {
+        app?: string | undefined;
+        blocks?: string | undefined;
+        tabs?: string | undefined;
+    };
+}): {
+    created: string[];
+};