@starci/hfs 5.0.4 → 5.0.6

package/runtime/scripts/hfs/rules/contract.d.mts

@@ -15,12 +15,20 @@ export declare function contractFindings({ repoRoot, files, repo, resolver }: {
  * `openapi.json` and `status` one of `fresh`, `stale`, `not-committed`, `none` (nothing emitted, nothing committed; GraphQL only),
  * `left-behind` (committed, nothing emitted) or `emit-failed`.
  */
-export declare function contractEmitFindings({ repoRoot, files, repo, emit }: {
+interface ContractEmitInput {
     repoRoot: string;
     files: string[];
     repo: Repo;
     emit: Parsed;
-}): {
+}
+/** The synchronous source finder and asynchronous app cache share every emission comparison and failure rule. */
+export declare function contractEmitFindings(input: ContractEmitInput): {
     findings: Finding[];
-    apps: any[];
+    apps: Parsed[];
 };
+/** Awaits actual governed compiler children before the existing drift proof can be recorded. */
+export declare function contractEmitFindingsAsync(input: ContractEmitInput): Promise<{
+    findings: Finding[];
+    apps: Parsed[];
+}>;
+export {};

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

@@ -6,6 +6,7 @@
 // resolvers the app root composes, and the OpenAPI 3.1 document of the typed operation table `apps/<app>/src/operations.ts`.
 // That the committed snapshot equals what the app emits now is contractEmitFindings (full pass only, never --fast): it emits every
 // api app into a temp directory through the injected `emit` (packages/hfs/emit) and compares hashes; an emit that cannot run is a finding.
+import { isNodeExecutionRefusal } from '../../api/node/run-node.mjs';
 import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -145,16 +146,7 @@ function artifactFindings({ repoRoot, tracked, scratch, app, artifact, what, emi
         findings.push(found(CONTRACT_SNAPSHOT_DRIFT, snapshot, `${snapshot} (${committed.slice(0, 12)}) differs from what ${app.name} emits now (${String(fresh).slice(0, 12)}); run \`npm run contract:emit\` and commit the result`, { app: app.name, drift: 'stale' }));
     }
 }
-/**
- * R23, full pass: each committed `contracts/<app>/schema.graphql` and `contracts/<app>/openapi.json` equals what `emit` writes for
- * the app now. `emit({ repoRoot, declaration, outDir })` is `emitContracts` of packages/hfs/emit and answers `{ written, skipped }`;
- * it is injected because the runtime scripts do not import the hfs package. Every api app is emitted on its own into a temp
- * directory, so one app that cannot emit does not hide the others; an uncommitted emitted snapshot is a finding here too. Answers
- * `{ findings, apps }`, `apps` being what was judged: `[{ app, artifact, status }]`, `artifact` being `schema.graphql` or
- * `openapi.json` and `status` one of `fresh`, `stale`, `not-committed`, `none` (nothing emitted, nothing committed; GraphQL only),
- * `left-behind` (committed, nothing emitted) or `emit-failed`.
- */
-export function contractEmitFindings({ repoRoot, files, repo, emit }) {
+function* contractProgram({ repoRoot, files, repo }) {
     const findings = [];
     const apps = [];
     if (repo.profile !== 'be')
@@ -166,9 +158,14 @@ export function contractEmitFindings({ repoRoot, files, repo, emit }) {
             const artifacts = [{ artifact: SNAPSHOT_OF.graphql, what: 'serves no GraphQL any more' }, { artifact: SNAPSHOT_OF.json, what: 'declares no operations any more' }];
             let emitted;
             try {
-                emitted = emit({ repoRoot, declaration: { apps: [app] }, outDir: scratch });
+                const response = yield { repoRoot, declaration: { apps: [app] }, outDir: scratch };
+                if ('error' in response)
+                    throw response.error;
+                emitted = response.value;
             }
             catch (error) {
+                if (isNodeExecutionRefusal(error))
+                    throw error;
                 emitFailure(app, artifacts, error, apps, findings);
                 continue;
             }
@@ -183,3 +180,45 @@ export function contractEmitFindings({ repoRoot, files, repo, emit }) {
     }
     return { findings, apps };
 }
+/** The synchronous source finder and asynchronous app cache share every emission comparison and failure rule. */
+export function contractEmitFindings(input) {
+    const program = contractProgram(input);
+    let step = program.next();
+    try {
+        while (!step.done) {
+            let response;
+            try {
+                response = { value: input.emit(step.value) };
+            }
+            catch (error) {
+                response = { error };
+            }
+            step = program.next(response);
+        }
+        return step.value;
+    }
+    finally {
+        program.return({ findings: [], apps: [] });
+    }
+}
+/** Awaits actual governed compiler children before the existing drift proof can be recorded. */
+export async function contractEmitFindingsAsync(input) {
+    const program = contractProgram(input);
+    let step = program.next();
+    try {
+        while (!step.done) {
+            let response;
+            try {
+                response = { value: await input.emit(step.value) };
+            }
+            catch (error) {
+                response = { error };
+            }
+            step = program.next(response);
+        }
+        return step.value;
+    }
+    finally {
+        program.return({ findings: [], apps: [] });
+    }
+}

package/runtime/scripts/hfs/rules/env-parity.mjs

@@ -22,7 +22,9 @@ import { fileURLToPath } from 'node:url';
 import { loadTypescript } from '../../lib/package-at.mjs';
 import { parseYaml } from '../../../engine/yaml.mjs';
 import { envelopeOf } from '../secret-document.mjs';
-import { SSH_GROUP, sshTransportMembers } from '../secret-standard.mjs';
+import { SSH_GROUP, sshTransportMembers, declaredServiceKeys } from '../secret-standard.mjs';
+import { repositoryName, identityQueryEnvironment } from '../repo-identity.mjs';
+import { serviceCredentialNames } from '../ci-declaration.mjs';
 import { memberOfName } from '../../lib/sealed-member.mjs';
 import { found, readText } from './read.mjs';
 export const ENV_REQUIRED_UNSET = 'ENV_REQUIRED_UNSET';
@@ -342,12 +344,12 @@ function addRequiredFindings(reads, sealed, declared, findings) {
         }
     }
 }
-function sealedMemberFinding(key, member, reads, declared) {
+function sealedMemberFinding(key, member, reads, declared, serviceConsumer) {
     // The specific public-custody code wins over the generic unread one for a NEXT_PUBLIC_* key.
     if (key.startsWith('NEXT_PUBLIC_')) {
         return found(ENV_PUBLIC_SEALED, member, `${member} seals the public key ${key}; NEXT_PUBLIC_* values are public configuration and never enter custody`);
     }
-    if (!reads.has(key) && !declared.has(key)) {
+    if (!reads.has(key) && !declared.has(key) && !serviceConsumer(member, key)) {
         return found(ENV_SEALED_UNREAD, member, `${member} seals ${key}, which no EnvSource reader and no declared consumer uses; unseal it or declare who consumes it`);
     }
     return null;
@@ -362,10 +364,10 @@ function transportMembers(repoRoot) {
     catch { /* a malformed stacks yaml is the shape rule's finding, not this one's */ }
     return (environment) => sshTransportMembers(stacks.environments?.[environment]);
 }
-function addSealedFindings(sealed, reads, declared, transport, findings) {
+function addSealedFindings(sealed, reads, declared, transport, findings, serviceConsumer) {
     for (const [key, members] of sealed) {
         for (const member of members) {
-            const finding = sealedMemberFinding(key, member, reads, declared);
+            const finding = sealedMemberFinding(key, member, reads, declared, serviceConsumer);
             if (finding !== null)
                 findings.push(finding);
         }
@@ -410,8 +412,15 @@ export function envParityFindings({ repoRoot, all = [], isRoot }) {
     const sealed = sealedKeys(repoRoot, all);
     const declared = declaredKeys(repoRoot, all);
     const findings = [];
+    let stacks = {};
+    try {
+        stacks = parseYaml(readText(repoRoot, '.starcistacks/application-stacks.yaml') ?? '') ?? {};
+    }
+    catch { /* the shape owner reports invalid YAML */ }
+    const repository = repositoryName(repoRoot, { env: identityQueryEnvironment(process.env, serviceCredentialNames(stacks)) });
+    const serviceConsumer = (file, key) => declaredServiceKeys(stacks, repository, file.split('/')[1], memberOfName(file.split('/').pop())).includes(key);
     addRequiredFindings(reads, sealed, declared, findings);
-    addSealedFindings(sealed, reads, declared, transportMembers(repoRoot), findings);
+    addSealedFindings(sealed, reads, declared, transportMembers(repoRoot), findings, serviceConsumer);
     addExampleFindings(repoRoot, all, reads, findings);
     return findings;
 }

package/runtime/scripts/hfs/secret-standard.d.mts

@@ -46,6 +46,7 @@ export interface MoveOptions {
 }
 /** The provider a key belongs to: its first word (`SEPAY_IPN_SECRET_KEY` is `sepay`, `OPENROUTER_API_KEY` is `openrouter`). */
 export declare const providerOf: (key: string) => string;
+export declare function declaredServiceKeys(document: StacksDocument, repository: string, environment: string, member: string): string[];
 /** The keys of the one sealed SSH member `deploy.remote.sealed` names (stack/remote.mjs): the deploy transport reads exactly these. */
 export declare const SSH_GROUP: readonly string[];
 /**

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

@@ -13,12 +13,26 @@ import { configuredRecipients } from "./secret-init.mjs";
 import { envelopeOf, validateMap } from "./secret-document.mjs";
 import { deleteSealed, fileOf, sealedFiles, writeSecret } from "./secret-store.mjs";
 import { SecretError } from "./secret-errors.mjs";
+import { serviceMemberPath, serviceCredentialNames } from "./ci-declaration.mjs";
+import { repositoryName, identityQueryEnvironment } from "./repo-identity.mjs";
+import { list } from "../lib/list.mjs";
 /** The provider a key belongs to: its first word (`SEPAY_IPN_SECRET_KEY` is `sepay`, `OPENROUTER_API_KEY` is `openrouter`). */
 export const providerOf = (key) => key.split("_")[0].toLowerCase();
 const sameSet = (left, right) => left.length === right.length && left.every((item) => right.includes(item));
 const keyList = (keys) => keys.join(", ");
 /** The member a `secrets:` entry names: `member`, else the slug of `where`, else its `name`. */
 const memberOfEntry = (entry) => entry?.member ?? /^secrets\/([a-z0-9-]+)/u.exec(entry?.where ?? "")?.[1] ?? entry?.name;
+/** The declared connection/credential keys of this project's services, including separately kept operator login custody. */
+function declaredServiceReferences(document, repository) {
+    const services = document.services;
+    return Object.values(services ?? {}).flatMap((service) => list(service?.credentials).flatMap((credential) => {
+        const selected = serviceMemberPath(credential?.custody?.path);
+        return credential?.custody?.repository === repository && selected && typeof credential.key === "string" ? [{ ...selected, key: credential.key }] : [];
+    }));
+}
+export function declaredServiceKeys(document, repository, environment, member) {
+    return declaredServiceReferences(document, repository).filter((reference) => reference.environment === environment && reference.member === member).map((reference) => reference.key);
+}
 /** The keys an environment's `secrets:` declares for `member`: an entry naming `key` with that `member`, or a whole-member entry. */
 function declaredKeys(spec, member, keys) {
     const entries = Array.isArray(spec?.secrets) ? spec.secrets : [];
@@ -80,6 +94,11 @@ export function auditSecrets(repoRoot, environment = null) {
             .map((entry) => entry.name)
             .sort();
     const findings = [];
+    const repository = repositoryName(repoRoot, { env: identityQueryEnvironment(process.env, serviceCredentialNames(stacks)) });
+    for (const reference of declaredServiceReferences(stacks, repository).filter((item) => !environment || item.environment === environment)) {
+        if (!Object.hasOwn(stacks.environments ?? {}, reference.environment) || !fs.existsSync(path.join(repoRoot, reference.path)))
+            findings.push({ code: "MISSING", env: reference.environment, member: reference.member, detail: "service credential references a missing member or undeclared environment" });
+    }
     for (const env of environments) {
         const directory = path.join(root, env, "secrets");
         const spec = stacks.environments?.[env];
@@ -92,16 +111,17 @@ export function auditSecrets(repoRoot, environment = null) {
             const providers = [...new Set(envelope.keys.map(providerOf))];
             if (isLegacyName(name))
                 add("LEGACY_MEMBER", `is a dotenv .enc member; move it: starci app secret migrate --env ${env} ${member} [--to <provider>] --execute`);
-            if (providers.length > 1 && !declaredGroup(spec, member, envelope.keys))
+            const serviceKeys = declaredServiceKeys(stacks, repository, env, member);
+            if (providers.length > 1 && !declaredGroup(spec, member, envelope.keys) && !envelope.keys.every((key) => serviceKeys.includes(key)))
                 add("MIXED_PROVIDERS", `holds keys of ${providers.length} providers by their first word (${providers.join(", ")}) that the stack does not group in it; split it (starci app secret split --env ${env} ${member} [--group KEY=member] --execute) or declare its keys in environments.${env}.secrets (an entry naming ${member} with keys: [...])`);
             const wanted = recipientsFor(repoRoot, path.join(directory, `${member}${MEMBER_SUFFIX}`));
             if (!isLegacyName(name) && wanted.length && !sameSet(wanted, envelope.recipients))
                 add("RECIPIENT_DRIFT", `is sealed to ${keyList(envelope.recipients)}, its environment's rule names ${keyList(wanted)}; seal it again: starci app secret migrate --env ${env} ${member} --execute`);
             if (spec) {
-                const declared = declaredKeys(spec, member, envelope.keys);
+                const declared = [...declaredKeys(spec, member, envelope.keys), ...serviceKeys];
                 const missing = envelope.keys.filter((key) => !declared.includes(key));
                 if (missing.length)
-                    add("UNDECLARED_KEY", `holds ${keyList(missing)}, not declared in environments.${env}.secrets of application-stacks.yaml`);
+                    add("UNDECLARED_KEY", `holds ${keyList(missing)}, not declared as runtime secrets or exact service credential references in application-stacks.yaml`);
             }
             if (tracked && !tracked.has(name))
                 add("UNTRACKED", "is not committed; commit it (it is ciphertext)");
@@ -155,7 +175,8 @@ export function declareKeys(repoRoot, environment, member, keys) {
     const spec = document.environments?.[environment];
     if (!spec)
         return { declared: [], byHand: [] };
-    const missing = keys.filter((key) => !declaredKeys(spec, member, keys).includes(key));
+    const serviceKeys = declaredServiceKeys(document, repositoryName(repoRoot, { env: identityQueryEnvironment(process.env, serviceCredentialNames(document)) }), environment, member);
+    const missing = keys.filter((key) => !declaredKeys(spec, member, keys).includes(key) && !serviceKeys.includes(key));
     if (!missing.length)
         return { declared: [], byHand: [] };
     // A swarm environment's secret is a versioned external secret its stack file names (runtimeName, deploy grants): its

package/runtime/scripts/hfs/secret-store.d.mts

@@ -1,7 +1,12 @@
 import { type SecretSops } from "./secret-sops.mjs";
+import type { ServiceBinding } from "./ci-declaration.mjs";
 /** The directory of the sealed secrets of the app at `repoRoot` for `env`; the one env that has secrets when none is named. */
 export declare function secretsDirectory(repoRoot: string, env?: string | null): string;
 export declare const fileOf: (directory: string, slug: string | undefined) => string;
+/** Judge a selected service member and cleartext key names without decrypting; its real path stays in this product. */
+export declare function serviceCredentialFile(repoRoot: string, binding: ServiceBinding): string;
+/** Native service loader: one exact key, decrypted in memory through the common identity/SOPS owner, never an env fallback. */
+export declare function serviceCredentialValue(repoRoot: string, binding: ServiceBinding, sops: Pick<SecretSops, "decrypt">): string;
 /** Replace one existing sealed member with an already validated envelope: same claim and atomic publish as set. */
 export declare const replaceSealed: (file: string, sealed: string) => void;
 /** Delete one sealed member under the writer claim. */

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

@@ -41,6 +41,37 @@ export const fileOf = (directory, slug) => {
         throw new SecretError(error.message);
     }
 };
+/** Judge a selected service member and cleartext key names without decrypting; its real path stays in this product. */
+export function serviceCredentialFile(repoRoot, binding) {
+    const file = fileOf(secretsDirectory(repoRoot, binding.environment), binding.member);
+    const declared = path.resolve(repoRoot, binding.path);
+    try {
+        if (file !== declared || !fs.statSync(file).isFile() || fs.realpathSync(file) !== path.join(fs.realpathSync(repoRoot), binding.path))
+            throw new SecretError("service custody must name one regular sealed member inside this product");
+        if (!envelopeOf(fs.readFileSync(file, "utf8")).keys.includes(binding.key))
+            throw new SecretError("service custody does not hold the declared key");
+    }
+    catch {
+        throw new SecretError("service custody is missing, ambiguous or outside this product");
+    }
+    return file;
+}
+/** Native service loader: one exact key, decrypted in memory through the common identity/SOPS owner, never an env fallback. */
+export function serviceCredentialValue(repoRoot, binding, sops) {
+    const file = serviceCredentialFile(repoRoot, binding);
+    try {
+        const envelope = envelopeOf(fs.readFileSync(file, "utf8"));
+        if (!envelope.keys.includes(binding.key))
+            throw new SecretError("service credential key is absent from the selected member");
+        const value = sops.decrypt(file, envelope.format)[binding.key];
+        if (typeof value !== "string" || !value.length)
+            throw new SecretError("service credential key is empty or absent");
+        return value;
+    }
+    catch {
+        throw new SecretError("service credential custody could not be opened; check its member, key and owner identity");
+    }
+}
 /**
  * Build and validate a replacement envelope without publishing it. An existing member is decrypted only when it holds a key
  * `values` does not replace; a member whose every key is replaced (the one-key member a `set` re-seals) needs no age identity.

package/src/main.d.mts

@@ -1,3 +1,4 @@
+import { type HeavyNodeRun } from '../runtime/scripts/api/node/run-node.mjs';
 import { type LockResult } from '../scaffold/app.mjs';
 import type { GhSpawn } from '../ci/github.mjs';
 import type { Prompt } from '../runtime/scripts/hfs/secret-prompt.mjs';
@@ -39,6 +40,7 @@ interface AppIo {
     stackIo?: Record<string, unknown> | undefined;
     runLinter?: LinterRunner | undefined;
     checkApp?: ((args: Dynamic) => Dynamic) | undefined;
+    runHeavyNode?: HeavyNodeRun | undefined;
     /** --quiet: no progress on stderr (the diagnosis stays). */
     quiet?: boolean | undefined;
     stderrIsTty?: boolean | undefined;
@@ -57,5 +59,5 @@ export declare function appRootAbove(dir: string): string;
  * the HFS check and `stackIo` Swarm tools; production defaults execute every check. `hostIdentity` ({ label, read }) is the
  * harness CLI's own secret.env SOPS_AGE_KEY, which every verb that opens a sealed member (secret, stack, release, db) reads last for the age identity (decryptionIdentity); `prompt` replaces its masked prompt.
  */
-export declare function main(argv: string[], { cwd: baseCwd, harness, stdout, stderr, presets, prettier, lock, run, stackMain, env, stdin, prompt, hostIdentity, sops, tools, platform, stackIo, runLinter, checkApp, stderrIsTty, }?: MainOptions): Promise<number>;
+export declare function main(argv: string[], { cwd: baseCwd, harness, stdout, stderr, presets, prettier, lock, run, stackMain, env, stdin, prompt, hostIdentity, sops, tools, platform, stackIo, runLinter, runHeavyNode, checkApp, stderrIsTty, }?: MainOptions): Promise<number>;
 export {};

package/src/main.mjs

@@ -64,7 +64,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 //   starci app secret materialize --env <env> | list --env <env> | verify --env <env> | recipients --env <env> [--add|--remove <age1...|owner>] [--execute]
 //                                            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] [--execute]  reads the value from stdin only; dry until --execute.
+//   starci app ci secret set <NAME> [--from-custody] [--env E | --dependabot] [--repo owner/name] [--execute]  stdin or the explicit service custody binding; dry until --execute.
 //   starci app ci var set <NAME> [--env E] [--value v] [--execute] | var sync [--execute] | verify [--json] | local [--execute]
 //                                            declared GitHub CI custody; verify compares names, scopes and public values; local prints the CI plan, --execute runs it.
 //   starci app db new <name> | baseline | restamp --map <restamp.yaml> | migrate | post-cutover | dump | drift   [--db-url-env <NAME>]
@@ -83,6 +83,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 // Every finding names a why code and carries its Vietnamese text. check, lint and slot read the app, never write to it. Exit codes:
 // 0 clean, 1 error findings, 2 a refusal or bad usage.
 import fs from 'node:fs';
+import { isHostHeld } from '../runtime/scripts/api/node/run-node.mjs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -99,13 +100,13 @@ import { HFS_DECLARATION_FILE, HfsSlotsError, loadSlotManifest, readRepoDeclarat
 import { main as syncMain } from '../sync/cli.mjs';
 import { runWorkHygiene } from '../sync/hygiene.mjs';
 import { SyncError, bundledPresets } from '../sync/index.mjs';
-import { emitContracts } from '../emit/contracts.mjs';
+import { emitContractsAsync } from '../emit/contracts.mjs';
 import { ScaffoldError, newService, newSpec } from '../scaffold/service.mjs';
 import { EditionRefusal } from '../scaffold/edition-gate.mjs';
 import { addKind } from '../scaffold/add.mjs';
 import { scaffoldApp } from '../scaffold/app.mjs';
 import { newImages } from '../scaffold/image.mjs';
-import { cachedLinters, eslintRepository, lintRepository, parseLintArgs, printLintText } from '../lint/run.mjs';
+import { cachedLinters, eslintRepository, lintRepository, parseLintArgs, printLintText, runLinter as nativeLinter } from '../lint/run.mjs';
 import { runSonarForApp, runTestForApp, runTestShard, runTypesForApp } from '../cache/app-families.mjs';
 import { CACHE_ENV, createDiskSession } from '../cache/session.mjs';
 import { DEFAULT_FAMILIES, runAppFamilies } from '../cache/run.mjs';
@@ -359,7 +360,7 @@ function openSession({ repoRoot, tracked, io, full, use, planned }) {
 async function appPass({ repoRoot, harness, only, presets, prettier, io, selected, full, use = 'normal', session: given }) {
     const tracked = trackedFiles(repoRoot);
     const session = given ?? openSession({ repoRoot, tracked, io, full, use: only === undefined ? use : 'bypass', planned: tracked.length * Math.max(1, selected.size) });
-    const result = await runAppFamilies({ repoRoot, tracked, session, selected, harness, presets, prettier, only, edition: undefined });
+    const result = await runAppFamilies({ repoRoot, tracked, session, selected, harness, presets, prettier, only, edition: undefined, execute: io.runHeavyNode });
     if (given !== undefined)
         return result;
     const flushed = session.flush();
@@ -529,9 +530,9 @@ async function checkRun({ io, selected, full, use, coverageFrom }) {
             eslint = await eslintRepository({ repoRoot, changed: null, existing: [], run: runLinter });
     }
     if (session !== undefined && selected.has('types'))
-        extra.push(...runTypesForApp(session, { repoRoot, tracked, env: io.env }).findings);
+        extra.push(...(await runTypesForApp(session, { repoRoot, tracked, env: io.env, execute: io.runHeavyNode })).findings);
     if (session !== undefined && selected.has('test')) {
-        const tests = await runTestForApp(session, { repoRoot, tracked });
+        const tests = await runTestForApp(session, { repoRoot, tracked, execute: io.runHeavyNode });
         extra.push(...tests.findings);
     }
     if (session !== undefined && selected.has('sonar'))
@@ -589,7 +590,7 @@ async function checkMain(opts, io) {
         const total = Number(match?.[2]);
         if (match === null || !Number.isSafeInteger(index) || !Number.isSafeInteger(total) || index < 1 || total < index)
             throw new Error('--shard needs <i>/<n> with 1 <= i <= n');
-        return runTestShard(repoRoot, index, total);
+        return runTestShard(repoRoot, index, total, io.runHeavyNode);
     }
     // A coverage report judged on its own (the merge job of a sharded run) runs no family; with selectors it comes on top of them.
     const selected = explicit.size > 0 ? explicit : coverageFrom === undefined ? new Set(DEFAULT_FAMILIES) : new Set();
@@ -609,13 +610,13 @@ async function checkMain(opts, io) {
     writeRunLog(repoRoot, { command: `check${[...new Set(listFlag(opts, 'gate') ?? [])].map((gate) => ` --gate ${gate}`).join('')}${opts['no-cache'] === true ? ' --no-cache' : ''}${coverageFrom === undefined ? '' : ` --coverage-from ${JSON.stringify(coverageFrom)}`}`, seconds, exit, families: result.families.map((report) => ({ ...report, seconds: 0 })) }, io.env);
     return exit;
 }
-function emitMain(opts, { cwd: repoRoot, stdout: out }) {
+async function emitMain(opts, { cwd: repoRoot, stdout: out, runHeavyNode }) {
     if (opts.positional.length)
         throw new Error('starci app emit takes no path');
     const be = readRepoDeclaration(loadSlotManifest(), repoRoot).sides?.be;
     if (!be)
         throw new Error('starci app emit runs at the app root (the folder of hfs.json)');
-    const { written, skipped, standIns } = emitContracts({ repoRoot: path.join(repoRoot, 'be'), declaration: be });
+    const { written, skipped, standIns } = await emitContractsAsync({ repoRoot: path.join(repoRoot, 'be'), declaration: be, execute: runHeavyNode });
     for (const file of written)
         out(`wrote be/${file}\n`);
     const skipSummary = skipped.length ? `, ${skipped.join(', ')} serve no GraphQL` : '';
@@ -737,7 +738,7 @@ function errorMessage(error) {
  * the HFS check and `stackIo` Swarm tools; production defaults execute every check. `hostIdentity` ({ label, read }) is the
  * harness CLI's own secret.env SOPS_AGE_KEY, which every verb that opens a sealed member (secret, stack, release, db) reads last for the age identity (decryptionIdentity); `prompt` replaces its masked prompt.
  */
-export async function main(argv, { cwd: baseCwd = process.cwd(), harness, stdout = (s) => process.stdout.write(s), stderr = (s) => process.stderr.write(s), presets, prettier, lock, run, stackMain, env = process.env, stdin, prompt, hostIdentity, sops, tools, platform, stackIo, runLinter, checkApp, stderrIsTty = process.stderr.isTTY === true, } = {}) {
+export async function main(argv, { cwd: baseCwd = process.cwd(), harness, stdout = (s) => process.stdout.write(s), stderr = (s) => process.stderr.write(s), presets, prettier, lock, run, stackMain, env = process.env, stdin, prompt, hostIdentity, sops, tools, platform, stackIo, runLinter, runHeavyNode, checkApp, stderrIsTty = process.stderr.isTTY === true, } = {}) {
     try {
         const global = globalOptions(argv, path.resolve(baseCwd));
         const [verb, ...given] = global.argv;
@@ -752,10 +753,12 @@ export async function main(argv, { cwd: baseCwd = process.cwd(), harness, stdout
             return 2;
         }
         const { edition, argv: rest } = editionOption(verb, given);
-        return await dispatchMain(verb, rest, { cwd: global.cwd, harness, edition, quiet: global.quiet, stderrIsTty, stdout: out, stderr, presets, prettier, lock, run, stackMain, env, stdin, prompt, hostIdentity, sops, tools, platform, stackIo, runLinter, checkApp });
+        return await dispatchMain(verb, rest, { cwd: global.cwd, harness, edition, quiet: global.quiet, stderrIsTty, stdout: out, stderr, presets, prettier, lock, run, stackMain, env, stdin, prompt, hostIdentity, sops, tools, platform, stackIo, runHeavyNode, runLinter: runLinter ?? ((spec) => nativeLinter(spec, runHeavyNode)), checkApp });
     }
     catch (error) {
         stderr(errorMessage(error));
+        if (isHostHeld(error))
+            return 75;
         return 2;
     }
 }

package/sync/ci-commands.mjs

@@ -35,7 +35,7 @@ function sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor, timeout) {
     if (!sonar)
         return '';
     const condition = SONAR_CONDITION;
-    const host = sonar.provider === 'sonarcloud' ? 'https://sonarcloud.io' : `\${{ vars.${sonar.hostVar} }}`;
+    const host = sonar.hostSecret ? `\${{ secrets.${sonar.hostSecret} }}` : sonar.provider === 'sonarcloud' ? 'https://sonarcloud.io' : `\${{ vars.${sonar.hostVar} }}`;
     const header = [
         '  sonar:',
         '    needs: [plan, lint, coverage]',
@@ -52,6 +52,7 @@ function sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor, timeout) {
         `        if: ${condition}`,
         '        run: |',
         `          if [ -z "$SONAR_TOKEN" ]; then echo "::error::SONAR_TOKEN is not set: Sonar is required, so a missing token fails this job (secret ${sonar.token})"; exit 1; fi`,
+        '          if [ -z "$SONAR_HOST_URL" ]; then echo "::error::SONAR_HOST_URL is not set: the declared analysis endpoint is required"; exit 1; fi',
         `      - uses: ${DOWNLOAD_ARTIFACT}`,
         `        if: ${condition}`,
         '        with:',

package/sync/quality-services.mjs

@@ -1,7 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { parseYaml as bundledParseYaml } from '../runtime/engine/yaml.mjs';
-import { qualityServices } from '../runtime/scripts/hfs/ci-declaration.mjs';
+import { qualityServices, serviceCredentialNames } from '../runtime/scripts/hfs/ci-declaration.mjs';
+import { repositoryName, identityQueryEnvironment } from '../runtime/scripts/hfs/repo-identity.mjs';
 import { isRuntimeExampleApp } from '../runtime/scripts/lib/runtime-example.mjs';
 import { badgeTokenNotices, renderReadmeBadges } from './readme-badges.mjs';
 import { DECLARATION } from './sonar-key.mjs';
@@ -19,7 +20,7 @@ export function hasDeclaredServices(root, { parseYaml = bundledParseYaml } = {})
 export function readDeclaredQuality(root, { parseYaml = bundledParseYaml } = {}) {
     try {
         const doc = parseYaml(fs.readFileSync(path.join(root, DECLARATION), 'utf8'));
-        return qualityServices(doc, { example: isRuntimeExampleApp(root) });
+        return qualityServices(doc, { example: isRuntimeExampleApp(root), repository: repositoryName(root, { env: identityQueryEnvironment(process.env, serviceCredentialNames(doc)) }) });
     }
     catch {
         return qualityServices({});

package/sync/readme-badges.mjs

@@ -17,7 +17,7 @@ export function renderReadmeBadges(doc, { repository, example = false } = {}) {
     const branch = encodeURIComponent(github.defaultBranch ?? 'main');
     const workflow = encodeURIComponent(github.workflow ?? 'ci.yml');
     const base = `https://github.com/${repo}`;
-    const quality = qualityServices(doc, { example });
+    const quality = qualityServices(doc, { example, repository: repo.split('/')[1] });
     const lines = [badge('CI', `${base}/actions/workflows/${workflow}/badge.svg?branch=${branch}`, `${base}/actions/workflows/${workflow}`)];
     if (quality.codecov.enabled) {
         const params = [];

package/sync/sonar-key.d.mts

@@ -1,9 +1,9 @@
+import { repositoryName } from '../runtime/scripts/hfs/repo-identity.mjs';
+export { repositoryName };
 type Declaration = any;
 type ParseYaml = (text: string) => Declaration;
 /** The stack declaration, app-relative: .starcistacks sits at the app root, beside be/, fe/ and .starciwork. */
 export declare const DECLARATION: string;
-/** The repository name the declaration lists its projects under: the app package.json name, else the folder name. */
-export declare function repositoryName(root: string): string;
 /** The keys services.sonar declares for `repository` in a parsed declaration (empty when it declares none). */
 export declare function declaredSonarKeys(declaration: Declaration, repository: string): string[];
 /**
@@ -28,4 +28,3 @@ export declare function readDeclaredSonarGate(root: string, { parseYaml }?: {
 } | null;
 /** The quality-gate name for an app edition from the one sonar-gate document. */
 export declare function sonarGateName(document: Declaration, edition?: string): string | null;
-export {};

package/sync/sonar-key.mjs

@@ -4,20 +4,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { parseYaml as bundledParseYaml } from '../runtime/engine/yaml.mjs';
+import { repositoryName, identityQueryEnvironment } from '../runtime/scripts/hfs/repo-identity.mjs';
+import { serviceCredentialNames } from '../runtime/scripts/hfs/ci-declaration.mjs';
+export { repositoryName };
 /** The stack declaration, app-relative: .starcistacks sits at the app root, beside be/, fe/ and .starciwork. */
 export const DECLARATION = path.join('.starcistacks', 'application-stacks.yaml');
-/** The repository name the declaration lists its projects under: the app package.json name, else the folder name. */
-export function repositoryName(root) {
-    try {
-        const name = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).name;
-        if (typeof name === 'string' && name)
-            return name;
-    }
-    catch {
-        // no readable package.json: the folder name stands in
-    }
-    return path.basename(path.resolve(root));
-}
 /** The keys services.sonar declares for `repository` in a parsed declaration (empty when it declares none). */
 export function declaredSonarKeys(declaration, repository) {
     const projects = declaration?.services?.sonar?.projects;
@@ -35,9 +26,11 @@ export async function readDeclaredSonarKey(root, { parseYaml, fail }) {
     if (!fs.existsSync(file))
         return null;
     const parse = parseYaml ?? bundledParseYaml;
-    const keys = declaredSonarKeys(parse(fs.readFileSync(file, 'utf8')), repositoryName(root));
+    const doc = parse(fs.readFileSync(file, 'utf8'));
+    const repository = repositoryName(root, { env: identityQueryEnvironment(process.env, serviceCredentialNames(doc)) });
+    const keys = declaredSonarKeys(doc, repository);
     if (keys.length > 1)
-        fail(`${DECLARATION.split(path.sep).join('/')} declares ${keys.length} Sonar projects for ${repositoryName(root)} (${keys.join(', ')}); one app has one key`);
+        fail(`${DECLARATION.split(path.sep).join('/')} declares ${keys.length} Sonar projects for ${repository} (${keys.join(', ')}); one app has one key`);
     return keys[0] ?? null;
 }
 /**

package/templates/app/skeleton/.starcistacks/application-stacks.yaml

@@ -181,11 +181,15 @@ services:
       environment: dev
       compose: compose.yaml
     auth: token
-    credentials: []
+    credentials:
+      - id: analysis
+        project: "{{project}}"
+        key: SONAR_TOKEN
+        custody: {repository: "{{project}}", path: .starcistacks/dev/secrets/sonar.enc.yaml}
     projects: [{repository: "{{project}}", key: "{{project}}"}]
-    ci: {wiring: required, workflow: .github/workflows/ci.yml, token: SONAR_TOKEN, hostVar: SONAR_HOST_URL}
+    ci: {wiring: required, workflow: .github/workflows/ci.yml, token: SONAR_TOKEN, hostVar: SONAR_HOST_URL, secrets: [{name: SONAR_TOKEN, credential: analysis}]}
     ownerAction:
-      needed: Provision this app's Sonar host and project, then set SONAR_TOKEN with starci app ci secret set SONAR_TOKEN --execute and sync SONAR_HOST_URL.
+      needed: Declare this app's connection profile and project credential with its actual sealed member/key and project reference, seal it through starci app secret, bind ci.secrets to that credential, then set the CI execution copy with starci app ci secret set SONAR_TOKEN --from-custody --execute and sync SONAR_HOST_URL.
       reason: A fresh app declares its quality service without fabricating credentials or a successful analysis.
   codecov:
     provider: codecov

package/templates/app/skeleton-lite/.starcistacks/application-stacks.yaml

@@ -270,11 +270,15 @@ services:
       environment: dev
       compose: compose.yaml
     auth: token
-    credentials: []
+    credentials:
+      - id: analysis
+        project: "{{project}}"
+        key: SONAR_TOKEN
+        custody: {repository: "{{project}}", path: .starcistacks/dev/secrets/sonar.enc.yaml}
     projects: [{repository: "{{project}}", key: "{{project}}"}]
-    ci: {wiring: required, workflow: .github/workflows/ci.yml, token: SONAR_TOKEN, hostVar: SONAR_HOST_URL}
+    ci: {wiring: required, workflow: .github/workflows/ci.yml, token: SONAR_TOKEN, hostVar: SONAR_HOST_URL, secrets: [{name: SONAR_TOKEN, credential: analysis}]}
     ownerAction:
-      needed: Provision this app's Sonar host and project, then set SONAR_TOKEN with starci app ci secret set SONAR_TOKEN --execute and sync SONAR_HOST_URL.
+      needed: Declare this app's connection profile and project credential with its actual sealed member/key and project reference, seal it through starci app secret, bind ci.secrets to that credential, then set the CI execution copy with starci app ci secret set SONAR_TOKEN --from-custody --execute and sync SONAR_HOST_URL.
       reason: A fresh app declares its quality service without fabricating credentials or a successful analysis.
   codecov:
     provider: codecov