@starci/hfs 4.2.17 → 4.3.0

package/templates/be/skeleton/src/modules/platform/config/env-source.config.ts

@@ -21,18 +21,18 @@ export class Secret {
 }
 
 /**
- * The only reader of the process environment. Typed readers name the missing or malformed key in the error; a key
- * `<KEY>_FILE` supplies `<KEY>` from a file, so secrets can be mounted instead of exported.
+ * The only reader of the process environment. Typed readers name the missing or malformed key in the error.
+ * A declared `<KEY>_FILE` takes priority over `<KEY>` and supplies its exact file contents, so secrets can be mounted.
  */
 export class EnvSource {
     constructor(private readonly values: Readonly<Record<string, string | undefined>>) {}
 
-    /** Reads the process environment once, resolving every `<KEY>_FILE` into `<KEY>`. */
+    /** Reads the process environment once; a declared `<KEY>_FILE` must be readable and never falls back to `<KEY>`. */
     static fromProcess(): EnvSource {
         const values: Record<string, string | undefined> = { ...process.env }
-        for (const [key, path] of Object.entries(process.env)) {
-            if (key.endsWith(FILE_SUFFIX) && path)
-                values[key.slice(0, -FILE_SUFFIX.length)] = readFileSync(path, "utf8").trim()
+        for (const [key, path] of Object.entries(values)) {
+            if (key.endsWith(FILE_SUFFIX) && path !== undefined)
+                values[key.slice(0, -FILE_SUFFIX.length)] = readFileSync(path, "utf8")
         }
         return new EnvSource(values)
     }

package/templates/be/skeleton-lite/apps/api/src/api.env.ts

@@ -0,0 +1,25 @@
+import type { EnvSource } from "@modules/platform/config"
+import { parseServerConfig } from "@modules/platform/config"
+import { parsePrimaryDatabaseConfig } from "@modules/platform/database"
+import { parseHttpSecurityConfig } from "@modules/platform/http-security"
+import { parseSupabaseConfig } from "@modules/integrations/supabase"
+
+/** The API environment values required before composition. */
+export interface ApiEnv {
+    /** The HTTP listener. */
+    readonly server: ReturnType<typeof parseServerConfig>
+    /** The origin allowlist and rate limits. */
+    readonly httpSecurity: ReturnType<typeof parseHttpSecurityConfig>
+    /** The least-privilege PostgreSQL connection to the Supabase project. */
+    readonly database: ReturnType<typeof parsePrimaryDatabaseConfig>
+    /** Supabase Auth, Storage and token-verification configuration. */
+    readonly supabase: ReturnType<typeof parseSupabaseConfig>
+}
+
+/** Reads the API environment; missing or invalid values fail boot, and secrets use `_FILE` first. */
+export const readApiEnv = (env: EnvSource): ApiEnv => ({
+    server: parseServerConfig(env),
+    httpSecurity: parseHttpSecurityConfig(env),
+    database: parsePrimaryDatabaseConfig(env),
+    supabase: parseSupabaseConfig(env),
+})

package/templates/be/skeleton-lite/apps/api/src/api.options.ts

@@ -3,7 +3,7 @@ import type { ServerOptions } from "@modules/platform/config"
 import type { DatabaseConnectionOptions } from "@modules/platform/database"
 import type { HttpSecurityOptions } from "@modules/platform/http-security"
 
-/** Everything the API needs from its environment, parsed once by `main.ts` and handed to `AppModule.register`. */
+/** Everything the API needs from its environment, parsed by `api.env.ts` and handed to `AppModule.register`. */
 export interface ApiOptions {
     /** The HTTP listener. */
     readonly server: ServerOptions

package/templates/be/skeleton-lite/apps/api/src/app.module.ts

@@ -2,33 +2,21 @@ import { Module } from "@nestjs/common"
 import type { DynamicModule } from "@nestjs/common"
 import { APP_FILTER, APP_GUARD } from "@nestjs/core"
 import { SystemHealthHttpModule } from "@features/api/system-health"
-import { AuthGuard, IDENTITY_ERROR_KINDS, IDENTITY_MESSAGES, IdentityModule } from "@modules/domain/identity"
+import { AuthGuard, IdentityModule } from "@modules/domain/identity"
 import {
     SUPABASE_ACCESS_TOKEN_VERIFIER,
     SUPABASE_ADMIN_CLIENT,
-    SUPABASE_ERROR_KINDS,
     createSupabaseAccessTokenVerifier,
     createSupabaseAdminClient,
 } from "@modules/integrations/supabase"
 import { LivenessModule } from "@modules/domain/liveness"
-import { ClockModule } from "@modules/platform/clock"
-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, ErrorsFilter, ErrorsModule } from "@modules/platform/errors"
-import {
-    HTTP_SECURITY_ERROR_KINDS,
-    HTTP_SECURITY_MESSAGES,
-    HttpSecurityModule,
-    OriginGuard,
-    RateLimitGuard,
-} from "@modules/platform/http-security"
-import { I18nModule } from "@modules/platform/i18n"
-import { LoggingModule } from "@modules/platform/logging"
+import { ErrorsFilter } from "@modules/platform/errors"
+import { OriginGuard, RateLimitGuard } from "@modules/platform/http-security"
+import { platformModules } from "./compose/platform"
 import type { ApiOptions } from "./api.options"
 
 @Module({})
-/** Composition root of the API: every capability is registered once and the three guards run in a fixed order. */
+/** Composition root of the API: it spreads the composition groups of `compose/`, and the three guards run in a fixed order. */
 export class AppModule {
     /** Builds the module from options parsed once at boot; nothing here reads the environment. */
     static register(options: ApiOptions): DynamicModule {
@@ -36,31 +24,7 @@ export class AppModule {
         return {
             module: AppModule,
             imports: [
-                ClockModule.register({ isGlobal: true }),
-                LoggingModule.register({ isGlobal: true }),
-                I18nModule.register({
-                    isGlobal: true,
-                    bundles: [ERRORS_MESSAGES, HTTP_SECURITY_MESSAGES, IDENTITY_MESSAGES],
-                }),
-                ErrorsModule.register({
-                    isGlobal: true,
-                    kinds: [
-                        CONFIG_ERROR_KINDS,
-                        DATABASE_ERROR_KINDS,
-                        HTTP_SECURITY_ERROR_KINDS,
-                        IDENTITY_ERROR_KINDS,
-                        SUPABASE_ERROR_KINDS,
-                    ],
-                }),
-                CqrsModule.register({ isGlobal: true }),
-                HttpSecurityModule.register({
-                    isGlobal: true,
-                    ...options.httpSecurity,
-                }),
-                DatabaseModule.register({
-                    isGlobal: true,
-                    connections: [options.database],
-                }),
+                ...platformModules(options),
                 IdentityModule.register({ isGlobal: true, verifyAccessToken }),
                 LivenessModule.register({ isGlobal: true }),
                 SystemHealthHttpModule,

package/templates/be/skeleton-lite/apps/api/src/compose/platform.ts

@@ -0,0 +1,45 @@
+import type { DynamicModule } from "@nestjs/common"
+import { IDENTITY_ERROR_KINDS, IDENTITY_MESSAGES } from "@modules/domain/identity"
+import { SUPABASE_ERROR_KINDS } from "@modules/integrations/supabase"
+import { ClockModule } from "@modules/platform/clock"
+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 { I18nModule } from "@modules/platform/i18n"
+import { LoggingModule } from "@modules/platform/logging"
+import type { ApiOptions } from "../api.options"
+
+/**
+ * The platform area of the API: every platform capability, registered once and app-wide. A composition group holds
+ * one area's module list and nothing else (no logic, no environment read); `app.module.ts` spreads it into its
+ * imports.
+ */
+export const platformModules = (options: ApiOptions): Array<DynamicModule> => [
+    ClockModule.register({ isGlobal: true }),
+    LoggingModule.register({ isGlobal: true }),
+    I18nModule.register({
+        isGlobal: true,
+        bundles: [ERRORS_MESSAGES, HTTP_SECURITY_MESSAGES, IDENTITY_MESSAGES],
+    }),
+    ErrorsModule.register({
+        isGlobal: true,
+        kinds: [
+            CONFIG_ERROR_KINDS,
+            DATABASE_ERROR_KINDS,
+            HTTP_SECURITY_ERROR_KINDS,
+            IDENTITY_ERROR_KINDS,
+            SUPABASE_ERROR_KINDS,
+        ],
+    }),
+    CqrsModule.register({ isGlobal: true }),
+    HttpSecurityModule.register({
+        isGlobal: true,
+        ...options.httpSecurity,
+    }),
+    DatabaseModule.register({
+        isGlobal: true,
+        connections: [options.database],
+    }),
+]

package/templates/be/skeleton-lite/apps/api/src/main.ts

@@ -1,22 +1,15 @@
 import { NestFactory } from "@nestjs/core"
 import { SystemClockService } from "@modules/platform/clock"
-import { EnvSource, parseServerConfig } from "@modules/platform/config"
-import { parsePrimaryDatabaseConfig } from "@modules/platform/database"
-import { parseHttpSecurityConfig, RequestValidationService } from "@modules/platform/http-security"
+import { EnvSource } from "@modules/platform/config"
+import { RequestValidationService } from "@modules/platform/http-security"
 import { createJsonLogger, LoggingLogEvent } from "@modules/platform/logging"
-import { parseSupabaseConfig } from "@modules/integrations/supabase"
+import { readApiEnv } from "./api.env"
 import { AppModule } from "./app.module"
-import type { ApiOptions } from "./api.options"
 
 /** Reads the environment once, composes the API from parsed options and serves until a shutdown signal. */
 const bootstrap = async (): Promise<void> => {
     const env = EnvSource.fromProcess()
-    const options: ApiOptions = {
-        server: parseServerConfig(env),
-        httpSecurity: parseHttpSecurityConfig(env),
-        database: parsePrimaryDatabaseConfig(env),
-        supabase: parseSupabaseConfig(env),
-    }
+    const options = readApiEnv(env)
     const app = await NestFactory.create(AppModule.register(options), { rawBody: true })
     app.enableCors({ origin: [...options.httpSecurity.allowedOrigins] })
     app.enableShutdownHooks()

package/templates/be/skeleton-lite/apps/cli/src/cli.env.ts

@@ -0,0 +1,17 @@
+import type { EnvSource, Secret } from "@modules/platform/config"
+import { parsePrimaryDatabaseConfig } from "@modules/platform/database"
+
+/** The cli's primary database configuration before command composition. */
+export interface CliEnv {
+    /** The logical connection name declared in `hfs.json`. */
+    readonly name: string
+    /** The Supabase PostgreSQL provider. */
+    readonly provider: "supabase"
+    /** The least-privilege database connection URL, read through the secret source. */
+    readonly url: Secret
+    /** The isolated PostgreSQL schema. */
+    readonly schema?: string
+}
+
+/** Reads the cli environment with no defaults; database secret readers prefer mounted files. */
+export const readCliEnv = (env: EnvSource): CliEnv => parsePrimaryDatabaseConfig(env)

package/upgrade/file-state.mjs

@@ -0,0 +1,68 @@
+// Authored-file preservation, snapshots and rollback for an additive edition upgrade.
+import fs from "node:fs";
+import path from "node:path";
+import { dockerfilePath } from "../runtime/scripts/hfs/rules/docker.mjs";
+
+/** App-owned additions are preserved; only declared regular optional front-end images receive that treatment. */
+export function authoredAdditionReasons(declaration, source) {
+  const reasons = new Map([[
+    ".starcistacks/application-stacks.yaml",
+    "The app already declares its stacks; the declaration stays as the app wrote it.",
+  ]]);
+  for (const app of declaration.sides.fe.apps) {
+    const file = dockerfilePath("fe", app.name);
+    if (source.hasImage(file)) reasons.set(file,
+      "The lite app already authors this optional front-end image; its Dockerfile stays as the app wrote it.");
+  }
+  return reasons;
+}
+
+export function remember(snapshot, target) {
+  if (snapshot.has(target)) return;
+  snapshot.set(
+    target,
+    fs.existsSync(target) && fs.statSync(target).isFile()
+      ? fs.readFileSync(target)
+      : null,
+  );
+}
+
+export function ensureParent(root, target, directories) {
+  const missing = [];
+  for (
+    let at = path.dirname(target);
+    at.startsWith(root) && at !== root && !fs.existsSync(at);
+    at = path.dirname(at)
+  )
+    missing.push(at);
+  for (const directory of missing.reverse()) {
+    fs.mkdirSync(directory);
+    directories.push(directory);
+  }
+}
+
+export function writeFile(root, file, content, snapshot, directories) {
+  const target = path.join(root, ...file.split("/"));
+  remember(snapshot, target);
+  ensureParent(root, target, directories);
+  fs.writeFileSync(target, content);
+}
+
+export function restore(snapshot, directories) {
+  for (const [target, content] of [...snapshot.entries()].reverse()) {
+    if (content === null) {
+      if (fs.existsSync(target) && fs.statSync(target).isFile())
+        fs.unlinkSync(target);
+    } else {
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.writeFileSync(target, content);
+    }
+  }
+  for (const directory of [...directories].reverse()) {
+    try {
+      fs.rmdirSync(directory);
+    } catch {
+      /* It is non-empty or already absent: preserve it. */
+    }
+  }
+}

package/upgrade/index.mjs

@@ -6,6 +6,7 @@
 // restored before the refusal is returned.
 import fs from "node:fs";
 import path from "node:path";
+import { authoredAdditionReasons, remember, ensureParent, writeFile, restore } from "./file-state.mjs";
 import { parseYaml } from "../runtime/engine/yaml.mjs";
 import {
   loadSlotManifest,
@@ -229,9 +230,9 @@ function additions(root, full, hadCli, manifest) {
   const variables = { project: full.project, app: "cli", appPascal: "Cli" };
   const files = [
     ...templateFiles("app/upgrade-full", "", variables),
-    ...(fs.existsSync(path.join(root, ".starciwork", "index.yaml"))
-      ? []
-      : scaffoldWorkSeeds(full.project).filter((file) => !fs.existsSync(path.join(root, file.path)))),
+    ...scaffoldWorkSeeds(full.project).filter((file) =>
+      !fs.existsSync(path.join(root, file.path))
+      && (file.path === ".starciwork/workspace.yaml" || !fs.existsSync(path.join(root, ".starciwork", "index.yaml")))),
     ...(!hadCli
       ? [
           ...STANDARD_CLI_FILES.map((file) => ({
@@ -270,8 +271,6 @@ function sourceWithAdditions(root, additions) {
   };
 }
 
-// Files the app authors itself: the upgrade never overwrites them and keeps an existing one (CONTEXT: declarations are preserved).
-const APP_OWNED = new Set([".starcistacks/application-stacks.yaml"]);
 const publicStep = ({ op, path: file, why }) => ({ op, path: file, why });
 
 async function model({ root, to, presets, manifest }) {
@@ -286,6 +285,7 @@ async function model({ root, to, presets, manifest }) {
   );
   const full = fullEditionDeclaration(declaration, manifest);
   const desired = additions(root, full, hadCli, manifest);
+  const authored = authoredAdditionReasons(declaration, appSource(root));
   const pins = parseYaml(fs.readFileSync(PINS_FILE, "utf8")).pins;
   const upgradedPackage = pinnedPackage(root, pins);
   const resolvedPresets = presets ?? UPGRADE_PRESETS;
@@ -357,8 +357,8 @@ async function model({ root, to, presets, manifest }) {
   for (const file of desired) {
     const target = path.join(root, ...file.path.split("/"));
     if (fs.existsSync(target)) {
-      if (APP_OWNED.has(file.path)) {
-        steps.push({ op: "keep", path: file.path, why: "The app already declares its stacks; the declaration stays as the app wrote it.", kind: "keep" });
+      if (authored.has(file.path)) {
+        steps.push({ op: "keep", path: file.path, why: authored.get(file.path), kind: "keep" });
         continue;
       }
       if (!sameText(root, file.path, file.content))
@@ -400,55 +400,6 @@ async function model({ root, to, presets, manifest }) {
   return { full, managed: managedWithoutPackage, steps, dependenciesChanged };
 }
 
-function remember(snapshot, target) {
-  if (snapshot.has(target)) return;
-  snapshot.set(
-    target,
-    fs.existsSync(target) && fs.statSync(target).isFile()
-      ? fs.readFileSync(target)
-      : null,
-  );
-}
-
-function ensureParent(root, target, directories) {
-  const missing = [];
-  for (
-    let at = path.dirname(target);
-    at.startsWith(root) && at !== root && !fs.existsSync(at);
-    at = path.dirname(at)
-  )
-    missing.push(at);
-  for (const directory of missing.reverse()) {
-    fs.mkdirSync(directory);
-    directories.push(directory);
-  }
-}
-
-function writeFile(root, file, content, snapshot, directories) {
-  const target = path.join(root, ...file.split("/"));
-  remember(snapshot, target);
-  ensureParent(root, target, directories);
-  fs.writeFileSync(target, content);
-}
-
-function restore(snapshot, directories) {
-  for (const [target, content] of [...snapshot.entries()].reverse()) {
-    if (content === null) {
-      if (fs.existsSync(target) && fs.statSync(target).isFile())
-        fs.unlinkSync(target);
-    } else {
-      fs.mkdirSync(path.dirname(target), { recursive: true });
-      fs.writeFileSync(target, content);
-    }
-  }
-  for (const directory of [...directories].reverse()) {
-    try {
-      fs.rmdirSync(directory);
-    } catch {
-      /* It is non-empty or already absent: preserve it. */
-    }
-  }
-}
 
 /**
  * Plans or applies the lite -> full migration. Returns the ordered public plan (`{op,path,why}[]`) in both modes.

package/runtime/scripts/api/git/log.mjs

@@ -1,5 +0,0 @@
-// log.mjs — `git log <args>`: the commit history in a caller-chosen format.
-import { runGit } from './lib.mjs';
-
-/** The spawn result {status, stdout, stderr, error} of `git log ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
-export const log = (args = [], options = {}) => runGit(['log', ...args], options);

package/templates/app/skeleton-lite/.starciwork/shell/index.yaml

@@ -1,55 +0,0 @@
-schema: work/layout-tree@1
-id: shell
-kind: shell
-state: todo
-rev: 1
-origin: planned
-productLocale:
-  default: vi
-  fallback: vi
-  locales:
-    - vi
-breakpoints:
-  - name: desktop
-    width: 1440
-    height: 900
-  - name: mobile
-    width: 390
-    height: 844
-themes:
-  - light
-apps:
-  - name: web
-    root: fe/apps/web
-    appDir: fe/apps/web/src/app
-    framework: next-app-router
-    localeParam: locale
-    nodes:
-      - id: /
-        parent: null
-        segment: /
-        segmentKind: root
-        url: /
-        origin: planned
-      - id: /[locale]
-        parent: /
-        segment: "[locale]"
-        segmentKind: dynamic
-        url: /[locale]
-        origin: planned
-        files:
-          layout:
-            path: fe/apps/web/src/app/[locale]/layout.tsx
-          page:
-            path: fe/apps/web/src/app/[locale]/page.tsx
-          loading:
-            path: fe/apps/web/src/app/[locale]/loading.tsx
-          error:
-            path: fe/apps/web/src/app/[locale]/error.tsx
-          not-found:
-            path: fe/apps/web/src/app/[locale]/not-found.tsx
-        layout:
-          component: AppLayout
-          chrome: visible
-          state: todo
-          rev: 1