@starci/hfs 4.3.0 → 4.4.0

package/scaffold/add-fe-page.mjs

@@ -0,0 +1,269 @@
+import fs from "node:fs";
+import path from "node:path";
+import { loadSlotManifest, readRepoDeclaration } from "../runtime/scripts/hfs/slots.mjs";
+import { ScaffoldError, pascalOf } from "./service.mjs";
+
+const NAME = /^[a-z][a-z0-9-]*$/;
+const RESERVED = /^(?:con|prn|aux|nul|com[0-9]|lpt[0-9])$/i;
+const jsonText = (value) => `${JSON.stringify(value, null, 2)}\n`;
+const objectCatalog = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+
+/** Validate a CLI name before it is used in a path, symbol or catalog key. */
+export function feName(value, label = "name") {
+  if (typeof value !== "string" || !NAME.test(value) || value.split("-").includes("") || RESERVED.test(value)) {
+    throw new ScaffoldError("HFS_ADD_NAME_INVALID", `${label} must be kebab-case, without a path or a reserved filename`);
+  }
+  return value;
+}
+
+/** An app-relative target whose existing ancestors are real directories, never symlinks. */
+function feTarget(root, relative) {
+  const target = path.resolve(root, relative);
+  const inside = path.relative(root, target);
+  if (!inside || inside.startsWith("..") || path.isAbsolute(inside)) {
+    throw new ScaffoldError("HFS_ADD_PATH_UNSAFE", `${relative} must stay inside the app root`);
+  }
+  let at = root;
+  const pieces = inside.split(path.sep);
+  for (let index = 0; index < pieces.length; index += 1) {
+    at = path.join(at, pieces[index]);
+    const stat = fs.lstatSync(at, { throwIfNoEntry: false });
+    if (!stat) continue;
+    if (stat.isSymbolicLink() || (index < pieces.length - 1 && !stat.isDirectory())) {
+      throw new ScaffoldError("HFS_ADD_PATH_UNSAFE", `${relative} has a symlink or a non-directory ancestor`);
+    }
+  }
+  return target;
+}
+
+/** Resolve the declared Next app; a multi-app repository must select one explicitly. */
+export function readFeContext({ root, app }) {
+  const repoRoot = path.resolve(root);
+  const stat = fs.lstatSync(repoRoot, { throwIfNoEntry: false });
+  if (!stat?.isDirectory() || stat.isSymbolicLink()) {
+    throw new ScaffoldError("HFS_ADD_NOT_AN_APP", "add page and overlay run at a real app root directory");
+  }
+  const declaration = feTarget(repoRoot, "hfs.json");
+  const packageFile = feTarget(repoRoot, "package.json");
+  if (!fs.existsSync(declaration) || !fs.existsSync(packageFile)) {
+    throw new ScaffoldError("HFS_ADD_NOT_AN_APP", "add page and overlay need hfs.json and package.json at the app root");
+  }
+  const repo = readRepoDeclaration(loadSlotManifest(), repoRoot);
+  const apps = repo.sides?.fe?.apps.filter((candidate) => candidate.kind === "next") ?? [];
+  if (!apps.length) throw new ScaffoldError("HFS_ADD_NO_FRONT_END", "this app has no declared Next front end");
+  if (app !== undefined) feName(app, "app");
+  if (app === undefined && apps.length !== 1) {
+    throw new ScaffoldError("HFS_ADD_OPTION_MISSING", "add page and overlay need --app when several Next apps are declared");
+  }
+  const selected = apps.find((candidate) => candidate.name === (app ?? apps[0].name));
+  if (!selected) throw new ScaffoldError("HFS_ADD_APP_UNKNOWN", `front-end app ${app} is not declared`);
+  feName(selected.name, "declared app");
+  return { root: repoRoot, app: selected.name, repo, source: `fe/apps/${selected.name}/src` };
+}
+
+/** Read a required owner file only after checking every path ancestor. */
+export function readFeFile(context, relative) {
+  const target = feTarget(context.root, relative);
+  if (!fs.existsSync(target) || !fs.statSync(target).isFile()) {
+    throw new ScaffoldError("HFS_ADD_WIRE_MISSING", `${relative} is required before this feature can be added`);
+  }
+  return fs.readFileSync(target, "utf8");
+}
+
+/** Refuse an existing owner, including a partially generated one. */
+export function requireNewFeOwner(context, relative) {
+  if (fs.existsSync(feTarget(context.root, relative))) {
+    throw new ScaffoldError("HFS_ADD_EXISTS", `${relative} already exists; add never replaces an existing owner`);
+  }
+}
+
+function readCatalogs(context) {
+  const directory = `${context.source}/modules/i18n/messages`;
+  const target = feTarget(context.root, directory);
+  if (!fs.existsSync(target)) throw new ScaffoldError("HFS_ADD_WIRE_MISSING", `${directory} is required`);
+  if (!fs.statSync(target).isDirectory()) throw new ScaffoldError("HFS_ADD_I18N_INVALID", `${directory} must be a directory`);
+  const files = fs.readdirSync(target).filter((file) => file.endsWith(".json")).sort();
+  if (!["vi.json", "en.json"].every((file) => files.includes(file))) {
+    throw new ScaffoldError("HFS_ADD_I18N_MISSING", `${directory} needs both vi.json and en.json`);
+  }
+  return files.map((file) => {
+    const relative = `${directory}/${file}`;
+    const before = readFeFile(context, relative);
+    return { relative, before, locale: file.slice(0, -5), catalog: parseCatalog(before, relative) };
+  });
+}
+
+function parseCatalog(before, relative) {
+  let catalog;
+  try { catalog = JSON.parse(before); } catch {
+    throw new ScaffoldError("HFS_ADD_I18N_INVALID", `${relative} must contain valid JSON`);
+  }
+  if (!objectCatalog(catalog)) throw new ScaffoldError("HFS_ADD_I18N_INVALID", `${relative} must contain a catalog object`);
+  return catalog;
+}
+
+function catalogNamespace(catalogs, app) {
+  const first = catalogs[0].catalog;
+  const keys = Object.keys(first);
+  let namespace = keys.length === 1 ? keys[0] : app;
+  if (!Object.hasOwn(first, namespace) && Object.hasOwn(first, "app")) namespace = "app";
+  if (!catalogs.every(({ catalog }) => Object.hasOwn(catalog, namespace) && objectCatalog(catalog[namespace]))) {
+    throw new ScaffoldError("HFS_ADD_I18N_INVALID", "the app catalogs need a shared object namespace");
+  }
+  return namespace;
+}
+
+function catalogCopy(locale, defaults, messages) {
+  const copy = messages?.[locale] ?? defaults[locale];
+  const required = Object.keys(defaults.en);
+  if (!copy || !required.every((key) => typeof copy[key] === "string" && copy[key].trim())) {
+    throw new ScaffoldError("HFS_ADD_I18N_INVALID", `provide the ${required.join(", ")} messages for locale ${locale}`);
+  }
+  return Object.fromEntries(required.map((key) => [key, copy[key]]));
+}
+
+/** Plan matching localized keys in every catalog without changing existing copy. */
+export function planFeCatalogs(context, { group, name, defaults, messages }) {
+  const catalogs = readCatalogs(context);
+  const namespace = catalogNamespace(catalogs, context.app);
+  const updates = catalogs.map(({ catalog, locale, relative, before }) => {
+    const owner = catalog[namespace];
+    if (owner[group] !== undefined && !objectCatalog(owner[group])) {
+      throw new ScaffoldError("HFS_ADD_I18N_INVALID", `${relative}: ${namespace}.${group} must be an object`);
+    }
+    owner[group] ??= {};
+    if (Object.hasOwn(owner[group], name)) {
+      throw new ScaffoldError("HFS_ADD_EXISTS", `${relative} already declares ${namespace}.${group}.${name}`);
+    }
+    owner[group][name] = catalogCopy(locale, defaults, messages);
+    return { relative, before, body: jsonText(catalog) };
+  });
+  return { namespace: `${namespace}.${group}.${name}`, updates };
+}
+
+function createParent(root, target, made) {
+  const missing = [];
+  for (let at = path.dirname(target); at !== root && !fs.existsSync(at); at = path.dirname(at)) missing.push(at);
+  for (const directory of missing.reverse()) {
+    fs.mkdirSync(directory);
+    made.push(directory);
+  }
+}
+
+function writeCreated(target, body, written) {
+  const descriptor = fs.openSync(target, "wx");
+  written.push(target);
+  try { fs.writeFileSync(descriptor, body); } finally { fs.closeSync(descriptor); }
+}
+
+/** Execute a fully checked plan and restore updated owners if a write fails. */
+export function writeFePlan(context, created, updates) {
+  for (const file of created) requireNewFeOwner(context, file.relative);
+  for (const file of updates) {
+    if (readFeFile(context, file.relative) !== file.before) {
+      throw new ScaffoldError("HFS_ADD_WIRE_INVALID", `${file.relative} changed while planning the feature`);
+    }
+  }
+  const written = [];
+  const updated = [];
+  const directories = [];
+  try {
+    for (const file of created) {
+      const target = feTarget(context.root, file.relative);
+      createParent(context.root, target, directories);
+      writeCreated(target, file.body, written);
+    }
+    for (const file of updates) {
+      updated.push(file);
+      fs.writeFileSync(feTarget(context.root, file.relative), file.body);
+    }
+  } catch (error) {
+    for (const file of updated.reverse()) fs.writeFileSync(feTarget(context.root, file.relative), file.before);
+    for (const file of written.reverse()) fs.rmSync(file);
+    for (const directory of directories.reverse()) fs.rmdirSync(directory);
+    throw error;
+  }
+  return { created: created.map((file) => file.relative), updated: updates.map((file) => file.relative) };
+}
+
+function pageSources({ name, namespace, symbol, routeSymbol }) {
+  const metadata = `${name.split("-").map((word, index) => index ? pascalOf(word) : word).join("")}Metadata`;
+  return {
+    metadata,
+    entry: `import type { Metadata } from "next"
+import { getTranslations } from "next-intl/server"
+import { ${routeSymbol} } from "@/modules/routes"
+import { ${symbol}Base } from "./component"
+
+/** The localized document title and canonical destination of this page. */
+export const ${metadata} = async (): Promise<Metadata> => {
+    const t = await getTranslations(${JSON.stringify(namespace)})
+    return { title: t("title"), alternates: { canonical: ${routeSymbol} } }
+}
+
+/** Resolve the requested locale's copy before drawing this server page. */
+export const ${symbol} = async () => {
+    const t = await getTranslations(${JSON.stringify(namespace)})
+    return <${symbol}Base props={{ title: t("title") }} />
+}
+`,
+    component: `import { Heading } from "@starci/grammar/common"
+
+/** The localized words displayed by this page. */
+export interface ${symbol}BaseProps {
+    readonly props: { readonly title: string }
+}
+
+/** Draw the page using the settled copy supplied by its server owner. */
+export const ${symbol}Base = (props: ${symbol}BaseProps) => (
+    <Heading level={1}>{props.props.title}</Heading>
+)
+`,
+  };
+}
+
+function pageRoute(symbol, metadata) {
+  return `import { ${symbol} } from "@/features/pages/${symbol}"
+
+/** The locale-aware metadata of this page. */
+export { ${metadata} as generateMetadata } from "@/features/pages/${symbol}"
+
+/** Mount the page's public server owner. */
+const Page = () => <${symbol} />
+
+export default Page
+`;
+}
+
+/** Add a server page, its thin localized route and matching vi/en catalog entries. */
+export function addFePage({ root, app, name, route = name, messages }) {
+  feName(name, "page name");
+  if (typeof route !== "string" || !route) throw new ScaffoldError("HFS_ADD_OPTION_INVALID", "--route needs one or more kebab-case path segments");
+  for (const segment of route.split("/")) feName(segment, "route segment");
+  const context = readFeContext({ root, app });
+  const symbol = `${pascalOf(name)}Page`;
+  const owner = `${context.source}/features/pages/${symbol}`;
+  requireNewFeOwner(context, owner);
+  const routeFile = `${context.source}/app/[locale]/${route}/page.tsx`;
+  requireNewFeOwner(context, routeFile);
+  const catalogs = planFeCatalogs(context, {
+    group: "pages", name, messages,
+    defaults: { vi: { title: "Trang m\u1edbi" }, en: { title: "New page" } },
+  });
+  const routeSymbol = `${name.replaceAll("-", "_").toUpperCase()}_PAGE_ROUTE`;
+  const routesFile = `${context.source}/modules/routes/index.ts`;
+  const before = readFeFile(context, routesFile);
+  if (before.split(/[^A-Za-z0-9_]/).includes(routeSymbol)) {
+    throw new ScaffoldError("HFS_ADD_EXISTS", `${routesFile} already declares ${routeSymbol}`);
+  }
+  const sources = pageSources({ name, namespace: catalogs.namespace, symbol, routeSymbol });
+  const created = [
+    { relative: `${owner}/index.tsx`, body: sources.entry },
+    { relative: `${owner}/component.tsx`, body: sources.component },
+    { relative: routeFile, body: pageRoute(symbol, sources.metadata) },
+  ];
+  const destination = `/${route}`;
+  const routeBody = `${before.trimEnd()}\n\n/** The canonical destination of the ${symbol} owner. */\nexport const ${routeSymbol} = ${JSON.stringify(destination)} as const\n`;
+  const updates = [...catalogs.updates, { relative: routesFile, before, body: routeBody }];
+  return { ...writeFePlan(context, created, updates), registered: { app: context.app, page: symbol, route: destination } };
+}

package/scaffold/add-inbox-lite.mjs

@@ -3,6 +3,9 @@ import path from "node:path";
 import { render, TEMPLATES_DIR } from "../sync/index.mjs";
 import { ScaffoldError, pascalOf } from "./service.mjs";
 import { filesBelow } from "./lite-exports.mjs";
+import { jsonText } from "./app.mjs";
+import { byCodeUnit } from "../report/order.mjs";
+import { withSqlIdentifierError } from "./add-database-lite.mjs";
 
 const MIGRATION = /^(\d{14})_[a-z][a-z0-9]*(?:-[a-z0-9]+)*\.sql$/;
 const PLACEHOLDER = /@@([A-Za-z][A-Za-z0-9]*)@@/g;
@@ -50,7 +53,7 @@ function validateProcessingOwner({ root, service, serviceModule, provider }) {
     );
   const owner = path.join(root, "be", "src", "modules", "domain", ...capability.split("/"));
   const candidates = filesBelow(owner).filter((file) =>
-    file.endsWith(".service.ts") && new RegExp(`\\bexport\\s+class\\s+${service}\\b`).test(fs.readFileSync(file, "utf8")),
+    file.endsWith(".service.ts") && new RegExp(String.raw`\bexport\s+class\s+${service}\b`).test(fs.readFileSync(file, "utf8")),
   );
   if (candidates.length !== 1)
     throw new ScaffoldError(
@@ -70,8 +73,10 @@ const databasePatches = (root) => {
     );
   let index = fs.readFileSync(indexFile, "utf8").replace(/\r\n/g, "\n");
   if (!index.includes('export { recordWebhookDelivery } from "./webhook-inbox.client"'))
-    index = `${index.replace(/\n+$/, "")}\nexport { recordWebhookDelivery } from "./webhook-inbox.client"\n`;
-  let error = fs.readFileSync(errorFile, "utf8").replace(/\r\n/g, "\n");
+    index = `${index.trimEnd()}\nexport { recordWebhookDelivery } from "./webhook-inbox.client"\n`;
+  if (!index.split("\n").some((line) => line.startsWith("export { ") && line.includes("DatabaseErrorCode") && line.endsWith(' } from "./errors/database.error"')))
+    index = `${index.trimEnd()}\nexport { DatabaseError, DatabaseErrorCode } from "./errors/database.error"\n`;
+  let error = withSqlIdentifierError(fs.readFileSync(errorFile, "utf8").replace(/\r\n/g, "\n"));
   const enumLine =
     '    WebhookDeliveryIdRequired = "DATABASE_WEBHOOK_DELIVERY_ID_REQUIRED",';
   if (!error.includes(enumLine)) {
@@ -97,44 +102,58 @@ const databasePatches = (root) => {
   ];
 };
 
-const wiredAppModule = ({ root, repo, provider, Provider }) => {
-  const app = repo.sides.be.apps.find((entry) => entry.kind === "api");
-  if (!app)
-    throw new ScaffoldError(
-      "HFS_ADD_NO_API_OWNER",
-      "add webhook needs a declared lite api app",
-    );
-  const file = path.join(root, "be", "apps", app.name, "src", "app.module.ts");
-  const relative = `be/apps/${app.name}/src/app.module.ts`;
-  if (!fs.existsSync(file))
-    throw new ScaffoldError(
-      "HFS_ADD_WIRE_MISSING",
-      `add webhook registers its inbox in ${relative}, which does not exist`,
-    );
-  const symbol = `${Provider}InboxModule`;
-  const importLine = `import { ${symbol} } from "@modules/domain/${provider}-inbox"`;
-  const lines = fs.readFileSync(file, "utf8").replace(/\r\n/g, "\n").split("\n");
-  const lastImport = lines.reduce(
-    (last, line, index) => (line.startsWith("import ") ? index : last),
-    -1,
-  );
-  const imports = lines.findIndex((line) => /^\s*imports: \[$/.test(line));
-  if (lastImport < 0 || imports < 0)
-    throw new ScaffoldError(
-      "HFS_ADD_WIRE_INVALID",
-      `add webhook could not find the imports array in ${relative}`,
-    );
-  if (!lines.includes(importLine)) {
-    lines.splice(lastImport + 1, 0, importLine);
-    const shiftedImports = imports > lastImport ? imports + 1 : imports;
-    const indent = /^(\s*)/.exec(lines[shiftedImports])?.[1] ?? "";
-    lines.splice(
-      shiftedImports + 1,
-      0,
-      `${indent}    ${symbol}.register({ isGlobal: true }),`,
-    );
+/** The first webhook installs only the lite inbox claim and transactional event publisher, shared by all providers. */
+const handoffPlatformFiles = (root, values) => {
+  const planned = [];
+  for (const capability of ["inbox", "event-bus"]) {
+    const base = `be/src/modules/platform/${capability}`;
+    if (fs.existsSync(path.join(root, base, "index.ts"))) continue;
+    const folder = path.join(TEMPLATES_DIR, "be", "inbox", "platform", capability);
+    for (const file of filesBelow(folder)) {
+      const relative = path.relative(folder, file).replaceAll("\\", "/");
+      planned.push({
+        relative: `${base}/${relative.replace(/\.tpl$/, "")}`,
+        text: template(`platform/${capability}/${relative}`, values),
+      });
+    }
   }
-  return { file, text: `${lines.join("\n").replace(/\n+$/, "")}\n` };
+  return planned;
+};
+
+/** A provider may already publish other events; retain its barrel and contract when adding the receipt event. */
+const eventFiles = (root, provider, values) => {
+  const entries = [
+    { relative: `be/src/modules/events/${provider}/index.ts`, text: template("event-index.ts.tpl", values) },
+    { relative: `be/contracts/${provider}/events.json`, text: template("events.json.tpl", values) },
+  ];
+  const planned = [];
+  const patches = [];
+  for (const entry of entries) {
+    const file = path.join(root, ...entry.relative.split("/"));
+    if (!fs.existsSync(file)) {
+      planned.push(entry);
+      continue;
+    }
+    const previous = fs.readFileSync(file, "utf8").replace(/\r\n/g, "\n");
+    if (entry.relative.endsWith("index.ts")) {
+      patches.push({ file, text: previous.includes(entry.text.trim()) ? previous : `${previous.trimEnd()}\n${entry.text}` });
+    } else {
+      const contract = JSON.parse(previous);
+      if (contract.schema !== "starci/event-contract@1" || contract.service !== provider || !contract.events || Array.isArray(contract.events) || typeof contract.events !== "object")
+        throw new ScaffoldError("HFS_ADD_EVENT_CONTRACT", `${entry.relative} is not the event contract of ${provider}`);
+      const additions = JSON.parse(entry.text).events;
+      contract.events = { ...contract.events, ...additions };
+      patches.push({ file, text: jsonText(contract) });
+    }
+  }
+  return { planned, patches };
+};
+
+const eventPatternPatch = (root) => {
+  const file = path.join(root, "hfs.json");
+  const declaration = JSON.parse(fs.readFileSync(file, "utf8"));
+  declaration.sides.be.patterns = [...new Set([...(declaration.sides.be.patterns ?? []), "event-bus"])].sort(byCodeUnit);
+  return { file, text: jsonText(declaration) };
 };
 
 /** Writes the lite provider inbox. Processing belongs to a separately added reactor or job, after the record commits. */
@@ -152,7 +171,7 @@ export function addLiteWebhookInbox({
   const table = `${snakeOf(provider)}_inbox`;
   const migrationsDir = path.join(root, "supabase", "migrations");
   const migrations = fs.existsSync(migrationsDir)
-    ? fs.readdirSync(migrationsDir).filter((file) => MIGRATION.test(file)).sort()
+    ? fs.readdirSync(migrationsDir).filter((file) => MIGRATION.test(file)).sort(byCodeUnit)
     : [];
   const suffix = `${provider}-inbox.sql`;
   if (migrations.some((file) => file.endsWith(`_${suffix}`)))
@@ -175,6 +194,7 @@ export function addLiteWebhookInbox({
     table,
   };
   const base = `be/src/modules/domain/${provider}-inbox`;
+  const events = eventFiles(root, provider, renderValues);
   const planned = [
     {
       relative: `supabase/migrations/${stamp}_${suffix}`,
@@ -205,7 +225,18 @@ export function addLiteWebhookInbox({
       relative: `${base}/persistence/${provider}-inbox.sql.ts`,
       text: template("sql.ts.tpl", renderValues),
     },
+    {
+      relative: `be/src/modules/events/${provider}/${provider}-delivery-recorded.event.ts`,
+      text: template("delivery-recorded.event.ts.tpl", renderValues),
+    },
+    ...events.planned,
+    ...handoffPlatformFiles(root, renderValues),
   ];
+  const hasHandoffStorage = migrations.some((file) =>
+    /create\s+table\s+public\.event_bus\b/i.test(fs.readFileSync(path.join(migrationsDir, file), "utf8")),
+  );
+  if (!hasHandoffStorage)
+    planned[0].text = `${template("platform/migration.sql.tpl", renderValues)}\n${planned[0].text}`;
   const databaseSql = "be/src/modules/platform/database/database.sql.ts";
   if (!fs.existsSync(path.join(root, ...databaseSql.split("/")))) {
     planned.push({
@@ -249,7 +280,8 @@ export function addLiteWebhookInbox({
     );
   const patches = [
     ...databasePatches(root),
-    wiredAppModule({ root, repo, provider, Provider }),
+    ...events.patches,
+    eventPatternPatch(root),
   ];
   for (const entry of planned) {
     const target = path.join(root, ...entry.relative.split("/"));