@starci/hfs 4.11.22 → 4.12.2

package/scaffold/app.d.mts

@@ -0,0 +1,198 @@
+import { type Presets } from '../sync/index.mjs';
+import type { SlotManifest } from '../runtime/scripts/hfs/manifest-shape.mjs';
+/** The canon pins by package name (canonPins). */
+type Pins = Readonly<Record<string, {
+    readonly version: string;
+}>>;
+/** A concern of the front-end stack catalog. */
+interface FeStackConcern {
+    readonly id?: string;
+    readonly tier?: string;
+    readonly packages?: readonly string[];
+}
+/** The parsed front-end stack catalog. */
+interface FeStack {
+    readonly concerns?: readonly FeStackConcern[];
+}
+/** The core packages of the fe stack, split into the app workspaces' and the root's. */
+interface CoreFeStackPackages {
+    readonly app: string[];
+    readonly root: string[];
+}
+/** An app of a side of the declaration. */
+interface AppEntry {
+    readonly name: string;
+    readonly kind: string;
+}
+/** A side of a resolved declaration. */
+interface SideDeclaration {
+    readonly apps: readonly AppEntry[];
+    readonly grammar?: string;
+}
+/** The resolved declaration of an app, as far as the scaffold reads it. */
+interface ResolvedApp {
+    readonly edition: string;
+    readonly project: string;
+    readonly sides: {
+        readonly be: SideDeclaration;
+        readonly fe: SideDeclaration;
+    };
+}
+type Scope = 'app' | 'be' | 'fe';
+/** The values a skeleton file may fill. */
+type SkeletonVars = Readonly<Record<string, string>>;
+/** A file of the scaffold: app-relative path and text. */
+interface GeneratedFile {
+    readonly path: string;
+    readonly content: string;
+}
+/** The root package.json of a new app. */
+interface PackageManifest {
+    name: string;
+    version: string;
+    private: boolean;
+    packageManager: string;
+    workspaces: string[];
+    dependencies: Record<string, string>;
+    devDependencies: Record<string, string>;
+    overrides?: Record<string, string>;
+}
+/** The outcome of npm resolving the lockfile. */
+export type LockResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly detail: string;
+};
+/** git init, as the scaffold calls it. */
+type InitGit = (root: string, options: {
+    branch: string;
+}) => {
+    ok?: boolean;
+    stderr?: unknown;
+} | null | undefined;
+/** The fe apps that carry the shared app core: every declared Next app but the marketing one. */
+export declare const coreFeApps: <T extends AppEntry>(apps: readonly T[]) => T[];
+/**
+ * The `tier: core` packages of the fe stack every scaffold installs, read from fe-stack.yaml (never listed here), split into
+ * `app` (the runtime imports of each product fe app workspace) and `root` (the tools at the app root). Both editions alike.
+ */
+export declare function coreFeStackPackages(stack?: FeStack): CoreFeStackPackages;
+/**
+ * A JSON file as prettier prints it (the app's format check judges every file the scaffold writes): an object one key per line, an
+ * array of plain values on one line, any other array one item per line.
+ */
+export declare function jsonText(value: unknown): string;
+/** A package.json as Prettier prints it (notably, package workspaces stay one entry per line). */
+export declare const packageJsonText: (value: unknown) => string;
+/** The app hfs.json of a new app called `name`; full remains the byte-for-byte default declaration. */
+export declare const starterDeclaration: (name: string, manifest?: SlotManifest, edition?: string) => {
+    project: string;
+    sides: Readonly<{
+        be: Readonly<{
+            apps: {
+                name: string;
+                kind: string;
+            }[];
+            kinds: string[];
+            connections: {
+                name: string;
+                envPrefix: string;
+                owner: string;
+                isolation: string;
+            }[];
+        }>;
+        fe: Readonly<{
+            grammar: "core";
+            apps: {
+                name: string;
+                kind: string;
+            }[];
+            reads: string[];
+            optionalSlots: string[];
+        }>;
+    }> | Readonly<{
+        be: Readonly<{
+            apps: {
+                name: string;
+                kind: string;
+            }[];
+            kinds: string[];
+            connections: {
+                name: string;
+                envPrefix: string;
+                owner: string;
+                isolation: string;
+                provider: string;
+            }[];
+        }>;
+        fe: Readonly<{
+            grammar: "core";
+            apps: {
+                name: string;
+                kind: string;
+            }[];
+            reads: string[];
+        }>;
+    }>;
+    edition?: string;
+    hfs: number;
+    kind: string;
+};
+/** A runtime-peer pair of the catalog: `requires` is needed when every `when` package is declared (at its major, when given). */
+interface PeerPair {
+    readonly requires: string;
+    readonly when: ReadonlyArray<{
+        readonly package: string;
+        readonly major?: number;
+    }>;
+}
+/**
+ * The runtime peers (R111, knowledge/hfs/peer-integrations.yaml) a root package.json needs and does not declare in its
+ * dependencies: the `requires` of every pair whose `when` packages it declares (at the named major, read from the declared
+ * exact pin), each at its canon pin. Both editions alike: @nestjs/apollo on @nestjs/platform-express 11 needs
+ * @as-integrations/express5.
+ */
+export declare function peerDependencies(pkg: Pick<PackageManifest, 'dependencies' | 'devDependencies'>, pins: Pins, pairs?: readonly PeerPair[]): Record<string, string>;
+/** Let sync's renderer expand partials first while leaving every source placeholder for `fill` to validate or preserve. */
+export declare const PARTIAL_VARIABLES: any;
+/**
+ * The be files a generator writes when it first needs them, never the starter, so a fresh app carries no file and no export that
+ * nothing reads (R25). In both editions: the entity bases of platform/database (abstract.entity.ts, BE-PERSISTENCE-3), written by
+ * the first table whose entity extends them, since no starter table has both timestamps. In lite also: the cli's runners, the in-order
+ * relay, and the raw SQL helpers of platform/database (the sql tag, and the database-function call statement with its spec), which only
+ * the table, queue, jobs and webhook capabilities call; a fresh app reads and writes through entities alone (R334).
+ */
+export declare const ENTITY_BASE_FILE = "src/modules/platform/database/abstract.entity.ts";
+/**
+ * The skeleton files of one scope (app root, be, fe): [{ path, content }], app-relative; a `__app__` file once per api app of the
+ * be side (once per product app of the fe side, coreFeApps), the be `apps/cli/` folder once when the cli app is declared, an fe `apps/<name>/` folder
+ * once for the declared fe app <name> (none other), `__project__` in a path replaced by the project name.
+ */
+export declare function skeletonOf(scope: Scope, app: ResolvedApp, vars: SkeletonVars): GeneratedFile[];
+/** The npm step that resolves the lockfile of a new app, exactly as the error names it. */
+export declare const LOCK_STEP = "npm install --package-lock-only --ignore-scripts --no-audit --no-fund";
+/**
+ * Resolves the real package-lock.json of the app at `root` with npm (the registry and the npm cache; no node_modules and no
+ * lifecycle script). `{ ok: true }` or `{ ok: false, detail }`.
+ */
+export declare function npmLock(root: string): LockResult;
+export declare function scaffoldApp({ name, into, presets, harness, edition, registryVisibility, manifest, pins, lock, initGit, now }: {
+    name: string;
+    into: string;
+    presets: Presets | null | undefined;
+    harness: {
+        version?: string | undefined;
+    } | undefined;
+    edition?: string;
+    registryVisibility?: string;
+    manifest?: SlotManifest;
+    pins?: Pins;
+    lock?: (root: string) => LockResult;
+    initGit?: InitGit;
+    now?: () => Date;
+}): {
+    root: string;
+    files: string[];
+};
+export {};