@starci/hfs 4.0.8 → 4.0.9

package/scaffold/lite-exports.mjs

@@ -0,0 +1,186 @@
+import fs from "node:fs"
+import path from "node:path"
+import { ScaffoldError } from "./service.mjs"
+
+const REGISTRATIONS = Object.freeze({
+  api: [
+    {
+      file: "be/src/modules/domain/identity/index.ts",
+      source: "./identity.decorators",
+      names: ["CurrentPrincipal"],
+    },
+    {
+      file: "be/src/modules/platform/cqrs/index.ts",
+      source: "./cqrs.contracts",
+      names: ["ExecuteParams"],
+      type: true,
+    },
+    {
+      file: "be/src/modules/platform/cqrs/index.ts",
+      source: "./cqrs.decorators",
+      names: ["InjectCommandBus"],
+    },
+  ],
+  table: [
+    {
+      file: "be/src/modules/platform/database/index.ts",
+      source: "./database.sql",
+      names: ["requireOwnedRow", "sql"],
+      beforeSource: "./errors/database.error",
+    },
+    {
+      file: "be/src/modules/platform/database/index.ts",
+      source: "./primary.decorators",
+      names: ["InjectPrimaryEntityManager"],
+    },
+  ],
+  webhook: [
+    {
+      file: "be/src/modules/platform/database/index.ts",
+      source: "./database.sql",
+      names: ["sql"],
+      beforeSource: "./errors/database.error",
+    },
+    {
+      file: "be/src/modules/platform/database/index.ts",
+      source: "./primary.decorators",
+      names: ["InjectPrimaryEntityManager"],
+    },
+    {
+      file: "be/src/modules/platform/http-security/index.ts",
+      source: "./http-security.config",
+      names: ["parseWebhookProviderConfig"],
+    },
+    {
+      file: "be/src/modules/platform/http-security/index.ts",
+      source: "./http-security.decorators",
+      names: ["InjectWebhookSignature"],
+    },
+    {
+      file: "be/src/modules/platform/http-security/index.ts",
+      source: "./rate-limit.guard",
+      names: ["RateLimit", "RateTier"],
+    },
+    {
+      file: "be/src/modules/platform/http-security/index.ts",
+      source: "./webhook-signature.service",
+      names: ["WebhookSignatureService"],
+    },
+  ],
+  "webhook-full": [
+    {
+      file: "be/src/modules/platform/http-security/index.ts",
+      source: "./http-security.config",
+      names: ["parseWebhookProviderConfig"],
+    },
+    {
+      file: "be/src/modules/platform/http-security/index.ts",
+      source: "./http-security.decorators",
+      names: ["InjectWebhookSignature"],
+    },
+    {
+      file: "be/src/modules/platform/http-security/index.ts",
+      source: "./rate-limit.guard",
+      names: ["RateLimit", "RateTier"],
+    },
+    {
+      file: "be/src/modules/platform/http-security/index.ts",
+      source: "./webhook-signature.service",
+      names: ["WebhookSignatureService"],
+    },
+  ],
+  cli: [
+    {
+      file: "be/src/modules/platform/database/index.ts",
+      source: "./migration-runner.service",
+      names: ["MigrationRunnerService"],
+      beforeSource: "./database.options",
+    },
+    {
+      file: "be/src/modules/platform/database/index.ts",
+      source: "./seed-runner.service",
+      names: ["SeedRunnerService"],
+      beforeSource: "./database.options",
+    },
+  ],
+})
+
+const escape = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+
+/** Every file below a folder (absolute paths); none when the folder is absent. */
+export const filesBelow = (folder) => {
+  const files = []
+  const visit = (at) => {
+    for (const entry of fs.readdirSync(at, { withFileTypes: true })) {
+      const target = path.join(at, entry.name)
+      if (entry.isDirectory()) visit(target)
+      else files.push(target)
+    }
+  }
+  if (fs.existsSync(folder)) visit(folder)
+  return files
+}
+
+function addExport(text, registration) {
+  const kind = registration.type === true ? "export type" : "export"
+  const line = new RegExp(`^${kind} \\{ ([^}]*) \\} from "${escape(registration.source)}"$`, "m")
+  const found = line.exec(text)
+  if (found) {
+    const names = [...new Set([...found[1].split(",").map((name) => name.trim()), ...registration.names])].sort()
+    return text.replace(line, `${kind} { ${names.join(", ")} } from "${registration.source}"`)
+  }
+  const added = `${kind} { ${registration.names.join(", ")} } from "${registration.source}"`
+  if (registration.beforeSource) {
+    const before = new RegExp(`^export(?: type)? \\{ [^}]* \\} from "${escape(registration.beforeSource)}"$`, "m")
+    if (before.test(text)) return text.replace(before, `${added}\n$&`)
+  }
+  return `${text.replace(/\n+$/, "")}\n${added}\n`
+}
+
+/** Adds only the barrel exports first consumed by one generator; full webhooks share the same optional platform API. */
+export function registerLiteExports({ root, generator }) {
+  const registrations = REGISTRATIONS[generator]
+  if (!registrations) throw new ScaffoldError("HFS_ADD_EXPORTS_UNKNOWN", `no export registration exists for ${generator}`)
+  const byFile = new Map()
+  for (const registration of registrations) {
+    const list = byFile.get(registration.file) ?? []
+    list.push(registration)
+    byFile.set(registration.file, list)
+  }
+  const changed = []
+  for (const [relative, entries] of byFile) {
+    const file = path.join(root, ...relative.split("/"))
+    if (!fs.existsSync(file)) {
+      throw new ScaffoldError("HFS_ADD_EXPORTS_MISSING", `${generator} needs the scaffolded barrel ${relative}`)
+    }
+    const before = fs.readFileSync(file, "utf8").replace(/\r\n/g, "\n")
+    const after = entries.reduce(addExport, before)
+    if (after !== before) {
+      fs.writeFileSync(file, after)
+      changed.push(relative)
+    }
+  }
+  return changed
+}
+
+/** Makes a domain service public only when a generated transport first imports its module barrel. */
+export function registerLiteDomainService({ root, moduleSpecifier, service }) {
+  const prefix = "@modules/domain/"
+  if (!moduleSpecifier.startsWith(prefix)) return null
+  const owner = path.join(root, "be", "src", "modules", "domain", ...moduleSpecifier.slice(prefix.length).split("/"))
+  const index = path.join(owner, "index.ts")
+  if (!fs.existsSync(index)) {
+    throw new ScaffoldError("HFS_ADD_EXPORTS_MISSING", `the generated transport needs the domain barrel ${moduleSpecifier}/index.ts`)
+  }
+  const candidates = filesBelow(owner).filter(
+    (file) => file.endsWith(".service.ts") && new RegExp(`\\bexport\\s+class\\s+${escape(service)}\\b`).test(fs.readFileSync(file, "utf8")),
+  )
+  if (candidates.length !== 1) {
+    throw new ScaffoldError("HFS_ADD_EXPORTS_SERVICE", `${moduleSpecifier} must contain exactly one exported ${service} in a .service.ts file`)
+  }
+  const before = fs.readFileSync(index, "utf8").replace(/\r\n/g, "\n")
+  if (new RegExp(`\\b${escape(service)}\\b`).test(before)) return null
+  const source = `./${path.relative(owner, candidates[0]).replaceAll("\\", "/").replace(/\.ts$/, "")}`
+  fs.writeFileSync(index, `${before.replace(/\n+$/, "")}\nexport { ${service} } from "${source}"\n`)
+  return path.relative(root, index).replaceAll("\\", "/")
+}

package/scaffold/service.mjs

@@ -1,4 +1,4 @@
-// hfs new service | spec - the one way a `*.service.ts` and its unit spec come into being.
+// starci app new service | spec - the one way a `*.service.ts` and its unit spec come into being.
 //
 // Unit test standard (owner-locked): only `*.service.ts` files are unit-tested, each with exactly one colocated
 // `<name>.service.spec.ts`, built with `Test.createTestingModule({ providers }).compile()` and `moduleRef.get(Service)`,
@@ -15,7 +15,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { createRequire } from 'node:module';
 import { explainPath } from '../runtime/scripts/hfs/check.mjs';
-import { loadSlotManifest, readRepoDeclaration } from '../runtime/scripts/hfs/slots.mjs';
+import { createSlotResolver, loadSlotManifest, readRepoDeclaration } from '../runtime/scripts/hfs/slots.mjs';
+import { refuseInEdition } from './edition-gate.mjs';
 
 export class ScaffoldError extends Error {
   constructor(code, message) {
@@ -36,7 +37,7 @@ const words = name => name.replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/([A-Z
 /** `member-profile` -> `MemberProfile`. */
 export const pascalOf = name => words(name).map(word => word[0].toUpperCase() + word.slice(1).toLowerCase()).join('');
 /** `InjectPrimaryEntityManager` -> `PRIMARY_ENTITY_MANAGER`. */
-export const tokenNameOf = decorator => words(decorator.replace(/^Inject/, '')).map(word => word.toUpperCase()).join('_');
+const tokenNameOf = decorator => words(decorator.replace(/^Inject/, '')).map(word => word.toUpperCase()).join('_');
 const camelOf = name => { const pascal = pascalOf(name); return pascal[0].toLowerCase() + pascal.slice(1); };
 
 const SERVICE_NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
@@ -49,7 +50,7 @@ const SERVICE_NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
  *   decorator (or `@Inject(TOKEN)`), or { kind: 'class', name, className, module } for a class-typed parameter.
  *   `type` is { text, imports: [{ name, module }] }, the parameter type and where each imported name of it comes from.
  */
-export function readServiceShape({ ts, fileName, text }) {
+function readServiceShape({ ts, fileName, text }) {
   const source = ts.createSourceFile(fileName, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
   const imported = new Map();
   for (const statement of source.statements) {
@@ -116,7 +117,8 @@ const EMITTERS = {
   mockEntityManager: () => ({ code: 'mockEntityManager()', uses: ['mockEntityManager'] }),
   fakeTransaction: () => ({ code: 'fakeTransaction(mockEntityManager())', uses: ['fakeTransaction', 'mockEntityManager'] }),
   FakeClock: () => ({ code: 'clock', clock: true }),
-  recordingOutbox: () => ({ code: 'recordingOutbox()', uses: ['recordingOutbox'] }),
+  recordingEventBus: () => ({ code: 'recordingEventBus()', uses: ['recordingEventBus'] }),
+  recordingQueueOutbox: () => ({ code: 'recordingQueueOutbox()', uses: ['recordingQueueOutbox'] }),
   fakeCache: () => ({ code: 'fakeCache(clock)', uses: ['fakeCache'], clock: true }),
   fakeLock: () => ({ code: 'fakeLock(clock)', uses: ['fakeLock'], clock: true }),
   fakeIds: () => ({ code: 'fakeIds()', uses: ['fakeIds'] }),
@@ -137,7 +139,7 @@ const compareModules = (a, b) => {
 };
 
 /** The spec skeleton of a service shape: text of `<name>.service.spec.ts`. */
-export function specSkeleton({ shape, serviceFile, manifest = loadSlotManifest() }) {
+function specSkeleton({ shape, serviceFile, manifest = loadSlotManifest() }) {
   const table = tableOf(manifest);
   const subject = `./${path.basename(serviceFile).replace(/\.ts$/, '')}`;
   const kit = new Set();
@@ -161,7 +163,7 @@ export function specSkeleton({ shape, serviceFile, manifest = loadSlotManifest()
     }
     const entry = doubleOf(table, dependency.token);
     const emit = EMITTERS[entry.double];
-    if (!emit) throw new ScaffoldError('HFS_NEW_DOUBLE_UNKNOWN', `the slot manifest names the double ${entry.double} for ${dependency.token}, which hfs new cannot write yet`);
+    if (!emit) throw new ScaffoldError('HFS_NEW_DOUBLE_UNKNOWN', `the slot manifest names the double ${entry.double} for ${dependency.token}, which starci app new cannot write yet`);
     const made = emit(dependency);
     for (const name of made.uses ?? []) kit.add(name);
     if (made.clock) { needsClock = true; kit.add('FakeClock'); }
@@ -239,7 +241,7 @@ function uniqueName(name, taken) {
  * `--inject` entries: `InjectCache=@modules/integrations/cache:Cache` (a token dependency: decorator, the module that exports the
  * decorator and its token, the parameter type) or `ProbeCheckerService=@modules/platform/probes` (a class dependency).
  */
-export function parseInject(entry) {
+function parseInject(entry) {
   const match = /^([A-Za-z][A-Za-z0-9]*)=([^:\s]+)(?::([A-Za-z][A-Za-z0-9<>, ]*))?$/.exec(entry);
   if (!match) throw new ScaffoldError('HFS_NEW_INJECT_INVALID', `--inject ${entry}: expected InjectName=<module>:<Type> or ClassName=<module>`);
   const [, name, module, type] = match;
@@ -252,7 +254,7 @@ export function parseInject(entry) {
 }
 
 /** The text of a new `<name>.service.ts` with the given dependencies (parseInject results). */
-export function serviceSource({ name, dependencies = [] }) {
+function serviceSource({ name, dependencies = [] }) {
   const className = `${pascalOf(name)}Service`;
   const values = new Map();
   const types = new Map();
@@ -280,24 +282,24 @@ export function serviceSource({ name, dependencies = [] }) {
 
 const loadTypeScript = repoRoot => {
   try { return createRequire(path.join(repoRoot, 'package.json'))('typescript'); } catch {
-    throw new ScaffoldError('HFS_NEW_TYPESCRIPT_MISSING', `typescript is not installed under ${repoRoot}; run npm ci first, hfs new reads the constructor with the repository's own TypeScript`);
+    throw new ScaffoldError('HFS_NEW_TYPESCRIPT_MISSING', `typescript is not installed under ${repoRoot}; run npm ci first, starci app new reads the constructor with the repository's own TypeScript`);
   }
 };
 
 const BE = 'be';
 
-/** The be side folder of the app at `appRoot`: hfs new runs at the app root and writes into be/ only. */
-const backEndOf = appRoot => {
+/** The declaration of the app at `appRoot` and its be side folder: starci app new runs at the app root and writes into be/ only. */
+const backEndOf = (appRoot, manifest = loadSlotManifest()) => {
   let repo;
-  try { repo = readRepoDeclaration(loadSlotManifest(), appRoot); } catch (error) { throw new ScaffoldError('HFS_NEW_NO_HFS', `${appRoot} has no valid app hfs.json (${error.message})`); }
-  if (!repo.sides) throw new ScaffoldError('HFS_NEW_NO_HFS', `${appRoot} is not the app root; run hfs new at the folder of hfs.json`);
-  return path.join(appRoot, BE);
+  try { repo = readRepoDeclaration(manifest, appRoot); } catch (error) { throw new ScaffoldError('HFS_NEW_NO_HFS', `${appRoot} has no valid app hfs.json (${error.message})`); }
+  if (!repo.sides) throw new ScaffoldError('HFS_NEW_NO_HFS', `${appRoot} is not the app root; run starci app new at the folder of hfs.json`);
+  return { repo, beRoot: path.join(appRoot, BE) };
 };
 
 /** An app-relative path below be/ as a be-relative one; a path of the root or of fe/ is refused. */
 const belowBackEnd = input => {
   const relative = input.split(path.sep).join('/').replace(/^\.\//, '').replace(/\/$/, '');
-  if (!relative.startsWith(`${BE}/`)) throw new ScaffoldError('HFS_NEW_BACKEND_ONLY', `hfs new service | spec writes back-end services under be/; ${relative} is not below be/`);
+  if (!relative.startsWith(`${BE}/`)) throw new ScaffoldError('HFS_NEW_BACKEND_ONLY', `starci app new service | spec writes back-end services under be/; ${relative} is not below be/`);
   return relative.slice(BE.length + 1);
 };
 
@@ -309,35 +311,39 @@ const requireSlot = (repoRoot, relative) => {
 
 const writeNew = (repoRoot, relative, text) => {
   const target = path.join(repoRoot, relative);
-  if (fs.existsSync(target)) throw new ScaffoldError('HFS_NEW_EXISTS', `${relative} already exists; hfs new never overwrites`);
+  if (fs.existsSync(target)) throw new ScaffoldError('HFS_NEW_EXISTS', `${relative} already exists; starci app new never overwrites`);
   fs.mkdirSync(path.dirname(target), { recursive: true });
   fs.writeFileSync(target, text);
   return relative;
 };
 
-/** `hfs new spec be/<file>.service.ts` at the app root: writes the spec skeleton of an existing service; returns the created app-relative paths. */
-export function newSpec({ repoRoot: appRoot, file, ts = loadTypeScript(appRoot), manifest = loadSlotManifest() }) {
-  const repoRoot = backEndOf(appRoot);
+/** `starci app new spec be/<file>.service.ts` at the app root: writes the spec skeleton of an existing service; returns the created app-relative paths. */
+export function newSpec({ repoRoot: appRoot, file, ts, manifest = loadSlotManifest() }) {
+  const { repo, beRoot: repoRoot } = backEndOf(appRoot, manifest);
+  // `new spec` writes a unit spec: the test world it belongs to (be.tests.*) is a full-edition capability.
+  refuseInEdition({ resolver: createSlotResolver(manifest, repo), slotIds: ['be.tests.world'], command: 'new spec' });
   const relative = belowBackEnd(file);
   if (!relative.endsWith('.service.ts')) throw new ScaffoldError('HFS_NEW_NOT_A_SERVICE', `${relative} is not a *.service.ts file: only services have a unit spec`);
   const absolute = path.join(repoRoot, relative);
   if (!fs.existsSync(absolute)) throw new ScaffoldError('HFS_NEW_NO_SERVICE', `${relative} does not exist`);
   const specPath = relative.replace(/\.ts$/, '.spec.ts');
   requireSlot(repoRoot, specPath);
-  const shape = readServiceShape({ ts, fileName: absolute, text: fs.readFileSync(absolute, 'utf8') });
+  const shape = readServiceShape({ ts: ts ?? loadTypeScript(appRoot), fileName: absolute, text: fs.readFileSync(absolute, 'utf8') });
   return [writeNew(repoRoot, specPath, specSkeleton({ shape, serviceFile: relative, manifest }))].map(created => `${BE}/${created}`);
 }
 
-/** `hfs new service be/<dir> <name> [--inject ...]` at the app root: writes the service and its spec skeleton; returns the created app-relative paths. */
-export function newService({ repoRoot: appRoot, dir, name, inject = [], ts = loadTypeScript(appRoot), manifest = loadSlotManifest() }) {
-  const repoRoot = backEndOf(appRoot);
+/** `starci app new service be/<dir> <name> [--inject ...]` at the app root: writes the service and its spec skeleton; returns the created app-relative paths. */
+export function newService({ repoRoot: appRoot, dir, name, inject = [], ts, manifest = loadSlotManifest() }) {
+  const { repo, beRoot: repoRoot } = backEndOf(appRoot, manifest);
+  // `new service` writes the service and its unit spec: the test world (be.tests.*) is a full-edition capability.
+  refuseInEdition({ resolver: createSlotResolver(manifest, repo), slotIds: ['be.tests.world'], command: 'new service' });
   if (!SERVICE_NAME.test(name)) throw new ScaffoldError('HFS_NEW_NAME_INVALID', `the service name ${name} must be kebab-case (member-profile), without the .service suffix`);
   const relative = path.posix.join(belowBackEnd(dir), `${name}.service.ts`);
   requireSlot(repoRoot, relative);
   requireSlot(repoRoot, relative.replace(/\.ts$/, '.spec.ts'));
-  for (const target of [relative, relative.replace(/\.ts$/, '.spec.ts')]) if (fs.existsSync(path.join(repoRoot, target))) throw new ScaffoldError('HFS_NEW_EXISTS', `${target} already exists; hfs new never overwrites`);
+  for (const target of [relative, relative.replace(/\.ts$/, '.spec.ts')]) if (fs.existsSync(path.join(repoRoot, target))) throw new ScaffoldError('HFS_NEW_EXISTS', `${target} already exists; starci app new never overwrites`);
   const text = serviceSource({ name, dependencies: inject.map(parseInject) });
-  const shape = readServiceShape({ ts, fileName: path.join(repoRoot, relative), text });
+  const shape = readServiceShape({ ts: ts ?? loadTypeScript(appRoot), fileName: path.join(repoRoot, relative), text });
   const spec = specSkeleton({ shape, serviceFile: relative, manifest });
   return [writeNew(repoRoot, relative, text), writeNew(repoRoot, relative.replace(/\.ts$/, '.spec.ts'), spec)].map(created => `${BE}/${created}`);
 }

package/scaffold/supabase-ports.mjs

@@ -0,0 +1,26 @@
+// supabase-ports.mjs - the local Supabase ports of one lite app, derived from its project name.
+// The Supabase CLI default ports (54321-54329) belong to whichever stack starts first, so a scaffolded app never uses them: it
+// writes its own port block into supabase/config.toml, one block of ten consecutive ports per project name, so two apps (and a
+// proof run beside another stack) never contend. The same name always gets the same block.
+
+/** The first port of the block range and how many blocks it holds (41000-44999); clear of the CLI defaults (543xx) and of the Next dev port. */
+const RANGE_START = 41000;
+const BLOCK_SIZE = 10;
+const BLOCK_COUNT = 400;
+/** The offsets inside one block, by config.toml section. */
+const OFFSETS = Object.freeze({ shadow: 0, api: 1, db: 2, studio: 3, inbucket: 4, analytics: 7, pooler: 9 });
+
+/** The template variables of the port block: `supabasePort<Name>` for every section above. */
+export const SUPABASE_PORT_VARIABLES = Object.freeze(Object.keys(OFFSETS).map((key) => `supabasePort${key[0].toUpperCase()}${key.slice(1)}`));
+
+/** FNV-1a over the project name: stable, dependency-free. */
+const hash = (text) => [...text].reduce((value, char) => Math.imul(value ^ char.charCodeAt(0), 16777619) >>> 0, 2166136261);
+
+/** The first port of the project's block. */
+export const supabasePortBase = (project) => RANGE_START + (hash(String(project)) % BLOCK_COUNT) * BLOCK_SIZE;
+
+/** { supabasePortApi: '41231', ... }: the variables a skeleton file fills. */
+export function supabasePortVars(project) {
+  const base = supabasePortBase(project);
+  return Object.fromEntries(Object.entries(OFFSETS).map(([key, offset]) => [`supabasePort${key[0].toUpperCase()}${key.slice(1)}`, String(base + offset)]));
+}