@starci/hfs 4.11.22 → 4.12.0

package/runtime/scripts/hfs/runtime-rules/source-ast.mjs

@@ -7,47 +7,51 @@
 //   exportedNames(source)         the names the module exports (export function/const/class, export {a as b}, default)
 import { createRequire } from 'node:module';
 import path from 'node:path';
-
 let typescript = null;
 /** The TypeScript compiler, loaded once from the runtime's own dependencies. */
 export const ts = () => (typescript ??= createRequire(import.meta.url)('typescript'));
-
 const FS_MODULES = new Set(['fs', 'node:fs', 'fs/promises', 'node:fs/promises']);
-
 /** `node` is a string literal naming an fs module specifier ('fs', 'node:fs', 'fs/promises', 'node:fs/promises'). */
 const fsSpecifier = (t, node) => Boolean(node && t.isStringLiteralLike(node) && FS_MODULES.has(node.text));
-
 /** `node` is a `require('fs' | 'node:fs' | 'fs/promises' | 'node:fs/promises')` call. */
 const fsRequireCall = (t, node) => node && t.isCallExpression(node) && t.isIdentifier(node.expression) && node.expression.text === 'require' && fsSpecifier(t, node.arguments[0]);
-
 function bindImport(t, node, wanted, namespaces, members) {
-  if (!t.isImportDeclaration(node) || !fsSpecifier(t, node.moduleSpecifier)) return;
-  const clause = node.importClause;
-  if (clause?.name) namespaces.add(clause.name.text);
-  const bindings = clause?.namedBindings;
-  if (bindings && t.isNamespaceImport(bindings)) namespaces.add(bindings.name.text);
-  if (bindings && t.isNamedImports(bindings)) for (const element of bindings.elements) {
-    const imported = (element.propertyName ?? element.name).text;
-    if (imported === 'promises') namespaces.add(element.name.text);
-    else if (wanted(imported)) members.set(element.name.text, imported);
-  }
+    if (!t.isImportDeclaration(node) || !fsSpecifier(t, node.moduleSpecifier))
+        return;
+    const clause = node.importClause;
+    if (clause?.name)
+        namespaces.add(clause.name.text);
+    const bindings = clause?.namedBindings;
+    if (bindings && t.isNamespaceImport(bindings))
+        namespaces.add(bindings.name.text);
+    if (bindings && t.isNamedImports(bindings))
+        for (const element of bindings.elements) {
+            const imported = (element.propertyName ?? element.name).text;
+            if (imported === 'promises')
+                namespaces.add(element.name.text);
+            else if (wanted(imported))
+                members.set(element.name.text, imported);
+        }
 }
-
 function requiredName(t, element) {
-  if (element.propertyName && t.isIdentifier(element.propertyName)) return element.propertyName.text;
-  if (t.isIdentifier(element.name)) return element.name.text;
-  return null;
+    if (element.propertyName && t.isIdentifier(element.propertyName))
+        return element.propertyName.text;
+    if (t.isIdentifier(element.name))
+        return element.name.text;
+    return null;
 }
-
 function bindRequire(t, node, wanted, namespaces, members, destructuredRequires) {
-  if (!t.isVariableDeclaration(node) || !node.initializer || !fsRequireCall(t, node.initializer)) return;
-  if (t.isIdentifier(node.name)) namespaces.add(node.name.text);
-  else if (destructuredRequires && t.isObjectBindingPattern(node.name)) for (const element of node.name.elements) {
-    const imported = requiredName(t, element);
-    if (imported && wanted(imported) && t.isIdentifier(element.name)) members.set(element.name.text, imported);
-  }
+    if (!t.isVariableDeclaration(node) || !node.initializer || !fsRequireCall(t, node.initializer))
+        return;
+    if (t.isIdentifier(node.name))
+        namespaces.add(node.name.text);
+    else if (destructuredRequires && t.isObjectBindingPattern(node.name))
+        for (const element of node.name.elements) {
+            const imported = requiredName(t, element);
+            if (imported && wanted(imported) && t.isIdentifier(element.name))
+                members.set(element.name.text, imported);
+        }
 }
-
 /**
  * The fs bindings a parsed source declares: `{ namespaces, members }`. `namespaces` holds the local names bound to
  * a whole fs module - a default or namespace import, a `promises` named import, `const fs = require('fs')`.
@@ -55,131 +59,141 @@ function bindRequire(t, node, wanted, namespaces, members, destructuredRequires)
  * `const {x} = require('fs')` destructure unless `destructuredRequires` is false.
  */
 export function fsBindings(source, wanted, { destructuredRequires = true } = {}) {
-  const t = ts();
-  const namespaces = new Set();
-  const members = new Map();
-  const bind = (node) => {
-    bindImport(t, node, wanted, namespaces, members);
-    bindRequire(t, node, wanted, namespaces, members, destructuredRequires);
-    t.forEachChild(node, bind);
-  };
-  bind(source);
-  return { namespaces, members };
+    const t = ts();
+    const namespaces = new Set();
+    const members = new Map();
+    const bind = (node) => {
+        bindImport(t, node, wanted, namespaces, members);
+        bindRequire(t, node, wanted, namespaces, members, destructuredRequires);
+        t.forEachChild(node, bind);
+    };
+    bind(source);
+    return { namespaces, members };
 }
-
 /** The fs member `callee` (a property access: `fs.X`, `fs.promises.X`) reaches through `namespaces`, or null. */
 export const fsMemberAccess = (t, callee, namespaces, wanted) => {
-  if (!t.isPropertyAccessExpression(callee) || !wanted(callee.name.text)) return null;
-  const target = callee.expression;
-  if (t.isIdentifier(target) && namespaces.has(target.text)) return callee.name.text;
-  if (t.isPropertyAccessExpression(target) && target.name.text === 'promises' && t.isIdentifier(target.expression) && namespaces.has(target.expression.text)) return callee.name.text;
-  return null;
+    if (!t.isPropertyAccessExpression(callee) || !wanted(callee.name.text))
+        return null;
+    const target = callee.expression;
+    if (t.isIdentifier(target) && namespaces.has(target.text))
+        return callee.name.text;
+    if (t.isPropertyAccessExpression(target) && target.name.text === 'promises' && t.isIdentifier(target.expression) && namespaces.has(target.expression.text))
+        return callee.name.text;
+    return null;
 };
-
 /** The SourceFile of `text`; `.ts` files parse as TypeScript, everything else as JavaScript. */
 export function parseSource(text, file = 'x.mjs') {
-  const t = ts();
-  return t.createSourceFile(file, String(text), t.ScriptTarget.Latest, true, file.endsWith('.ts') ? t.ScriptKind.TS : t.ScriptKind.JS);
+    const t = ts();
+    return t.createSourceFile(file, String(text), t.ScriptTarget.Latest, true, file.endsWith('.ts') ? t.ScriptKind.TS : t.ScriptKind.JS);
 }
-
 /** The 1-based line of `node` in `source`. */
 export const lineOf = (source, node) => source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1;
-
 /** Every module reference of a parsed file: static imports, re-exports, require('x') and import('x') with a string specifier. */
 export function moduleRefs(source) {
-  const t = ts();
-  const out = [];
-  const visit = (node) => {
-    if ((t.isImportDeclaration(node) || t.isExportDeclaration(node)) && node.moduleSpecifier && t.isStringLiteralLike(node.moduleSpecifier)) {
-      out.push({ module: node.moduleSpecifier.text, line: lineOf(source, node), column: source.getLineAndCharacterOfPosition(node.getStart(source)).character + 1 });
-    } else if (t.isCallExpression(node) && node.arguments.length && t.isStringLiteralLike(node.arguments[0])) {
-      const callee = node.expression;
-      if ((t.isIdentifier(callee) && callee.text === 'require') || callee.kind === t.SyntaxKind.ImportKeyword) {
-        out.push({ module: node.arguments[0].text, line: lineOf(source, node), column: source.getLineAndCharacterOfPosition(node.getStart(source)).character + 1 });
-      }
-    }
-    t.forEachChild(node, visit);
-  };
-  visit(source);
-  return out;
+    const t = ts();
+    const out = [];
+    const visit = (node) => {
+        if ((t.isImportDeclaration(node) || t.isExportDeclaration(node)) && node.moduleSpecifier && t.isStringLiteralLike(node.moduleSpecifier)) {
+            out.push({ module: node.moduleSpecifier.text, line: lineOf(source, node), column: source.getLineAndCharacterOfPosition(node.getStart(source)).character + 1 });
+        }
+        else if (t.isCallExpression(node) && node.arguments.length && t.isStringLiteralLike(node.arguments[0])) {
+            const callee = node.expression;
+            if ((t.isIdentifier(callee) && callee.text === 'require') || callee.kind === t.SyntaxKind.ImportKeyword) {
+                out.push({ module: node.arguments[0].text, line: lineOf(source, node), column: source.getLineAndCharacterOfPosition(node.getStart(source)).character + 1 });
+            }
+        }
+        t.forEachChild(node, visit);
+    };
+    visit(source);
+    return out;
 }
-
 /** The relative module references (`./x.mjs`, `../y.mjs`) of a parsed file. */
 const relativeImports = (source) => moduleRefs(source).filter((ref) => ref.module.startsWith('.')).map((ref) => ({ specifier: ref.module, line: ref.line, column: ref.column }));
-
 /**
  * Exact relative runtime module targets from the shared AST. Tracked targets participate in the owner graph;
  * an existing ignored generated target remains outside it. An absent target cannot silently remove an edge.
  */
 export function relativeImportTargets(ctx, file) {
-  return relativeImports(ctx.parsed(file)).map((ref) => {
-    const to = path.posix.normalize(path.posix.join(path.posix.dirname(file), ref.specifier));
-    const tracked = ctx.fileSet.has(to);
-    const missing = ctx.read(to) == null;
-    return { ...ref, to, tracked, missing };
-  });
+    return relativeImports(ctx.parsed(file)).map((ref) => {
+        const to = path.posix.normalize(path.posix.join(path.posix.dirname(file), ref.specifier));
+        const tracked = ctx.fileSet.has(to);
+        const missing = ctx.read(to) == null;
+        return { ...ref, to, tracked, missing };
+    });
 }
-
 /** Adds the names `name` binds (an identifier, or the elements of a destructuring pattern) to `names`. */
 function addBoundNames(t, name, names) {
-  if (!name) return;
-  if (t.isIdentifier(name)) names.add(name.text);
-  else if (t.isObjectBindingPattern(name) || t.isArrayBindingPattern(name)) for (const el of name.elements) if (!t.isOmittedExpression(el)) addBoundNames(t, el.name, names);
+    if (!name)
+        return;
+    if (t.isIdentifier(name))
+        names.add(name.text);
+    else if (t.isObjectBindingPattern(name) || t.isArrayBindingPattern(name))
+        for (const el of name.elements)
+            if (!t.isOmittedExpression(el))
+                addBoundNames(t, el.name, names);
 }
-
 const isNamedDeclaration = (t, node) => (t.isFunctionDeclaration(node) || t.isClassDeclaration(node) || t.isFunctionExpression(node) || t.isClassExpression(node)) && node.name;
-
 /** Adds the local name `node` binds, when it binds one, to `names`. */
 function addNodeBindings(t, node, names) {
-  if (t.isVariableDeclaration(node) || t.isParameter(node)) addBoundNames(t, node.name, names);
-  else if (isNamedDeclaration(t, node)) names.add(node.name.text);
-  else if (t.isImportClause(node) && node.name) names.add(node.name.text);
-  else if (t.isNamespaceImport(node) || t.isImportSpecifier(node)) names.add(node.name.text);
+    if (t.isVariableDeclaration(node) || t.isParameter(node))
+        addBoundNames(t, node.name, names);
+    else if (isNamedDeclaration(t, node))
+        names.add(node.name.text);
+    else if (t.isImportClause(node) && node.name)
+        names.add(node.name.text);
+    else if (t.isNamespaceImport(node) || t.isImportSpecifier(node))
+        names.add(node.name.text);
 }
-
 /** Every local name a parsed file binds: variable and parameter names (destructuring included), functions, classes, imports. */
 export function localBindings(source) {
-  const t = ts();
-  const names = new Set();
-  const visit = (node) => {
-    addNodeBindings(t, node, names);
-    t.forEachChild(node, visit);
-  };
-  visit(source);
-  return names;
+    const t = ts();
+    const names = new Set();
+    const visit = (node) => {
+        addNodeBindings(t, node, names);
+        t.forEachChild(node, visit);
+    };
+    visit(source);
+    return names;
 }
-
 function variableExports(t, node, source) {
-  const out = [];
-  for (const declaration of node.declarationList.declarations) {
-    if (!t.isIdentifier(declaration.name)) { out.push({ name: '<pattern>', fn: false, line: lineOf(source, declaration) }); continue; }
-    const initializer = declaration.initializer;
-    out.push({ name: declaration.name.text, fn: Boolean(initializer && (t.isArrowFunction(initializer) || t.isFunctionExpression(initializer))), line: lineOf(source, declaration) });
-  }
-  return out;
+    const out = [];
+    for (const declaration of node.declarationList.declarations) {
+        if (!t.isIdentifier(declaration.name)) {
+            out.push({ name: '<pattern>', fn: false, line: lineOf(source, declaration) });
+            continue;
+        }
+        const initializer = declaration.initializer;
+        out.push({ name: declaration.name.text, fn: Boolean(initializer && (t.isArrowFunction(initializer) || t.isFunctionExpression(initializer))), line: lineOf(source, declaration) });
+    }
+    return out;
 }
-
 function exportClauseNames(t, node, source) {
-  if (!node.exportClause) return [{ name: '*', fn: false, line: lineOf(source, node) }];
-  if (t.isNamedExports(node.exportClause)) return node.exportClause.elements.map((element) => ({ name: element.name.text, fn: false, line: lineOf(source, element), reexport: true }));
-  return [{ name: node.exportClause.name.text, fn: false, line: lineOf(source, node) }];
+    if (!node.exportClause)
+        return [{ name: '*', fn: false, line: lineOf(source, node) }];
+    if (t.isNamedExports(node.exportClause))
+        return node.exportClause.elements.map((element) => ({ name: element.name.text, fn: false, line: lineOf(source, element), reexport: true }));
+    return [{ name: node.exportClause.name.text, fn: false, line: lineOf(source, node) }];
 }
-
 function statementExports(t, node, source, exported, isDefault) {
-  if (t.isFunctionDeclaration(node) && exported(node)) return [{ name: isDefault(node) ? 'default' : node.name?.text ?? 'default', fn: true, line: lineOf(source, node) }];
-  if (t.isClassDeclaration(node) && exported(node)) return [{ name: isDefault(node) ? 'default' : node.name?.text ?? 'default', fn: false, line: lineOf(source, node) }];
-  if (t.isVariableStatement(node) && exported(node)) return variableExports(t, node, source);
-  if (t.isExportDeclaration(node)) return exportClauseNames(t, node, source);
-  if (t.isExportAssignment(node)) return [{ name: 'default', fn: false, line: lineOf(source, node) }];
-  return [];
+    if (t.isFunctionDeclaration(node) && exported(node))
+        return [{ name: isDefault(node) ? 'default' : node.name?.text ?? 'default', fn: true, line: lineOf(source, node) }];
+    if (t.isClassDeclaration(node) && exported(node))
+        return [{ name: isDefault(node) ? 'default' : node.name?.text ?? 'default', fn: false, line: lineOf(source, node) }];
+    if (t.isVariableStatement(node) && exported(node))
+        return variableExports(t, node, source);
+    if (t.isExportDeclaration(node))
+        return exportClauseNames(t, node, source);
+    if (t.isExportAssignment(node))
+        return [{ name: 'default', fn: false, line: lineOf(source, node) }];
+    return [];
 }
-
 /** The names a parsed module exports, each with whether it is a function (declaration or an arrow/function initializer). */
 export function exportedNames(source) {
-  const t = ts();
-  const out = [];
-  const exported = (node) => (t.canHaveModifiers?.(node) ? t.getModifiers(node) : node.modifiers)?.some((m) => m.kind === t.SyntaxKind.ExportKeyword);
-  const isDefault = (node) => (t.canHaveModifiers?.(node) ? t.getModifiers(node) : node.modifiers)?.some((m) => m.kind === t.SyntaxKind.DefaultKeyword);
-  for (const node of source.statements) out.push(...statementExports(t, node, source, exported, isDefault));
-  return out;
+    const t = ts();
+    const out = [];
+    const exported = (node) => (t.canHaveModifiers?.(node) ? t.getModifiers(node) : node.modifiers)?.some((m) => m.kind === t.SyntaxKind.ExportKeyword);
+    const isDefault = (node) => (t.canHaveModifiers?.(node) ? t.getModifiers(node) : node.modifiers)?.some((m) => m.kind === t.SyntaxKind.DefaultKeyword);
+    for (const node of source.statements)
+        out.push(...statementExports(t, node, source, exported, isDefault));
+    return out;
 }

package/runtime/scripts/hfs/runtime-rules/workflow-source.d.mts

@@ -0,0 +1,5 @@
+import type { Parsed } from '../rules/rule-types.mjs';
+/** The parsed workflow, or null when the text is not YAML (the other checks name that). */
+export declare function parseWorkflow(text: string): any;
+/** The findings of `perFile({path, text})` over every tracked workflow `ctx` holds (ctx of scripts/hfs/runtime-check.mjs). */
+export declare const workflowFindings: (ctx: Parsed, perFile: Parsed) => any[];

package/runtime/scripts/hfs/runtime-rules/workflow-source.mjs

@@ -1,19 +1,20 @@
 // workflow-source.mjs - what the workflow rules (ci-upload.mjs, git-triggers.mjs) share: which tracked files are CI workflows, and a workflow's
 // YAML document. A template's `{{placeholder}}` lines are blanked before the text is parsed.
 import { parseYaml } from '../../../engine/yaml.mjs';
-
 const WORKFLOW = /(?:^|\/)\.?(?:github\/)?workflows\/[^/]+\.ya?ml$/;
-
 /** The tracked workflow files of the runtime, its examples and the hfs templates. */
 const workflowFiles = (files) => files.filter((file) => WORKFLOW.test(file));
-
 /** The parsed workflow, or null when the text is not YAML (the other checks name that). */
 export function parseWorkflow(text) {
-  try { return parseYaml(text.replace(/^\{\{\w+\}\}\s*$/gm, '').replace(/\{\{\w+\}\}/g, 'x')); } catch { return null; }
+    try {
+        return parseYaml(text.replace(/^\{\{\w+\}\}\s*$/gm, '').replace(/\{\{\w+\}\}/g, 'x'));
+    }
+    catch {
+        return null;
+    }
 }
-
 /** The findings of `perFile({path, text})` over every tracked workflow `ctx` holds (ctx of scripts/hfs/runtime-check.mjs). */
 export const workflowFindings = (ctx, perFile) => workflowFiles(ctx.files).flatMap((file) => {
-  const text = ctx.read(file);
-  return text === null || text === undefined ? [] : perFile({ path: file, text });
+    const text = ctx.read(file);
+    return text === null || text === undefined ? [] : perFile({ path: file, text });
 });

package/runtime/scripts/hfs/sealed-members.d.mts

@@ -0,0 +1,22 @@
+import type { SecretSops } from './secret-sops.mjs';
+/** A sealed member a declaration names: the environment, the file slug and the environment keys it holds. */
+export interface SealedMember {
+    env: string;
+    slug: string;
+    keys: string[];
+}
+/** Resolve public member/key names without opening any existing envelope or private identity. */
+export declare function declaredSealedMembers(repoRoot: string): SealedMember[];
+/** How the missing members are sealed: the app public age recipient(s), the sops adapter (absent: the sops-free bootstrap sealer) and the selector of members. */
+export interface PlaceholderOptions {
+    recipient?: string | undefined;
+    recipientsForFile?: ((file: string) => string[]) | undefined;
+    processEnv?: NodeJS.ProcessEnv | undefined;
+    sops?: Pick<SecretSops, 'seal'> | undefined;
+    write?: ((file: string, sealed: string) => void) | undefined;
+    only?: ((member: SealedMember) => boolean) | undefined;
+}
+/** Create missing members (those `only` selects) for this app's recipient, preserving owner-provisioned members. */
+export declare function materializeDeclaredPlaceholders(repoRoot: string, { recipient, recipientsForFile, processEnv, sops, write, only }?: PlaceholderOptions): {
+    members: string[];
+};

package/runtime/scripts/hfs/sealed-members.mjs

@@ -7,99 +7,103 @@ import { byCodeUnit } from '../lib/list.mjs';
 import { setSecretValues } from './secret-store.mjs';
 import { memberFile } from '../lib/sealed-member.mjs';
 import { sealBootstrapValues } from './secret-bootstrap-crypto.mjs';
-
 const ENVIRONMENT = /^[a-z0-9][a-z0-9-]*$/u;
 const MEMBER = /^secrets\/([a-z0-9][a-z0-9-]*)(?:\.enc(?:\.yaml)?)?$/u;
 const KEY = /^[A-Z][A-Z0-9_]*$/u;
-
 function readDocument(file, format) {
-  if (!fs.existsSync(file)) return {};
-  const text = fs.readFileSync(file, 'utf8');
-  return format === 'json' ? JSON.parse(text) : parseYaml(text);
+    if (!fs.existsSync(file))
+        return {};
+    const text = fs.readFileSync(file, 'utf8');
+    return format === 'json' ? JSON.parse(text) : parseYaml(text);
 }
-
 function memberOf(environment, declaration) {
-  const entry = typeof declaration === 'string' ? { where: declaration } : declaration;
-  const location = entry?.where ?? (entry?.name && `secrets/${entry.name}`);
-  const match = MEMBER.exec(location ?? '');
-  if (!ENVIRONMENT.test(environment) || !match)
-    throw new Error('sealed member declarations must use .starcistacks/<environment>/secrets/<slug>');
-  return { env: environment, slug: match[1], keys: entry.keys };
+    const entry = typeof declaration === 'string' ? { where: declaration } : declaration;
+    const location = entry?.where ?? (entry?.name && `secrets/${entry.name}`);
+    const match = MEMBER.exec(location ?? '');
+    if (!ENVIRONMENT.test(environment) || !match)
+        throw new Error('sealed member declarations must use .starcistacks/<environment>/secrets/<slug>');
+    return { env: environment, slug: match[1], keys: entry.keys };
 }
-
 function rosterKeys(repoRoot, member) {
-  const file = path.join(repoRoot, '.starcistacks', member.env, 'runtime', 'env', 'KEYS.md');
-  if (!fs.existsSync(file)) return [];
-  const keys = [];
-  for (const line of fs.readFileSync(file, 'utf8').split(/\r?\n/u)) {
-    const key = /^\|\s*`([A-Z][A-Z0-9_]*)`\s*\|/u.exec(line)?.[1];
-    if (!key) continue;
-    const locations = [...line.matchAll(/(?:secrets\/|\/run\/secrets\/)([a-z0-9][a-z0-9-]*)(?:\.enc(?:\.yaml)?)?/gu)];
-    if (locations.some((match) => match[1] === member.slug)) keys.push(key);
-  }
-  return keys;
+    const file = path.join(repoRoot, '.starcistacks', member.env, 'runtime', 'env', 'KEYS.md');
+    if (!fs.existsSync(file))
+        return [];
+    const keys = [];
+    for (const line of fs.readFileSync(file, 'utf8').split(/\r?\n/u)) {
+        const key = /^|s*`|\s*`([A-Z][A-Z0-9_]*)`\s*\|/u.exec(line)?.[1];
+        if (!key)
+            continue;
+        const locations = [...line.matchAll(/(?:secrets\/|\/run\/secrets\/)([a-z0-9][a-z0-9-]*)(?:\.enc(?:\.yaml)?)?/gu)];
+        if (locations.some((match) => match[1] === member.slug))
+            keys.push(key);
+    }
+    return keys;
 }
-
 function keysOf(repoRoot, member) {
-  const declared = Array.isArray(member.keys) ? member.keys : rosterKeys(repoRoot, member);
-  const keys = declared.length ? declared : [member.slug.replaceAll('-', '_').toUpperCase()];
-  if (keys.some((key) => !KEY.test(key))) throw new Error('sealed member keys must be environment key names');
-  return [...new Set(keys)].sort(byCodeUnit);
+    const declared = Array.isArray(member.keys) ? member.keys : rosterKeys(repoRoot, member);
+    const keys = declared.length ? declared : [member.slug.replaceAll('-', '_').toUpperCase()];
+    if (keys.some((key) => !KEY.test(key)))
+        throw new Error('sealed member keys must be environment key names');
+    return [...new Set(keys)].sort(byCodeUnit);
 }
-
 function descriptorMembers(repoRoot) {
-  const stacks = path.join(repoRoot, '.starcistacks');
-  if (!fs.existsSync(stacks)) return [];
-  const members = [];
-  for (const entry of fs.readdirSync(stacks, { withFileTypes: true })) {
-    if (!entry.isDirectory() || !ENVIRONMENT.test(entry.name)) continue;
-    const descriptor = readDocument(path.join(stacks, entry.name, 'environment.json'), 'json');
-    for (const declaration of descriptor.secrets ?? []) members.push(memberOf(entry.name, declaration));
-  }
-  return members;
+    const stacks = path.join(repoRoot, '.starcistacks');
+    const members = [];
+    if (!fs.existsSync(stacks))
+        return [];
+    for (const entry of fs.readdirSync(stacks, { withFileTypes: true })) {
+        if (!entry.isDirectory() || !ENVIRONMENT.test(entry.name))
+            continue;
+        const descriptor = readDocument(path.join(stacks, entry.name, 'environment.json'), 'json');
+        for (const declaration of descriptor.secrets ?? [])
+            members.push(memberOf(entry.name, declaration));
+    }
+    return members;
 }
-
 /** Resolve public member/key names without opening any existing envelope or private identity. */
 export function declaredSealedMembers(repoRoot) {
-  const manifest = readDocument(path.join(repoRoot, '.starcistacks', 'application-stacks.yaml'), 'yaml');
-  const declarations = descriptorMembers(repoRoot);
-  for (const [environment, model] of Object.entries(manifest?.environments ?? {})) {
-    for (const declaration of model?.secrets ?? []) declarations.push(memberOf(environment, declaration));
-  }
-  const members = new Map();
-  for (const member of declarations) {
-    const id = `${member.env}/${member.slug}`;
-    members.set(id, { ...member, keys: keysOf(repoRoot, member) });
-  }
-  return [...members.values()].sort((left, right) => `${left.env}/${left.slug}`.localeCompare(`${right.env}/${right.slug}`));
+    const manifest = readDocument(path.join(repoRoot, '.starcistacks', 'application-stacks.yaml'), 'yaml');
+    const declarations = descriptorMembers(repoRoot);
+    for (const [environment, model] of Object.entries(manifest?.environments ?? {})) {
+        for (const declaration of model?.secrets ?? [])
+            declarations.push(memberOf(environment, declaration));
+    }
+    const members = new Map();
+    for (const member of declarations) {
+        const id = `${member.env}/${member.slug}`;
+        members.set(id, { ...member, keys: keysOf(repoRoot, member) });
+    }
+    return [...members.values()].sort((left, right) => `${left.env}/${left.slug}`.localeCompare(`${right.env}/${right.slug}`));
 }
-
 function placeholderValue(key) {
-  const generated = randomUUID();
-  if (key.endsWith('_URL') && key.slice(0, -4).endsWith('DB')) return `postgresql://app_be:${generated}@db.invalid:5432/app`;
-  if (key.endsWith('_URL')) return `https://example.invalid/${generated}`;
-  return generated;
+    const generated = randomUUID();
+    if (key.endsWith('_URL') && key.slice(0, -4).endsWith('DB'))
+        return `postgresql://app_be:${generated}@db.invalid:5432/app`;
+    if (key.endsWith('_URL'))
+        return `https://example.invalid/${generated}`;
+    return generated;
 }
-
 /** Create missing members (those `only` selects) for this app's recipient, preserving owner-provisioned members. */
 export function materializeDeclaredPlaceholders(repoRoot, { recipient, recipientsForFile, processEnv = process.env, sops, write, only = () => true } = {}) {
-  const members = [];
-  for (const member of declaredSealedMembers(repoRoot).filter((declared) => only(declared))) {
-    const directory = path.join(repoRoot, '.starcistacks', member.env, 'secrets');
-    if (fs.existsSync(memberFile(directory, member.slug))) continue;
-    // The sops-free bootstrap sealer writes dotenv only, so its placeholder is a legacy `.enc` until `migrate` moves it.
-    const file = sops ? memberFile(directory, member.slug) : path.join(directory, `${member.slug}.enc`);
-    const relative = path.relative(repoRoot, file).split(path.sep).join('/');
-    const age = recipientsForFile?.(file) ?? [recipient];
-    if (!age.length || age.some((value) => !/^age1[a-z0-9]+$/u.test(value ?? '')))
-      throw new Error('sealed placeholders require the app public age recipient');
-    if (!sops && age.length !== 1) throw new Error('multiple recipients require the standard SOPS adapter');
-    const values = Object.fromEntries(member.keys.map((key) => [key, placeholderValue(key)]));
-    const adapter = sops ?? { seal: () => sealBootstrapValues({ values, recipient: age[0] }) };
-    setSecretValues(repoRoot, { slug: member.slug, values, env: member.env }, {
-      age, processEnv, sops: adapter, write, legacy: !sops,
-    });
-    members.push(relative);
-  }
-  return { members };
+    const members = [];
+    for (const member of declaredSealedMembers(repoRoot).filter((declared) => only(declared))) {
+        const directory = path.join(repoRoot, '.starcistacks', member.env, 'secrets');
+        if (fs.existsSync(memberFile(directory, member.slug)))
+            continue;
+        // The sops-free bootstrap sealer writes dotenv only, so its placeholder is a legacy `.enc` until `migrate` moves it.
+        const file = sops ? memberFile(directory, member.slug) : path.join(directory, `${member.slug}.enc`);
+        const relative = path.relative(repoRoot, file).split(path.sep).join('/');
+        const age = (recipientsForFile?.(file) ?? [recipient]);
+        if (!age.length || age.some((value) => !/^age1[a-z0-9]+$/u.test(value ?? '')))
+            throw new Error('sealed placeholders require the app public age recipient');
+        if (!sops && age.length !== 1)
+            throw new Error('multiple recipients require the standard SOPS adapter');
+        const values = Object.fromEntries(member.keys.map((key) => [key, placeholderValue(key)]));
+        const adapter = (sops ?? { seal: () => sealBootstrapValues({ values, recipient: age[0] }) });
+        setSecretValues(repoRoot, { slug: member.slug, values, env: member.env }, {
+            age, processEnv, sops: adapter, write, legacy: !sops,
+        });
+        members.push(relative);
+    }
+    return { members };
 }

package/runtime/scripts/hfs/secret-bootstrap-crypto.d.mts

@@ -0,0 +1,12 @@
+/** A fresh app identity: the secret identity bytes and its public age recipient. */
+export interface AppIdentity {
+    identity: Buffer;
+    recipient: string;
+}
+/** Return a fresh app identity in memory. The caller owns custody and zeroing. */
+export declare function generateAppIdentity(): AppIdentity;
+/** Encrypt bootstrap values to the app's public key; no private key is needed. */
+export declare function sealBootstrapValues({ values, recipient, }: {
+    values: unknown;
+    recipient: string;
+}): string;