@starci/hfs 4.2.17 → 4.4.0

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,
@@ -24,6 +25,7 @@ import {
   renderTargets,
   writeTargets,
 } from "../sync/index.mjs";
+import { readDeclaredStack } from "../sync/stack-images.mjs";
 
 const PACKAGE_ROOT = path.join(import.meta.dirname, "..");
 const PINS_FILE = path.join(
@@ -78,6 +80,11 @@ const sameText = (root, file, content) =>
 const readmeCommand = (name) =>
   name === "test" ? "npm test" : `npm run ${name}`;
 
+function listsCommand(section, command) {
+  const escaped = command.replace(/[.*+?^${}()|[\]\\]/gu, String.raw`\$&`);
+  return new RegExp(String.raw`^\s*${escaped}\s*$`, "mu").test(section);
+}
+
 /** Add only the top-level commands that the full managed scripts introduce, preserving every existing README byte around them. */
 function upgradedReadme(root) {
   const file = path.join(root, "README.md");
@@ -98,13 +105,7 @@ function upgradedReadme(root) {
   const section = lines.slice(start + 1, stop).join("\n");
   const commands = addedNames
     .map(readmeCommand)
-    .filter(
-      (command) =>
-        !new RegExp(
-          `^\\s*${command.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&")}\\s*$`,
-          "mu",
-        ).test(section),
-    );
+    .filter((command) => !listsCommand(section, command));
   if (commands.length === 0) return null;
   let insert = -1;
   for (let index = start + 1; index < stop; index += 1)
@@ -167,7 +168,7 @@ export function fullEditionDeclaration(
 function pinnedPackage(root, pins) {
   const current = readJson(root, "package.json");
   const section = (name, dependencies) => {
-    const next = { ...(current[name] ?? {}) };
+    const next = { ...current[name] };
     for (const dependency of dependencies) {
       const pin = pins[dependency]?.version;
       if (!pin)
@@ -225,13 +226,21 @@ function templateFiles(group, prefix, variables) {
   }));
 }
 
+/** Keep an existing topology and its runbooks together; the fallback stack is only for apps without a declaration. */
+function stackAdditions(root, variables) {
+  const declaration = ".starcistacks/application-stacks.yaml";
+  const hasStacks = fs.existsSync(path.join(root, declaration));
+  return templateFiles("app/upgrade-full", "", variables).filter((file) =>
+    !hasStacks || file.path === declaration || !file.path.startsWith(".starcistacks/"));
+}
+
 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)))),
+    ...stackAdditions(root, variables),
+    ...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) => ({
@@ -267,13 +276,35 @@ function sourceWithAdditions(root, additions) {
   return {
     files: [...new Set([...current.files, ...added.keys()])].sort(byCodeUnit),
     read: (file) => added.get(file) ?? current.read(file),
+    // The declared images and pass-through variables render the managed stack-deploy.yml exactly as `app sync` will.
+    stack: readDeclaredStack(root, { parseYaml }),
   };
 }
 
-// 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 });
 
+function additionReason(file) {
+  if (file.startsWith(".starcistacks/")) return "Add the pinned Supabase/Postgres and api full-stack skeleton.";
+  if (file.startsWith(".starciwork/")) return "Add the canonical product catalog and existing liveness feature overview.";
+  if (file.includes("/tests/")) return "Open the full test layer without inventing a spec.";
+  return "Add the full-only cli or image scaffold.";
+}
+
+function additionStep(root, file, authored) {
+  const target = path.join(root, ...file.path.split("/"));
+  if (!fs.existsSync(target)) return {
+    op: "add", path: file.path, why: additionReason(file.path), content: file.content, kind: "file",
+  };
+  if (authored.has(file.path)) return {
+    op: "keep", path: file.path, why: authored.get(file.path), kind: "keep",
+  };
+  if (!sameText(root, file.path, file.content)) throw new UpgradeError(
+    "HFS_UPGRADE_FILE_CONFLICT",
+    `${file.path} already exists and is not the upgrade scaffold; no file was overwritten`,
+  );
+  return null;
+}
+
 async function model({ root, to, presets, manifest }) {
   if (to !== "full")
     throw new UpgradeError(
@@ -286,6 +317,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;
@@ -355,32 +387,8 @@ async function model({ root, to, presets, manifest }) {
       kind: "file",
     });
   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" });
-        continue;
-      }
-      if (!sameText(root, file.path, file.content))
-        throw new UpgradeError(
-          "HFS_UPGRADE_FILE_CONFLICT",
-          `${file.path} already exists and is not the upgrade scaffold; no file was overwritten`,
-        );
-      continue;
-    }
-    steps.push({
-      op: "add",
-      path: file.path,
-      why: file.path.startsWith(".starcistacks/")
-        ? "Add the pinned Supabase/Postgres and api full-stack skeleton."
-        : file.path.startsWith(".starciwork/")
-          ? "Add the canonical product catalog and existing liveness feature overview."
-          : file.path.includes("/tests/")
-          ? "Open the full test layer without inventing a spec."
-          : "Add the full-only cli or image scaffold.",
-      content: file.content,
-      kind: "file",
-    });
+    const step = additionStep(root, file, authored);
+    if (step) steps.push(step);
   }
   if (!sameText(root, "be/nest-cli.json", nestCliText(full)))
     steps.push({
@@ -400,55 +408,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.
@@ -499,11 +458,7 @@ export async function upgradeEdition({
   return result;
 }
 
-/** CLI adapter kept outside the CLI entry so that verb wiring remains one line. */
-export async function upgradeMain(
-  argv,
-  { stdout = (value) => process.stdout.write(value), presets } = {},
-) {
+function upgradeArguments(argv) {
   let to;
   let plan = false;
   let root = process.cwd();
@@ -523,6 +478,15 @@ export async function upgradeMain(
       "HFS_UPGRADE_USAGE",
       "starci app upgrade needs --edition full",
     );
+  return { root, to, plan };
+}
+
+/** CLI adapter kept outside the CLI entry so that verb wiring remains one line. */
+export async function upgradeMain(
+  argv,
+  { stdout = (value) => process.stdout.write(value), presets } = {},
+) {
+  const { root, to, plan } = upgradeArguments(argv);
   const steps = await upgradeEdition({ root, to, plan, presets });
   for (const step of steps) stdout(`${step.op} ${step.path}: ${step.why}\n`);
   stdout(

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