@starci/hfs 4.9.6 → 4.9.9

package/scaffold/add-fe-unit.mjs

@@ -0,0 +1,288 @@
+// starci app add <block|composite|branch|leaf> <name> - one front-end unit, already in the shape-slot pattern.
+//
+// The bodies are templates/fe/units/<tier>/; this module only fills them and places them (contexts/code/fe function.md
+// FE-FUNCTION-2..4 and FE-FUNCTION-7, README.md FE-ERROR-1).
+//
+//   starci app add block handoff-block                                  HandoffBlock: one read folded into a DataSlot, no shape
+//   starci app add block handoff-block --shapes prepared,sent,returned  plus HANDOFF_BLOCK_SHAPES, HandoffBlockShape and an exhaustive switch
+//   starci app add composite term-value | branch disclosure | leaf status-label
+//
+// A block reads `useQuery<Read>Swr` of hooks/swr (`--read`, default: the block name without its `Block` suffix; `add table --fe`
+// writes that hook). A block with shapes takes its shape from the read's `status` (the placeholder's own while the read loads), so
+// the read names its shape in that field. The first block of an app also writes the app's one copy of the status owners
+// (FE-ERROR-1): DataSlot and SlotLabels in modules/types, slotOfSwr/mapSlot/loadingSlot in hooks/slot/slot.shared.ts,
+// useSlotLabels, the SlotView composite and the shared `status` namespace of every catalog. Nothing that exists is overwritten.
+// A composite, branch or leaf, SlotView among them, is vocabulary that knows no feature: in a front end of two or more apps with
+// the shared ui package (slot fe.package.ui) it lives in that package and its barrel, DataSlot and SlotLabels are declared beside
+// SlotView there and modules/types re-exports them (R91 `monorepo-tier-belongs-to-its-side`); else it lives in the app's components.
+// A shape that names a data status is refused by the lint (R92 `no-data-status-shape`), which owns that word list.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ScaffoldError, camelOf, pascalOf } from './service.mjs';
+import { coreFeApps } from './app.mjs';
+
+const UNITS_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'templates', 'fe', 'units');
+
+/** The nouns this module answers, and the components layer each one writes into. */
+export const FE_UNIT_LAYERS = Object.freeze({ block: 'blocks', composite: 'composites', branch: 'branches', leaf: 'leaves' });
+
+/** The shared status copy of FE-ERROR-1, by catalog locale; any other locale takes the English sentences. */
+const STATUS_COPY = Object.freeze({
+  en: { forbidden: 'You do not have access to this.', error: 'This could not be loaded.', retry: 'Try again' },
+  vi: { forbidden: 'Bạn không có quyền xem phần này.', error: 'Không tải được phần này.', retry: 'Thử lại' },
+});
+/** The empty sentence of a new block, by catalog locale. */
+const EMPTY_COPY = Object.freeze({ en: 'Nothing to show yet.', vi: 'Chưa có gì để hiển thị.' });
+
+export const words = (name) => name.replace(/([a-z0-9])([A-Z])/g, '$1 $2').split(/[\s_-]+/).filter(Boolean).map((word) => word.toLowerCase());
+export const humanOf = (name) => { const text = words(name).join(' '); return text[0].toUpperCase() + text.slice(1); };
+
+/** A template body with its `{{name}}` variables filled; a variable without a value is a template error, never left in place. */
+export function fill(file, vars) {
+  const body = fs.readFileSync(path.join(UNITS_DIR, ...file.split('/')), 'utf8').replace(/\r\n/g, '\n');
+  return body.replace(/\{\{(\w+)\}\}/g, (_, key) => {
+    if (!Object.hasOwn(vars, key)) throw new ScaffoldError('HFS_SCAFFOLD_TEMPLATE_VARIABLE', `templates/fe/units/${file} names {{${key}}}, which has no value`);
+    return vars[key];
+  });
+}
+
+/** The parsed hfs.json of the app root. */
+export function declarationOf(repoRoot) {
+  const declarationFile = path.join(repoRoot, 'hfs.json');
+  if (!fs.existsSync(declarationFile)) throw new ScaffoldError('HFS_ADD_NOT_AN_APP', 'starci app add needs the app root hfs.json');
+  return JSON.parse(fs.readFileSync(declarationFile, 'utf8'));
+}
+
+/** The one product app the unit belongs to: `--app`, else the only product Next app of hfs.json. */
+export function appOf(declaration, requested) {
+  const apps = coreFeApps(declaration.sides?.fe?.apps ?? []);
+  if (requested !== undefined) {
+    if (!apps.some((entry) => entry.name === requested)) throw new ScaffoldError('HFS_ADD_NO_FRONT_END', `${requested} is not a product Next app of hfs.json`);
+    return requested;
+  }
+  if (apps.length !== 1) throw new ScaffoldError('HFS_ADD_NO_FRONT_END', `a front-end unit names its app with --app when hfs.json declares ${apps.length} product Next apps`);
+  return apps[0].name;
+}
+
+/**
+ * Where the vocabulary tiers go: the shared ui package (`fe/packages/<project>-ui`: its folder and its import name) when the front
+ * end has two or more apps and the package exists, else null (the app's own components).
+ */
+function sharedUiOf(repoRoot, declaration) {
+  if ((declaration.sides?.fe?.apps ?? []).length < 2) return null;
+  const relative = `fe/packages/${declaration.project}-ui`;
+  const manifest = path.join(repoRoot, ...relative.split('/'), 'package.json');
+  if (!fs.existsSync(manifest)) return null;
+  return { relative, name: JSON.parse(fs.readFileSync(manifest, 'utf8')).name };
+}
+
+/** The shape members of `--shapes a,b,c`: none, or two or more distinct camelCase words, in the order given. */
+function shapesOf(option) {
+  if (option === undefined || option === false) return [];
+  const shapes = (Array.isArray(option) ? option : String(option).split(',')).map((value) => value.trim()).filter(Boolean);
+  if (shapes.length < 2) throw new ScaffoldError('HFS_ADD_SHAPES_INVALID', '--shapes names two or more drawn shapes; a unit with one shape takes none');
+  if (new Set(shapes).size !== shapes.length) throw new ScaffoldError('HFS_ADD_SHAPES_INVALID', `--shapes repeats a member: ${shapes.join(',')}`);
+  const unworded = shapes.find((shape) => !/^[a-z][a-zA-Z0-9]*$/.test(shape));
+  if (unworded !== undefined) throw new ScaffoldError('HFS_ADD_SHAPES_INVALID', `the shape "${unworded}" is not a camelCase word`);
+  return shapes;
+}
+
+/** Writes one file the unit owns (`relative` to the repository root); the unit's own files must not exist yet. */
+export function writeNew(created, repoRoot, relative, body) {
+  const file = path.join(repoRoot, ...relative.split('/'));
+  if (fs.existsSync(file)) throw new ScaffoldError('HFS_ADD_EXISTS', `${relative} already exists; starci app add never overwrites a unit`);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, body);
+  created.push(relative);
+}
+
+/** Writes one shared file only when it is missing (the status owners have one copy per app). */
+function writeOnce(created, repoRoot, relative, body) {
+  const file = path.join(repoRoot, ...relative.split('/'));
+  if (fs.existsSync(file)) return;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, body);
+  created.push(relative);
+}
+
+/** Adds `line` to a barrel, creating it, unless the barrel already has it. */
+export function exportFrom(created, repoRoot, relative, line) {
+  const file = path.join(repoRoot, ...relative.split('/'));
+  const before = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  if (before.split(/\r?\n/).includes(line)) return;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${before}${before === '' || before.endsWith('\n') ? '' : '\n'}${line}\n`);
+  if (!created.includes(relative)) created.push(relative);
+}
+
+/** The app's one copy of the FE-ERROR-1 owners, written by the first block that needs them; SlotView is shared vocabulary. */
+function ensureSlotOwners(created, { repoRoot, appBase, ui }) {
+  const types = fill('slot/data-slot.ts.tpl', {});
+  if (ui === null) {
+    writeOnce(created, repoRoot, `${appBase}/src/modules/types/data-slot.ts`, types);
+    exportFrom(created, repoRoot, `${appBase}/src/modules/types/index.ts`, 'export type { DataSlot, SlotLabels } from "./data-slot"');
+    writeOnce(created, repoRoot, `${appBase}/src/components/composites/SlotView/index.tsx`, fill('slot/SlotView.tsx.tpl', { slotTypes: 'import type { DataSlot, SlotLabels } from "@/modules/types"\n' }));
+  } else {
+    writeOnce(created, repoRoot, `${ui.relative}/src/composites/SlotView/index.tsx`, fill('slot/SlotView.tsx.tpl', { slotTypes: `\n${types}` }));
+    exportFrom(created, repoRoot, `${ui.relative}/src/index.ts`, 'export { SlotView } from "./composites/SlotView"');
+    exportFrom(created, repoRoot, `${ui.relative}/src/index.ts`, 'export type { DataSlot, SlotLabels } from "./composites/SlotView"');
+    exportFrom(created, repoRoot, `${appBase}/src/modules/types/index.ts`, `export type { DataSlot, SlotLabels } from "${ui.name}"`);
+  }
+  writeOnce(created, repoRoot, `${appBase}/src/hooks/slot/slot.shared.ts`, fill('slot/slot.shared.ts.tpl', {}));
+  writeOnce(created, repoRoot, `${appBase}/src/hooks/slot/useSlotLabels.ts`, fill('slot/useSlotLabels.ts.tpl', {}));
+  exportFrom(created, repoRoot, `${appBase}/src/hooks/slot/index.ts`, 'export { loadingSlot, mapSlot, slotOfSwr } from "./slot.shared"');
+  exportFrom(created, repoRoot, `${appBase}/src/hooks/slot/index.ts`, 'export { useSlotLabels } from "./useSlotLabels"');
+}
+
+/**
+ * Adds namespaces to every catalog of the app, keeping what is there: `namespacesOf(locale)` gives `{ namespace: copy }`, and a
+ * namespace the catalog already has is left as it is.
+ */
+export function addCatalogNamespaces(created, { repoRoot, appBase }, namespacesOf) {
+  const dir = path.join(repoRoot, ...appBase.split('/'), 'src', 'modules', 'i18n', 'messages');
+  if (!fs.existsSync(dir)) throw new ScaffoldError('HFS_ADD_WIRE_MISSING', 'a front-end unit reads its copy from modules/i18n/messages, which does not exist');
+  for (const entry of fs.readdirSync(dir).filter((file) => file.endsWith('.json')).sort()) {
+    const file = path.join(dir, entry);
+    const catalog = JSON.parse(fs.readFileSync(file, 'utf8'));
+    const before = JSON.stringify(catalog);
+    for (const [namespace, copy] of Object.entries(namespacesOf(entry.slice(0, -'.json'.length)))) catalog[namespace] ??= copy;
+    if (JSON.stringify(catalog) === before) continue;
+    fs.writeFileSync(file, `${JSON.stringify(catalog, null, 2)}\n`);
+    created.push(`${appBase}/src/modules/i18n/messages/${entry}`);
+  }
+}
+
+/** The shared `status` namespace and the block's own namespace. */
+function addCatalogKeys(created, place, { nameCamel, title, shapes }) {
+  addCatalogNamespaces(created, place, (locale) => ({
+    status: { ...(STATUS_COPY[locale] ?? STATUS_COPY.en) },
+    [nameCamel]: {
+      title,
+      empty: EMPTY_COPY[locale] ?? EMPTY_COPY.en,
+      ...(shapes.length ? { shapes: Object.fromEntries(shapes.map((shape) => [shape, humanOf(shape)])) } : {}),
+    },
+  }));
+}
+
+/** The pure half's shape inventory, union and exhaustive switch (FE-FUNCTION-7): one case per member, in the given order. */
+function shapeParts({ Name, NAME_UPPER, shapes }) {
+  const cases = shapes.map((shape) => [
+    `        case "${shape}":`,
+    '            return (',
+    '                <>',
+    `                    <Text isSkeleton={isSkeleton}>{shapeLabels.${shape}}</Text>`,
+    '                    <Text isSkeleton={isSkeleton}>{item.id}</Text>',
+    '                </>',
+    '            )',
+  ].join('\n')).join('\n');
+  return {
+    shapeDeclarations: [
+      '',
+      `/** The drawn shapes of ${Name}, in the order the owner approved them: one drawing and one story each, never a data status. */`,
+      `export const ${NAME_UPPER}_SHAPES = [${shapes.map((shape) => `"${shape}"`).join(', ')}] as const`,
+      '',
+      `/** One drawn shape of ${Name}. */`,
+      `export type ${Name}Shape = (typeof ${NAME_UPPER}_SHAPES)[number]`,
+      '',
+    ].join('\n'),
+    shapeBody: [
+      '',
+      `/** The ready tree of one drawn shape: one case per member of ${Name}Shape, so a member nobody draws fails the lint. */`,
+      `const readyTreeOf = (shape: ${Name}Shape, shapeLabels: ${Name}BaseProps["props"]["shapeLabels"], item: ${Name}Item, isSkeleton: boolean) => {`,
+      '    switch (shape) {',
+      cases,
+      '    }',
+      '}',
+      '',
+    ].join('\n'),
+    shapeOfHelper: `\n/** The drawn shape a read's \`status\` names; a status no shape draws takes the placeholder's. */\nconst shapeOf = (status: string): ${Name}Shape => ${NAME_UPPER}_SHAPES.find((shape) => shape === status) ?? ${NAME_UPPER}_PLACEHOLDER.shape\n`,
+  };
+}
+
+/** The variables of the block templates; the shape parts are empty when the block has one shape. */
+function blockVars({ Name, nameCamel, nameKebab, Read, shapes, title, ui }) {
+  const NAME_UPPER = words(Name).join('_').toUpperCase();
+  const shaped = shapes.length > 0;
+  const parts = shaped ? shapeParts({ Name, NAME_UPPER, shapes }) : { shapeDeclarations: '', shapeBody: '', shapeOfHelper: '' };
+  const story = (shape) => pascalOf(shape);
+  const readyStories = (shaped ? shapes : ['ready']).map((shape) => [
+    '',
+    `/** The ${shaped ? `${shape} shape` : 'ready read'}, settled. */`,
+    `export const ${story(shape)}: Story = {`,
+    ...(shaped ? [`    args: { shape: "${shape}" },`] : []),
+    `    parameters: { dna: { pair: "${story(shape)}", phase: "ready" } },`,
+    '}',
+  ].join('\n')).join('\n');
+  return {
+    Name, nameCamel, nameKebab, Read, title, NAME_UPPER, ...parts,
+    slotViewFrom: ui === null ? '@/components/composites/SlotView' : ui.name,
+    itemShapeMember: shaped ? `    readonly shape: ${Name}Shape\n` : '',
+    shapeMember: shaped ? `    readonly shape: ${Name}Shape\n` : '',
+    shapeLabelsMember: shaped ? `        readonly shapeLabels: { ${shapes.map((shape) => `readonly ${shape}: string`).join('; ')} }\n` : '',
+    placeholderShapeDoc: shaped ? ', and its shape is the block\'s while the read loads' : '',
+    placeholderShape: shaped ? `, shape: "${shapes[0]}"` : '',
+    readyTree: shaped ? 'readyTreeOf(props.shape, props.props.shapeLabels, item, isSkeleton)' : '<Text isSkeleton={isSkeleton}>{item.id}</Text>',
+    componentImports: shaped ? `${NAME_UPPER}_PLACEHOLDER, ${NAME_UPPER}_SHAPES, ${Name}Base` : `${Name}Base`,
+    componentTypeImport: shaped ? `import type { ${Name}Shape } from "./component"\n` : '',
+    connectedDoc: shaped ? 'takes its shape from the read (the placeholder\'s while it loads), ' : '',
+    itemShapeMapped: shaped ? ', shape: shapeOf(value.status)' : '',
+    shapeAttribute: shaped ? `            shape={(item.items ?? ${NAME_UPPER}_PLACEHOLDER).shape}\n` : '',
+    shapeLabelsResolved: shaped ? `                shapeLabels: { ${shapes.map((shape) => `${shape}: t("shapes.${shape}")`).join(', ')} },\n` : '',
+    shapeLabelsFixture: shaped ? `    shapeLabels: { ${shapes.map((shape) => `${shape}: "${humanOf(shape)}"`).join(', ')} },\n` : '',
+    fixtureShape: shaped ? `, shape: "${shapes[0]}"` : '',
+    shapeArg: shaped ? `shape: "${shapes[0]}", ` : '',
+    storiesDoc: shaped ? 'one story per drawn shape' : 'the settled read',
+    readyStories,
+    firstStory: story(shaped ? shapes[0] : 'ready'),
+  };
+}
+
+/** Writes one block: its two halves (the pure one with its shapes, when it has them), its stories and its copy. */
+function addBlock({ created, place, names, options }) {
+  const shapes = shapesOf(options.shapes);
+  const nameWords = words(names.Name);
+  const read = options.read ?? (nameWords.at(-1) === 'block' && nameWords.length > 1 ? nameWords.slice(0, -1).join('-') : names.nameKebab);
+  const vars = blockVars({ ...names, Read: pascalOf(read), shapes, title: humanOf(names.Name), ui: place.ui });
+  const folder = `${place.appBase}/src/components/blocks/${names.Name}`;
+  const stories = `${place.appBase}/stories/blocks/${names.Name}.stories.tsx`;
+  for (const relative of [folder, stories]) {
+    if (fs.existsSync(path.join(place.repoRoot, ...relative.split('/')))) throw new ScaffoldError('HFS_ADD_EXISTS', `${relative} already exists; starci app add never overwrites a unit`);
+  }
+  ensureSlotOwners(created, place);
+  writeNew(created, place.repoRoot, `${folder}/index.tsx`, fill('block/index.tsx.tpl', vars));
+  writeNew(created, place.repoRoot, `${folder}/component.tsx`, fill('block/component.tsx.tpl', vars));
+  writeNew(created, place.repoRoot, stories, fill('block/stories.tsx.tpl', vars));
+  addCatalogKeys(created, place, { nameCamel: names.nameCamel, title: vars.title, shapes });
+}
+
+/** Writes one composite, branch or leaf: into the shared ui package and its barrel, or into the app's components. */
+function addVocabulary({ created, place, noun, Name }) {
+  const layer = FE_UNIT_LAYERS[noun];
+  const body = fill(`${noun}/index.tsx.tpl`, { Name });
+  if (place.ui === null) {
+    writeNew(created, place.repoRoot, `${place.appBase}/src/components/${layer}/${Name}/index.tsx`, body);
+    return;
+  }
+  writeNew(created, place.repoRoot, `${place.ui.relative}/src/${layer}/${Name}/index.tsx`, body);
+  exportFrom(created, place.repoRoot, `${place.ui.relative}/src/index.ts`, `export { ${Name} } from "./${layer}/${Name}"`);
+}
+
+/**
+ * Generates one front-end unit of the shape-slot pattern in the app at `repoRoot`.
+ *
+ * @param {{ repoRoot: string, noun: string, name: string, options?: { app?: string, shapes?: string | string[], read?: string } }} input - The app root, the tier noun, the unit name (kebab or PascalCase) and its options.
+ * @returns {{ created: string[] }} The files written or extended, relative to the app root (the folder of hfs.json).
+ */
+export function addFeUnit({ repoRoot, noun, name, options = {} }) {
+  if (!Object.hasOwn(FE_UNIT_LAYERS, noun)) throw new ScaffoldError('HFS_ADD_UNKNOWN_NOUN', `${noun} is not a front-end unit tier`);
+  const Name = pascalOf(name);
+  if (!/^[A-Z][A-Za-z0-9]*$/.test(Name)) throw new ScaffoldError('HFS_ADD_NAME_INVALID', `${name} is not a unit name`);
+  if (noun !== 'block' && options.shapes !== undefined) throw new ScaffoldError('HFS_ADD_SHAPES_INVALID', `a ${noun} has no shapes; a pure half with shapes is a block's`);
+  const declaration = declarationOf(repoRoot);
+  const place = { repoRoot, appBase: `fe/apps/${appOf(declaration, options.app)}`, ui: sharedUiOf(repoRoot, declaration) };
+  const created = [];
+  if (noun === 'block') addBlock({ created, place, names: { Name, nameCamel: camelOf(Name), nameKebab: words(Name).join('-') }, options });
+  else addVocabulary({ created, place, noun, Name });
+  return { created };
+}

package/scaffold/add.mjs

@@ -11,6 +11,9 @@
 //   starci app add reactor payment-status --event payment-settled --from payment --service PaymentStatusService=@modules/domain/order
 //   starci app add queue receipt                          modules/queues/receipt: the typed producer
 //   starci app add projection order-summary --connection order
+//   starci app add block handoff-block --shapes prepared,sent,returned   a front-end unit in the shape-slot pattern (add-fe-unit.mjs)
+//   starci app add page handoffs | overlay invite-member --kind modal | layout settings   a route page, overlay or segment layout
+//                                                         (add-fe-page.mjs, add-fe-overlay.mjs, add-fe-layout.mjs)
 //
 // Body placeholders: for each variable `v` of the tree (job, step, event, ...) `@@v@@` is its kebab name, `@@V@@` its PascalCase and
 // `@@vCamel@@` its camelCase, `@@vUpper@@` its UPPER_SNAKE and `@@vSnake@@` its snake_case; the option `--service Class=module` gives `@@service@@` (the class) and `@@serviceModule@@`.
@@ -20,6 +23,10 @@ import { ScaffoldError, pascalOf } from './service.mjs';
 import { addTable, graphqlPlatformFiles } from './add-table.mjs';
 import { addModuleImport, compositionCode, readComposeGroup, writeComposeGroup } from './add-compose.mjs';
 import { addApp } from './add-app.mjs';
+import { FE_UNIT_LAYERS, addFeUnit } from './add-fe-unit.mjs';
+import { addFePage } from './add-fe-page.mjs';
+import { addFeOverlay } from './add-fe-overlay.mjs';
+import { addFeLayout } from './add-fe-layout.mjs';
 import { ensureLiteCli } from './add-cli-lite.mjs';
 import { addLiteWebhookInbox } from './add-inbox-lite.mjs';
 import { planLiteQueue } from './add-queue-lite.mjs';
@@ -30,10 +37,17 @@ import { bundledPins } from '../runtime/scripts/hfs/canon-pins.mjs';
 import { byCodeUnit } from '../report/order.mjs';
 import { registerLiteDomainService, registerLiteExports } from './lite-exports.mjs';
 
+/** The front-end owner nouns besides the component tiers: each one's generator, given the app root, the name and the options. */
+const FE_OWNERS = Object.freeze({
+  page: ({ repoRoot, name, options }) => addFePage({ repoRoot, route: name, options }),
+  overlay: addFeOverlay,
+  layout: ({ repoRoot, name, options }) => addFeLayout({ repoRoot, segment: name, options }),
+});
+
 /**
  * Generates the tree of one noun in the app at `repoRoot` (the folder of hfs.json).
  *
- * @param {{ repoRoot: string, noun: string, name: string, options?: object, now?: () => number }} input - The app root, the noun (job, reactor, queue, projection), the instance name and the options the noun needs.
+ * @param {{ repoRoot: string, noun: string, name: string, options?: object, now?: () => number }} input - The app root, the noun (job, reactor, queue, projection, ..., or a front-end unit: block, composite, branch, leaf, page, overlay, layout), the instance name and the options the noun needs.
  * @returns {{ created: Array<string>, registered: { patterns: Array<string>, kinds: Array<string> } }} The files written (app-root relative) and what hfs.json gained.
  */
 export function addKind({ repoRoot, noun, name, options = {}, now = Date.now }) {
@@ -45,6 +59,11 @@ export function addKind({ repoRoot, noun, name, options = {}, now = Date.now })
     const result = addApp({ root: repoRoot, name });
     return { ...result, registered: { patterns: [], kinds: [] } };
   }
+  const feOwner = FE_OWNERS[noun];
+  if (feOwner !== undefined || Object.hasOwn(FE_UNIT_LAYERS, noun)) {
+    const result = feOwner === undefined ? addFeUnit({ repoRoot, noun, name, options }) : feOwner({ repoRoot, name, options });
+    return { ...result, registered: { patterns: [], kinds: [] } };
+  }
   const context = readAddContext({ repoRoot, noun, name, options, now });
   const builtin = addBuiltinLiteCli(context);
   if (builtin) return builtin;

package/scaffold/app.mjs

@@ -407,11 +407,12 @@ const declaresCliApp = app => app.sides.be.apps.some(entry => entry.kind === 'cl
 
 const LITE_APP_REUSED = new Set(['.editorconfig', '.gitattributes', '.nvmrc']);
 const LITE_DEFERRED_GENERATOR_FILES = new Set([
-  'src/modules/platform/database/database.sql.ts',
   'src/modules/platform/database/migration-runner.service.ts',
   'src/modules/platform/database/seed-runner.service.ts',
   'src/modules/platform/primitives/sequence.policy.ts',
 ]);
+/** The TypeORM schema files of a platform capability: lite's schema authority is supabase/migrations (be.persistence lite overlay). */
+const LITE_TYPEORM_SCHEMA = /^src\/modules\/platform\/[^/]+\/persistence\/(?:connection\.ts$|entities\/|migrations\/)/;
 const liteBaseSource = (rel) => !rel.startsWith('apps/cli/')
     && !rel.startsWith('src/features/cli/')
     && !rel.startsWith('src/modules/domain/note/')
@@ -419,6 +420,7 @@ const liteBaseSource = (rel) => !rel.startsWith('apps/cli/')
     && rel !== 'src/modules/platform/database/migrate-connections.client.ts'
     && rel !== 'src/modules/platform/database/seed-connections.client.ts'
     && !LITE_DEFERRED_GENERATOR_FILES.has(rel)
+    && !LITE_TYPEORM_SCHEMA.test(rel)
     && !rel.startsWith('src/tests/');
 /** The be files the lite overlay replaces: a base unit spec of such a file tests the full variant, so lite carries its own. */
 const liteOverlaid = (() => {

package/src/main.mjs

@@ -55,6 +55,11 @@
 //                                            exactly that kind's file tree, generated FROM the files: tree of its pattern topic (knowledge/patterns/be) with the
 //                                            one template body of each entry (templates/be/patterns), plus the platform capabilities it needs when they are missing;
 //                                            it registers the patterns and the trigger kind in hfs.json (sides.be.patterns, sides.be.kinds). Never overwrites a file (scaffold/add.mjs). In a lite app a noun whose slots lite does not have refuses: `add <noun>: full edition only`.
+//   starci app add <block|composite|branch|leaf> <name> [--shapes a,b,c] [--read <read>] [--app <fe app>] [--cwd <dir>]
+//   starci app add <page|layout> <route> [--blocks a,b] [--tabs a,b (page)] | overlay <name> --kind modal|drawer [--form]   a route page, segment layout
+//                                            or overlay owner (scaffold/add-fe-page.mjs, add-fe-layout.mjs, add-fe-overlay.mjs).
+//                                            one front-end unit in the shape-slot pattern from templates/fe/units (scaffold/add-fe-unit.mjs); the
+//                                            first block writes the app's one copy of the status owners. Never overwrites a unit.
 // Every finding names a why code and carries its Vietnamese text. check, lint and explain read the app, never write to it. Exit codes:
 // 0 clean, 1 error findings, 2 a refusal or bad usage.
 import fs from 'node:fs';
@@ -97,7 +102,7 @@ export const VERBS = Object.freeze(['scaffold', 'add', 'lint', 'sync', 'check',
 const DATABASE_VERBS = new Map([['baseline', dbBaselineMain], ['restamp', dbRestampMain], ['plan', dbPlanMain], ['migrate', dbMigrateMain], ['post-cutover', dbPostCutoverMain], ['dump', dbDumpMain], ['reset', dbResetMain]]);
 
 const USAGE = `starci app scaffold <name> [--into <dir>] [--edition full|lite] [--registry-visibility public|private] [--cwd <dir>]
-starci app add <api|webhook|realtime|saga|job|reactor|queue|projection|cli|table|app> <name> [options] [--cwd <dir>]
+starci app add <api|webhook|realtime|saga|job|reactor|queue|projection|cli|table|app|block|composite|branch|leaf|page|overlay|layout> <name> [options] [--cwd <dir>]
 starci app lint [--cwd <dir>] [--changed <file>...] [--workspace <dir>] [--side be|fe] [--fix] [--format text|json] [--sonar <file>]
 starci app codemod button-intent [--write] [--format json|markdown] [--report <file.json|file.md>] [--cwd <dir>]
 starci app sync (--check | --write) [--cwd <dir>]
@@ -136,10 +141,10 @@ starci app hygiene [--cwd <dir>]
 starci app coverage merge --out <lcov> <lcov-or-dir>... [--cwd <dir>]
 `;
 const PER_CODE_LIMIT = 25;
-const VALUE_FLAGS = new Set(['--base', '--inject', '--into', '--event', '--from', '--service', '--connection', '--owner', '--failed', '--done', '--coverage-from', '--registry-visibility', '--shapes', '--read', '--app']);
+const VALUE_FLAGS = new Set(['--base', '--inject', '--into', '--event', '--from', '--service', '--connection', '--owner', '--failed', '--done', '--coverage-from', '--registry-visibility', '--shapes', '--read', '--app', '--kind', '--blocks', '--tabs']);
 /** Flags that may repeat: their values are collected in order. */
 const LIST_FLAGS = new Set(['--inject']);
-const BOOL_FLAGS = new Set(['--json', '--fast', '--fe', '--no-types', '--db-types', '--wiring']);
+const BOOL_FLAGS = new Set(['--json', '--fast', '--fe', '--no-types', '--db-types', '--wiring', '--form']);
 
 function coverageArgument(arg, args, opts) {
   const inline = arg.startsWith('--coverage-from=');
@@ -390,10 +395,11 @@ function newMain(opts, { cwd: repoRoot, stdout: out }) {
 function addMain(opts, { cwd: repoRoot, stdout: out }) {
   const [noun, name, ...extra] = opts.positional;
   if (!noun || !name || extra.length) throw new Error('starci app add takes `<noun> <name>` and the options of the noun');
-  const { created, registered } = addKind({ repoRoot, noun, name, options: { event: opts.event, from: opts.from, service: opts.service, connection: opts.connection, owner: opts.owner, failed: opts.failed, done: opts.done, fe: opts.fe, noTypes: opts['no-types'], shapes: opts.shapes, read: opts.read, app: opts.app } });
+  const { created, registered } = addKind({ repoRoot, noun, name, options: { event: opts.event, from: opts.from, service: opts.service, connection: opts.connection, owner: opts.owner, failed: opts.failed, done: opts.done, fe: opts.fe, noTypes: opts['no-types'], shapes: opts.shapes, read: opts.read, app: opts.app, kind: opts.kind, form: opts.form, blocks: opts.blocks, tabs: opts.tabs } });
   for (const file of created) out(`created ${file}\n`);
   const kinds = registered.kinds.length ? `; kinds ${registered.kinds.join(', ')}` : '';
-  out(`starci app add ${noun}: registered patterns ${registered.patterns.join(', ')}${kinds}\n`);
+  // A noun that registers nothing in hfs.json (a table, an app, a front-end unit) ends with what it wrote.
+  if (registered.patterns.length || registered.kinds.length) out(`starci app add ${noun}: registered patterns ${registered.patterns.join(', ')}${kinds}\n`);
   return 0;
 }
 

package/templates/app/skeleton-lite/supabase/migrations/__timestamp___baseline.sql

@@ -62,3 +62,44 @@ grant usage on schema public to app_be;
 revoke all on table public.profiles from public, anon, authenticated;
 grant select, insert on table public.profiles to app_be;
 grant update (display_name) on table public.profiles to app_be;
+
+-- The rate limit windows of platform/http-security: every api replica counts a caller's hits in the same row, and a hit
+-- that opens a fresh window prunes a bounded batch of the ended ones.
+create table public.http_security_rate_windows (
+    key varchar(128) primary key,
+    hits integer not null check (hits > 0),
+    reset_at timestamptz not null
+);
+
+create index http_security_rate_windows_reset_at_idx on public.http_security_rate_windows (reset_at);
+
+alter table public.http_security_rate_windows enable row level security;
+alter table public.http_security_rate_windows force row level security;
+
+create policy http_security_rate_windows_app_be_select
+on public.http_security_rate_windows
+for select
+to app_be
+using (current_user = 'app_be');
+
+create policy http_security_rate_windows_app_be_insert
+on public.http_security_rate_windows
+for insert
+to app_be
+with check (current_user = 'app_be');
+
+create policy http_security_rate_windows_app_be_update
+on public.http_security_rate_windows
+for update
+to app_be
+using (current_user = 'app_be')
+with check (current_user = 'app_be');
+
+create policy http_security_rate_windows_app_be_delete
+on public.http_security_rate_windows
+for delete
+to app_be
+using (current_user = 'app_be');
+
+revoke all on table public.http_security_rate_windows from public, anon, authenticated;
+grant select, insert, update, delete on table public.http_security_rate_windows to app_be;

package/templates/be/skeleton/apps/__app__/src/compose/platform.ts

@@ -6,7 +6,13 @@ import { CONFIG_ERROR_KINDS } from "@modules/platform/config"
 import { CqrsModule } from "@modules/platform/cqrs"
 import { DATABASE_ERROR_KINDS, DatabaseModule } from "@modules/platform/database"
 import { ERRORS_MESSAGES, ErrorsModule } from "@modules/platform/errors"
-import { HTTP_SECURITY_ERROR_KINDS, HTTP_SECURITY_MESSAGES, HttpSecurityModule } from "@modules/platform/http-security"
+import {
+    HTTP_SECURITY_ERROR_KINDS,
+    HTTP_SECURITY_MESSAGES,
+    HttpSecurityModule,
+    httpSecurityEntities,
+    httpSecurityMigrations,
+} from "@modules/platform/http-security"
 import { I18nModule } from "@modules/platform/i18n"
 import { IdsModule } from "@modules/platform/ids"
 import { HTTP_ERROR_KINDS, HTTP_MESSAGES, HttpModule } from "@modules/platform/http"
@@ -44,6 +50,12 @@ export const platformModules = (options: {{appPascal}}Options): Array<DynamicMod
     HttpSecurityModule.register({ isGlobal: true, ...options.httpSecurity }),
     DatabaseModule.register({
         isGlobal: true,
-        connections: [{ ...options.database, entities: noteEntities, migrations: noteMigrations }],
+        connections: [
+            {
+                ...options.database,
+                entities: [...httpSecurityEntities, ...noteEntities],
+                migrations: [...httpSecurityMigrations, ...noteMigrations],
+            },
+        ],
     }),
 ]

package/templates/be/skeleton/apps/cli/src/compose/platform.ts

@@ -5,14 +5,15 @@ import { DatabaseModule } from "@modules/platform/database"
 import type { DatabaseConnectionConfig, DatabaseConnectionOptions } from "@modules/platform/database"
 import { IdsModule } from "@modules/platform/ids"
 import { HttpModule } from "@modules/platform/http"
+import { httpSecurityEntities, httpSecurityMigrations } from "@modules/platform/http-security"
 import { LoggingModule } from "@modules/platform/logging"
 import type { CliAppOptions } from "../cli.options"
 
 /** Binds the primary connection to its owners' entities and migrations during composition. */
 const primaryConnectionOf = (primary: DatabaseConnectionConfig): DatabaseConnectionOptions => ({
     ...primary,
-    entities: noteEntities,
-    migrations: noteMigrations,
+    entities: [...httpSecurityEntities, ...noteEntities],
+    migrations: [...httpSecurityMigrations, ...noteMigrations],
 })
 
 /** The clock, logger and declared database connections shared by CLI commands. */

package/templates/be/skeleton/src/modules/platform/http-security/index.ts

@@ -4,6 +4,7 @@ export { HttpSecurityModule } from "./http-security.module"
 export type { HttpSecurityOptions } from "./http-security.options"
 export { HTTP_SECURITY_MESSAGES } from "./messages/http-security.messages"
 export { OriginGuard } from "./origin.guard"
+export { httpSecurityEntities, httpSecurityMigrations } from "./persistence/connection"
 export { requestOf } from "./execution-request.mapper"
 export { RateLimitGuard } from "./rate-limit.guard"
 export { applyHttpSecurity } from "./edge-security.service"

package/templates/be/skeleton/src/modules/platform/http-security/persistence/connection.ts

@@ -0,0 +1,8 @@
+import { RateWindowEntity } from "./entities/rate-window.entity"
+import { CreateRateWindows1789900000000 } from "./migrations/1789900000000-create-rate-windows"
+
+/** The entities of the http-security capability, for the primary connection its rate limit counts in. */
+export const httpSecurityEntities = [RateWindowEntity]
+
+/** The migrations of the http-security capability, in the order they run. */
+export const httpSecurityMigrations = [CreateRateWindows1789900000000]

package/templates/be/skeleton/src/modules/platform/http-security/persistence/entities/rate-window.entity.ts

@@ -0,0 +1,17 @@
+import { Column, Entity, PrimaryColumn } from "typeorm"
+
+@Entity("http_security_rate_windows")
+/** One rate limit window of one caller and tier: the hits it counted and when it ends. */
+export class RateWindowEntity {
+    /** The tier and caller address the window counts. */
+    @PrimaryColumn({ name: "key", type: "varchar", length: 128 })
+    key!: string
+
+    /** The hits counted in the window. */
+    @Column({ name: "hits", type: "integer" })
+    hits!: number
+
+    /** When the window ends; a hit after it opens a fresh one. */
+    @Column({ name: "reset_at", type: "timestamptz" })
+    resetAt!: Date
+}

package/templates/be/skeleton/src/modules/platform/http-security/persistence/migrations/1789900000000-create-rate-windows.ts

@@ -0,0 +1,24 @@
+import type { MigrationInterface, QueryRunner } from "typeorm"
+
+/** Creates the rate limit windows every api replica counts in. */
+export class CreateRateWindows1789900000000 implements MigrationInterface {
+    name = "CreateRateWindows1789900000000"
+
+    /** Creates the windows table and the index the prune reads. */
+    async up(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`CREATE TABLE http_security_rate_windows (
+    key varchar(128) PRIMARY KEY,
+    hits integer NOT NULL CHECK (hits > 0),
+    reset_at timestamptz NOT NULL
+)`)
+        await queryRunner.query(
+            `CREATE INDEX ix_http_security_rate_windows_reset_at ON http_security_rate_windows (reset_at)`,
+        )
+    }
+
+    /** Drops the index and the table. */
+    async down(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`DROP INDEX ix_http_security_rate_windows_reset_at`)
+        await queryRunner.query(`DROP TABLE http_security_rate_windows`)
+    }
+}

package/templates/be/skeleton/src/modules/platform/http-security/persistence/rate-limit.rows.ts

@@ -0,0 +1,5 @@
+/** The row HIT_RATE_WINDOW answers. */
+export interface RateWindowRow {
+    /** The hits of the caller's current window, this one included. */
+    readonly hits: number
+}

package/templates/be/skeleton/src/modules/platform/http-security/persistence/rate-limit.sql.ts

@@ -0,0 +1,20 @@
+import { sql } from "@modules/platform/database"
+
+/**
+ * Counts one hit in the caller's window and answers the hits of that window: a missing or expired window opens afresh at one
+ * hit and ends at $3 ($1 tier and address key, $2 instant, $3 end of a fresh window).
+ */
+export const HIT_RATE_WINDOW = sql`INSERT INTO http_security_rate_windows (key, hits, reset_at)
+    VALUES ($1::varchar, 1, $3::timestamptz)
+    ON CONFLICT (key) DO UPDATE SET
+        hits = CASE WHEN http_security_rate_windows.reset_at <= $2::timestamptz THEN 1
+            ELSE http_security_rate_windows.hits + 1 END,
+        reset_at = CASE WHEN http_security_rate_windows.reset_at <= $2::timestamptz THEN EXCLUDED.reset_at
+            ELSE http_security_rate_windows.reset_at END
+    RETURNING hits`
+
+/** Deletes a bounded batch of the windows that ended by $1; a second replica skips the rows this one holds. */
+export const PRUNE_RATE_WINDOWS = sql`DELETE FROM http_security_rate_windows WHERE key IN (
+    SELECT key FROM http_security_rate_windows WHERE reset_at <= $1::timestamptz
+    LIMIT 100 FOR UPDATE SKIP LOCKED
+)`