@starci/hfs 2.0.2 → 4.0.0

package/runtime/scripts/lib/safe-remove.mjs

@@ -13,11 +13,12 @@
 // its own path under its parent's real path (any name-surrogate reparse point). A link that cannot be
 // unlinked stops the removal of everything above it; nothing is ever deleted through it.
 //
-// safeRemoveWorktree removes a git worktree's directory with safeRemoveTree and then prunes the registration,
-// so `git worktree remove --force` never walks the tree.
+// safeRemoveWorktree removes a git worktree: every link removed as a link first (found without following one), zero
+// links asserted, only then `git worktree remove --force`, and the main checkout asserted untouched afterwards.
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { sleepSync } from './sleep-sync.mjs';
 import { samePath } from './path-key.mjs';
@@ -46,6 +47,22 @@ export function isLinkLike(p, { parentReal = null, stat = null } = {}) {
 }
 
 /** Remove a link itself, never its target. True when nothing is left at `p`. */
+/** Every link (symlink, junction, other reparse point) under root, found with lstat; the walk never enters one. */
+export function linksUnder(root) {
+  const found = [];
+  const visit = (p, parentReal) => {
+    let stat;
+    try { stat = fs.lstatSync(p); } catch { return; }
+    if (isLinkLike(p, { parentReal, stat })) { found.push(p); return; }
+    if (!stat.isDirectory()) return;
+    let real, names;
+    try { real = fs.realpathSync.native(p); names = fs.readdirSync(p); } catch { return; }
+    for (const name of names) visit(path.join(p, name), real);
+  };
+  visit(path.resolve(root), null);
+  return found;
+}
+
 export function unlinkOnly(p) {
   try { fs.lstatSync(p); } catch (error) { return error?.code === 'ENOENT'; }
   try { fs.unlinkSync(p); } catch { try { fs.rmdirSync(p); } catch { /* verified below */ } }
@@ -164,16 +181,84 @@ export function safeRemoveTree(root, { retries = 5, checkoutsUnder = null } = {}
   return out;
 }
 
+/** Remove one link as a link, never its target: `cmd /c rmdir <link>` on Windows (no /s), then unlinkOnly. */
+export function removeLink(p) {
+  if (WIN) {
+    let st = null;
+    try { st = fs.lstatSync(p); } catch { return true; }
+    if (st.isDirectory() || st.isSymbolicLink()) spawnSync('cmd', ['/d', '/c', 'rmdir', p], { windowsHide: true, encoding: 'utf8' });
+  }
+  return unlinkOnly(p);
+}
+
+/** The main checkout's state a removal must never change: its tracked deletions and its node_modules entry counts. */
+export function mainCheckoutGuard(mainRoot, { git = null } = {}) {
+  const run = git ?? ((args, opts) => gitSpawn('git', args, { cwd: opts.cwd, maxBuffer: 64 * 1024 * 1024 }));
+  const count = (rel) => { try { return fs.readdirSync(path.join(mainRoot, rel)).length; } catch { return null; } };
+  // porcelain v2 ("1 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <path>"): no leading blank a runner's trim could eat.
+  const st = run(['status', '--porcelain=v2', '--untracked-files=no'], { cwd: mainRoot });
+  const text = String(st?.stdout ?? st?.out ?? '');
+  const ok = st?.ok ?? (!st?.error && st?.status === 0);
+  const deleted = text.split(/\r?\n/).map((l) => l.trim().split(' ')).filter((f) => f[0] === '1' && f.length >= 9 && f[1].includes('D')).map((f) => f.slice(8).join(' '));
+  return { ok: Boolean(ok), deleted: new Set(deleted),
+    nodeModules: count('node_modules'), packagesNodeModules: count(path.join('packages', 'node_modules')) };
+}
+/** What changed in the main checkout between two guards: [] when nothing. */
+export function mainCheckoutDamage(before, after) {
+  const out = [];
+  if (before.ok && after.ok) for (const f of after.deleted) if (!before.deleted.has(f)) out.push(`tracked file deleted: ${f}`);
+  if (before.nodeModules !== after.nodeModules) out.push(`node_modules entries ${before.nodeModules} -> ${after.nodeModules}`);
+  if (before.packagesNodeModules !== after.packagesNodeModules) out.push(`packages/node_modules entries ${before.packagesNodeModules} -> ${after.packagesNodeModules}`);
+  return out;
+}
+
 /**
- * Remove a git worktree without letting git walk it: its directory goes through safeRemoveTree, then
- * `git worktree prune` (run in `repo`) drops the registration. `git(args, {cwd})` is the caller's git runner;
- * omitted, git is spawned directly.
+ * Remove a git worktree (the one algorithm; the 490-file .claude incident and nivo-fe inc-c8fbf76aa499):
+ *   1. enumerate every link in it WITHOUT following one (linksUnder);
+ *   2. remove each as a link (removeLink: `cmd /c rmdir <link>`, never /s), outermost first;
+ *   3. re-scan the same way and refuse (link-stuck, nothing deleted) unless ZERO links remain;
+ *   4. only then `git worktree remove --force` (a link-free tree: git cannot walk out of it); a directory git does not know
+ *      goes through safeRemoveTree (never follows a link); `git worktree prune`;
+ *   5. assert the main checkout is untouched: no new tracked deletion, node_modules and packages/node_modules entry counts
+ *      unchanged - a violation is {ok:false, fatal:true, reason:'main-checkout-damaged'}: the caller (the GC) stops.
+ * Never robocopy, rm -rf or rmdir /s. `git(args, {cwd})` is the caller's git runner; `repo` any checkout of the repository.
+ * {ok, root, links, removed, errors, damage?}
  */
 export function safeRemoveWorktree(worktree, { repo, git = null, retries = 5 } = {}) {
-  const removed = safeRemoveTree(worktree, { retries });
-  if (repo) {
-    const run = git ?? ((args, opts) => gitSpawn('git', args, { cwd: opts.cwd }));
-    try { run(['worktree', 'prune'], { cwd: repo }); } catch { /* the registration is pruned on the next prune */ }
+  const target = path.resolve(String(worktree ?? ''));
+  const run = git ?? ((args, opts) => gitSpawn('git', args, { cwd: opts.cwd, maxBuffer: 64 * 1024 * 1024 }));
+  const out = { ok: false, root: target, links: 0, removed: { files: 0, dirs: 0, links: 0 }, errors: [] };
+  const list = repo ? String((run(['worktree', 'list', '--porcelain'], { cwd: repo }) ?? {}).stdout ?? '') : '';
+  const trees = list.split(/\r?\n/).filter((l) => l.startsWith('worktree ')).map((l) => path.resolve(l.slice(9).trim()));
+  const mainRoot = trees[0] ?? null;
+  if (mainRoot && same(mainRoot, target)) { out.errors.push({ path: target, code: 'REFUSED', message: 'refusing to remove the main checkout' }); return out; }
+  const refused = forbiddenRoot(target);
+  if (refused) { out.errors.push({ path: target, code: 'REFUSED', message: `refusing to remove ${refused}` }); return out; }
+  const before = mainRoot ? mainCheckoutGuard(mainRoot, { git: run }) : null;
+  if (fs.existsSync(target)) {
+    for (const link of linksUnder(target)) { if (removeLink(link)) out.links += 1; else out.errors.push({ path: link, code: 'LINK_STUCK', message: 'a link could not be removed' }); }
+    const left = linksUnder(target);
+    if (left.length) {
+      for (const l of left) if (!out.errors.some((e) => e.path === l)) out.errors.push({ path: l, code: 'LINK_STUCK', message: 'a link is still there after removal' });
+      out.reason = 'link-stuck';
+      return out;
+    }
+    out.removed.links = out.links;
+    const registered = trees.some((t) => same(t, target));
+    if (registered && repo) run(['worktree', 'remove', '--force', target], { cwd: repo });
+    if (fs.existsSync(target)) {
+      if (linksUnder(target).length) { out.errors.push({ path: target, code: 'LINK_STUCK', message: 'a link appeared during removal' }); out.reason = 'link-stuck'; return out; }
+      const rm = safeRemoveTree(target, { retries });
+      out.removed.files += rm.removed.files; out.removed.dirs += rm.removed.dirs;
+      out.errors.push(...rm.errors);
+    }
   }
-  return removed;
+  if (repo) { try { run(['worktree', 'prune'], { cwd: repo }); } catch { /* the registration is pruned on the next prune */ } }
+  if (before) {
+    const damage = mainCheckoutDamage(before, mainCheckoutGuard(mainRoot, { git: run }));
+    if (damage.length) { out.damage = damage; out.fatal = true; out.reason = 'main-checkout-damaged'; out.errors.push({ path: mainRoot, code: 'main-checkout-damaged', message: damage.join('; ') }); return out; }
+  }
+  out.ok = !fs.existsSync(target) && (() => { try { fs.lstatSync(target); return false; } catch { return true; } })();
+  if (!out.ok && !out.reason) out.reason = 'remove-failed';
+  return out;
 }

package/scaffold/app.mjs

@@ -0,0 +1,179 @@
+// hfs scaffold app <name> - the first tree of a new app, the one shape every StarCi product has:
+//
+//   <name>/            hfs.json (kind app), package.json (every dependency of both sides at its canon pin, the managed scripts),
+//                      package-lock.json, README.md, the managed root files (CI, husky, .gitignore block, Sonar, prettier) and
+//                      .starciwork; scripts/codegen.mjs, the app's own step of `npm run codegen`
+//   <name>/be/         the back-end side: the managed tool configuration and the templates/be/skeleton tree (the api app's
+//                      entrypoint, platform config/logging/errors/clock/cqrs, the liveness capability and the health feature)
+//   <name>/fe/         the front-end side: the managed tool configuration and the templates/fe/skeleton tree (the next-intl
+//                      [locale] shell with vi default, as-needed prefix and proxy.ts; each route slot mounts one pages feature
+//                      drawn with @starci/grammar)
+//
+// The skeleton files are written once from templates/<app|be|fe>/skeleton ({{project}}, {{app}} and {{appPascal}} filled, a
+// `__app__` folder named after the side's app); the managed files are the render of `hfs sync` (sync/index.mjs), so a fresh app
+// is in sync by construction. Nothing is installed: `npm install` completes the lockfile, which is written as the root entry only.
+// An existing directory is refused, never merged into.
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadSlotManifest, resolveRepoDeclaration } from '../runtime/scripts/lib/hfs-slots.mjs';
+import { parseYaml } from '../runtime/engine/yaml.mjs';
+import { TEMPLATES_DIR, renderTargets, writeTargets } from '../sync/index.mjs';
+import { ScaffoldError } from './service.mjs';
+
+const NAME = /^[a-z][a-z0-9-]*$/;
+const APP_DIR = '__app__';
+const PINS_FILE = path.join(import.meta.dirname, '..', 'runtime', 'knowledge', 'hfs', 'canon-pins.yaml');
+const SONAR_GATE_FILE = path.join(import.meta.dirname, '..', 'runtime', 'knowledge', 'sonar-gate.yaml');
+const pascal = name => name.split('-').map(part => part[0].toUpperCase() + part.slice(1)).join('');
+
+/**
+ * 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.
+ */
+function jsonText(value) {
+  const print = (item, indent) => {
+    const inner = `${indent}  `;
+    if (Array.isArray(item)) {
+      if (item.every(entry => entry === null || typeof entry !== 'object')) return `[${item.map(entry => JSON.stringify(entry)).join(', ')}]`;
+      return `[\n${item.map(entry => `${inner}${print(entry, inner)}`).join(',\n')}\n${indent}]`;
+    }
+    if (item !== null && typeof item === 'object') {
+      const keys = Object.keys(item);
+      if (!keys.length) return '{}';
+      return `{\n${keys.map(key => `${inner}${JSON.stringify(key)}: ${print(item[key], inner)}`).join(',\n')}\n${indent}}`;
+    }
+    return JSON.stringify(item);
+  };
+  return `${print(value, '')}\n`;
+}
+
+/** The apps a new app starts with: one api app on the be side, one Next app on the fe side, which reads the be contracts for its codegen. */
+export const STARTER_SIDES = Object.freeze({
+  be: Object.freeze({ apps: [{ name: 'api', kind: 'api' }] }),
+  fe: Object.freeze({ apps: [{ name: 'web', kind: 'next' }], reads: ['be/contracts/'] }),
+});
+
+/**
+ * The dependencies of the starter: what the skeleton imports and the tools the managed scripts and configs run. A name with a
+ * canon pin (knowledge/hfs/canon-pins.yaml) takes the pin; the others take the range the reference apps (examples/todo-app)
+ * declare.
+ */
+const STARTER_DEPENDENCIES = Object.freeze({
+  dependencies: {
+    '@heroui/react': null, '@heroui/styles': null, '@nestjs/common': null, '@nestjs/core': null, '@nestjs/cqrs': '^11.0.3',
+    '@nestjs/platform-express': null, '@starci/grammar': null, next: null, 'next-intl': null, react: null, 'react-dom': null,
+    'reflect-metadata': '^0.2.2', rxjs: '^7.8.1', 'server-only': '^0.0.1', tslib: '^2.8.1',
+  },
+  devDependencies: {
+    '@nestjs/testing': null, '@starci/eslint-canon-be': null, '@starci/eslint-canon-fe': null, '@starci/hfs': null, '@starci/jest-preset': null,
+    '@starci/prettier-config': null, '@starci/stylelint-canon': null, '@starci/test-world': null, '@starci/tsconfig': null, '@tailwindcss/postcss': '^4', '@types/express': '^4.17.21',
+    '@types/jest': null, '@types/node': null, '@types/react': '^19.0.0', '@types/react-dom': '^19.0.0', eslint: null, 'eslint-plugin-react-hooks': null,
+    husky: '^9.1.7', jest: null, 'postcss-value-parser': null, prettier: null, stylelint: null, tailwindcss: '^4', 'ts-jest': null,
+    'ts-node-dev': '^2.0.0', 'tsc-alias': '^1.8.10', 'tsconfig-paths': '^4.2.0', typescript: null,
+  },
+});
+
+/** The app hfs.json of a new app called `name`. */
+export const starterDeclaration = (name, manifest = loadSlotManifest()) => ({ hfs: manifest.major, kind: 'app', project: name, sides: structuredClone(STARTER_SIDES) });
+
+/** The root package.json of a new app: name, the dependencies at their pins; the managed scripts are sync's. */
+function packageManifest(name, pins) {
+  const pinned = (dependency, range) => {
+    if (range !== null) return range;
+    if (!pins[dependency]) throw new ScaffoldError('HFS_SCAFFOLD_PIN_MISSING', `${dependency} has no canon pin in knowledge/hfs/canon-pins.yaml`);
+    return pins[dependency].version;
+  };
+  const section = entries => Object.fromEntries(Object.entries(entries).sort(([a], [b]) => a.localeCompare(b)).map(([dependency, range]) => [dependency, pinned(dependency, range)]));
+  return { name, version: '0.0.0', private: true, dependencies: section(STARTER_DEPENDENCIES.dependencies), devDependencies: section(STARTER_DEPENDENCIES.devDependencies) };
+}
+
+function listFiles(dir, base = dir) {
+  return fs.readdirSync(dir, { withFileTypes: true }).flatMap(entry => {
+    const full = path.join(dir, entry.name);
+    return entry.isDirectory() ? listFiles(full, base) : [path.relative(base, full).split(path.sep).join('/')];
+  });
+}
+
+/** The be side's nest-cli.json: one Nest project per be app, the first api app the default. */
+function nestCli(app) {
+  const projects = Object.fromEntries(app.sides.be.apps.map(entry => [entry.name, { type: 'application', root: `apps/${entry.name}`, entryFile: 'main', sourceRoot: `apps/${entry.name}/src` }]));
+  const first = app.sides.be.apps.find(entry => entry.kind === 'api');
+  return { $schema: 'https://json.schemastore.org/nest-cli', collection: '@nestjs/schematics', monorepo: true, root: `apps/${first.name}`, sourceRoot: `apps/${first.name}/src`, projects };
+}
+
+/**
+ * The tsconfig.json of one Next app of the fe side: the side's managed tsconfig plus the app's `@/*` alias and the Next plugin. It is
+ * written from code, not kept as a template file: a tsconfig.json inside templates/ would make every TypeScript tool of this
+ * repository treat the skeleton as a project of its own.
+ */
+function nextAppTsconfig() {
+  return {
+    extends: '../../tsconfig.json',
+    compilerOptions: { plugins: [{ name: 'next' }], incremental: true, paths: { '@/*': ['./src/*'] } },
+    include: ['next-env.d.ts', 'src/**/*.ts', 'src/**/*.tsx', '.next/types/**/*.ts'],
+    exclude: ['node_modules'],
+  };
+}
+
+/** The names a skeleton file may fill: {{project}}, {{app}}, {{appPascal}} (the side's app) and {{sonarGate}}. */
+const SKELETON_VARIABLES = Object.freeze(['project', 'app', 'appPascal', 'sonarGate']);
+
+/**
+ * A skeleton file with its variables filled. Only the skeleton names are variables: every other `{{name}}` is source the app keeps
+ * (a message placeholder of the i18n canon, `{{title}}` in a catalog), and a skeleton name with no value for this file is an error.
+ */
+function fill(source, vars, file) {
+  return source.replace(new RegExp(`\\{\\{(${SKELETON_VARIABLES.join('|')})\\}\\}`, 'g'), (_, key) => {
+    if (!Object.hasOwn(vars, key)) throw new ScaffoldError('HFS_SCAFFOLD_TEMPLATE_VARIABLE', `${file} names {{${key}}}, which has no value outside a __app__ folder`);
+    return vars[key];
+  });
+}
+
+/** The skeleton files of one scope (app root, be, fe): [{ path, content }], app-relative; a `__app__` file once per app of the side. */
+function skeletonOf(scope, app, vars) {
+  const dir = path.join(TEMPLATES_DIR, scope, 'skeleton');
+  if (!fs.existsSync(dir)) throw new ScaffoldError('HFS_SCAFFOLD_SKELETON_MISSING', `no skeleton templates in templates/${scope}/skeleton`);
+  const apps = scope === 'app' ? [] : app.sides[scope].apps.filter(entry => scope === 'fe' || entry.kind === 'api');
+  const prefix = scope === 'app' ? '' : `${scope}/`;
+  const files = [];
+  for (const rel of listFiles(dir)) {
+    const source = fs.readFileSync(path.join(dir, rel), 'utf8').replace(/\r\n/g, '\n');
+    const once = { project: app.project, ...vars };
+    if (!rel.includes(APP_DIR)) {
+      files.push({ path: `${prefix}${rel}`, content: fill(source, once, rel) });
+      continue;
+    }
+    for (const entry of apps) files.push({ path: `${prefix}${rel.split(APP_DIR).join(entry.name)}`, content: fill(source, { ...once, app: entry.name, appPascal: pascal(entry.name) }, rel) });
+  }
+  return files;
+}
+
+/**
+ * `hfs scaffold app <name>`: writes the new app under `into` and returns `{ root, files }` (app-relative paths, sorted). `presets`
+ * is what sync loads from the installed @starci/jest-preset (the Sonar exclusions); the CLI passes the one it resolves.
+ */
+export function scaffoldApp({ name, into, presets, manifest = loadSlotManifest() }) {
+  if (!NAME.test(String(name))) throw new ScaffoldError('HFS_SCAFFOLD_NAME_INVALID', `the app name ${name} must be kebab-case (a project name: ${NAME})`);
+  const root = path.join(into, name);
+  if (fs.existsSync(root)) throw new ScaffoldError('HFS_SCAFFOLD_EXISTS', `${root} already exists; hfs scaffold app never writes into an existing directory`);
+  const declaration = starterDeclaration(name, manifest);
+  const app = resolveRepoDeclaration(manifest, declaration);
+  const pins = parseYaml(fs.readFileSync(PINS_FILE, 'utf8')).pins;
+  const pkg = packageManifest(name, pins);
+  const files = [
+    { path: 'hfs.json', content: jsonText(declaration) },
+    { path: 'package.json', content: jsonText(pkg) },
+    { path: 'package-lock.json', content: jsonText({ name, version: pkg.version, lockfileVersion: 3, requires: true, packages: { '': { name, version: pkg.version, dependencies: pkg.dependencies, devDependencies: pkg.devDependencies } } }) },
+    { path: 'be/nest-cli.json', content: jsonText(nestCli(app)) },
+    ...app.sides.fe.apps.map(entry => ({ path: `fe/apps/${entry.name}/tsconfig.json`, content: jsonText(nextAppTsconfig()) })),
+    ...['app', 'be', 'fe'].flatMap(scope => skeletonOf(scope, app, { sonarGate: parseYaml(fs.readFileSync(SONAR_GATE_FILE, 'utf8')).gate.name })),
+  ];
+  for (const file of files) {
+    const target = path.join(root, ...file.path.split('/'));
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, file.content);
+  }
+  const targets = renderTargets(declaration, presets, { manifest });
+  writeTargets(root, targets);
+  return { root, files: [...new Set([...files.map(file => file.path), ...targets.map(target => target.path)])].sort() };
+}

package/scaffold/service.mjs

@@ -15,7 +15,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { createRequire } from 'node:module';
 import { explainPath } from '../runtime/scripts/lib/hfs-check.mjs';
-import { loadSlotManifest } from '../runtime/scripts/lib/hfs-slots.mjs';
+import { loadSlotManifest, readRepoDeclaration } from '../runtime/scripts/lib/hfs-slots.mjs';
 
 export class ScaffoldError extends Error {
   constructor(code, message) {
@@ -284,11 +284,21 @@ const loadTypeScript = repoRoot => {
   }
 };
 
-const profileOf = repoRoot => {
-  let declaration;
-  try { declaration = JSON.parse(fs.readFileSync(path.join(repoRoot, 'hfs.json'), 'utf8')); } catch { throw new ScaffoldError('HFS_NEW_NO_HFS', `${repoRoot} has no readable hfs.json`); }
-  if (declaration.profile !== 'be') throw new ScaffoldError('HFS_NEW_BACKEND_ONLY', 'hfs new service | spec writes back-end services; this repository is a front end');
-  return declaration;
+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 => {
+  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);
+};
+
+/** 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/`);
+  return relative.slice(BE.length + 1);
 };
 
 /** The slot check of a target: the manifest must own the path, else nothing is written. */
@@ -305,29 +315,29 @@ const writeNew = (repoRoot, relative, text) => {
   return relative;
 };
 
-/** `hfs new spec <file>.service.ts`: writes the spec skeleton of an existing service; returns the created paths. */
-export function newSpec({ repoRoot, file, ts = loadTypeScript(repoRoot), manifest = loadSlotManifest() }) {
-  profileOf(repoRoot);
-  const relative = file.split(path.sep).join('/').replace(/^\.\//, '');
+/** `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);
+  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') });
-  return [writeNew(repoRoot, specPath, specSkeleton({ shape, serviceFile: relative, manifest }))];
+  return [writeNew(repoRoot, specPath, specSkeleton({ shape, serviceFile: relative, manifest }))].map(created => `${BE}/${created}`);
 }
 
-/** `hfs new service <dir> <name> [--inject ...]`: writes the service and its spec skeleton; returns the created paths. */
-export function newService({ repoRoot, dir, name, inject = [], ts = loadTypeScript(repoRoot), manifest = loadSlotManifest() }) {
-  profileOf(repoRoot);
+/** `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);
   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(dir.split(path.sep).join('/').replace(/^\.\//, '').replace(/\/$/, ''), `${name}.service.ts`);
+  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`);
   const text = serviceSource({ name, dependencies: inject.map(parseInject) });
   const shape = readServiceShape({ ts, 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)];
+  return [writeNew(repoRoot, relative, text), writeNew(repoRoot, relative.replace(/\.ts$/, '.spec.ts'), spec)].map(created => `${BE}/${created}`);
 }

package/sync/cli.mjs

@@ -8,7 +8,7 @@ export async function main(argv) {
   const [command, ...rest] = argv;
   if (command === 'sync') return runSync(rest);
   if (command === 'work-hygiene') return runWorkHygiene();
-  process.stdout.write('usage: hfs sync (--check | --write | --init) [--root <dir>] | hfs work-hygiene\n');
+  process.stdout.write('usage: hfs sync (--check | --write) [--root <dir>] | hfs work-hygiene\n');
   return 2;
 }
 

package/sync/hygiene.mjs

@@ -1,6 +1,6 @@
-// hfs work-hygiene: the guard for the two trees a back end tracks besides source. A file under .starciwork must be
-// product content (the .starciwork/.gitignore allowlist admits it, so agent output is refused), and a file under
-// .starcistacks must not be a plaintext secret (only *.enc is sealed). It is also the secrets guard of the commit: every staged file, in
+// hfs work-hygiene: the guard for the two trees an app tracks besides source. A file under the app root's .starciwork must be
+// product content (the .starciwork/.gitignore allowlist admits it, so agent output is refused), and a file under the be side's
+// be/.starcistacks must not be a plaintext secret (only *.enc is sealed). It is also the secrets guard of the commit: every staged file, in
 // any tree, is read from the index and judged with the one secret judgement of `hfs check` (scripts/lib/hfs-rules/secrets.mjs: a secret by
 // being, an .enc that is no sops envelope, a line that matches a secret pattern), so no plaintext secret reaches the history whatever
 // .gitignore says (`git add -f`, a path tracked before a rule tightened). There is no override. The pre-commit hook judges the staged
@@ -18,7 +18,10 @@ import { pathToFileURL } from 'node:url';
 import { secretFileFindings } from '../runtime/scripts/lib/hfs-rules/secrets.mjs';
 
 const PLAINTEXT_NAME = /(^|\/)(\.env(\..*)?|[^/]*\.(pem|key|identity|age))$/;
-const GUARDED = file => file.startsWith('.starciwork/') || file.startsWith('.starcistacks/');
+/** The app root's work tree and the be side's stack tree, app-relative (hfs work-hygiene runs at the app root). */
+const WORK = '.starciwork/';
+const STACKS = 'be/.starcistacks/';
+const GUARDED = file => file.startsWith(WORK) || file.startsWith(STACKS);
 
 /** The subset of `files` git ignores (as if untracked), asked in one call: a Set of paths. */
 export function ignoredAmong(cwd, files) {
@@ -36,12 +39,12 @@ export function ignoredAmong(cwd, files) {
 export function hygieneFindings(files, ignored) {
   const findings = [];
   for (const file of files) {
-    if (file.startsWith('.starciwork/') && ignored.has(file)) {
+    if (file.startsWith(WORK) && ignored.has(file)) {
       findings.push({ file, code: 'HFS_WORK_AGENT_DATA', message: 'is agent output, which .starciwork/.gitignore refuses; keep it in the scratchpad or the blob store' });
     }
-    if (file.startsWith('.starcistacks/') && !file.endsWith('.enc') && !file.endsWith('.env.example')) {
+    if (file.startsWith(STACKS) && !file.endsWith('.enc') && !file.endsWith('.env.example')) {
       if (file.includes('/secrets/')) findings.push({ file, code: 'HFS_PLAINTEXT_SECRET', message: 'sits under secrets/ but is not sealed; only <slug>.enc may be tracked' });
-      else if (PLAINTEXT_NAME.test(file)) findings.push({ file, code: 'HFS_PLAINTEXT_SECRET', message: 'is a plaintext secret; seal it to .starcistacks/<env>/secrets/<slug>.enc' });
+      else if (PLAINTEXT_NAME.test(file)) findings.push({ file, code: 'HFS_PLAINTEXT_SECRET', message: 'is a plaintext secret; seal it to be/.starcistacks/<env>/secrets/<slug>.enc' });
     }
   }
   return findings;
@@ -75,7 +78,7 @@ export function secretGuardFindings(cwd, files, alreadyRefused = new Set()) {
 /** Findings for `files`: the guarded trees, then the secret guard over every file. */
 export function judge(cwd, files) {
   const guarded = files.filter(GUARDED);
-  const findings = hygieneFindings(guarded, ignoredAmong(cwd, guarded.filter(file => file.startsWith('.starciwork/'))));
+  const findings = hygieneFindings(guarded, ignoredAmong(cwd, guarded.filter(file => file.startsWith(WORK))));
   const refused = new Set(findings.filter(finding => finding.code === 'HFS_PLAINTEXT_SECRET').map(finding => finding.file));
   return { checked: files.length, findings: [...findings, ...secretGuardFindings(cwd, files, refused)] };
 }