@starci/hfs 4.0.10 → 4.2.0

package/runtime/scripts/hfs/rules/secrets.mjs

@@ -29,8 +29,8 @@ export function secretFileFindings({ file, text }) {
   const findings = [];
   const lines = text.split(/\r?\n/);
   const seen = new Set();
-  for (let index = 0; index < lines.length; index += 1) {
-    for (const pattern of secretHits(file, lines[index])) {
+  for (const [index, line] of lines.entries()) {
+    for (const pattern of secretHits(file, line)) {
       if (seen.has(pattern)) continue;
       seen.add(pattern);
       findings.push(found(PLAINTEXT_SECRET, file, `${file}:${index + 1} holds a plaintext secret (${pattern}); seal it with sops at .starcistacks/<env>/secrets/<slug>.enc and read it by *_FILE`, { line: index + 1, pattern }));
@@ -45,7 +45,8 @@ export function secretFindings({ repoRoot, files, resolver }) {
   for (const file of files) {
     const slot = resolver.classifyPath(file);
     if (slot.status === 'forbidden' && slotOwnsSecrets(resolver.slot(slot.slot))) {
-      findings.push(found(PLAINTEXT_SECRET, file, `${file} is a plaintext secret file tracked in ${slot.slot}${slot.goesTo ? `; it belongs at ${slot.goesTo}` : ''}`, { slot: slot.slot, goesTo: slot.goesTo }));
+      const destination = slot.goesTo ? `; it belongs at ${slot.goesTo}` : '';
+      findings.push(found(PLAINTEXT_SECRET, file, `${file} is a plaintext secret file tracked in ${slot.slot}${destination}`, { slot: slot.slot, goesTo: slot.goesTo }));
       continue;
     }
     findings.push(...secretFileFindings({ file, text: readText(repoRoot, file) }));

package/runtime/scripts/hfs/rules/services.mjs

@@ -20,6 +20,7 @@ import { loadTypescript } from '../../lib/package-at.mjs';
 import { propertyText } from '../../lib/ts-ast.mjs';
 import { folded, readEventClasses, snapshotText } from '../../lib/event-contract.mjs';
 import { found, readText } from './read.mjs';
+import { byCodeUnit } from '../../lib/list.mjs';
 
 const SERVICE_PLACEMENT = 'HFS_SERVICE_PLACEMENT';
 const IMAGE_UNPINNED = 'HFS_IMAGE_UNPINNED';
@@ -68,7 +69,7 @@ function servicePlacementFindings({ files }) {
 /** The image reference with `${VAR:-default}` resolved to its default, or null when it cannot be (a bare `${VAR}`). */
 function resolvedImage(image) {
   let unresolved = false;
-  const resolved = image.replace(/\$\{[^}:]+(?::-([^}]*))?\}/g, (_all, fallback) => { if (fallback === undefined) unresolved = true; return fallback ?? ''; });
+  const resolved = image.replace(/\$\{[^}:]+(?::-([^}]*))?\}/g, (_all, fallback) => { if (fallback === undefined) { unresolved = true; } return fallback ?? ''; });
   return unresolved ? null : resolved;
 }
 
@@ -126,7 +127,7 @@ function serviceStackFindings({ repoRoot, repo }) {
 function eventClassesOf({ repoRoot, files, ts }) {
   const classes = [];
   const problems = [];
-  for (const file of files.filter((candidate) => EVENT_CLASS_FILE.test(candidate)).sort()) {
+  for (const file of files.filter((candidate) => EVENT_CLASS_FILE.test(candidate)).sort(byCodeUnit)) {
     const service = EVENT_CLASS_FILE.exec(file)[1];
     const read = readEventClasses(ts, readText(repoRoot, file) ?? '', file);
     for (const event of read.events) classes.push({ service, file, ...event });
@@ -135,6 +136,35 @@ function eventClassesOf({ repoRoot, files, ts }) {
   return { classes, problems };
 }
 
+/** Findings for each service whose vendored `events.json` is missing or differs from what its event classes emit. */
+function snapshotDriftFindings(repoRoot, tracked, services, classes) {
+  const findings = [];
+  for (const service of services) {
+    const snapshot = `be/contracts/${service}/events.json`;
+    const events = classes.filter((event) => event.service === service);
+    if (!tracked.has(snapshot)) findings.push(found(EVENT_CONTRACT, snapshot, `${service} declares event classes (be/src/modules/events/${service}/) but ${snapshot} is not committed; run \`npm run contract:emit\` and commit the snapshot, the contract its consumers rely on.`, { service }));
+    else if (folded(readText(repoRoot, snapshot) ?? '') !== snapshotText(service, events)) findings.push(found(EVENT_CONTRACT, snapshot, `${snapshot} differs from what the event classes of ${service} emit now; run \`npm run contract:emit\` and commit the result.`, { service, drift: 'stale' }));
+  }
+  return findings;
+}
+
+/** Findings for committed snapshots of a service that declares no event class. */
+function leftBehindSnapshotFindings(snapshots, services, problems) {
+  const findings = [];
+  for (const snapshot of snapshots) {
+    const service = SNAPSHOT.exec(snapshot)[1];
+    if (!services.includes(service) && !problems.some((entry) => entry.service === service)) findings.push(found(EVENT_CONTRACT, snapshot, `${snapshot} is committed but be/src/modules/events/${service}/ declares no event class; delete the snapshot or restore the classes.`, { service, drift: 'left-behind' }));
+  }
+  return findings;
+}
+
+/** Findings for compensating events that name an event no class declares. */
+function undeclaredCompensationFindings(classes, declared) {
+  return classes
+    .filter((event) => event.compensates !== undefined && !declared.has(event.compensates))
+    .map((event) => found(EVENT_CONTRACT, event.file, `${event.file}: event "${event.name}" compensates "${event.compensates}", which no event class declares; name the event whose step it undoes.`, { service: event.service, event: event.name }));
+}
+
 /** Findings of R166: each service's event classes are the one source of its vendored `events.json`, and a compensating event names a declared event. */
 function eventContractFindings({ repoRoot, files }) {
   const classFiles = files.filter((file) => EVENT_CLASS_FILE.test(file));
@@ -145,21 +175,9 @@ function eventContractFindings({ repoRoot, files }) {
   const tracked = new Set(files);
   const { classes, problems } = eventClassesOf({ repoRoot, files, ts });
   const findings = problems.map(({ service, file, problem }) => found(EVENT_CONTRACT, file, `${file} is not an event class the contract can be emitted from: ${problem}.`, { service }));
-  const services = [...new Set(classes.map((event) => event.service))].sort();
+  const services = [...new Set(classes.map((event) => event.service))].sort(byCodeUnit);
   const declared = new Set(classes.map((event) => event.name));
-  for (const service of services) {
-    const snapshot = `be/contracts/${service}/events.json`;
-    const events = classes.filter((event) => event.service === service);
-    if (!tracked.has(snapshot)) findings.push(found(EVENT_CONTRACT, snapshot, `${service} declares event classes (be/src/modules/events/${service}/) but ${snapshot} is not committed; run \`npm run contract:emit\` and commit the snapshot, the contract its consumers rely on.`, { service }));
-    else if (folded(readText(repoRoot, snapshot) ?? '') !== snapshotText(service, events)) findings.push(found(EVENT_CONTRACT, snapshot, `${snapshot} differs from what the event classes of ${service} emit now; run \`npm run contract:emit\` and commit the result.`, { service, drift: 'stale' }));
-  }
-  for (const snapshot of snapshots) {
-    const service = SNAPSHOT.exec(snapshot)[1];
-    if (!services.includes(service) && !problems.some((entry) => entry.service === service)) findings.push(found(EVENT_CONTRACT, snapshot, `${snapshot} is committed but be/src/modules/events/${service}/ declares no event class; delete the snapshot or restore the classes.`, { service, drift: 'left-behind' }));
-  }
-  for (const event of classes) {
-    if (event.compensates !== undefined && !declared.has(event.compensates)) findings.push(found(EVENT_CONTRACT, event.file, `${event.file}: event "${event.name}" compensates "${event.compensates}", which no event class declares; name the event whose step it undoes.`, { service: event.service, event: event.name }));
-  }
+  findings.push(...snapshotDriftFindings(repoRoot, tracked, services, classes), ...leftBehindSnapshotFindings(snapshots, services, problems), ...undeclaredCompensationFindings(classes, declared));
   return findings;
 }
 

package/runtime/scripts/hfs/rules/stacks.mjs

@@ -4,7 +4,7 @@
 //     secrets/<slug>.enc, seeds}); a `.enc` outside <env>/secrets/ is never allowed, `runtime/files/`, a root `DESIGN.md`,
 //     `deployment.json` and `k8s/` are not in the list, so they fall out of it;
 //   - the declaration (read by scripts/lib/stack-declaration.mjs, the one reader of it) states a sonar service, a local
-//     Sonar is owned by the host (`stack.owner: host`, root `.claude/ext/sonar`), and no service still points at `.stacks`.
+//     Sonar is owned by the host (`stack.owner: host`, root `.claude/ext/sonar`).
 // The declaration's services contract (custody, CI wiring, project keys) stays check-starcistacks's; this file judges shape only.
 import { braceVariants, globExpression } from '../../lib/glob.mjs';
 import { declaredStack, findStackDeclaration, STACK_ROOT, text } from '../../lib/stack-declaration.mjs';
@@ -13,31 +13,29 @@ import { found } from './read.mjs';
 const STACKS_SHAPE = 'HFS_STACKS_SHAPE';
 const STACKS_SLOT = 'app.starcistacks';
 const HOST_SONAR_ROOT = '.claude/ext/sonar';
-const SEALED = /\.enc$/;
 const INSIDE_SECRETS = /^[^/]+\/secrets\/[^/]+\.enc$/;
-const RETIRED_ROOT = /^\.?stacks(?:\/|$)/;
 
 /** The anchored expressions of a slot's `allows` entries: `<name>` is one path segment, braces alternate. */
 const allowedExpressions = (allows) => allows.flatMap((entry) => braceVariants(entry.replace(/<[a-z][a-z0-9-]*>/g, '*'))).map((variant) => globExpression(variant.endsWith('/') ? `${variant}**` : variant));
 
 const shapeFinding = (file, message, extra) => found(STACKS_SHAPE, file, message, extra);
 
-/** The shape findings of the `.starcistacks` tree at the app root (`repoRoot` is the app root, `files` its own tracked paths). */
-export function stacksFindings({ repoRoot, files, resolver }) {
-  const slot = resolver.slot(STACKS_SLOT);
-  if (!slot) return [];
+function treeFindings(files, allowed, prefix) {
   const findings = [];
-  const allowed = allowedExpressions(slot.allows ?? []);
-  const prefix = `${STACK_ROOT}/`;
   for (const file of files.filter((f) => f.startsWith(prefix))) {
     const rel = file.slice(prefix.length);
-    if (SEALED.test(rel) && !INSIDE_SECRETS.test(rel)) findings.push(shapeFinding(file, `${file} is a sealed secret outside <env>/secrets/<slug>.enc; move it to .starcistacks/<env>/secrets/`));
+    if (rel.endsWith('.enc') && !INSIDE_SECRETS.test(rel)) findings.push(shapeFinding(file, `${file} is a sealed secret outside <env>/secrets/<slug>.enc; move it to .starcistacks/<env>/secrets/`));
     else if (!allowed.some((expression) => expression.test(rel))) findings.push(shapeFinding(file, `${file} is not part of the standard .starcistacks shape (application-stacks.yaml and <env>/{README.md, environment.json, infra, runtime/{config,env}, secrets/<slug>.enc, seeds}); move or delete it`));
   }
-  if (!files.some((f) => f === `${prefix}application-stacks.yaml`)) return findings;
-  const declaration = findStackDeclaration(repoRoot);
+  return findings;
+}
+
+function declarationFindings(repoRoot, files, prefix) {
   const declared = `${prefix}application-stacks.yaml`;
-  if (declaration.error) return [...findings, shapeFinding(declared, `${declared} cannot be read: ${declaration.error}`)];
+  if (!files.includes(declared)) return [];
+  const findings = [];
+  const declaration = findStackDeclaration(repoRoot);
+  if (declaration.error) return [shapeFinding(declared, `${declared} cannot be read: ${declaration.error}`)];
   const services = declaration.doc?.services;
   if (services === undefined || typeof services.sonar !== 'object' || services.sonar === null) {
     findings.push(shapeFinding(declared, `${declared} declares no sonar service; every repository states its Sonar owner (a local one is owned by the host: stack.owner host, root ${HOST_SONAR_ROOT})`));
@@ -45,10 +43,19 @@ export function stacksFindings({ repoRoot, files, resolver }) {
   }
   for (const [id, entry] of Object.entries(services)) {
     const stack = declaredStack(entry);
-    if (stack?.root && RETIRED_ROOT.test(stack.root)) findings.push(shapeFinding(declared, `${declared} services.${id}.stack.root ${stack.root} still points at the retired .stacks root; the stack root is ${STACK_ROOT}`));
     if (id === 'sonar' && text(entry?.mode) === 'local' && !(stack?.hostOwned && stack.root === HOST_SONAR_ROOT)) {
       findings.push(shapeFinding(declared, `${declared} services.sonar is a local Sonar but is not owned by the host; declare stack.owner host with root ${HOST_SONAR_ROOT}`));
     }
   }
   return findings;
 }
+
+/** The shape findings of the `.starcistacks` tree at the app root (`repoRoot` is the app root, `files` its own tracked paths). */
+export function stacksFindings({ repoRoot, files, resolver }) {
+  const slot = resolver.slot(STACKS_SLOT);
+  if (!slot) return [];
+  const prefix = `${STACK_ROOT}/`;
+  const findings = treeFindings(files, allowedExpressions(slot.allows ?? []), prefix);
+  findings.push(...declarationFindings(repoRoot, files, prefix));
+  return findings;
+}

package/runtime/scripts/hfs/rules/supabase-secrets.mjs

@@ -46,33 +46,42 @@ const liteSecretPatterns = line => {
 
 const inSecretFreeTree = (repo, file) => repo.profile === 'fe' || file.startsWith('fe/') || file.startsWith('supabase/');
 
+function custodyPathFinding(file, repo, findings) {
+  if (repo.profile === 'app') {
+    if (ROOT_ENV.test(file) || SECRETS_ENV.test(file) || SECRETS_DIRECTORY.test(file)) {
+      findings.push(found(LITE_SECRET_CUSTODY, file, `${file} is forbidden at the lite app root; lite keeps no .env*, secrets.env or .secrets/ custody path.`, { pattern: 'lite-forbidden-entry' }));
+      return true;
+    }
+    if (file.endsWith('.enc') && !SEALED_HOME.test(file)) {
+      findings.push(found(LITE_SECRET_CUSTODY, file, `${file} is a sealed file outside .starcistacks/<env>/secrets/; lite has exactly one encrypted custody path.`, { pattern: 'sealed-file-home' }));
+    }
+  } else if (file.endsWith('.enc')) {
+    findings.push(found(LITE_SECRET_CUSTODY, file, `${file} is a sealed file inside a side tree; lite keeps *.enc only at the app root under .starcistacks/<env>/secrets/.`, { pattern: 'sealed-file-home' }));
+  }
+  return false;
+}
+
+function providerSecretFindings(repoRoot, file, repo, findings) {
+  if (!inSecretFreeTree(repo, file) || LOCKFILE.test(file)) return;
+  const text = readText(repoRoot, file);
+  if (text === null) return;
+  const seen = new Set();
+  const lines = text.split(/\r?\n/u);
+  for (const [index, line] of lines.entries()) {
+    for (const pattern of liteSecretPatterns(line)) {
+      if (seen.has(pattern)) continue;
+      seen.add(pattern);
+      findings.push(found(LITE_SECRET_CUSTODY, file, `${file}:${index + 1} holds a provider-shaped secret (${pattern}); lite keeps no secret literal under fe/ or supabase/.`, { line: index + 1, pattern }));
+    }
+  }
+}
+
 /** Raw L17 findings. The catalog-driven findings filter decides which editions judge them. */
 export function liteSecretCustodyFindings({ repoRoot, files, repo }) {
   const findings = [];
   for (const file of files) {
-    if (repo.profile === 'app') {
-      if (ROOT_ENV.test(file) || SECRETS_ENV.test(file) || SECRETS_DIRECTORY.test(file)) {
-        findings.push(found(LITE_SECRET_CUSTODY, file, `${file} is forbidden at the lite app root; lite keeps no .env*, secrets.env or .secrets/ custody path.`, { pattern: 'lite-forbidden-entry' }));
-        continue;
-      }
-      if (file.endsWith('.enc') && !SEALED_HOME.test(file)) {
-        findings.push(found(LITE_SECRET_CUSTODY, file, `${file} is a sealed file outside .starcistacks/<env>/secrets/; lite has exactly one encrypted custody path.`, { pattern: 'sealed-file-home' }));
-      }
-    } else if (file.endsWith('.enc')) {
-      findings.push(found(LITE_SECRET_CUSTODY, file, `${file} is a sealed file inside a side tree; lite keeps *.enc only at the app root under .starcistacks/<env>/secrets/.`, { pattern: 'sealed-file-home' }));
-    }
-    if (!inSecretFreeTree(repo, file) || LOCKFILE.test(file)) continue;
-    const text = readText(repoRoot, file);
-    if (text === null) continue;
-    const seen = new Set();
-    const lines = text.split(/\r?\n/u);
-    for (let index = 0; index < lines.length; index += 1) {
-      for (const pattern of liteSecretPatterns(lines[index])) {
-        if (seen.has(pattern)) continue;
-        seen.add(pattern);
-        findings.push(found(LITE_SECRET_CUSTODY, file, `${file}:${index + 1} holds a provider-shaped secret (${pattern}); lite keeps no secret literal under fe/ or supabase/.`, { line: index + 1, pattern }));
-      }
-    }
+    if (custodyPathFinding(file, repo, findings)) continue;
+    providerSecretFindings(repoRoot, file, repo, findings);
   }
   return findings;
 }

package/runtime/scripts/hfs/rules/test-topology.mjs

@@ -3,29 +3,43 @@
 //   - there is no `testing/` folder: doubles and builders live in `src/tests/fixtures/`, next to the subject as `*.spec.ts`;
 //   - one `jest.config.js` at the root: a second jest config (`jest.config.<x>.js`, `jest.<x>.config.*`, one per app) and a
 //     `jest` key in a package.json are refused.
-// `int-spec`, `harness-spec`, the retired test folders and the per-lane configs under src/tests are the architecture machine's
+// `int-spec`, `harness-spec`, the unsupported test folders and the per-lane configs under src/tests are the architecture machine's
 // (reported under this same code, BE_TEST_TOPOLOGY); that jest.config.js is the rendered one (projects `unit`, `integration`, `e2e` and
 // `contract`, diagnostics off) is the managed-file check's (HFS_MANAGED_FILE_DRIFT); a spec whose suffix disagrees with its src/tests folder has no slot (HFS_SLOT_UNDECLARED).
 import { found, readJson } from './read.mjs';
 
 const TEST_TOPOLOGY = 'BE_TEST_TOPOLOGY';
 const DOT_TEST = /\.test\.[cm]?[jt]sx?$/;
-const JEST_CONFIG = /(?:^|\/)jest(?:\.[^/]+)*\.config(?:\.[^/]+)*\.(?:[cm]?[jt]s|json)$|(?:^|\/)jest\.config\.[^/]+$/;
+const JEST_CONFIG_NAMED = /(?:^|\/)jest(?:\.[^/]+)?\.config(?:\.[^/]+)?\.(?:[cm]?[jt]s|json)$/;
+const JEST_CONFIG_ANY_EXTENSION = /(?:^|\/)jest\.config\.[^/]+$/;
 const ROOT_JEST_CONFIG = 'jest.config.js';
 
+const isJestConfig = (file) => JEST_CONFIG_NAMED.test(file) || JEST_CONFIG_ANY_EXTENSION.test(file);
+
+/** The finding of the tracked file's own path, else null. */
+function pathFinding(file) {
+  if (DOT_TEST.test(file)) return found(TEST_TOPOLOGY, file, `${file} is a \`.test\` file; a unit spec is <name>.spec.ts beside its subject and an integration, e2e or contract spec is *.integration-spec.ts, *.e2e-spec.ts or *.contract-spec.ts under its own src/tests folder`);
+  if (file.split('/').slice(0, -1).includes('testing')) return found(TEST_TOPOLOGY, file, `${file} sits in a testing/ folder; doubles and builders live in src/tests/fixtures/ and specs sit beside their subject`);
+  if (isJestConfig(file) && file !== ROOT_JEST_CONFIG) return found(TEST_TOPOLOGY, file, `${file} is a second jest configuration; the one root ${ROOT_JEST_CONFIG} declares the projects unit, integration, e2e and contract`);
+  return null;
+}
+
+/** The finding of a package.json that carries a `jest` key, else null. */
+function packageFinding(repoRoot, file) {
+  if (file !== 'package.json' && !file.endsWith('/package.json')) return null;
+  if (file.includes('node_modules/')) return null;
+  const pkg = readJson(repoRoot, file);
+  return pkg && Object.hasOwn(pkg, 'jest') ? found(TEST_TOPOLOGY, file, `${file} carries a jest key; jest is configured only by the root ${ROOT_JEST_CONFIG}`) : null;
+}
+
 /** The findings of R47 over the tracked paths `files` of a back-end repository at `repoRoot`. */
 export function testTopologyFindings({ repoRoot, files }) {
   const findings = [];
   for (const file of files) {
-    const segments = file.split('/');
-    if (DOT_TEST.test(file)) findings.push(found(TEST_TOPOLOGY, file, `${file} is a \`.test\` file; a unit spec is <name>.spec.ts beside its subject and an integration, e2e or contract spec is *.integration-spec.ts, *.e2e-spec.ts or *.contract-spec.ts under its own src/tests folder`));
-    else if (segments.slice(0, -1).includes('testing')) findings.push(found(TEST_TOPOLOGY, file, `${file} sits in a testing/ folder; doubles and builders live in src/tests/fixtures/ and specs sit beside their subject`));
-    else if (JEST_CONFIG.test(file) && file !== ROOT_JEST_CONFIG) findings.push(found(TEST_TOPOLOGY, file, `${file} is a second jest configuration; the one root ${ROOT_JEST_CONFIG} declares the projects unit, integration, e2e and contract`));
-    if (file === 'package.json' || file.endsWith('/package.json')) {
-      if (file.includes('node_modules/')) continue;
-      const pkg = readJson(repoRoot, file);
-      if (pkg && Object.hasOwn(pkg, 'jest')) findings.push(found(TEST_TOPOLOGY, file, `${file} carries a jest key; jest is configured only by the root ${ROOT_JEST_CONFIG}`));
-    }
+    const own = pathFinding(file);
+    if (own) findings.push(own);
+    const packaged = packageFinding(repoRoot, file);
+    if (packaged) findings.push(packaged);
   }
   return findings;
 }

package/runtime/scripts/hfs/secret.mjs

@@ -1,6 +1,6 @@
 // secret.mjs - `starci app secret list|show|set|gen`: the canon command over an app's sealed secrets.
 // (R06: a secret exists only as a sops envelope there). It is the one way an operator or an agent reads or writes one; a plain
-// `sops` command in a KEYS.md or a runbook is retired. Every sops use goes through scripts/api/sops (decrypt.mjs, seal.mjs):
+// `sops` command in a KEYS.md or a runbook is not the way. Every sops use goes through scripts/api/sops (decrypt.mjs, seal.mjs):
 //   starci app secret list [--env <name>]                       every secret of the env and the keys it holds (names only, nothing decrypted)
 //   starci app secret show <slug> [--key <NAME>] [--env <name>] decrypt one value to stdout
 //   starci app secret set <slug> [--key <NAME>] [--age <recipient>]... [--env <name>]
@@ -16,18 +16,23 @@ import { runProgram } from '../api/process/run-program.mjs';
 import { resolveRealTool } from '../api/process/resolve-real-tool.mjs';
 const sopsInvocation = Object.freeze({runProgram,resolveRealTool});
 import { randomBytes, randomUUID } from 'node:crypto';
-import { claimManager } from '../connectors/lib.mjs';
-import { sha256 } from '../../engine/digest.mjs';
+import { claimFile } from '../api/fs/claim-file.mjs';
 import { isSopsEnvelope } from '../lib/sops-envelope.mjs';
 import { decrypt as sopsDecrypt } from '../api/sops/decrypt.mjs';
 import { seal as sopsSeal } from '../api/sops/seal.mjs';
+import { byCodeUnit } from '../lib/list.mjs';
 
 class SecretError extends Error {}
-// claimManager is process-owned; refuse a recursive same-process write as well.
-const writingSecrets = new Set();
 
 const SLUG = /^[a-z0-9][a-z0-9-]*$/u;
-const KEY = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+const KEY = /^[A-Za-z_]\w*$/u;
+const WHITESPACE = String.raw`\s`;
+const REQUIRED_INDENT = `${WHITESPACE}+`;
+const OPTIONAL_DASH = '-?';
+const OPTIONAL_SPACING = `${WHITESPACE}*`;
+const RECIPIENT_NAME = 'recipient:';
+const RECIPIENT_VALUE = String.raw`(\S+)`;
+const RECIPIENT_LINE = new RegExp(`^${REQUIRED_INDENT}${OPTIONAL_DASH}${OPTIONAL_SPACING}${RECIPIENT_NAME}${OPTIONAL_SPACING}${RECIPIENT_VALUE}`, 'gmu');
 const DEFAULT_KEY = 'data';
 const VERBS = new Set(['list', 'show', 'set', 'gen']);
 
@@ -47,19 +52,19 @@ export function envelopeOf(text) {
     return { format, keys: Object.keys(doc).filter((name) => name !== 'sops'), recipients: (doc.sops?.age ?? []).map((entry) => entry.recipient).filter(Boolean) };
   }
   if (format === 'yaml') {
-    const keys = [...text.matchAll(/^([A-Za-z_][A-Za-z0-9_]*):/gmu)].map((match) => match[1]).filter((name) => name !== 'sops');
-    return { format, keys, recipients: [...text.matchAll(/^\s+-?\s*recipient:\s*(\S+)/gmu)].map((match) => match[1]) };
+    const keys = [...text.matchAll(/^([A-Za-z_]\w*):/gmu)].map((match) => match[1]).filter((name) => name !== 'sops');
+    return { format, keys, recipients: [...text.matchAll(RECIPIENT_LINE)].map((match) => match[1]) };
   }
-  const keys = [...text.matchAll(/^([A-Za-z_][A-Za-z0-9_]*)=/gmu)].map((match) => match[1]).filter((name) => !name.startsWith('sops_'));
+  const keys = [...text.matchAll(/^([A-Za-z_]\w*)=/gmu)].map((match) => match[1]).filter((name) => !name.startsWith('sops_'));
   return { format, keys, recipients: [...text.matchAll(/^sops_age__list_\d+__map_recipient=(\S+)/gmu)].map((match) => match[1]) };
 }
 
 /** The plaintext document `map` in the given format. A dotenv value cannot hold a line break. */
 export function plaintextOf(format, map) {
   if (format === 'json') return `${JSON.stringify(map)}\n`;
-  if (format === 'yaml') return `${Object.entries(map).map(([name, value]) => `${name}: ${JSON.stringify(value)}`).join('\n')}\n`;
+  if (format === 'yaml') return Object.entries(map).map(([name, value]) => name + ': ' + JSON.stringify(value)).join('\n') + '\n';
   for (const [name, value] of Object.entries(map)) if (/[\r\n]/u.test(value)) throw new SecretError(`${name} holds a line break; a dotenv secret holds one-line values only`);
-  return `${Object.entries(map).map(([name, value]) => `${name}=${value}`).join('\n')}\n`;
+  return Object.entries(map).map(([name, value]) => name + '=' + value).join('\n') + '\n';
 }
 
 /** The directory of the sealed secrets of the app at `repoRoot` for `env`; the one env that has secrets when none is named. */
@@ -118,14 +123,10 @@ function parse(argv) {
 const readStdin = () => fs.readFileSync(0, 'utf8');
 
 /** Seal `key = value` into the secret `slug`: an existing document keeps its other keys and its recipients. */
-function writeSecret({ file, values, age, sops, processEnv = process.env }) {
+function writeSecret({ file, values, age, sops }) {
   for (const key of Object.keys(values)) if (!KEY.test(key)) throw new SecretError(`${key} is not a key name`);
-  const absolute = path.resolve(file), target = process.platform === 'win32' ? absolute.toLowerCase() : absolute;
-  const name = `sealed-secret-${sha256(target)}`;
-  if (writingSecrets.has(name)) throw new SecretError('the sealed secret is being updated; retry after that write settles');
-  const held = claimManager(name, { env: processEnv });
+  const held = claimFile(path.resolve(file));
   if (!held.ok) throw new SecretError('the sealed secret is being updated; retry after that write settles');
-  writingSecrets.add(name);
   try {
   let format = 'json';
   let map = {};
@@ -148,7 +149,7 @@ function writeSecret({ file, values, age, sops, processEnv = process.env }) {
     fs.writeFileSync(temporary, sealed, { flag: 'wx', mode: 0o600, flush: true });
     fs.renameSync(temporary, file);
   } finally { if (fs.existsSync(temporary)) fs.unlinkSync(temporary); }
-  } finally { writingSecrets.delete(name); held.release(); }
+  } finally { held.release(); }
 }
 
 /** Update named keys through the same canonical sealed-secret owner used by the CLI. */
@@ -157,10 +158,45 @@ export function setSecretValues(repoRoot, { slug, values, env = null }, { sops =
   const file = fileOf(directory, slug);
   if (!values || typeof values !== 'object' || Array.isArray(values) || !Object.keys(values).length) throw new SecretError('secret update requires named values');
   for (const value of Object.values(values)) if (typeof value !== 'string' || value === '') throw new SecretError('secret values must be nonempty strings');
-  writeSecret({ file, values, age, sops: sops ?? defaultSops(processEnv), processEnv });
+  writeSecret({ file, values, age, sops: sops ?? defaultSops(processEnv) });
   return { file, via: 'sealed-secret' };
 }
 
+function listSecrets(opts, directory, repoRoot, stdout) {
+  if (opts.positional.length) throw new SecretError('starci app secret list takes no name');
+  const files = fs.existsSync(directory) ? fs.readdirSync(directory).filter((name) => name.endsWith('.enc')).sort(byCodeUnit) : [];
+  for (const name of files) stdout(`${name.slice(0, -'.enc'.length)}  ${envelopeOf(fs.readFileSync(path.join(directory, name), 'utf8')).keys.join(', ')}\n`);
+  stdout(`${files.length} secret${files.length === 1 ? '' : 's'} in ${path.relative(repoRoot, directory).split(path.sep).join('/')}\n`);
+  return 0;
+}
+
+function showSecret(opts, file, seam, stdout) {
+  if (!fs.existsSync(file)) throw new SecretError(`${opts.positional[0]} is not sealed in this env`);
+  const { format, keys } = envelopeOf(fs.readFileSync(file, 'utf8'));
+  if (opts.key === undefined && !keys.includes(DEFAULT_KEY) && keys.length !== 1) throw new SecretError(`${opts.positional[0]} holds ${keys.join(', ')}; name one with --key`);
+  const map = seam.decrypt(file, format);
+  const name = opts.key ?? (keys.includes(DEFAULT_KEY) ? DEFAULT_KEY : keys[0]);
+  if (!Object.hasOwn(map, name)) throw new SecretError(`${opts.positional[0]} has no key ${name}`);
+  stdout(`${String(map[name])}\n`);
+  return 0;
+}
+
+function setSecretFromStdin(opts, file, key, seam, stdin, stdout) {
+  const value = String(stdin()).replace(/\r?\n$/u, '');
+  if (value === '') throw new SecretError('the value on stdin is empty');
+  writeSecret({ file, values: { [key]: value }, age: opts.age, sops: seam });
+  stdout(`sealed ${opts.positional[0]} (${key})\n`);
+  return 0;
+}
+
+function generateSecret(opts, file, key, seam, random, stdout) {
+  const bytes = opts.bytes === undefined ? 32 : Number(opts.bytes);
+  if (!Number.isInteger(bytes) || bytes < 16 || bytes > 1024) throw new SecretError('--bytes is a whole number from 16 to 1024');
+  writeSecret({ file, values: { [key]: random(bytes).toString('base64url') }, age: opts.age, sops: seam });
+  stdout(`generated and sealed ${opts.positional[0]} (${key}, ${bytes} bytes); read it with starci app secret show\n`);
+  return 0;
+}
+
 /** `starci app secret <verb> ...`; `stdin` returns the value `set` seals, `sops` and `random` are test seams. */
 export function secretMain(argv, { stdout = (s) => process.stdout.write(s), stderr = (s) => process.stderr.write(s), stdin = readStdin, sops = null, random = randomBytes, env = process.env, cwd = process.cwd() } = {}) {
   const [verb, ...rest] = argv;
@@ -170,38 +206,13 @@ export function secretMain(argv, { stdout = (s) => process.stdout.write(s), stde
     const repoRoot = path.resolve(cwd, opts.cwd ?? '.');
     const directory = secretsDirectory(repoRoot, opts.env);
     const key = opts.key ?? DEFAULT_KEY;
-    if (verb === 'list') {
-      if (opts.positional.length) throw new SecretError('starci app secret list takes no name');
-      const files = fs.existsSync(directory) ? fs.readdirSync(directory).filter((name) => name.endsWith('.enc')).sort() : [];
-      for (const name of files) stdout(`${name.slice(0, -'.enc'.length)}  ${envelopeOf(fs.readFileSync(path.join(directory, name), 'utf8')).keys.join(', ')}\n`);
-      stdout(`${files.length} secret${files.length === 1 ? '' : 's'} in ${path.relative(repoRoot, directory).split(path.sep).join('/')}\n`);
-      return 0;
-    }
+    if (verb === 'list') return listSecrets(opts, directory, repoRoot, stdout);
     if (opts.positional.length !== 1) throw new SecretError(`starci app secret ${verb} takes one secret name`);
     const file = fileOf(directory, opts.positional[0]);
     const seam = sops ?? defaultSops(env);
-    if (verb === 'show') {
-      if (!fs.existsSync(file)) throw new SecretError(`${opts.positional[0]} is not sealed in this env`);
-      const { format, keys } = envelopeOf(fs.readFileSync(file, 'utf8'));
-      if (opts.key === undefined && !keys.includes(DEFAULT_KEY) && keys.length !== 1) throw new SecretError(`${opts.positional[0]} holds ${keys.join(', ')}; name one with --key`);
-      const map = seam.decrypt(file, format);
-      const name = opts.key ?? (keys.includes(DEFAULT_KEY) ? DEFAULT_KEY : keys[0]);
-      if (!Object.hasOwn(map, name)) throw new SecretError(`${opts.positional[0]} has no key ${name}`);
-      stdout(`${String(map[name])}\n`);
-      return 0;
-    }
-    if (verb === 'set') {
-      const value = String(stdin()).replace(/\r?\n$/u, '');
-      if (value === '') throw new SecretError('the value on stdin is empty');
-      writeSecret({ file, values: { [key]: value }, age: opts.age, sops: seam, processEnv: env });
-      stdout(`sealed ${opts.positional[0]} (${key})\n`);
-      return 0;
-    }
-    const bytes = opts.bytes === undefined ? 32 : Number(opts.bytes);
-    if (!Number.isInteger(bytes) || bytes < 16 || bytes > 1024) throw new SecretError('--bytes is a whole number from 16 to 1024');
-    writeSecret({ file, values: { [key]: random(bytes).toString('base64url') }, age: opts.age, sops: seam, processEnv: env });
-    stdout(`generated and sealed ${opts.positional[0]} (${key}, ${bytes} bytes); read it with starci app secret show\n`);
-    return 0;
+    if (verb === 'show') return showSecret(opts, file, seam, stdout);
+    if (verb === 'set') return setSecretFromStdin(opts, file, key, seam, stdin, stdout);
+    return generateSecret(opts, file, key, seam, random, stdout);
   } catch (error) {
     if (error instanceof SecretError || error instanceof SyntaxError) { stderr(`starci app secret: ${error.message}\n`); return 2; }
     throw error;

package/runtime/scripts/hfs/slot-app-view.mjs

@@ -0,0 +1,102 @@
+// slot-app-view.mjs - the resolver of a whole app: a root path is answered by the scope of the app root, a path below a side folder
+// (be/, fe/) by that side's scope with the side prefixed back onto every path and root it returns. Only the declared `reads` cross sides.
+// slots.mjs builds the scopes (`root` and `sides`, each a resolver of one scope) and hands them to appResolver.
+import { APP_SCOPE, PROFILES } from './slot-manifest-shape.mjs';
+import { cleanSlotPath } from './slot-path.mjs';
+
+/** { side, rest } when `p` lies below a side folder, else null. */
+function splitSide(input) {
+  const p = cleanSlotPath(input);
+  const slash = p.indexOf('/');
+  const head = slash < 0 ? p : p.slice(0, slash);
+  return PROFILES.includes(head) && slash > 0 ? { side: head, rest: p.slice(slash + 1) } : null;
+}
+
+const under = (side, rel) => (rel ? `${side}/${rel}` : side);
+
+function prefixed(side, c) {
+  return {
+    ...c,
+    path: under(side, c.path),
+    side,
+    ...(c.root !== undefined ? { root: under(side, c.root) } : {}),
+    ...(c.nearest ? { nearest: { ...c.nearest, matchedPrefix: under(side, c.nearest.matchedPrefix), matchedDepth: c.nearest.matchedDepth + 1 } } : {}),
+  };
+}
+
+function classifyApp({ root, sides }, input) {
+  const at = splitSide(input);
+  return at ? prefixed(at.side, sides[at.side].classifyPath(at.rest)) : root.classifyPath(input);
+}
+
+function ownerApp({ root, sides }, input) {
+  const at = splitSide(input);
+  if (!at) return root.ownerOf(input);
+  const owner = sides[at.side].ownerOf(at.rest);
+  return owner ? { ...owner, root: under(at.side, owner.root), side: at.side } : null;
+}
+
+/** Whether `toPath`, of the other side, lies below a path `fromSide` declares it reads. */
+const readsPath = (repo, fromSide, toPath) => repo.sides[fromSide].reads.some((read) => `${cleanSlotPath(toPath)}/`.startsWith(read));
+
+/** The verdict of an import from a side file to a path of the other side (or of the app root, `toSide` null): allowed only through a declared read. */
+function sideCrossing(repo, fromSide, toSide, toPath) {
+  return readsPath(repo, fromSide, toPath)
+    ? { allowed: true, reason: 'sideRead', fromSide, toSide }
+    : { allowed: false, reason: 'crossSide', fromSide, toSide, reads: repo.sides[fromSide].reads };
+}
+
+function importAllowedApp({ repo, root, sides }, fromPath, toPath) {
+  const from = splitSide(fromPath);
+  const to = splitSide(toPath);
+  // A side file may read an app-root path (supabase/types/) only through a declared read, exactly as it reads the other side.
+  if (from && from.side !== to?.side) return sideCrossing(repo, from.side, to?.side ?? null, toPath);
+  if (from && to) return sides[from.side].importAllowed(from.rest, to.rest);
+  return root.importAllowed(fromPath, toPath);
+}
+
+function requiredPathsApp({ root, sides }) {
+  const own = root.requiredPaths();
+  const paths = [...own.paths];
+  const minimums = [...own.minimums];
+  for (const side of PROFILES) {
+    const required = sides[side].requiredPaths();
+    paths.push(...required.paths.map((entry) => ({ ...entry, path: under(side, entry.path), side })));
+    minimums.push(...required.minimums.map((entry) => ({ ...entry, side })));
+  }
+  return { paths, minimums };
+}
+
+function slotEnabledApp({ root, sides }, slot) {
+  if (slot.profiles.includes(APP_SCOPE)) return root.slotEnabled(slot);
+  return PROFILES.some((side) => slot.profiles.includes(side) && sides[side].slotEnabled(slot));
+}
+
+/** The resolver of the app `repo`: `root` answers its root paths and `sides[side]` the paths below that side's folder. */
+export function appResolver(repo, root, sides) {
+  const view = { repo, root, sides };
+  const allSlots = [...new Map([...root.slots(), ...PROFILES.flatMap((side) => sides[side].slots())].map((s) => [s.id, s])).values()];
+  const byId = new Map(allSlots.map((s) => [s.id, s]));
+  const classifyPath = (input) => classifyApp(view, input);
+  return Object.freeze({
+    repo,
+    sides: Object.freeze(sides),
+    /** The side of a path (be, fe) or null for a root path. */
+    sideOf: (input) => splitSide(input)?.side ?? null,
+    slot: (id) => byId.get(id) ?? null,
+    slots: () => allSlots,
+    slotEnabled: (slot) => slotEnabledApp(view, slot),
+    classifyPath,
+    slotOf: (p) => { const c = classifyPath(p); return c.slot ? byId.get(c.slot) : null; },
+    ownerOf: (input) => ownerApp(view, input),
+    tierOf: (input) => { const at = splitSide(input); return at ? sides[at.side].tierOf(at.rest) : root.tierOf(input); },
+    importAllowed: (fromPath, toPath) => importAllowedApp(view, fromPath, toPath),
+    requiredFiles: (input) => { const at = splitSide(input); return at ? sides[at.side].requiredFiles(at.rest).map((p) => under(at.side, p)) : root.requiredFiles(input); },
+    requiredPaths: () => requiredPathsApp(view),
+    trackingOf: (p) => classifyPath(p).tracking ?? null,
+    isTracked: (p) => classifyPath(p).tracking === 'tracked',
+    // The root has no tier and no rule parameters of its own; each side has them (sides.<side>.ruleParams()).
+    ruleParams: () => null,
+    allowedImports: () => null,
+  });
+}