@starci/hfs 4.3.0 → 4.4.0

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

@@ -53,69 +53,70 @@ export const fileOf = (directory, slug) => {
   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",
-    );
+/** Build and validate a replacement envelope without publishing it. */
+function sealSecretMap({ file, values, age, sops }) {
+  let map = Object.create(null);
+  let recipients = age;
+  if (fs.existsSync(file)) {
+    const envelope = envelopeOf(fs.readFileSync(file, "utf8"));
+    map = sops.decrypt(file, envelope.format);
+    if (!age.length) recipients = envelope.recipients;
+  }
+  validateMap(map);
+  map = { ...map, ...values };
+  const sealed = sops.seal({ inputType: "dotenv", plaintext: plaintextOf("dotenv", 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");
+  return sealed;
+}
+
+/** Publish through an explicit file owner, or the canonical atomic replace. */
+function publishSealed(file, sealed, write) {
+  if (write) { write(file, sealed); return; }
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = path.join(path.dirname(file), "." + path.basename(file) + "-" + randomUUID() + ".tmp");
   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);
-    }
+    fs.writeFileSync(temporary, sealed, { flag: "wx", mode: 0o600, flush: true });
+    fs.renameSync(temporary, file);
   } finally {
-    held.release();
+    if (fs.existsSync(temporary)) fs.unlinkSync(temporary);
   }
 }
 
+function underClaim(file, action) {
+  const held = claimFile(path.resolve(file));
+  if (!held.ok)
+    throw new SecretError("the sealed secret is being updated; retry after that write settles");
+  try {
+    action();
+  } finally { held.release(); }
+}
+
+/** Replace one existing sealed member with an already validated envelope: same claim and atomic publish as set. */
+export const replaceSealed = (file, sealed) => underClaim(file, () => publishSealed(file, sealed));
+
+/** Delete one sealed member under the writer claim. */
+export const deleteSealed = (file) => underClaim(file, () => fs.unlinkSync(file));
+
+/** Seal named values; a supplied writer owns its own claim and rollback (the fresh-app scaffold). */
+export function writeSecret({ file, values, age, sops, write }) {
+  for (const key of Object.keys(values)) validateKey(key);
+  const held = write ? { ok: true, release() {} } : claimFile(path.resolve(file));
+  if (!held.ok)
+    throw new SecretError("the sealed secret is being updated; retry after that write settles");
+  try {
+    publishSealed(file, sealSecretMap({ file, values, age, sops }), write);
+  } 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 } = {},
+  { sops = null, age = [], processEnv = process.env, write } = {},
 ) {
   const directory = secretsDirectory(repoRoot, env);
   const file = fileOf(directory, slug);
@@ -134,6 +135,7 @@ export function setSecretValues(
     values,
     age,
     sops: sops ?? defaultSops(processEnv, repoRoot),
+    write,
   });
   return { file, via: "sealed-secret" };
 }

package/runtime/scripts/hfs/secret.mjs

@@ -1,6 +1,8 @@
-// secret.mjs - app secret init|set|get|materialize|list: sealed custody and private KEY files.
+// secret.mjs - app secret init|set|get|unset|rename|remove|materialize|list|verify: sealed custody and private KEY files.
 // SOPS plaintext travels on stdin and stays in memory; normal CLI output contains names and local file paths only.
 // Every verb runs at the app root or --cwd. Exit 0 done, 2 refusal; --reveal is the only plaintext stdout path.
+// unset, rename and remove edit one sealed member and are dry runs until --execute (scripts/hfs/secret-edit.mjs).
+// verify decrypts each member in memory and names only keys and violated shapes, never a value (R249).
 import fs from "node:fs";
 import path from "node:path";
 import { randomBytes } from "node:crypto";
@@ -11,11 +13,14 @@ import { defaultSops } from "./secret-sops.mjs";
 import { fileOf, secretsDirectory, writeSecret } from "./secret-store.mjs";
 import { getSecret, listSecrets, materializeSecrets } from "./secret-output.mjs";
 import { SecretError, publicStorage, secretErrorMessage } from "./secret-errors.mjs";
+import { editSecret, validateEditNames } from "./secret-edit.mjs";
+import { verifySecrets } from "./rules/env-value-shape.mjs";
 
 export { envelopeOf, formatOf, plaintextOf } from "./secret-document.mjs";
 export { setSecretValues } from "./secret-store.mjs";
 
-const VERBS = new Set(["init", "list", "get", "set", "materialize"]);
+const VERBS = new Set(["init", "list", "get", "set", "unset", "rename", "remove", "materialize", "verify"]);
+const EDIT_VERBS = new Set(["unset", "rename", "remove"]);
 
 function valueOption(opts, flag, value) {
   if (value === undefined || value.startsWith("--"))
@@ -32,7 +37,7 @@ function parse(argv) {
     const [flag, inline] = arg.split(/=(.*)/su);
     if (["--cwd", "--generate"].includes(flag)) {
       valueOption(opts, flag, inline ?? argv[++i]);
-    } else if (["--to-file", "--reveal"].includes(flag)) {
+    } else if (["--to-file", "--reveal", "--execute", "--force-nonempty"].includes(flag)) {
       if (inline !== undefined && !["true", "false"].includes(inline))
         throw new SecretError(`${flag} expects true or false`);
       opts[flag.slice(2)] = inline !== "false";
@@ -55,9 +60,19 @@ function usageArguments(verb) {
   if (verb === "init") return "";
   if (verb === "set") return "<env> <slug> <KEY> [--generate <bytes>]";
   if (verb === "get") return "<env> <slug> [KEY] --to-file [--reveal]";
+  if (verb === "unset") return "<env> <slug> <KEY> [--execute]";
+  if (verb === "rename") return "<env> <slug> <OLD> <NEW> [--execute]";
+  if (verb === "remove") return "<env> <slug> [--execute] [--force-nonempty]";
   return "<env>";
 }
 
+function editOptionsFor(verb, opts) {
+  if (opts.execute !== undefined && !EDIT_VERBS.has(verb))
+    throw new SecretError("--execute is only valid for unset, rename and remove");
+  if (opts["force-nonempty"] !== undefined && verb !== "remove")
+    throw new SecretError("--force-nonempty is only valid for remove");
+}
+
 function outputOptionsFor(verb, opts) {
   if (
     (opts["to-file"] !== undefined || opts.reveal !== undefined) &&
@@ -74,8 +89,12 @@ function optionsFor(verb, opts) {
     init: [0, 0],
     list: [1, 1],
     materialize: [1, 1],
+    verify: [1, 1],
     set: [3, 3],
     get: [2, 3],
+    unset: [3, 3],
+    rename: [4, 4],
+    remove: [2, 2],
   }[verb];
   if (count < bounds[0] || count > bounds[1])
     throw new SecretError(
@@ -84,6 +103,8 @@ function optionsFor(verb, opts) {
   if (opts.generate !== undefined && verb !== "set")
     throw new SecretError("--generate is only valid for set");
   outputOptionsFor(verb, opts);
+  editOptionsFor(verb, opts);
+  if (EDIT_VERBS.has(verb)) validateEditNames(verb, opts.positional.slice(2));
   if (verb === "set") validateKey(opts.positional[2]);
   if (verb === "get" && opts.positional[2] !== undefined)
     validateKey(opts.positional[2]);
@@ -130,7 +151,7 @@ export function secretMain(
   try {
     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>",
+        "usage: starci app secret init | set <env> <slug> <KEY> | get <env> <slug> [KEY] --to-file | unset <env> <slug> <KEY> | rename <env> <slug> <OLD> <NEW> | remove <env> <slug> | materialize <env> | list <env> | verify <env>",
       );
     const opts = parse(rest);
     optionsFor(verb, opts);
@@ -142,7 +163,15 @@ export function secretMain(
     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 open = () => sops ?? defaultSops(env, repoRoot, platform, tools);
+    if (EDIT_VERBS.has(verb))
+      return editSecret(verb, {
+        directory, environment, slug, names: opts.positional.slice(2),
+        execute: opts.execute === true, force: opts["force-nonempty"] === true, sops: open, stdout,
+      });
+    const seam = open();
+    if (verb === "verify")
+      return verifySecrets({ repoRoot, directory, environment, sops: seam, stdout });
     const output = { repoRoot, environment, env, platform, stdout };
     if (verb === "materialize")
       return materializeSecrets(directory, seam, output);

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

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

package/runtime/scripts/hfs/slots.mjs

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

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

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

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

@@ -0,0 +1,313 @@
+// stack-deploy-config.mjs - the ONE reader of `environments.<env>.deploy` in .starcistacks/application-stacks.yaml (R294).
+// `starci app stack ...` (packages/hfs/stack) normalises the block through it and `starci app check` (rules/stacks-deploy.mjs)
+// judges the same block through it, so the verbs and the rule can never disagree. Pure given the block and a probe of the app tree.
+import { isPlainObject as plain } from '../../engine/plain-object.mjs';
+import { closedFields, collector, patternField, treeFile } from './stack-config-kit.mjs';
+import { list } from '../lib/list.mjs';
+import { normalizeIngress } from './stack-ingress-config.mjs';
+
+export const DEPLOY_CONFIG_CODE = 'STACKS_DEPLOY_CONFIG_INVALID';
+
+export const NAME = /^[a-z][a-z0-9-]*$/u;
+export const KEY = /^[A-Z][A-Z0-9_]*$/u;
+const VOLUME = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/u;
+const HOST_ALIAS = /^[A-Za-z0-9][A-Za-z0-9._-]*$/u;
+const REMOTE_BASE = /^\/[A-Za-z0-9._/-]+$/u;
+const HTTP_URL = /^https?:\/\/[^\s]+$/u;
+const PINNED_HELPER_IMAGE = /^[a-z0-9./_-]+(?::[A-Za-z0-9._-]+)?@sha256:(?!0{64}$)[0-9a-f]{64}$/u;
+const ARGUMENT = /^[A-Za-z0-9_@%+=:,./-]+$/u;
+const UPPER_ENV = KEY;
+
+const FIELDS = {
+  deploy: ['stack', 'remote', 'images', 'volumes', 'secrets', 'environment', 'configs', 'passEnv', 'verify', 'jobs', 'tasks', 'backup', 'ingress', 'registry'],
+  remote: ['host', 'releasesBase', 'sealed'],
+  sealed: ['ops', 'sshKey', 'knownHosts'],
+  image: ['app', 'buildArgs'],
+  buildArgs: ['values', 'sealed'],
+  secrets: ['grants', 'settings'],
+  grant: ['service', 'filePointers', 'from'],
+  source: ['member', 'keys', 'required', 'fill'],
+  settings: ['member', 'keys'],
+  environment: ['files', 'values', 'settings'],
+  setting: ['key', 'default'],
+  config: ['name', 'file', 'env'],
+  verify: ['http', 'exec'],
+  http: ['name', 'url', 'method', 'body', 'status', 'json', 'contains', 'retry'],
+  exec: ['name', 'service', 'command', 'stdout'],
+  jobs: ['service', 'command'],
+  task: ['service', 'command'],
+  backup: ['image', 'keepDays', 'dir', 'volumes'],
+  backupVolume: ['name', 'volume'],
+  registry: ['host', 'visibility'],
+};
+
+const text = (value) => typeof value === 'string' && value.length > 0;
+
+const nameField = (c, at, value, pattern = NAME) => patternField(c, at, value, pattern);
+
+function stringList(c, at, value, itemPattern, { nonEmpty = false } = {}) {
+  if (!Array.isArray(value) || (nonEmpty && value.length === 0)) { c.problem(at, 'must be a list'); return []; }
+  value.forEach((item, index) => { if (typeof item !== 'string' || !itemPattern.test(item)) c.problem(`${at}[${index}]`, `must match ${itemPattern}`); });
+  return value;
+}
+
+function remote(c, block) {
+  if (block === undefined) return { host: 'vps', releasesBase: null, sealed: null };
+  if (!closedFields(c, 'deploy.remote', block, FIELDS.remote)) return { host: 'vps', releasesBase: null, sealed: null };
+  if (block.host !== undefined) nameField(c, 'deploy.remote.host', block.host, HOST_ALIAS);
+  if (block.releasesBase !== undefined && (!REMOTE_BASE.test(String(block.releasesBase)) || String(block.releasesBase).includes('..')))
+    c.problem('deploy.remote.releasesBase', 'must be an absolute path without ..');
+  let sealed = null;
+  if (block.sealed !== undefined && closedFields(c, 'deploy.remote.sealed', block.sealed, FIELDS.sealed)) {
+    for (const key of FIELDS.sealed) nameField(c, `deploy.remote.sealed.${key}`, block.sealed[key]);
+    sealed = { ...block.sealed };
+  }
+  return { host: block.host ?? 'vps', releasesBase: block.releasesBase ?? null, sealed };
+}
+
+function imageBuildArgs(c, at, block, members) {
+  const out = { values: {}, sealed: null };
+  if (block === undefined) return out;
+  if (!closedFields(c, at, block, FIELDS.buildArgs)) return out;
+  for (const [key, value] of Object.entries(block.values ?? {})) {
+    if (!KEY.test(key) || typeof value !== 'string') c.problem(`${at}.values.${key}`, 'must be KEY: "string"');
+    else out.values[key] = value;
+  }
+  if (block.sealed !== undefined && closedFields(c, `${at}.sealed`, block.sealed, FIELDS.settings)) {
+    memberRef(c, `${at}.sealed.member`, block.sealed.member, members);
+    out.sealed = { member: block.sealed.member, keys: stringList(c, `${at}.sealed.keys`, block.sealed.keys, KEY, { nonEmpty: true }) };
+  }
+  return out;
+}
+
+function memberRef(c, at, member, members) {
+  if (!nameField(c, at, member)) return;
+  if (members.size > 0 && !members.has(member)) c.problem(at, `sealed member ${member} has no .starcistacks/<env>/secrets/${member}.enc`);
+}
+
+function images(c, block, services, members) {
+  const out = {};
+  if (block === undefined) return out;
+  if (!plain(block)) { c.problem('deploy.images', 'must be a mapping of service to image'); return out; }
+  for (const [service, entry] of Object.entries(block)) {
+    const at = `deploy.images.${service}`;
+    nameField(c, at, service);
+    if (services.size > 0 && !services.has(service)) c.problem(at, `${service} is not a service of the stack source`);
+    if (!closedFields(c, at, entry, FIELDS.image)) continue;
+    nameField(c, `${at}.app`, entry.app);
+    out[service] = { app: entry.app, buildArgs: imageBuildArgs(c, `${at}.buildArgs`, entry.buildArgs, members) };
+  }
+  return out;
+}
+
+function sourceEntry(c, at, entry, members) {
+  if (!closedFields(c, at, entry, FIELDS.source)) return null;
+  memberRef(c, `${at}.member`, entry.member, members);
+  const keys = entry.keys === undefined ? null : stringList(c, `${at}.keys`, entry.keys, KEY, { nonEmpty: true });
+  for (const flag of ['required', 'fill']) if (entry[flag] !== undefined && typeof entry[flag] !== 'boolean') c.problem(`${at}.${flag}`, 'must be true or false');
+  if (entry.required === true && keys === null) c.problem(`${at}.required`, 'needs an explicit keys list');
+  return { member: entry.member, keys, required: entry.required === true, fill: entry.fill === true };
+}
+
+function grants(c, block, services, members) {
+  const out = [];
+  list(block).forEach((grant, index) => {
+    const at = `deploy.secrets.grants[${index}]`;
+    if (!closedFields(c, at, grant, FIELDS.grant)) return;
+    nameField(c, `${at}.service`, grant.service);
+    if (services.size > 0 && !services.has(grant.service)) c.problem(`${at}.service`, `${grant.service} is not a service of the stack source`);
+    if (grant.filePointers !== undefined && typeof grant.filePointers !== 'boolean') c.problem(`${at}.filePointers`, 'must be true or false');
+    if (!Array.isArray(grant.from) || grant.from.length === 0) { c.problem(`${at}.from`, 'must list at least one sealed source'); return; }
+    const from = grant.from.map((entry, at2) => sourceEntry(c, `${at}.from[${at2}]`, entry, members)).filter(Boolean);
+    out.push({ service: grant.service, filePointers: grant.filePointers === true, from });
+  });
+  return out;
+}
+
+function secretSettings(c, block, members) {
+  if (block === undefined) return null;
+  if (!closedFields(c, 'deploy.secrets.settings', block, FIELDS.settings)) return null;
+  memberRef(c, 'deploy.secrets.settings.member', block.member, members);
+  return { member: block.member, keys: stringList(c, 'deploy.secrets.settings.keys', block.keys, KEY, { nonEmpty: true }) };
+}
+
+function secrets(c, block, services, members) {
+  if (block === undefined) return { grants: [], settings: null };
+  if (!closedFields(c, 'deploy.secrets', block, FIELDS.secrets)) return { grants: [], settings: null };
+  if (block.grants !== undefined && !Array.isArray(block.grants)) c.problem('deploy.secrets.grants', 'must be a list');
+  return { grants: grants(c, block.grants, services, members), settings: secretSettings(c, block.settings, members) };
+}
+
+function serviceEnvironment(c, at, entry, probe) {
+  const out = { files: [], values: {}, settings: {} };
+  if (!closedFields(c, at, entry, FIELDS.environment)) return out;
+  list(entry.files).forEach((file, index) => { treeFile(c, `${at}.files[${index}]`, file, probe); out.files.push(file); });
+  for (const [key, value] of Object.entries(entry.values ?? {})) {
+    if (!UPPER_ENV.test(key) || typeof value !== 'string') c.problem(`${at}.values.${key}`, 'must be KEY: "string"');
+    else out.values[key] = value;
+  }
+  for (const [key, setting] of Object.entries(entry.settings ?? {})) {
+    if (!UPPER_ENV.test(key)) { c.problem(`${at}.settings.${key}`, `the environment name must match ${UPPER_ENV}`); continue; }
+    if (!closedFields(c, `${at}.settings.${key}`, setting, FIELDS.setting) || !nameField(c, `${at}.settings.${key}.key`, setting.key, KEY)) continue;
+    out.settings[key] = { key: setting.key, default: setting.default === undefined ? null : String(setting.default) };
+  }
+  return out;
+}
+
+function environmentBlock(c, block, services, probe) {
+  const out = {};
+  if (block === undefined) return out;
+  if (!plain(block)) { c.problem('deploy.environment', 'must be a mapping of service to environment'); return out; }
+  for (const [service, entry] of Object.entries(block)) {
+    if (services.size > 0 && !services.has(service)) c.problem(`deploy.environment.${service}`, `${service} is not a service of the stack source`);
+    out[service] = serviceEnvironment(c, `deploy.environment.${service}`, entry, probe);
+  }
+  return out;
+}
+
+function configs(c, block, probe) {
+  const out = [];
+  list(block).forEach((entry, index) => {
+    const at = `deploy.configs[${index}]`;
+    if (!closedFields(c, at, entry, FIELDS.config)) return;
+    nameField(c, `${at}.name`, entry.name);
+    nameField(c, `${at}.env`, entry.env, KEY);
+    treeFile(c, `${at}.file`, entry.file, probe);
+    out.push({ name: entry.name, file: entry.file, env: entry.env });
+  });
+  const seen = new Set();
+  for (const entry of out) { if (seen.has(entry.name)) c.problem('deploy.configs', `config name ${entry.name} is declared twice`); seen.add(entry.name); }
+  return out;
+}
+
+function httpChecks(c, block) {
+  return list(block).flatMap((entry, index) => {
+    const at = `deploy.verify.http[${index}]`;
+    if (!closedFields(c, at, entry, FIELDS.http)) return [];
+    if (!text(entry.name)) c.problem(`${at}.name`, 'must be a non-empty string');
+    if (!HTTP_URL.test(String(entry.url))) c.problem(`${at}.url`, 'must be an http(s) URL');
+    if (entry.method !== undefined && !['GET', 'POST'].includes(entry.method)) c.problem(`${at}.method`, 'must be GET or POST');
+    if (entry.status !== undefined && !(Number.isInteger(entry.status) && entry.status >= 100 && entry.status <= 599)) c.problem(`${at}.status`, 'must be an HTTP status code');
+    if (entry.json !== undefined && !plain(entry.json)) c.problem(`${at}.json`, 'must be a mapping of expected fields');
+    return [{ name: entry.name, url: entry.url, method: entry.method ?? 'GET', body: entry.body ?? null, status: entry.status ?? 200, json: entry.json ?? null, contains: entry.contains ?? null, retry: entry.retry === true }];
+  });
+}
+
+function command(c, at, value) {
+  const items = stringList(c, at, value, ARGUMENT, { nonEmpty: true });
+  return items;
+}
+
+function execChecks(c, block, services) {
+  return list(block).flatMap((entry, index) => {
+    const at = `deploy.verify.exec[${index}]`;
+    if (!closedFields(c, at, entry, FIELDS.exec)) return [];
+    if (!text(entry.name)) c.problem(`${at}.name`, 'must be a non-empty string');
+    nameField(c, `${at}.service`, entry.service);
+    if (services.size > 0 && !services.has(entry.service)) c.problem(`${at}.service`, `${entry.service} is not a service of the stack source`);
+    if (entry.stdout !== undefined) try { new RegExp(entry.stdout, 'u'); } catch { c.problem(`${at}.stdout`, 'must be a valid regular expression'); }
+    return [{ name: entry.name, service: entry.service, command: command(c, `${at}.command`, entry.command), stdout: entry.stdout ?? null }];
+  });
+}
+
+function verify(c, block, services) {
+  if (block === undefined) return { http: [], exec: [] };
+  if (!closedFields(c, 'deploy.verify', block, FIELDS.verify)) return { http: [], exec: [] };
+  return { http: httpChecks(c, block.http), exec: execChecks(c, block.exec, services) };
+}
+
+function jobs(c, block, services) {
+  if (block === undefined) return null;
+  if (!closedFields(c, 'deploy.jobs', block, FIELDS.jobs)) return null;
+  nameField(c, 'deploy.jobs.service', block.service);
+  if (services.size > 0 && !services.has(block.service)) c.problem('deploy.jobs.service', `${block.service} is not a service of the stack source`);
+  return { service: block.service, command: command(c, 'deploy.jobs.command', block.command) };
+}
+
+const TASK_NAME = /^[a-z][a-z0-9-]{0,40}$/u;
+
+/** The one-off commands (`starci app stack task <name>`): name -> { service, command }, each run inside a running task of the service. */
+function tasks(c, block, services) {
+  if (block === undefined) return {};
+  if (!plain(block)) { c.problem('deploy.tasks', 'must be a mapping'); return {}; }
+  const out = {};
+  for (const [name, entry] of Object.entries(block)) {
+    const at = `deploy.tasks.${name}`;
+    if (!TASK_NAME.test(name)) c.problem(at, `the task name must match ${TASK_NAME}`);
+    if (!closedFields(c, at, entry, FIELDS.task)) continue;
+    nameField(c, `${at}.service`, entry.service);
+    if (services.size > 0 && !services.has(entry.service)) c.problem(`${at}.service`, `${entry.service} is not a service of the stack source`);
+    out[name] = { service: entry.service, command: command(c, `${at}.command`, entry.command) };
+  }
+  return out;
+}
+
+const REGISTRY_HOST = /^[a-z0-9][a-z0-9.-]*(?::[0-9]{1,5})?$/u;
+const VISIBILITY = ['public', 'private'];
+
+/** The image registry: host (default ghcr.io) and the visibility the app's packages are meant to have (default public, the canon scaffold writes it and the app owns it afterwards). */
+function registry(c, block) {
+  const fallback = { host: 'ghcr.io', visibility: 'public' };
+  if (block === undefined) return fallback;
+  if (!closedFields(c, 'deploy.registry', block, FIELDS.registry)) return fallback;
+  if (block.host !== undefined) patternField(c, 'deploy.registry.host', block.host, REGISTRY_HOST);
+  if (block.visibility !== undefined && !VISIBILITY.includes(block.visibility)) c.problem('deploy.registry.visibility', `must be one of ${VISIBILITY.join(', ')}`);
+  return { host: block.host ?? fallback.host, visibility: block.visibility ?? fallback.visibility };
+}
+
+function backup(c, block) {
+  if (block === undefined) return null;
+  if (!closedFields(c, 'deploy.backup', block, FIELDS.backup)) return null;
+  if (!PINNED_HELPER_IMAGE.test(String(block.image))) c.problem('deploy.backup.image', 'must be a digest-pinned image reference (no all-zero digest)');
+  if (block.keepDays !== undefined && !(Number.isInteger(block.keepDays) && block.keepDays >= 1 && block.keepDays <= 3650)) c.problem('deploy.backup.keepDays', 'must be a whole number of days from 1 to 3650');
+  if (block.dir !== undefined && (!REMOTE_BASE.test(String(block.dir)) || String(block.dir).includes('..'))) c.problem('deploy.backup.dir', 'must be an absolute path without ..');
+  const volumes = list(block.volumes).flatMap((entry, index) => {
+    const at = `deploy.backup.volumes[${index}]`;
+    if (!closedFields(c, at, entry, FIELDS.backupVolume)) return [];
+    nameField(c, `${at}.name`, entry.name);
+    nameField(c, `${at}.volume`, entry.volume, VOLUME);
+    return [{ name: entry.name, volume: entry.volume }];
+  });
+  if (volumes.length === 0) c.problem('deploy.backup.volumes', 'must list at least one volume');
+  return { image: block.image, keepDays: block.keepDays ?? 14, dir: block.dir ?? null, volumes };
+}
+
+function ingress(c, block, probe) {
+  if (block === undefined) return null;
+  const result = normalizeIngress(block, { probe });
+  for (const item of result.problems) c.problem(item.at, item.message);
+  return result.ingress;
+}
+
+/**
+ * Validates and normalises one `deploy` block.
+ *   probe.exists(rel)  does a file exist below .starcistacks/<env>/ ?
+ *   probe.services     the service names of the committed stack source (empty set = unknown, service references are not checked)
+ *   probe.members      the sealed member slugs of .starcistacks/<env>/secrets (empty set = unknown)
+ * Returns { config, problems } ; config is null when a problem was found.
+ */
+export function normalizeDeploy(block, { project, probe }) {
+  const c = collector();
+  if (!closedFields(c, 'deploy', block, FIELDS.deploy)) return { config: null, problems: c.problems };
+  const services = probe.services ?? new Set();
+  const members = probe.members ?? new Set();
+  if (block.stack !== undefined) nameField(c, 'deploy.stack', block.stack);
+  const config = {
+    stack: block.stack ?? project,
+    remote: remote(c, block.remote),
+    images: images(c, block.images, services, members),
+    volumes: block.volumes === undefined ? [] : stringList(c, 'deploy.volumes', block.volumes, VOLUME),
+    secrets: secrets(c, block.secrets, services, members),
+    environment: environmentBlock(c, block.environment, services, probe),
+    configs: configs(c, block.configs, probe),
+    passEnv: block.passEnv === undefined ? [] : stringList(c, 'deploy.passEnv', block.passEnv, KEY),
+    verify: verify(c, block.verify, services),
+    jobs: jobs(c, block.jobs, services),
+    tasks: tasks(c, block.tasks, services),
+    backup: backup(c, block.backup),
+    ingress: ingress(c, block.ingress, probe),
+    registry: registry(c, block.registry),
+  };
+  if (block.stack === undefined && !NAME.test(String(project))) c.problem('deploy.stack', `the stack name ${project} must match ${NAME}`);
+  return { config: c.problems.length === 0 ? config : null, problems: c.problems };
+}