@starci/hfs 4.0.8 → 4.0.10

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

@@ -0,0 +1,220 @@
+// services.mjs - the microservice policy of a product that runs more than one service (R163 to R167).
+// A product keeps every back-end service as a Nest app at `be/apps/<service>/` of the one repository, sharing the `be/src` libraries and
+// the one package.json; the services it does not own stay pinned images in the stack. Five tree checks:
+//   R163 HFS_SERVICE_PLACEMENT      a service root (a Dockerfile, or a package.json other than the app's own and a workspace package's)
+//                                   exists only at be/apps/<service>/ (fe/apps/<app>/Dockerfile is a front end's);
+//   R164 HFS_IMAGE_UNPINNED         in a multi-service product every component image of application-stacks.yaml is a digest or an exact
+//                                   version (x.y.z), never a missing tag, `latest`, a branch word or a major/minor-only tag;
+//   R165 HFS_SERVICE_STACK_DECLARATION  each api or worker app of a multi-service product is a `role: service` component of the stack;
+//   R166 HFS_EVENT_CONTRACT         the async contract is vendored: `be/contracts/<service>/events.json` equals the provider's
+//                                   `apps/<service>/src/events.ts` table (an event may declare `compensates: "<event>"`), every event a
+//                                   consumer's `apps/<app>/src/consumes.ts` names exists in that snapshot at the same version;
+//   R167 BE_ASYNC_SPEC_MISSING      every consumed event (a consumes.ts entry) is named by an e2e spec through `useTestWorld`; the spec of a
+//                                   saga step (an event whose contract says `compensates`) also names the compensated event, so the whole
+//                                   flow is driven, not the undo alone.
+// "Multi-service" = two or more be apps of kind api or worker. A single-service product is judged by R163 and R166-R167 only.
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { findStackDeclaration } from '../../lib/stack-declaration.mjs';
+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';
+
+const SERVICE_PLACEMENT = 'HFS_SERVICE_PLACEMENT';
+const IMAGE_UNPINNED = 'HFS_IMAGE_UNPINNED';
+const SERVICE_STACK_DECLARATION = 'HFS_SERVICE_STACK_DECLARATION';
+const EVENT_CONTRACT = 'HFS_EVENT_CONTRACT';
+const ASYNC_SPEC_MISSING = 'BE_ASYNC_SPEC_MISSING';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const SERVICE_KINDS = new Set(['api', 'worker']);
+const BE_SERVICE_FILE = /^be\/apps\/([^/]+)\/(.+)$/;
+const DOCKERFILE = /(?:^|\/)Dockerfile(?:\.[^/]+)?$/;
+const WORKSPACE_PACKAGE_JSON = /^fe\/(?:packages|apps)\/[^/]+\/package\.json$/;
+const SNAPSHOT = /^be\/contracts\/([^/]+)\/events\.json$/;
+const DIGEST = /@sha256:[0-9a-f]{64}$/;
+const EXACT_TAG = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
+const EVENT_CLASS_FILE = /^be\/src\/modules\/events\/([^/]+)\/[^/]+\.event\.ts$/;
+const CONSUMER_FILE = /^be\/src\/features\/(?:[^/]+\/)+transport\/message\/[^/]+\.consumer\.ts$/;
+const E2E_SPEC = /^be\/src\/tests\/e2e\/[^/]+\/[^/]+\.e2e-spec\.ts$/;
+const USE_TEST_WORLD = /\buseTestWorld\s*\(/;
+
+/** The be apps of kind api or worker. */
+const servicesOf = (repo) => (repo.sides?.be?.apps ?? []).filter((app) => SERVICE_KINDS.has(app.kind));
+
+/** The TypeScript compiler of the app (else of the runtime), or null. */
+const typescriptFor = (repoRoot) => loadTypescript(repoRoot, HERE);
+
+// ------------------------------------------------------------------------------------------------ R163 placement
+
+/** Findings of R163: a service root outside `be/apps/<service>/`. */
+function servicePlacementFindings({ files }) {
+  const findings = [];
+  for (const file of files) {
+    if (file.startsWith('.starciwork/') || file.startsWith('.starcistacks/') || file.includes('node_modules/')) continue;
+    const dockerfile = DOCKERFILE.test(file) && !BE_SERVICE_FILE.test(file) && !/^fe\/apps\/[^/]+\/Dockerfile(?:\.[^/]+)?$/.test(file) && file !== 'Dockerfile';
+    const manifest = path.posix.basename(file) === 'package.json' && file !== 'package.json' && !WORKSPACE_PACKAGE_JSON.test(file);
+    const rootDockerfile = file === 'Dockerfile';
+    if (!dockerfile && !manifest && !rootDockerfile) continue;
+    const what = manifest ? 'a package.json of its own' : 'a Dockerfile';
+    findings.push(found(SERVICE_PLACEMENT, file, `${file} gives a folder ${what}, which makes it a service root outside be/apps/<service>/; a back-end service is a Nest app at be/apps/<service>/ (own Dockerfile there) sharing the be/src libraries and the one package.json, never a folder of its own.`));
+  }
+  return findings;
+}
+
+// ------------------------------------------------------------------------------------------------ R164 pinned images
+
+/** 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 ?? ''; });
+  return unresolved ? null : resolved;
+}
+
+/** Why an image is not pinned, or null when it is: a digest, or an exact version tag. */
+function unpinnedReason(image) {
+  const resolved = resolvedImage(image);
+  if (resolved === null) return 'its reference is an environment variable with no default';
+  if (DIGEST.test(resolved)) return null;
+  const name = resolved.slice(resolved.lastIndexOf('/') + 1);
+  const colon = name.indexOf(':');
+  if (colon < 0) return 'it has no tag';
+  const tag = name.slice(colon + 1);
+  return EXACT_TAG.test(tag) ? null : `its tag \`${tag}\` is not an exact version (x.y.z) or a digest, so it moves`;
+}
+
+/** Findings of R164 over a multi-service product's stack declaration. */
+function imagePinFindings({ repoRoot, repo }) {
+  if (servicesOf(repo).length < 2) return [];
+  const declaration = findStackDeclaration(repoRoot);
+  const components = declaration.doc?.components;
+  if (components === null || typeof components !== 'object' || components === undefined) return [];
+  const file = '.starcistacks/application-stacks.yaml';
+  const findings = [];
+  for (const [name, component] of Object.entries(components)) {
+    const image = component?.image;
+    if (typeof image !== 'string') continue;
+    const reason = unpinnedReason(image);
+    if (reason !== null) findings.push(found(IMAGE_UNPINNED, file, `${file} components.${name}.image ${image}: ${reason}. A product with more than one service pins every image: an exact version (\`<repo>/<service>:1.2.3\`, \`postgres:16.4\`) or a digest (\`@sha256:...\`).`, { component: name, image }));
+  }
+  return findings;
+}
+
+// ------------------------------------------------------------------------------------------------ R165 stack declaration
+
+/** Findings of R165: each service app of a multi-service product is a `role: service` component. */
+function serviceStackFindings({ repoRoot, repo }) {
+  const services = servicesOf(repo);
+  if (services.length < 2) return [];
+  const declaration = findStackDeclaration(repoRoot);
+  if (declaration.doc === undefined) return [];
+  const components = declaration.doc.components ?? {};
+  const file = '.starcistacks/application-stacks.yaml';
+  const findings = [];
+  for (const app of services) {
+    const component = components[app.name];
+    if (component === null || typeof component !== 'object') findings.push(found(SERVICE_STACK_DECLARATION, file, `${file} declares no component \`${app.name}\` for the ${app.kind} app be/apps/${app.name}; every service of a multi-service product is a \`role: service\` component (own image \`<repo>/${app.name}:<exact version>\`, built from be/apps/${app.name}/Dockerfile).`, { app: app.name }));
+    else if (component.role !== 'service') findings.push(found(SERVICE_STACK_DECLARATION, file, `${file} components.${app.name} is the stack's face of be/apps/${app.name} and must be \`role: service\`, not \`${String(component.role)}\`.`, { app: app.name }));
+  }
+  return findings;
+}
+
+// ------------------------------------------------------------------------------------------------ R166 event contract
+
+/** The typed event classes of every service: `[{ service, file, className, name, version, compensates, payload }]` and the problems of the ones that cannot be read. */
+function eventClassesOf({ repoRoot, files, ts }) {
+  const classes = [];
+  const problems = [];
+  for (const file of files.filter((candidate) => EVENT_CLASS_FILE.test(candidate)).sort()) {
+    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 });
+    for (const problem of read.problems) problems.push({ service, file, problem });
+  }
+  return { classes, problems };
+}
+
+/** 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));
+  const snapshots = files.filter((file) => SNAPSHOT.test(file));
+  if (classFiles.length === 0 && snapshots.length === 0) return [];
+  const ts = typescriptFor(repoRoot);
+  if (ts === null) return [];
+  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 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 }));
+  }
+  return findings;
+}
+
+// ------------------------------------------------------------------------------------------------ R167 async specs
+
+/** The class an expression names, from `readonly event = <Class>` of a consumer: the identifier, or null. */
+function consumedClassOf(ts, text) {
+  return propertyText(ts, text, { file: 'consumer.ts', key: 'event', declaration: true, kind: 'identifier' });
+}
+
+/** The events the consumers consume: `[{ file, className, service, event }]` from `readonly event = <EventClass>` of every `transport/message/*.consumer.ts`. */
+function consumedEvents({ repoRoot, files, ts }) {
+  const { classes } = eventClassesOf({ repoRoot, files, ts });
+  const consumed = [];
+  for (const file of files.filter((candidate) => CONSUMER_FILE.test(candidate))) {
+    const className = consumedClassOf(ts, readText(repoRoot, file) ?? '');
+    const event = classes.find((candidate) => candidate.className === className);
+    if (event !== undefined) consumed.push({ file, className, service: event.service, event: event.name, compensates: event.compensates });
+  }
+  return consumed;
+}
+
+/** Findings of R167: every consumed event has an e2e spec through the world; a saga step's spec also names the event it compensates. */
+function asyncSpecFindings({ repoRoot, files }) {
+  const ts = typescriptFor(repoRoot);
+  if (ts === null) return [];
+  const consumed = consumedEvents({ repoRoot, files, ts });
+  if (consumed.length === 0) return [];
+  const specs = files
+    .filter((file) => E2E_SPEC.test(file))
+    .map((file) => ({ file, text: readText(repoRoot, file) ?? '' }))
+    .filter(({ text }) => USE_TEST_WORLD.test(text));
+  const findings = [];
+  for (const { file, className, service, event, compensates } of consumed) {
+    const named = specs.filter(({ text }) => text.includes(event));
+    if (named.length === 0) {
+      findings.push(found(ASYNC_SPEC_MISSING, file, `${file}: the consumer of ${service} event "${event}" (${className}) has no e2e spec; add be/src/tests/e2e/<area>/<name>.e2e-spec.ts, which boots the apps with useTestWorld and names it: publish the event, read the persisted effect back and redeliver it.`, { service, event }));
+      continue;
+    }
+    if (typeof compensates === 'string' && !named.some(({ text }) => text.includes(compensates))) {
+      findings.push(found(ASYNC_SPEC_MISSING, named[0].file, `${named[0].file} is the spec of the saga step "${event}", which undoes "${compensates}", but never names it; the spec drives the whole flow: the step, the failure, then the compensated state.`, { service, event, compensates }));
+    }
+  }
+  return findings;
+}
+
+// ------------------------------------------------------------------------------------------------ entry
+
+/** Every finding of the microservice policy over the app at `repoRoot`; `files` are its tracked app-relative paths. */
+export function serviceFindings({ repoRoot, files, repo }) {
+  return [
+    ...servicePlacementFindings({ files }),
+    ...imagePinFindings({ repoRoot, repo }),
+    ...serviceStackFindings({ repoRoot, repo }),
+    ...eventContractFindings({ repoRoot, files }),
+    ...asyncSpecFindings({ repoRoot, files }),
+  ];
+}

package/runtime/scripts/hfs/rules/spec-placement.mjs

@@ -7,7 +7,7 @@
 // finding names the rule rather than only the missing slot. Which folder is a layer is read from the slot manifest, never spelled here.
 import { found } from './read.mjs';
 
-export const SPEC_PLACEMENT = 'BE_SPEC_PLACEMENT';
+const SPEC_PLACEMENT = 'BE_SPEC_PLACEMENT';
 const SPEC_FILE = /(?:\.(?:spec|test)|-spec)\.[cm]?[jt]sx?$/;
 const TEST_SLOT_TESTS = new Set(['unit-beside', 'e2e']);
 

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

@@ -10,9 +10,9 @@ import { braceVariants, globExpression } from '../../lib/glob.mjs';
 import { declaredStack, findStackDeclaration, STACK_ROOT, text } from '../../lib/stack-declaration.mjs';
 import { found } from './read.mjs';
 
-export const STACKS_SHAPE = 'HFS_STACKS_SHAPE';
-export const STACKS_SLOT = 'app.starcistacks';
-export const HOST_SONAR_ROOT = '.claude/ext/sonar';
+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(?:\/|$)/;

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

@@ -0,0 +1,89 @@
+// supabase-secrets.mjs - L17 extends the one R06 secret scan for edition lite. It keeps the ordinary
+// HFS_PLAINTEXT_SECRET judgement, then adds the reduced lite custody tree and provider-shaped literals
+// which are meaningful only in the Supabase/FE surface. Findings name shapes, never captured values.
+import { Buffer } from 'node:buffer';
+import { secretFindings } from './secrets.mjs';
+import { found, readText } from './read.mjs';
+
+const LITE_SECRET_CUSTODY = 'HFS_LITE_SECRET_CUSTODY';
+
+const LOCKFILE = /(^|\/)package-lock\.json$/u;
+const ROOT_ENV = /^\.env(?:\..*)?$/iu;
+const SECRETS_ENV = /^secrets\.env$/iu;
+const SECRETS_DIRECTORY = /^\.secrets(?:\/|$)/iu;
+const SEALED_HOME = /^\.starcistacks\/[^/]+\/secrets\/[^/]+\.enc$/iu;
+
+const LITE_SECRET_PATTERNS = Object.freeze([
+  { name: 'supabase-personal-access-token', re: /\bsbp_[A-Za-z0-9_-]{20,}\b/u },
+  { name: 'supabase-publishable-key', re: /\bsb_publishable_[A-Za-z0-9_-]{20,}\b/u },
+  { name: 'supabase-secret-token', re: /\bsb_secret_[A-Za-z0-9_-]{20,}\b/u },
+  { name: 'password-connection-string', re: /\b(?:postgres(?:ql)?|mysql|mariadb|mongodb(?:\+srv)?|redis):\/\/[^:\s/@]+:[^@\s/${}]{8,}@/iu },
+]);
+const JWT_CANDIDATE = /(?<![A-Za-z0-9_-])eyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}(?![A-Za-z0-9_-])/gu;
+
+const jsonObject = segment => {
+  try {
+    const value = JSON.parse(Buffer.from(segment, 'base64url').toString('utf8'));
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+  } catch {
+    return null;
+  }
+};
+
+const validJwt = candidate => {
+  const [header, payload, signature, extra] = candidate.split('.');
+  if (extra !== undefined || !signature) return false;
+  const decodedHeader = jsonObject(header);
+  const decodedPayload = jsonObject(payload);
+  return typeof decodedHeader?.alg === 'string' && decodedHeader.alg.toLowerCase() !== 'none' && decodedPayload !== null;
+};
+
+const liteSecretPatterns = line => {
+  const names = LITE_SECRET_PATTERNS.filter(pattern => pattern.re.test(line)).map(pattern => pattern.name);
+  if ([...line.matchAll(JWT_CANDIDATE)].some(match => validJwt(match[0]))) names.push('supabase-eyj-service-token');
+  return names;
+};
+
+const inSecretFreeTree = (repo, file) => repo.profile === 'fe' || file.startsWith('fe/') || file.startsWith('supabase/');
+
+/** 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 }));
+      }
+    }
+  }
+  return findings;
+}
+
+/**
+ * Drop-in extension of secretFindings for scripts/hfs/check.mjs. When an L17 finding identifies the same file/line as
+ * the generic R06 scanner (a complete JWT, for example), the specific lite code wins so one physical issue is emitted once.
+ */
+export function supabaseSecretFindings(input) {
+  const ordinary = secretFindings(input);
+  const lite = liteSecretCustodyFindings(input);
+  const liteJwtAuthority = (input.repo.edition ?? 'full') === 'lite';
+  return [...ordinary.filter(item => !(liteJwtAuthority && item.pattern === 'jwt' && inSecretFreeTree(input.repo, item.path))), ...lite];
+}

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

@@ -4,11 +4,11 @@
 //   - 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
-// (HFS_TEST_KIND_RETIRED, a sub-code of this rule); that jest.config.js is the rendered one (projects `unit`, `integration`, `e2e` and
+// (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';
 
-export const TEST_TOPOLOGY = 'BE_TEST_TOPOLOGY';
+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 ROOT_JEST_CONFIG = 'jest.config.js';

package/runtime/scripts/hfs/secret.mjs

@@ -0,0 +1,209 @@
+// 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):
+//   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 { claimManager } from '../connectors/lib.mjs';
+import { sha256 } from '../../engine/digest.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';
+
+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 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_][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_][A-Za-z0-9_]*)=/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;
+    },
+  };
+}
+
+function parse(argv) {
+  const opts = { positional: [], age: [] };
+  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}`);
+    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, processEnv = process.env }) {
+  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 });
+  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 = {};
+  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 { writingSecrets.delete(name); 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), processEnv });
+  return { file, via: 'sealed-secret' };
+}
+
+/** `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;
+  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]');
+    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') {
+      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 (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;
+  } catch (error) {
+    if (error instanceof SecretError || error instanceof SyntaxError) { stderr(`starci app secret: ${error.message}\n`); return 2; }
+    throw error;
+  }
+}