@starci/hfs 4.2.17 → 4.4.0

package/runtime/scripts/hfs/secret.mjs

@@ -1,220 +1,189 @@
-// 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 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>]
-//                                                        the value is read from stdin (never from an argument); a new secret takes its
-//                                                        recipients from --age, else from the repository's .sops.yaml
-//   starci app secret gen <slug> [--key <NAME>] [--bytes <n>] [--age <recipient>]... [--env <name>]
-//                                                        a random value (base64url of n bytes, default 32) sealed without being printed
-// A single-value secret holds its value under the key `data`. Every verb runs at the app root (the folder of hfs.json), or at --cwd.
-// Exit 0 done, 2 a refusal or bad usage (a secret value is never part of a message).
-import fs from 'node:fs';
-import path from 'node:path';
-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 { 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 {}
-
-const SLUG = /^[a-z0-9][a-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']);
-
-/** The envelope format of a sealed secret, read from its text: json, yaml or dotenv. */
-export function formatOf(text) {
-  const body = String(text).trimStart();
-  if (body.startsWith('{')) return 'json';
-  if (/^sops:\s*$/mu.test(text)) return 'yaml';
-  return 'dotenv';
-}
-
-/** The key names a sealed document holds and the age recipients it is sealed to, read without decrypting anything. */
-export function envelopeOf(text) {
-  const format = formatOf(text);
-  if (format === 'json') {
-    const doc = JSON.parse(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_]\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_]\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';
-  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';
-}
-
-/** The directory of the sealed secrets of the app at `repoRoot` for `env`; the one env that has secrets when none is named. */
-function secretsDirectory(repoRoot, env) {
-  const stacks = path.join(repoRoot, '.starcistacks');
-  if (!fs.existsSync(stacks)) throw new SecretError('this app has no .starcistacks; run starci app secret at the app root, or pass --cwd');
-  if (env) {
-    if (!/^[a-z0-9][a-z0-9-]*$/u.test(env)) throw new SecretError(`--env ${env} is not an environment name`);
-    return path.join(stacks, env, 'secrets');
-  }
-  const withSecrets = fs.readdirSync(stacks, { withFileTypes: true }).filter((entry) => entry.isDirectory() && fs.existsSync(path.join(stacks, entry.name, 'secrets'))).map((entry) => entry.name);
-  if (withSecrets.length === 1) return path.join(stacks, withSecrets[0], 'secrets');
-  throw new SecretError(withSecrets.length === 0 ? 'no environment of .starcistacks has a secrets folder; pass --env to create the first secret' : `more than one environment has secrets (${withSecrets.join(', ')}); pass --env`);
-}
-
-const fileOf = (directory, slug) => {
-  if (!SLUG.test(slug ?? '')) throw new SecretError(`${slug === undefined ? 'a secret name' : slug} is not a secret slug: lowercase letters, digits and dashes`);
-  return path.join(directory, `${slug}.enc`);
-};
-
-/** The default sops seam: the runtime's sops api, which finds the binary on this machine. */
-function defaultSops(env = process.env) {
-  const refuse = (what, result) => {
-    if (result.error?.identityRefusal) return Object.assign(new SecretError(result.error.message), { identityRefusal: result.error.identityRefusal });
-    if (result.error?.code === 'SOPS_MISSING') return new SecretError(result.error.message);
-    return new SecretError(`sops could not ${what} (exit ${String(result.status)})`);
-  };
-  return {
-    decrypt(file, format) {
-      const result = sopsDecrypt(null, ['decrypt', '--input-type', format, '--output-type', 'json', file], { env, invocation: sopsInvocation });
-      if (result.status !== 0) throw refuse(`decrypt ${path.basename(file)}; is the age identity installed?`, result);
-      try { return JSON.parse(result.stdout); } catch { throw new SecretError('sops returned an invalid plaintext document'); }
-    },
-    seal(request) {
-      const result = sopsSeal(null, request, { env, invocation: sopsInvocation });
-      if (result.status !== 0) throw refuse('seal the secret', result);
-      return result.stdout;
-    },
-  };
+// secret.mjs - app secret init|set|get|unset|rename|remove|materialize|list|verify: sealed custody and private KEY files.
+// SOPS plaintext travels on stdin and stays in memory; normal CLI output contains names and local file paths only.
+// Every verb runs at the app root or --cwd. Exit 0 done, 2 refusal; --reveal is the only plaintext stdout path.
+// unset, rename and remove edit one sealed member and are dry runs until --execute (scripts/hfs/secret-edit.mjs).
+// verify decrypts each member in memory and names only keys and violated shapes, never a value (R249).
+import fs from "node:fs";
+import path from "node:path";
+import { randomBytes } from "node:crypto";
+import { invocationDir } from "../lib/roots.mjs";
+import { initializeSecrets } from "./secret-init.mjs";
+import { validateKey } from "./secret-document.mjs";
+import { defaultSops } from "./secret-sops.mjs";
+import { fileOf, secretsDirectory, writeSecret } from "./secret-store.mjs";
+import { getSecret, listSecrets, materializeSecrets } from "./secret-output.mjs";
+import { SecretError, publicStorage, secretErrorMessage } from "./secret-errors.mjs";
+import { editSecret, validateEditNames } from "./secret-edit.mjs";
+import { verifySecrets } from "./rules/env-value-shape.mjs";
+
+export { envelopeOf, formatOf, plaintextOf } from "./secret-document.mjs";
+export { setSecretValues } from "./secret-store.mjs";
+
+const VERBS = new Set(["init", "list", "get", "set", "unset", "rename", "remove", "materialize", "verify"]);
+const EDIT_VERBS = new Set(["unset", "rename", "remove"]);
+
+function valueOption(opts, flag, value) {
+  if (value === undefined || value.startsWith("--"))
+    throw new SecretError(`${flag} needs a value`);
+  if (Object.hasOwn(opts, flag.slice(2)))
+    throw new SecretError(`${flag} may be given only once`);
+  opts[flag.slice(2)] = value;
 }
 
 function parse(argv) {
-  const opts = { positional: [], age: [] };
+  const opts = { positional: [] };
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
-    if (['--cwd', '--env', '--key', '--bytes', '--age'].includes(arg)) {
-      if (argv[i + 1] === undefined) throw new SecretError(`${arg} needs a value`);
-      if (arg === '--age') opts.age.push(argv[i + 1]); else opts[arg.slice(2)] = argv[i + 1];
-      i += 1;
-    } else if (arg.startsWith('--')) throw new SecretError(`unknown flag ${arg}`);
+    const [flag, inline] = arg.split(/=(.*)/su);
+    if (["--cwd", "--generate"].includes(flag)) {
+      valueOption(opts, flag, inline ?? argv[++i]);
+    } else if (["--to-file", "--reveal", "--execute", "--force-nonempty"].includes(flag)) {
+      if (inline !== undefined && !["true", "false"].includes(inline))
+        throw new SecretError(`${flag} expects true or false`);
+      opts[flag.slice(2)] = inline !== "false";
+    } else if (arg.startsWith("--"))
+      throw new SecretError(`unknown flag ${arg}`);
     else opts.positional.push(arg);
   }
   return opts;
 }
 
-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 }) {
-  for (const key of Object.keys(values)) if (!KEY.test(key)) throw new SecretError(`${key} is not a key name`);
-  const held = claimFile(path.resolve(file));
-  if (!held.ok) throw new SecretError('the sealed secret is being updated; retry after that write settles');
-  try {
-  let format = 'json';
-  let map = {};
-  let recipients = age;
-  if (fs.existsSync(file)) {
-    const text = fs.readFileSync(file, 'utf8');
-    const envelope = envelopeOf(text);
-    format = envelope.format;
-    map = sops.decrypt(file, format);
-    if (!age.length) recipients = envelope.recipients;
-  }
-  Object.assign(map, values);
-  const sealed = sops.seal({ inputType: format, plaintext: plaintextOf(format, map), recipients, filenameOverride: file });
-  let parsed;
-  try { parsed = envelopeOf(sealed); } catch { throw new SecretError('sops returned an invalid sealed document'); }
-  if (!isSopsEnvelope(sealed) || parsed.keys.length !== Object.keys(map).length || !parsed.keys.every(key => Object.hasOwn(map, key))) throw new SecretError('sops returned an invalid sealed document');
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  const temporary = path.join(path.dirname(file), `.${path.basename(file)}-${randomUUID()}.tmp`);
-  try {
-    fs.writeFileSync(temporary, sealed, { flag: 'wx', mode: 0o600, flush: true });
-    fs.renameSync(temporary, file);
-  } finally { if (fs.existsSync(temporary)) fs.unlinkSync(temporary); }
-  } finally { held.release(); }
-}
+const readStdin = () => {
+  if (process.stdin.isTTY)
+    throw new SecretError(
+      "set reads a value from redirected stdin; use --generate <bytes> to generate one",
+    );
+  return fs.readFileSync(0, "utf8");
+};
 
-/** Update named keys through the same canonical sealed-secret owner used by the CLI. */
-export function setSecretValues(repoRoot, { slug, values, env = null }, { sops = null, age = [], processEnv = process.env } = {}) {
-  const directory = secretsDirectory(repoRoot, env);
-  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) });
-  return { file, via: 'sealed-secret' };
+function usageArguments(verb) {
+  if (verb === "init") return "";
+  if (verb === "set") return "<env> <slug> <KEY> [--generate <bytes>]";
+  if (verb === "get") return "<env> <slug> [KEY] --to-file [--reveal]";
+  if (verb === "unset") return "<env> <slug> <KEY> [--execute]";
+  if (verb === "rename") return "<env> <slug> <OLD> <NEW> [--execute]";
+  if (verb === "remove") return "<env> <slug> [--execute] [--force-nonempty]";
+  return "<env>";
 }
 
-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 editOptionsFor(verb, opts) {
+  if (opts.execute !== undefined && !EDIT_VERBS.has(verb))
+    throw new SecretError("--execute is only valid for unset, rename and remove");
+  if (opts["force-nonempty"] !== undefined && verb !== "remove")
+    throw new SecretError("--force-nonempty is only valid for remove");
 }
 
-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 outputOptionsFor(verb, opts) {
+  if (
+    (opts["to-file"] !== undefined || opts.reveal !== undefined) &&
+    verb !== "get"
+  )
+    throw new SecretError("--to-file and --reveal are only valid for get");
+  if (verb === "get" && !opts["to-file"] && !opts.reveal)
+    throw new SecretError("get requires --to-file or explicit --reveal");
 }
 
-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 optionsFor(verb, opts) {
+  const count = opts.positional.length;
+  const bounds = {
+    init: [0, 0],
+    list: [1, 1],
+    materialize: [1, 1],
+    verify: [1, 1],
+    set: [3, 3],
+    get: [2, 3],
+    unset: [3, 3],
+    rename: [4, 4],
+    remove: [2, 2],
+  }[verb];
+  if (count < bounds[0] || count > bounds[1])
+    throw new SecretError(
+      `usage: starci app secret ${verb} ${usageArguments(verb)}`,
+    );
+  if (opts.generate !== undefined && verb !== "set")
+    throw new SecretError("--generate is only valid for set");
+  outputOptionsFor(verb, opts);
+  editOptionsFor(verb, opts);
+  if (EDIT_VERBS.has(verb)) validateEditNames(verb, opts.positional.slice(2));
+  if (verb === "set") validateKey(opts.positional[2]);
+  if (verb === "get" && opts.positional[2] !== undefined)
+    validateKey(opts.positional[2]);
 }
 
-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;
+function secretValue(opts, stdin, random) {
+  let value;
+  if (opts.generate !== undefined) {
+    const bytes = Number(opts.generate);
+    if (!Number.isInteger(bytes) || bytes < 1 || bytes > 1024)
+      throw new SecretError(
+        "--generate must be a whole byte count from 1 to 1024",
+      );
+    value = random(bytes).toString("base64url");
+  } else {
+    if (typeof stdin !== "function" && stdin?.isTTY)
+      throw new SecretError("set requires redirected stdin");
+    value = String(
+      typeof stdin === "function"
+        ? stdin()
+        : fs.readFileSync(stdin?.fd ?? 0, "utf8"),
+    ).replace(/\r?\n$/u, "");
+  }
+  if (!value) throw new SecretError("the value on stdin is empty");
+  return value;
 }
 
-/** `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() } = {}) {
+/** All app secrets verbs; stdin, sops, random and tool ports permit isolated custody specs. */
+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 = invocationDir(),
+    platform = process.platform,
+    tools,
+  } = {},
+) {
   const [verb, ...rest] = argv;
   try {
-    if (!VERBS.has(verb)) throw new SecretError('usage: starci app secret list | show <slug> | set <slug> | gen <slug> [--key NAME] [--env NAME] [--age RECIPIENT] [--bytes N] [--cwd DIR]');
+    if (!VERBS.has(verb))
+      throw new SecretError(
+        "usage: starci app secret init | set <env> <slug> <KEY> | get <env> <slug> [KEY] --to-file | unset <env> <slug> <KEY> | rename <env> <slug> <OLD> <NEW> | remove <env> <slug> | materialize <env> | list <env> | verify <env>",
+      );
     const opts = parse(rest);
-    const repoRoot = path.resolve(cwd, opts.cwd ?? '.');
-    const directory = secretsDirectory(repoRoot, opts.env);
-    const key = opts.key ?? DEFAULT_KEY;
-    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') 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);
+    optionsFor(verb, opts);
+    const repoRoot = path.resolve(cwd, opts.cwd ?? ".");
+    if (verb === "init")
+      return publicStorage(() =>
+        initializeSecrets(repoRoot, { env, platform, tools, stdout }),
+      );
+    const [environment, slug, key] = opts.positional;
+    const directory = secretsDirectory(repoRoot, environment);
+    if (verb === "list") return listSecrets(directory, stdout);
+    const open = () => sops ?? defaultSops(env, repoRoot, platform, tools);
+    if (EDIT_VERBS.has(verb))
+      return editSecret(verb, {
+        directory, environment, slug, names: opts.positional.slice(2),
+        execute: opts.execute === true, force: opts["force-nonempty"] === true, sops: open, stdout,
+      });
+    const seam = open();
+    if (verb === "verify")
+      return verifySecrets({ repoRoot, directory, environment, sops: seam, stdout });
+    const output = { repoRoot, environment, env, platform, stdout };
+    if (verb === "materialize")
+      return materializeSecrets(directory, seam, output);
+    const file = fileOf(directory, slug);
+    if (verb === "get") return getSecret(file, key, seam, opts, output, stderr);
+    const value = secretValue(opts, stdin, random);
+    writeSecret({ file, values: { [key]: value }, age: [], sops: seam });
+    stdout(`sealed ${environment}/${slug} (${key})\n`);
+    return 0;
   } catch (error) {
-    if (error instanceof SecretError || error instanceof SyntaxError) { stderr(`starci app secret: ${error.message}\n`); return 2; }
-    throw error;
+    const message = secretErrorMessage(error);
+    stderr(`starci app secret: ${message}\n`);
+    return 2;
   }
 }

package/runtime/scripts/hfs/slot-imports.mjs

@@ -2,9 +2,14 @@
 // owner units, the layer order and the public entry of an owner. Cycles are a graph property of the architecture check, not of one edge.
 import { RUNTIME_KIND } from './manifest-shape.mjs';
 import { classifyIn, ownerIn, tierIn } from './slot-classify.mjs';
+import { braceVariants, globExpression } from '../lib/glob.mjs';
 
 const isEntryFile = (name) => name === 'index.ts' || name === 'index.tsx';
 
+function declaredEntry(slot, relative) {
+  return (slot.entries ?? []).some(entry => braceVariants(entry).some(pattern => globExpression(pattern).test(relative)));
+}
+
 function unownedPathProblem(from, to) {
   for (const side of [from, to]) {
     if (side.status === 'no-slot') return { allowed: false, reason: 'unowned', code: side.code, path: side.path, nearest: side.nearest };
@@ -39,12 +44,22 @@ function privateEntryProblem({ repo, byId }, to, toOwner) {
   if (toOwner && repo.kind !== RUNTIME_KIND) {
     const relative = to.path === toOwner.root ? '' : to.path.slice(toOwner.root.length + 1);
     const ownerSlot = byId.get(toOwner.slot);
-    const entry = isEntryFile(relative) || (byId.get(to.slot).entries ?? []).includes(to.path.slice(to.root.length + 1)) || (ownerSlot.tier === 'package' && relative === 'src/index.ts') || (ownerSlot.tier === 'app' && relative === 'app.module.ts');
+    const entry = isEntryFile(relative) || declaredEntry(byId.get(to.slot), to.path.slice(to.root.length + 1)) || (ownerSlot.tier === 'package' && relative === 'src/index.ts') || (ownerSlot.tier === 'app' && relative === 'app.module.ts');
     if (!entry) return { allowed: false, reason: 'notPublicEntry', owner: toOwner.root, path: to.path };
   }
   return null;
 }
 
+function tierImportProblem(scope, from, to, fromTier, toTier) {
+  const { mayImport, mayImportKinds, mayImportSlots } = scope.manifest.tiers[scope.profile][fromTier] ?? {};
+  if (!mayImport?.includes(toTier)) return { allowed: false, reason: 'tierDirection', fromTier, toTier, mayImport: mayImport ?? [] };
+  const kindRestriction = mayImportKinds?.[toTier];
+  if (kindRestriction && (!kindRestriction.from.includes(from.kind) || !kindRestriction.to.includes(to.kind))) return { allowed: false, reason: 'tierDirection', fromTier, toTier, mayImport, kindRestriction, fromKind: from.kind ?? null, toKind: to.kind ?? null };
+  const slotRestriction = mayImportSlots?.[toTier];
+  if (slotRestriction && !slotRestriction.from.includes(from.slot)) return { allowed: false, reason: 'tierDirection', fromTier, toTier, mayImport, slotRestriction, fromSlot: from.slot };
+  return null;
+}
+
 /**
  * Whether `fromPath` may import `toPath`: {allowed, reason, ...}. Reasons: sameOwner, untiered, crossApp,
  * tierDirection, layerOrder, notPublicEntry, allowed, slotForbidden, slotNotEnabled, slotAmbiguous, and unowned (HFS_SLOT_UNDECLARED for the path no slot owns).
@@ -65,8 +80,8 @@ export function importAllowedIn(scope, fromPath, toPath) {
   const fromOwner = ownerIn(scope, from.path);
   const toOwner = ownerIn(scope, to.path);
   if (sameOwnerUnit(from, fromOwner) === sameOwnerUnit(to, toOwner)) return { allowed: true, reason: 'sameOwner' };
-  const { mayImport } = scope.manifest.tiers[scope.profile][fromTier] ?? {};
-  if (!mayImport?.includes(toTier)) return { allowed: false, reason: 'tierDirection', fromTier, toTier, mayImport: mayImport ?? [] };
+  const tierProblem = tierImportProblem(scope, from, to, fromTier, toTier);
+  if (tierProblem) return tierProblem;
   const layerProblem = lowerLayerProblem(scope, from, to, fromTier, toTier, fromOwner, toOwner);
   if (layerProblem) return layerProblem;
   // A runtime owner is imported file by file (crossOwner of knowledge/hfs/runtime-slots.yaml): no public entry.

package/runtime/scripts/hfs/slot-required.mjs

@@ -5,6 +5,19 @@ import { braceVariants } from '../lib/glob.mjs';
 import { classifyIn, slotEnabled } from './slot-classify.mjs';
 import { fillVars, varsOf } from './slot-match.mjs';
 
+/** A populated fe.modules instance needs its index.ts only when it contains TypeScript, including nested files. */
+export function requiredFileApplies(slotId, target, files) {
+  if (!/^fe\.modules(?:\.|$)/u.test(slotId) || path.posix.basename(target) !== 'index.ts') return true;
+  const prefix = `${path.posix.dirname(target)}/`;
+  let populated = false;
+  for (const file of files) {
+    if (!file.startsWith(prefix)) continue;
+    populated = true;
+    if (/\.tsx?$/u.test(file)) return true;
+  }
+  return !populated;
+}
+
 /** One `requires` entry of a slot placed under `root`: a leading / makes it repository-relative, the variables are filled from `bindings`. */
 function requiredEntry(entry, bindings, root) {
   const rooted = entry.startsWith('/');

package/runtime/scripts/hfs/slot-semantic-problems.mjs

@@ -2,7 +2,7 @@
 import { isPlainObject } from '../../engine/plain-object.mjs';
 import { triggerProblems } from './declaration-slots.mjs';
 import { litePresenceOf, slotInEdition } from './edition-slots.mjs';
-import { manifestKind, RUNTIME_KIND, runtimeSemanticProblems } from './manifest-shape.mjs';
+import { manifestKind, RUNTIME_KIND, runtimeSemanticProblems, tierKindProblems } from './manifest-shape.mjs';
 import { APP_SCOPE, PROFILES } from './slot-manifest-shape.mjs';
 
 function checkAppRootSlot(slot, bad) {
@@ -113,6 +113,7 @@ function checkSideReads(manifest, bad, braceVariants) {
 }
 
 function checkProfileTierTargets(manifest, profile, bad) {
+  bad.push(...tierKindProblems(manifest, profile));
   for (const [tier, def] of Object.entries(manifest.tiers[profile])) {
     for (const target of def.mayImport) {
       if (!(target in manifest.tiers[profile])) bad.push(`tiers.${profile}.${tier}.mayImport names ${target}, which is not a ${profile} tier`);

package/runtime/scripts/hfs/slots.mjs

@@ -119,6 +119,7 @@ function sideDeclaration(manifest, declaration, name, edition, providers) {
     connections: Object.freeze((s.connections ?? []).map(connectionView)),
     providers,
     reads: Object.freeze([...(s.reads ?? [])]),
+    ...(s.extraPackages === undefined ? {} : { extraPackages: Object.freeze(s.extraPackages.map(entry => Object.freeze({ ...entry }))) }),
     manifestVersion: manifest.version,
   });
 }

package/runtime/scripts/hfs/stack-config-kit.mjs

@@ -0,0 +1,34 @@
+// stack-config-kit.mjs - the small validators the deploy block (stack-deploy-config.mjs) and its ingress block (stack-ingress-config.mjs)
+// share: a problem collector, closed field lists, pattern checks and the environment-relative file check.
+import path from 'node:path';
+import { isPlainObject as plain } from '../../engine/plain-object.mjs';
+
+const BACKSLASH = String.fromCodePoint(92);
+
+/** Collects problems with the path they concern; `problem(at, message)` is the only way to add one. */
+export function collector() {
+  const problems = [];
+  return { problems, problem: (at, message) => { problems.push({ at, message }); } };
+}
+
+/** True for a mapping; reports every key outside `allowed` as "not a field of the <label> block". */
+export function closedFields(c, at, value, allowed, label = 'deploy') {
+  if (!plain(value)) { c.problem(at, 'must be a mapping'); return false; }
+  for (const key of Object.keys(value)) if (!allowed.includes(key)) c.problem(`${at}.${key}`, `is not a field of the ${label} block`);
+  return true;
+}
+
+/** True when `value` is a string matching `pattern`; otherwise reports it. */
+export function patternField(c, at, value, pattern) {
+  if (typeof value !== 'string' || !pattern.test(value)) { c.problem(at, `must match ${pattern}`); return false; }
+  return true;
+}
+
+/** A path inside .starcistacks/<env>/ : relative, forward slashes, no `..`, and present in the tree. */
+export function treeFile(c, at, value, probe) {
+  if (typeof value !== 'string' || value === '' || path.posix.isAbsolute(value) || value.includes(BACKSLASH) || path.posix.normalize(value).split('/').includes('..')) {
+    c.problem(at, 'must be a relative path inside the environment directory');
+    return;
+  }
+  if (!probe.exists(value)) c.problem(at, `${value} does not exist under the environment directory`);
+}