@starci/hfs 4.4.1 → 4.5.1

package/runtime/scripts/hfs/rules/ci-custody.mjs

@@ -0,0 +1,104 @@
+// ci-custody.mjs - R296-R298: CI declarations, sealed app keys and workflow reads agree by consumer, without decrypting or contacting GitHub.
+import fs from 'node:fs';
+import { list } from '../../lib/list.mjs';
+import { findStackDeclaration, STACK_ROOT } from '../../lib/stack-declaration.mjs';
+import { readCiDeclaration, sealedKeyNames, workflowReferences, ciNamesOfServices } from '../ci-declaration.mjs';
+import { found } from './read.mjs';
+
+const DECLARATION = `${STACK_ROOT}/application-stacks.yaml`;
+const named = (entry) => typeof entry.name === 'string' && /^[A-Z][A-Z0-9_]*$/.test(entry.name);
+const identity = (kind, name) => `${kind}:${name}`;
+const atCi = (section) => `${DECLARATION}#ci.${section}`;
+
+/** A CI or Dependabot secret must never also live in a sealed app member. */
+function sealedFindings(ci, sealed) {
+  const names = new Set([...ci.secrets, ...ci.dependabotSecrets].filter(named).map((entry) => entry.name));
+  return sealed.filter(({ key }) => names.has(key)).map(({ key, file }) => found(
+    'CI_SECRET_SEALED', file,
+    `${key} is a CI secret (GitHub reads it) but it is sealed in ${file} for app containers; one key, one class: remove it from the member (starci app secret unset ...) and set it with starci app ci secret set ${key}`,
+  ));
+}
+
+/** A source selects sealed keys only from its own member and environment. */
+function sourceRuntimeFindings(source, grant, environment, { sealed, names, findings, seen }) {
+  for (const entry of sealed) {
+    if (entry.env !== environment || entry.member !== source?.member || !names.has(entry.key)) continue;
+    if (source.keys !== undefined && !list(source.keys).includes(entry.key)) continue;
+    const id = `${entry.file}:${grant.service}:${entry.key}`;
+    if (seen.has(id)) continue;
+    seen.add(id);
+    findings.push(found('APP_SECRET_IN_CI', entry.file,
+      `${entry.key} is read by the ${grant.service} container at runtime through the ${environment} deploy grant; keep it in the .enc and drop it from ci`));
+  }
+}
+
+/** Only keys actually selected by a grant, in that grant's environment and member, are runtime consumers. */
+function runtimeFindings(doc, ci, sealed) {
+  const names = new Set([...ci.secrets, ...ci.vars].filter(named).map((entry) => entry.name));
+  const findings = [], seen = new Set();
+  for (const [environment, spec] of Object.entries(doc.environments ?? {})) {
+    for (const grant of list(spec?.deploy?.secrets?.grants)) {
+      if (typeof grant?.service !== 'string') continue;
+      for (const source of list(grant.from)) sourceRuntimeFindings(source, grant, environment, { sealed, names, findings, seen });
+    }
+  }
+  return findings;
+}
+
+/** Workflow reads are class-sensitive; legacy lists remain readable, but an absent ci block always signals migration once per name. */
+function workflowFindings(doc, declared, references) {
+  const hasCi = doc.ci !== undefined;
+  const allowed = new Set(declared.map(({ kind, name }) => identity(kind, name)));
+  if (hasCi) {
+    for (const entry of ciNamesOfServices(doc).filter(named)) {
+      const legacy = list(doc.services?.[entry.service]?.ci?.[`${entry.kind}s`]);
+      if (legacy.some((item) => (typeof item === 'string' ? item : item?.name) === entry.name)) allowed.add(identity(`${entry.kind}s`, entry.name));
+    }
+  }
+  const findings = [], seen = new Set();
+  for (const { file, kind, name } of references) {
+    if (allowed.has(identity(kind, name))) continue;
+    const id = hasCi ? `${file}:${kind}:${name}` : name;
+    if (seen.has(id)) continue;
+    seen.add(id);
+    findings.push(found('CI_DECLARATION_DRIFT', file,
+      `${kind}.${name} is read by this workflow but is not declared in ci.${kind}; declare its name, scope and consumer in ${DECLARATION}`));
+  }
+  return findings;
+}
+
+/** Dependabot has its own store and consumer, so only Actions secrets and vars require a workflow read. */
+function driftFindings(doc, ci, references) {
+  const declared = [
+    ...ci.secrets.filter(named).map((entry) => ({ ...entry, kind: 'secrets' })),
+    ...ci.vars.filter(named).map((entry) => ({ ...entry, kind: 'vars' })),
+  ];
+  const findings = workflowFindings(doc, declared, references);
+  if (doc.ci === undefined) return findings;
+  const reads = new Set(references.map(({ kind, name }) => identity(kind, name)));
+  for (const { kind, name, optional } of declared) {
+    if (!optional && !reads.has(identity(kind, name))) findings.push(found('CI_DECLARATION_DRIFT', atCi(kind),
+      `${name} is declared in ci.${kind} as non-optional but no workflow reads it; remove the declaration, mark it optional or wire its workflow consumer`));
+  }
+  const names = new Set(declared.map(({ kind, name }) => identity(kind, name)));
+  for (const [service, entry] of Object.entries(doc.services ?? {})) {
+    for (const [field, kind] of [['token', 'secrets'], ['hostVar', 'vars']]) {
+      const name = entry?.ci?.[field];
+      if (typeof name !== 'string' || names.has(identity(kind, name))) continue;
+      findings.push(found('CI_DECLARATION_DRIFT', atCi(kind),
+        `services.${service}.ci.${field} names ${name}, which is not declared in ci.${kind}; declare the shared CI name`));
+    }
+  }
+  return findings;
+}
+
+/** Offline CI custody findings of an app root, in both lite and full editions. */
+export function ciCustodyFindings({ repoRoot, repo, isRoot }) {
+  if (repo?.kind !== 'app' || !['lite', 'full'].includes(repo.edition) || isRoot === false) return [];
+  const { doc } = findStackDeclaration(repoRoot);
+  if (!doc) return [];
+  const ci = readCiDeclaration(doc);
+  const sealed = sealedKeyNames(repoRoot, { fs });
+  const references = workflowReferences(repoRoot, { fs });
+  return [...sealedFindings(ci, sealed), ...runtimeFindings(doc, ci, sealed), ...driftFindings(doc, ci, references)];
+}

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

@@ -1,11 +1,11 @@
 // R251: product workflow custody, immutable dependencies and release-only triggers, in both editions.
-import { parseWorkflow, workflowFindings } from '../runtime-rules/workflow-source.mjs';
-import { found, readText } from './read.mjs';
+import { parseWorkflow } from '../runtime-rules/workflow-source.mjs';
+import { found } from './read.mjs';
+import { appWorkflowFindings } from './app-workflow-findings.mjs';
 import { isPlainObject as record } from '../../../engine/plain-object.mjs';
 import { workflowEventOptions } from '../../lib/workflow-events.mjs';
 
 const DEPLOY = 'HFS_DEPLOY_WORKFLOW';
-const PIN = 'HFS_WORKFLOW_PIN';
 const TOOL = 'HFS_CI_TOOL_INSTALL';
 const TRIGGER = 'HFS_APP_WORKFLOW_TRIGGER';
 // Only the age identity and SSH transport credentials belong in the CI secret store.
@@ -85,18 +85,6 @@ function triggerFindings(doc, refuse) {
   return findings;
 }
 
-function actionFindings(doc, refuse) {
-  const findings = [];
-  for (const { key, value } of entries(doc)) {
-    if (key !== 'uses') continue;
-    const local = typeof value === 'string' && /^\.\/[\w./-]+$/.test(value);
-    const remote = typeof value === 'string' && /^[\w.-]+\/[\w.-]+(?:\/[\w./-]+)?@[a-f\d]{40}$/i.test(value);
-    const container = typeof value === 'string' && /^docker:\/\/[^\s@]+@sha256:[a-f\d]{64}$/i.test(value);
-    if (!local && !remote && !container) findings.push(refuse(PIN, 'every remote uses entry needs a full 40-hex commit SHA (a container action needs a sha256 digest)'));
-  }
-  return findings;
-}
-
 function secretProblems(doc) {
   const problems = [];
   if (entries(doc).some(({ key, value }) => key === 'secrets' && value === 'inherit')) problems.push('inherited secrets are forbidden');
@@ -209,11 +197,10 @@ function perWorkflow({ path: file, text }) {
   const refuse = (code, message) => found(code, file, `${code} ${file}: ${message}`);
   const doc = parseWorkflow(text);
   if (!record(doc)) return [refuse(TRIGGER, 'the workflow must be valid YAML with a release-only on block'), ...(deployName(file) ? [refuse(DEPLOY, 'the deploy workflow must be valid YAML')] : [])];
-  return [...triggerFindings(doc, refuse), ...actionFindings(doc, refuse), ...deploymentFindings(doc, file, refuse), ...toolFindings(doc, refuse)];
+  return [...triggerFindings(doc, refuse), ...deploymentFindings(doc, file, refuse), ...toolFindings(doc, refuse)];
 }
 
 /** Synchronous R251 findings over the tracked workflows of a lite/full app. */
-export function deployWorkflowFindings({ repoRoot, files, all = files, repo, isRoot, inScope = () => true }) {
-  if (isRoot === false || repo?.kind !== 'app' || !['lite', 'full'].includes(repo.edition)) return [];
-  return workflowFindings({ files: all.filter((file) => inScope(file)), read: (file) => readText(repoRoot, file) }, perWorkflow);
+export function deployWorkflowFindings(ctx) {
+  return appWorkflowFindings(ctx, perWorkflow);
 }

package/runtime/scripts/hfs/rules/fe-build-args.mjs

@@ -0,0 +1,142 @@
+// R300 FE_PUBLIC_BUILD_ARG_MISSING: every required browser build value has a Dockerfile ARG default or a buildArgs name in every environment deploying that app; literal fallback reads are optional.
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadTypescript } from '../../lib/package-at.mjs';
+import { parseDockerfile, words } from '../../lib/dockerfile.mjs';
+import { parseYaml } from '../../../engine/yaml.mjs';
+import { byCodeUnit } from '../../lib/list.mjs';
+import { found, readText } from './read.mjs';
+
+export const FE_PUBLIC_BUILD_ARG_MISSING = 'FE_PUBLIC_BUILD_ARG_MISSING';
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const PUBLIC = /^NEXT_PUBLIC_[A-Z0-9_]+$/u;
+const SOURCE = /\.[cm]?[jt]sx?$/u;
+const SCHEMA = /(?:^|[/.-])(?:env|schema)(?:[/.-]|$)/u;
+const DECLARATION = '.starcistacks/application-stacks.yaml';
+
+function declarationOf(root) {
+  try { return parseYaml(readText(root, DECLARATION) ?? '') ?? {}; } catch { return {}; }
+}
+
+/** Parentheses and TypeScript assertions do not alter whether a read has a literal fallback. */
+function unwrappedParent(ts, node) {
+  let current = node;
+  while (current.parent && (ts.isParenthesizedExpression(current.parent) || ts.isAsExpression(current.parent) || ts.isNonNullExpression(current.parent))) current = current.parent;
+  return current;
+}
+
+function literalFallback(ts, node) {
+  const current = unwrappedParent(ts, node);
+  const parent = current.parent;
+  if (!parent || !ts.isBinaryExpression(parent) || parent.left !== current) return false;
+  const fallback = parent.operatorToken.kind === ts.SyntaxKind.QuestionQuestionToken || parent.operatorToken.kind === ts.SyntaxKind.BarBarToken;
+  return fallback && ts.isStringLiteralLike(parent.right);
+}
+
+function publicRead(ts, node) {
+  if (!ts.isPropertyAccessExpression(node) || !PUBLIC.test(node.name.text)) return null;
+  const owner = node.expression;
+  const env = ts.isIdentifier(owner) && owner.text === 'env';
+  const processEnv = ts.isPropertyAccessExpression(owner) && owner.name.text === 'env' && ts.isIdentifier(owner.expression) && owner.expression.text === 'process';
+  return env || processEnv ? node.name.text : null;
+}
+
+function optionalSchema(ts, node) {
+  if (!node) return false;
+  if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
+    if (['optional', 'default', 'catch', 'nullish'].includes(node.expression.name.text)) return true;
+    return optionalSchema(ts, node.expression.expression);
+  }
+  return false;
+}
+
+function schemaKey(ts, node) {
+  if (!ts.isPropertyAssignment(node) && !ts.isPropertySignature(node)) return null;
+  const name = node.name?.text;
+  if (!PUBLIC.test(name ?? '') || node.questionToken || optionalSchema(ts, node.initializer)) return null;
+  return name;
+}
+
+function sourceRequirements(ts, file, text) {
+  const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
+  const required = new Set();
+  const schema = SCHEMA.test(file);
+  const visit = node => {
+    const name = publicRead(ts, node);
+    if (name && !literalFallback(ts, node)) required.add(name);
+    const key = schema ? schemaKey(ts, node) : null;
+    if (key) required.add(key);
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return required;
+}
+
+/** JSON/YAML environment schemas declare required names explicitly; optional properties impose no build requirement. */
+function schemaRequirements(text) {
+  let schema;
+  try { schema = parseYaml(text); } catch { return []; }
+  const names = [];
+  const visit = value => {
+    if (!value || typeof value !== 'object') return;
+    if (Array.isArray(value.required)) names.push(...value.required.filter(name => typeof name === 'string' && PUBLIC.test(name)));
+    Object.values(value).forEach(child => { if (child && typeof child === 'object') visit(child); });
+  };
+  visit(schema);
+  return names;
+}
+
+function requiredNames(root, files, app, ts) {
+  const prefix = `fe/apps/${app}/`;
+  const names = new Set();
+  for (const file of files.filter(file => file.startsWith(prefix))) {
+    const local = file.slice(prefix.length);
+    const source = SOURCE.test(local) && (local.startsWith('src/') || /^next\.config\./u.test(local) || SCHEMA.test(local));
+    const schema = SCHEMA.test(local) && /\.(?:json|ya?ml)$/u.test(local);
+    if (!source && !schema) continue;
+    const text = readText(root, file);
+    if (text === null) continue;
+    const required = source ? sourceRequirements(ts, local, text) : schemaRequirements(text);
+    for (const name of required) names.add(name);
+  }
+  return [...names].sort(byCodeUnit);
+}
+
+function dockerDefaults(text) {
+  return new Set(parseDockerfile(text).instructions.filter(item => item.keyword === 'ARG')
+    .flatMap(item => words(item.text)).filter(word => word.includes('='))
+    .map(word => word.slice(0, word.indexOf('='))));
+}
+
+function missingForEnvironment(environment, app, required) {
+  const images = Object.values(environment?.deploy?.images ?? {}).filter(image => image?.app === app);
+  if (!images.length) return [];
+  return required.filter(name => images.some(image => {
+    const args = image.buildArgs ?? {};
+    return !Object.hasOwn(args.values ?? {}, name) && !(args.sealed?.keys ?? []).includes(name);
+  }));
+}
+
+function appFindings(context, app, environments, ts) {
+  const { repoRoot, files } = context;
+  const file = `fe/apps/${app}/Dockerfile`;
+  if (!files.includes(file)) return [];
+  const defaults = dockerDefaults(readText(repoRoot, file) ?? '');
+  const required = requiredNames(repoRoot, files, app, ts).filter(name => !defaults.has(name));
+  const missing = Object.entries(environments).flatMap(([environment, entry]) => {
+    const names = missingForEnvironment(entry, app, required);
+    return names.length ? [{ environment, names }] : [];
+  });
+  if (!missing.length) return [];
+  const detail = missing.map(entry => `${entry.environment}: ${entry.names.join(', ')}`).join('; ');
+  return [found(FE_PUBLIC_BUILD_ARG_MISSING, file, `${FE_PUBLIC_BUILD_ARG_MISSING}: ${file} requires public build values without ARG defaults or deploy image buildArgs (${detail}).`, { missing })];
+}
+
+/** Judge front-end Dockerfiles at the app root in both editions; only names are read, and sealed members are never opened. */
+export function feBuildArgsFindings({ repoRoot, files = [], all = files, repo, isRoot = true }) {
+  if (!repoRoot || !isRoot || !repo?.sides?.fe) return [];
+  const ts = loadTypescript(repoRoot, HERE);
+  if (!ts) return [];
+  const environments = declarationOf(repoRoot).environments ?? {};
+  return repo.sides.fe.apps.flatMap(app => appFindings({ repoRoot, files: all }, app.name, environments, ts));
+}

package/runtime/scripts/hfs/rules/supply-chain.mjs

@@ -1,5 +1,5 @@
 // R269: app repositories in both editions declare dependency updates, a production audit gate, and image SBOM/provenance.
-import { parseWorkflow } from '../runtime-rules/workflow-source.mjs';
+import { parseWorkflow, workflowFindings } from '../runtime-rules/workflow-source.mjs';
 import { found, readText } from './read.mjs';
 
 const DEPENDABOT = '.github/dependabot.yml';
@@ -85,12 +85,48 @@ function stepsOf(workflow) {
   return Object.values(workflow?.jobs ?? {}).filter(enabled).flatMap((job) => Array.isArray(job.steps) ? job.steps.filter(enabled) : []);
 }
 
+/** npm groups admit only minor and patch updates; canon packages are ignored for every update type. */
+function hasNpmPolicy(update) {
+  const groups = update.groups && typeof update.groups === 'object' && !Array.isArray(update.groups) ? Object.values(update.groups) : [];
+  const minorPatch = (group) => Array.isArray(group?.['update-types']) && group['update-types'].includes('minor') && group['update-types'].includes('patch');
+  return groups.length > 0 && groups.every((group) => Array.isArray(group?.['update-types']) && group['update-types'].length > 0 && group['update-types'].every((type) => ['minor', 'patch'].includes(type))) &&
+    groups.some((group) => minorPatch(group) && [undefined, 'version-updates'].includes(group['applies-to'])) &&
+    groups.some((group) => group['applies-to'] === 'security-updates') &&
+    Array.isArray(update.ignore) && update.ignore.some((entry) => entry?.['dependency-name'] === '@starci/*' && entry.versions === undefined && entry['update-types'] === undefined);
+}
+
 function hasDependabot(document) {
   const directory = (value) => typeof value === 'string' && value.startsWith('/');
   return document?.version === 2 && Array.isArray(document.updates) && ECOSYSTEMS.every((ecosystem) => document.updates.some((update) =>
     update?.['package-ecosystem'] === ecosystem &&
     (directory(update.directory) || Array.isArray(update.directories) && update.directories.length > 0 && update.directories.every(directory)) &&
-    ['daily', 'weekly', 'monthly'].includes(update.schedule?.interval)));
+    ['daily', 'weekly', 'monthly'].includes(update.schedule?.interval))) &&
+    document.updates.filter((update) => update?.['package-ecosystem'] === 'npm').every(hasNpmPolicy);
+}
+
+function pinnedAction(value) {
+  return typeof value === 'string' && (/^\.\/[\w./-]+$/.test(value) ||
+    /^[\w.-]+\/[\w.-]+(?:\/[\w.-]+)*@[a-f\d]{40}$/i.test(value) ||
+    /^docker:\/\/[^\s@]+@sha256:[a-f\d]{64}$/i.test(value));
+}
+
+/** Mark YAML keys before parsing so comments and script scalars are ignored while flow maps and quoted keys retain their source lines. */
+function workflowPinFindings({ path: file, text }) {
+  const marked = text.replace(/(^|[\s{,])(?:"uses"|'uses'|uses)([ \t]*:)/gm, (match, prefix, colon, offset) => {
+    const line = text.slice(0, offset + prefix.length).split('\n').length;
+    return `${prefix}__hfs_action_uses_line_${line}__${colon}`;
+  });
+  const findings = [];
+  function visit(value) {
+    if (!value || typeof value !== 'object') return;
+    for (const [key, member] of Object.entries(value)) {
+      const line = /^__hfs_action_uses_line_(\d+)__$/.exec(key)?.[1];
+      if (line && !pinnedAction(member)) findings.push(found('HFS_WORKFLOW_PIN', file, `${file}:${line}: every remote uses entry needs a full 40-hex commit SHA; container actions need a sha256 digest.`, { line: Number(line) }));
+      visit(member);
+    }
+  }
+  visit(parseWorkflow(marked));
+  return findings;
 }
 
 function hasAudit(steps) {
@@ -160,8 +196,9 @@ export function supplyChainFindings({ repoRoot, files, all = files, repo, isRoot
   const tracked = new Set(all);
   const parsed = (file) => tracked.has(file) ? parseWorkflow(readText(repoRoot, file) ?? '') : null;
   const findings = [];
-  if (inScope(DEPENDABOT) && !hasDependabot(parsed(DEPENDABOT))) findings.push(found('HFS_DEPENDABOT_MISSING', DEPENDABOT, 'Declare Dependabot version 2 updates for npm, github-actions and docker, each with a directory and schedule.'));
+  if (inScope(DEPENDABOT) && !hasDependabot(parsed(DEPENDABOT))) findings.push(found('HFS_DEPENDABOT_MISSING', DEPENDABOT, 'Declare Dependabot version 2 updates for npm, github-actions and docker, each with a directory and schedule; every npm update must group minor+patch version updates, restrict every group to minor/patch (never major), include a security-updates group, and ignore all @starci/* updates (canon pins move only by starci upgrade).'));
   if (inScope(CI) && !hasAudit(stepsOf(parsed(CI)))) findings.push(found('HFS_AUDIT_STEP_MISSING', CI, 'CI must run npm audit --omit=dev in an enabled step whose failure stops the job.'));
   if (inScope(IMAGES) && !imageEvidence(stepsOf(parsed(IMAGES)))) findings.push(found('HFS_SBOM_MISSING', IMAGES, 'The images workflow must generate an SBOM and provenance for its release images in enabled steps.'));
+  findings.push(...workflowFindings({ files: [...tracked].filter((file) => inScope(file)), read: (file) => readText(repoRoot, file) }, workflowPinFindings));
   return findings;
 }

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

@@ -0,0 +1,103 @@
+// R299: GitHub Actions expressions use only contexts available at their workflow key.
+import { parseWorkflow } from '../runtime-rules/workflow-source.mjs';
+import { found } from './read.mjs';
+import { appWorkflowFindings } from './app-workflow-findings.mjs';
+
+const WORKFLOW = ['github', 'inputs', 'vars'];
+const JOB_IF = ['github', 'needs', 'vars', 'inputs'];
+const JOB = [...JOB_IF, 'strategy', 'matrix'];
+const JOB_ENV = [...JOB, 'secrets'];
+const EXECUTION = [...JOB_ENV, 'job', 'runner', 'env'];
+const CONTEXTS = [...EXECUTION, 'steps'];
+const JOB_KEYS = new Set(['name', 'runs-on', 'concurrency', 'strategy', 'timeout-minutes', 'continue-on-error', 'with']);
+
+/** Container and service images are chosen before a runner exists; their other properties use execution contexts. */
+function containerContexts(keys) {
+  if (keys[2] === 'services') return keys[4] === 'image' ? JOB : EXECUTION;
+  return keys.length === 3 || keys[3] === 'image' ? JOB : EXECUTION;
+}
+
+/** The most specific row of GitHub's Context availability table governs each descendant value. */
+function jobContexts(keys) {
+  const key = keys[2];
+  if (key === 'steps') return CONTEXTS;
+  if (key === 'if') return JOB_IF;
+  if (key === 'strategy') return JOB_IF;
+  if (key === 'env' || key === 'secrets') return JOB_ENV;
+  if (key === 'outputs') return CONTEXTS;
+  if (key === 'defaults' && keys[3] === 'run') return [...JOB, 'env'];
+  if (key === 'environment') return keys[3] === 'url' ? CONTEXTS.filter((context) => context !== 'secrets') : JOB;
+  if (key === 'container' || key === 'services') return containerContexts(keys);
+  if (JOB_KEYS.has(key)) return JOB;
+  return [];
+}
+
+/** Unlisted workflow keys admit no contexts; reusable workflow outputs alone may read jobs. */
+function allowedContexts(keys) {
+  if (keys[0] === 'jobs') return jobContexts(keys);
+  if (keys[0] === 'env') return [...WORKFLOW, 'secrets'];
+  if (keys[0] === 'run-name' || keys[0] === 'concurrency') return WORKFLOW;
+  if (keys.slice(0, 3).join('.') === 'on.workflow_call.inputs' && keys[4] === 'default') return WORKFLOW;
+  if (keys.slice(0, 3).join('.') === 'on.workflow_call.outputs' && keys[4] === 'value') return [...WORKFLOW, 'jobs'];
+  return [];
+}
+
+/** Strings and property names are not context roots; bracket access and case-insensitive roots still are. */
+function expressionContexts(expression) {
+  const unquoted = expression.replace(/'(?:[^']|'')*'/g, ' ');
+  const tokens = unquoted.match(/[A-Za-z_][\w-]*|[^\s]/g) ?? [];
+  const roots = tokens.filter((token, index) => tokens[index - 1] !== '.' &&
+    ([...CONTEXTS, 'jobs'].includes(token.toLowerCase()) || ['.', '['].includes(tokens[index + 1]))).map((token) => token.toLowerCase());
+  return [...new Set(roots)];
+}
+
+/** A closing delimiter inside an Actions single-quoted string cannot end an expression. */
+function expressionEnd(value, start) {
+  let quoted = false;
+  for (let index = start; index < value.length; index++) {
+    if (value[index] === "'") quoted = !quoted;
+    if (!quoted && value.slice(index, index + 2) === '}}') return index;
+  }
+  return value.length;
+}
+
+/** Read marked expressions without ambiguous regex repetition or losing delimiters inside string literals. */
+function expressions(value) {
+  const result = [];
+  const marker = /\$\{\{ __hfs_context_line_(\d+)__ /g;
+  let match;
+  while ((match = marker.exec(value)) !== null) {
+    const end = expressionEnd(value, marker.lastIndex);
+    result.push({ line: Number(match[1]), body: value.slice(marker.lastIndex, end) });
+    marker.lastIndex = end + 2;
+  }
+  return result;
+}
+
+/** Source markers travel inside parsed scalar expressions, preserving flow maps, quoted keys and repeated values without matching comments. */
+function workflowContextFindings({ path: file, text }) {
+  const marked = text.replace(/\$\{\{/g, (match, offset) => `${match} __hfs_context_line_${text.slice(0, offset).split('\n').length}__ `);
+  const findings = [];
+  function inspect(value, keys) {
+    const allowed = allowedContexts(keys);
+    for (const { line, body } of expressions(value)) {
+      for (const context of expressionContexts(body)) {
+        if (allowed.includes(context)) continue;
+        const keyPath = keys.join('.');
+        findings.push(found('HFS_WORKFLOW_CONTEXT', file, `HFS_WORKFLOW_CONTEXT: ${file}:${line}: ${keyPath} forbids context ${context}.`, { line, keyPath, context }));
+      }
+    }
+  }
+  function visit(value, keys = []) {
+    if (typeof value === 'string') inspect(value, keys);
+    if (!value || typeof value !== 'object') return;
+    for (const [key, member] of Object.entries(value)) visit(member, [...keys, key]);
+  }
+  visit(parseWorkflow(marked));
+  return findings;
+}
+
+/** Judge every tracked workflow in scope at the full or lite app root, using the shared workflow selector. */
+export function workflowContextsFindings(ctx) {
+  return appWorkflowFindings(ctx, workflowContextFindings, { dedupe: true });
+}

package/runtime/scripts/lib/secret-patterns.mjs

@@ -43,11 +43,11 @@ const SECRET_NAME = [
   String.raw`[A-Za-z_$][A-Za-z0-9_$.-]*\s*[:=]\s*`,
 ].join('');
 
-// `password = "hunter2hunter2"` — the quoted literal. `env(NAME)` is a reference, never a secret.
+// `password = "example-password-1"` — the quoted literal. `env(NAME)` is a reference, never a secret.
 const ASSIGNED_QUOTED = new RegExp(
   SECRET_NAME + String.raw`['"\`](?!env\([A-Z_][A-Z0-9_]*\)['"\`])([^'"\`\n\s$<{]{12,})['"\`]`,
 );
-// `DB_PASSWORD=hunter2hunter2` — the compose list-item and dotenv form; the dotenv value has no `:` so
+// `DB_PASSWORD=example-password-1` — the compose list-item and dotenv form; the dotenv value has no `:` so
 // `password: secret:db/password` and `token: ref:vault/api` stay references, and the end boundary keeps
 // calls and member/index references such as `secret = credentialsSource.current` out of the literals.
 const ASSIGNED_UNQUOTED = new RegExp(

package/src/main.mjs

@@ -15,7 +15,7 @@
 //                                            runs on those owners without clones and dead exports. No merge-base is a refusal
 //                                            (exit 2), never a silent full pass. Exit 1 on any error-level finding. The root checks run once and
 //                                            the side checks and the machine once per side, the side folder as their root; every path is app-relative.
-//   starci app lint [--cwd <dir>] [--changed <file>...] [--workspace <dir>] [--fix] [--format text|json] [--sonar <file>]
+//   starci app lint [--cwd <dir>] [--changed <file>...] [--workspace <dir>] [--side be|fe] [--fix] [--format text|json] [--sonar <file>]
 //                                            the ONE lint entry (npm run lint): ESLint per side with that side's canon config (per-file rules and
 //                                            the project-graph rules), this check's findings, and stylelint over the fe side, as one starci/lint@1
 //                                            report; --sonar writes the one Sonar import file. Exit 0 clean, 1 findings, 2 a tool could not run (lint/run.mjs).
@@ -43,6 +43,9 @@
 //   starci app secret materialize <env> | list <env> | verify <env>
 //                                            dotenv custody in .starcistacks, public age rule initialization, private KEY files outside Git;
 //                                            values reach stdout only when get explicitly receives --reveal.
+//   starci app ci secret set <NAME> [--env E | --dependabot] [--repo owner/name]  reads the value from stdin only.
+//   starci app ci var set <NAME> [--env E] [--value v] | var sync [--execute] | verify [--json]
+//                                            declared GitHub CI custody; verify compares names, scopes and public values.
 //   starci app db baseline | restamp --map <restamp.yaml> | plan
 //                                            preview the database cutover or compare its state with the repo; baseline and restamp mutate only with --apply.
 //   starci app add <api|webhook|realtime|saga|job|reactor|queue|projection> <name> [--event <event> --from <service> --service <Class>=<module>] [--owner <service> --failed <event> --done <event>] [--connection <name>] [--cwd <dir>]
@@ -83,18 +86,22 @@ import { ACTIONS as STACK_ACTIONS, stackMain as deployStackMain } from '../stack
 import { releaseMain } from '../release/index.mjs';
 import { dbMigrateMain } from '../db/migrate.mjs';
 import { dbPostCutoverMain } from '../db/post-cutover.mjs';
+import { dbDumpMain } from '../db/dump.mjs';
+import { dbResetMain } from '../db/reset.mjs';
 
-export const VERBS = Object.freeze(['scaffold', 'add', 'lint', 'sync', 'check', 'upgrade', 'stack', 'release', 'explain', 'emit', 'new', 'secret', 'db', 'hygiene']);
-const DATABASE_VERBS = new Map([['baseline', dbBaselineMain], ['restamp', dbRestampMain], ['plan', dbPlanMain], ['migrate', dbMigrateMain], ['post-cutover', dbPostCutoverMain]]);
+export const VERBS = Object.freeze(['scaffold', 'add', 'lint', 'sync', 'check', 'upgrade', 'stack', 'release', 'explain', 'emit', 'new', 'secret', 'ci', 'db', 'hygiene']);
+const DATABASE_VERBS = new Map([['baseline', dbBaselineMain], ['restamp', dbRestampMain], ['plan', dbPlanMain], ['migrate', dbMigrateMain], ['post-cutover', dbPostCutoverMain], ['dump', dbDumpMain], ['reset', dbResetMain]]);
 
 const USAGE = `starci app scaffold <name> [--into <dir>] [--edition full|lite] [--registry-visibility public|private] [--cwd <dir>]
 starci app add <api|webhook|realtime|saga|job|reactor|queue|projection|cli|table|app> <name> [options] [--cwd <dir>]
-starci app lint [--cwd <dir>] [--changed <file>...] [--workspace <dir>] [--fix] [--format text|json] [--sonar <file>]
+starci app lint [--cwd <dir>] [--changed <file>...] [--workspace <dir>] [--side be|fe] [--fix] [--format text|json] [--sonar <file>]
 starci app sync (--check | --write) [--cwd <dir>]
 starci app check [--cwd <dir>] [--json] [--fast] [--base <ref>] [--edition full] [--db-types] [--wiring] [--coverage-from <lcov>]
 starci app db baseline [--stamp <version>] [--local] [--apply] [--cwd <dir>]
 starci app db restamp --map <restamp.yaml> [--local] [--apply] [--cwd <dir>]
 starci app db plan [--local] [--json] [--cwd <dir>]
+starci app db dump (--linked | --local | --url-env <NAME>) --out <dir> [--schema-only] [--json] [--cwd <dir>]
+starci app db reset --linked --auth keep|drop --storage keep|drop --backup <receipt.json> [--execute] [--json] [--cwd <dir>]
 starci app db migrate [--execute] [--linked | --url-env <NAME>] [--json] [--cwd <dir>]
 starci app db post-cutover [--execute] [--green-at <ISO> | --owner-confirms-old-app-gone] [--linked | --url-env <NAME>] [--json] [--cwd <dir>]
 starci app release gate [--execute] [--source <ref>] [--tag-prefix <prefix>] [--json] [--cwd <dir>]
@@ -116,6 +123,10 @@ starci app secret remove <env> <slug> [--execute] [--force-nonempty] [--cwd <dir
 starci app secret materialize <env> [--cwd <dir>]
 starci app secret list <env> [--cwd <dir>]
 starci app secret verify <env> [--cwd <dir>]
+starci app ci secret set <NAME> [--env E | --dependabot] [--repo owner/name] [--cwd <dir>]
+starci app ci var set <NAME> [--env E] [--value v] [--repo owner/name] [--cwd <dir>]
+starci app ci var sync [--execute] [--repo owner/name] [--cwd <dir>]
+starci app ci verify [--json] [--repo owner/name] [--cwd <dir>]
 starci app hygiene [--cwd <dir>]
 `;
 const PER_CODE_LIMIT = 25;
@@ -318,7 +329,7 @@ async function installedStackMain(cwd) {
 function databaseMain(argv, io) {
   const [verb, ...rest] = argv;
   const dispatch = DATABASE_VERBS.get(verb);
-  if (!dispatch) throw new Error('starci app db takes baseline, restamp, plan, migrate or post-cutover');
+  if (!dispatch) throw new Error('starci app db takes baseline, restamp, plan, migrate, post-cutover, dump or reset');
   return dispatch(rest, io);
 }
 
@@ -408,7 +419,7 @@ async function stackAppMain(argv, { cwd, edition, stackMain, stdout: out, stderr
   return run(argv, { cwd, out, err });
 }
 
-const DIRECT_VERBS = new Map([['lint', lintMain], ['secret', secretMain], ['db', databaseMain], ['upgrade', upgradeAppMain], ['stack', stackAppMain], ['release', releaseMain]]);
+const DIRECT_VERBS = new Map([['ci', async (argv, io) => (await import('../ci/cli.mjs')).ciMain(argv, io)], ['lint', lintMain], ['secret', secretMain], ['db', databaseMain], ['upgrade', upgradeAppMain], ['stack', stackAppMain], ['release', releaseMain]]);
 const PARSED_VERBS = new Map([['check', checkMain], ['emit', emitMain], ['new', newMain], ['add', addMain], ['scaffold', scaffoldMain], ['explain', explainMain]]);
 
 function dispatchMain(verb, argv, io) {

package/stack/context.mjs

@@ -1,11 +1,18 @@
 // context.mjs - the seams every stack module runs through: spawning tools, sleeping, the clock and the output.
 // Production uses the real implementations; a spec injects fakes.
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { defaultSops } from '../runtime/scripts/hfs/secret-sops.mjs';
 
 const MAX_BUFFER = 1 << 24;
 
 const realSpawn = (command, args, options = {}) => {
+  if (options.background) {
+    const childOptions = { ...options };
+    delete childOptions.background;
+    const child = spawn(command, args, { stdio: 'ignore', windowsHide: true, ...childOptions });
+    child.on('error', (error) => { child.spawnError = error; });
+    return child;
+  }
   const run = spawnSync(command, args, { encoding: 'utf8', maxBuffer: MAX_BUFFER, ...options });
   return { status: run.status, stdout: run.stdout ?? '', stderr: run.stderr ?? '', error: run.error };
 };
@@ -16,6 +23,8 @@ const realSleep = (ms) => new Promise((done) => { setTimeout(done, ms); });
  * The context of one stack invocation.
  *   cwd, env       the app root and the process environment
  *   spawn          (command, args, { input, env, cwd }) -> { status, stdout, stderr, error }; never a shell
+ *                  { background: true } -> ChildProcess, owned and killed by the command session
+ *   platform       POSIX control master or win32 loopback tunnel; sshPath optionally selects the POSIX SSH executable
  *   sleep, now     await sleep(ms); now() -> epoch ms
  *   stdout, stderr text writers
  *   fetch          the HTTP seam of verify (url, init) -> Response
@@ -29,6 +38,9 @@ export function stackContext(io = {}) {
     cwd,
     env,
     spawn: io.spawn ?? realSpawn,
+    platform: io.platform ?? process.platform,
+    username: io.username,
+    sshPath: io.sshPath,
     sleep: io.sleep ?? realSleep,
     now: io.now ?? Date.now,
     stdout: io.stdout ?? ((text) => process.stdout.write(text)),