@starci/hfs 4.2.17 → 4.3.0

package/runtime/scripts/hfs/secret-store.mjs

@@ -0,0 +1,161 @@
+// secret-store.mjs - sealed secret paths and atomic named-value updates.
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { claimFile } from "../api/fs/claim-file.mjs";
+import { isSopsEnvelope } from "../lib/sops-envelope.mjs";
+import { byCodeUnit } from "../lib/list.mjs";
+import {
+  envelopeOf,
+  plaintextOf,
+  validateKey,
+  validateMap,
+} from "./secret-document.mjs";
+import { defaultSops } from "./secret-sops.mjs";
+import { SecretError } from "./secret-errors.mjs";
+
+const SLUG = /^[a-z0-9][a-z0-9-]*$/u;
+
+/** The directory of the sealed secrets of the app at `repoRoot` for `env`; the one env that has secrets when none is named. */
+export function secretsDirectory(repoRoot, env) {
+  const stacks = path.join(repoRoot, ".starcistacks");
+  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");
+  }
+  if (!fs.existsSync(stacks))
+    throw new SecretError(
+      "this app has no .starcistacks; run starci app secret at the app root, or pass --cwd",
+    );
+  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`,
+  );
+}
+
+export 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`);
+};
+
+/** Seal `key = value` into the secret `slug`: an existing document keeps its other keys and its recipients. */
+export function writeSecret({ file, values, age, sops }) {
+  for (const key of Object.keys(values)) validateKey(key);
+  const held = claimFile(path.resolve(file));
+  if (!held.ok)
+    throw new SecretError(
+      "the sealed secret is being updated; retry after that write settles",
+    );
+  try {
+    const format = "dotenv";
+    let map = Object.create(null);
+    let recipients = age;
+    if (fs.existsSync(file)) {
+      const text = fs.readFileSync(file, "utf8");
+      const envelope = envelopeOf(text);
+      map = sops.decrypt(file, envelope.format);
+      if (!age.length) recipients = envelope.recipients;
+    }
+    validateMap(map);
+    map = { ...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();
+  }
+}
+
+/** 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, repoRoot),
+  });
+  return { file, via: "sealed-secret" };
+}
+
+export function sealedFiles(directory) {
+  return fs.existsSync(directory)
+    ? fs
+        .readdirSync(directory)
+        .filter((name) => name.endsWith(".enc"))
+        .sort(byCodeUnit)
+    : [];
+}
+
+export function readMap(file, sops) {
+  if (!fs.existsSync(file))
+    throw new SecretError(
+      "the requested secret is not sealed in this environment",
+    );
+  const map = sops.decrypt(
+    file,
+    envelopeOf(fs.readFileSync(file, "utf8")).format,
+  );
+  validateMap(map);
+  return map;
+}

package/runtime/scripts/hfs/secret.mjs

@@ -1,220 +1,160 @@
-// 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|materialize|list: 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.
+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";
+
+export { envelopeOf, formatOf, plaintextOf } from "./secret-document.mjs";
+export { setSecretValues } from "./secret-store.mjs";
+
+const VERBS = new Set(["init", "list", "get", "set", "materialize"]);
+
+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"].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(); }
-}
-
-/** 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' };
-}
+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");
+};
 
-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 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]";
+  return "<env>";
 }
 
-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],
+    set: [3, 3],
+    get: [2, 3],
+  }[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);
+  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 | materialize <env> | list <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 seam = sops ?? defaultSops(env, repoRoot, platform, tools);
+    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

@@ -65,8 +65,10 @@ 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] ?? {};
+  const { mayImport, mayImportKinds } = 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 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/tree-findings.mjs

@@ -0,0 +1,22 @@
+import { readTree, treeFacts, untrackedEntries } from './tree.mjs';
+import { liteStarciworkTreeFindings } from './path-findings.mjs';
+
+/** The tree findings of R03: empty directories, ghost siblings, untracked entries outside an ignored slot. */
+export function treeFindings({ repoRoot, resolver, tracked = [], reportedUntracked = new Set() }) {
+  const inIgnoredSlot = (rel) => resolver.classifyPath(`${rel}/.probe`).tracking === 'ignored';
+  const findings = liteStarciworkTreeFindings(repoRoot, resolver, tracked);
+  const facts = treeFacts(readTree(repoRoot, { isIgnored: inIgnoredSlot }));
+  for (const { path: dir, below } of facts.empty) {
+    findings.push({ code: 'HFS_EMPTY_DIR', level: 'error', path: dir, below, message: `${dir} has no file below it` + (below ? ` (nor in its ${below} sub-director${below === 1 && 'y' || 'ies'})` : '') + '; git tracks no empty directory, so it is a leftover' });
+  }
+  for (const { path: dir, of, distance } of facts.ghosts) {
+    findings.push({ code: 'HFS_GHOST_TREE', level: 'error', path: dir, of, distance, message: `${dir} is empty and ${distance} edit${distance === 1 ? '' : 's'} from its sibling ${of}: a renamed or misspelt structure that was never removed` });
+  }
+  for (const entry of untrackedEntries(repoRoot)) {
+    const bare = entry.replace(/\/$/, '');
+    if (reportedUntracked.has(bare)) continue;
+    const ignored = entry.endsWith('/') ? inIgnoredSlot(bare) : resolver.classifyPath(bare).tracking === 'ignored';
+    if (!ignored) findings.push({ code: 'HFS_UNTRACKED_ROOT_ENTRY', level: 'error', path: bare, message: `${entry} is neither tracked nor git-ignored, and no ignored slot owns it` });
+  }
+  return findings;
+}