@starci/hfs 5.0.4 → 5.0.6

package/release/gate.mjs

@@ -7,7 +7,9 @@ import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { isPlainObject as plain } from '../runtime/engine/plain-object.mjs';
-import { qualityServices } from '../runtime/scripts/hfs/ci-declaration.mjs';
+import { qualityServices, serviceBindings, projectServiceCredential, serviceCredentialNames } from '../runtime/scripts/hfs/ci-declaration.mjs';
+import { repositoryName, identityQueryEnvironment } from '../runtime/scripts/hfs/repo-identity.mjs';
+import { serviceCredentialFile, serviceCredentialValue } from '../runtime/scripts/hfs/secret-store.mjs';
 import { openHfs } from '../runtime/scripts/hfs/slots.mjs';
 import { firstLine, lines, tool } from '../stack/context.mjs';
 import { failure, refusal } from '../stack/errors.mjs';
@@ -74,21 +76,72 @@ function auditGate(audit) {
         throw refusal(RELEASE_CODE, 'services.audit.level must be an npm audit level');
     return { name: 'audit', command: ['npm', 'audit', ...(audit.omitDev ? ['--omit=dev'] : []), `--audit-level=${audit.level}`], summary: null, env: {} };
 }
-/** A requested local Sonar scan uses only the declared host and token variable; the token never enters argv. */
-function sonarGate(services, env) {
+/** The CI execution copy is job-local; a native owner run opens the selected product credential only when executed. */
+function sonarGate(services, ctx, execute) {
+    const env = ctx.env;
     const configured = services?.sonar;
-    const sonar = configured?.provider === 'sonarcloud' ? { ...configured, host: 'https://sonarcloud.io' } : configured;
+    let sonar = configured?.provider === 'sonarcloud' ? { ...configured, host: configured.host || 'https://sonarcloud.io' } : configured;
     const tokenName = sonar?.token;
-    if (!sonar?.host || !ENV_KEY.test(tokenName) || !env[tokenName])
-        throw refusal('RELEASE_SONAR_UNAVAILABLE', 'declare an enabled services.sonar host and set its ci.token environment variable');
-    const command = ['npx', '--yes', '@sonar/scan@4.3.0', `-Dsonar.host.url=${sonar.host}`];
+    if (!sonar || !ENV_KEY.test(tokenName))
+        throw refusal('RELEASE_SONAR_UNAVAILABLE', 'declare an enabled services.sonar host and ci.token selector');
+    let token;
+    let privateHost;
+    if (env.GITHUB_ACTIONS === 'true') {
+        token = env[tokenName];
+        if (!token)
+            throw refusal('RELEASE_SONAR_UNAVAILABLE', 'the declared Sonar CI execution copy is missing');
+        if (sonar.hostCredential) {
+            privateHost = env[sonar.hostVar || 'SONAR_HOST_URL'];
+            sonar = { ...sonar, host: privateHost ?? null, privateHost: true };
+        }
+    }
+    else {
+        const doc = services.declaration;
+        const repository = repositoryName(ctx.cwd, { env: identityQueryEnvironment(env, serviceCredentialNames(doc)) });
+        const selected = serviceBindings(doc, repository);
+        const binding = selected.bindings.find((item) => item.service === 'sonar' && item.name === tokenName);
+        if (selected.problems.length || !binding)
+            throw refusal('RELEASE_SONAR_UNAVAILABLE', 'declare one explicit Sonar project credential binding in this product');
+        try {
+            serviceCredentialFile(ctx.cwd, binding);
+            if (execute)
+                token = serviceCredentialValue(ctx.cwd, binding, ctx.sops);
+            if (sonar.hostCredential) {
+                const endpoint = projectServiceCredential(doc, 'sonar', sonar.hostCredential, repository);
+                if (!endpoint)
+                    throw new Error('invalid endpoint reference');
+                serviceCredentialFile(ctx.cwd, endpoint);
+                if (execute)
+                    privateHost = serviceCredentialValue(ctx.cwd, endpoint, ctx.sops);
+                sonar = { ...sonar, host: privateHost ?? null, privateHost: true };
+            }
+        }
+        catch {
+            throw refusal('RELEASE_SONAR_UNAVAILABLE', 'the selected Sonar project custody is missing or cannot be opened');
+        }
+    }
+    if (!sonar.host && !(sonar.hostCredential && !execute))
+        throw refusal('RELEASE_SONAR_UNAVAILABLE', 'the declared Sonar connection URL is missing');
+    if (sonar.host) {
+        try {
+            const url = new URL(sonar.host);
+            if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password)
+                throw new Error('invalid URL');
+        }
+        catch {
+            throw refusal('RELEASE_SONAR_UNAVAILABLE', 'the Sonar connection must be HTTP(S), with login kept in separate sealed credential keys');
+        }
+    }
+    const command = ['npx', '--yes', '@sonar/scan@4.3.0', ...(sonar.privateHost ? [] : [`-Dsonar.host.url=${sonar.host}`])];
+    if (sonar.projectKey)
+        command.push(`-Dsonar.projectKey=${sonar.projectKey}`);
     const organization = sonar.organization ?? (sonar.organizationVar ? env[sonar.organizationVar] : null);
     if (organization)
         command.push(`-Dsonar.organization=${organization}`);
     if (!command.every((word) => TOKEN.test(word)))
         throw refusal('RELEASE_SONAR_UNAVAILABLE', 'Sonar host and organization must be plain command arguments');
-    return { name: 'sonar', command, summary: null, env: { SONAR_TOKEN: env[tokenName] }, provider: sonar,
-        credentialNames: [...new Set(['SONAR_TOKEN', tokenName])] };
+    return { name: 'sonar', command, summary: null, env: { ...(token === undefined ? {} : { SONAR_TOKEN: token }), ...(privateHost ? { SONAR_HOST_URL: privateHost } : {}) }, provider: sonar,
+        credentialNames: [...new Set(['SONAR_TOKEN', tokenName, ...serviceCredentialNames(services.declaration), ...(sonar.hostCredential ? ['SONAR_HOST_URL', sonar.hostVar] : [])].filter((name) => typeof name === 'string'))] };
 }
 function gateProblems(entry, at, seen) {
     const found = [];
@@ -261,7 +314,7 @@ async function sonarAvailability(ctx, gate) {
     }
     if (up)
         return null;
-    return { pass: false, detail: `${SONAR_UNREACHABLE}: ${sonar.host} did not report UP within ten seconds` };
+    return { pass: false, detail: `${SONAR_UNREACHABLE}: ${sonar.privateHost ? 'the declared private host' : sonar.host} did not report UP within ten seconds` };
 }
 /** An unreachable Sonar host stays a red row with a real log and no scan invocation. */
 export async function runAvailableGate(ctx, gate, options) {
@@ -292,12 +345,18 @@ async function judgeQualityGate(ctx, gate, row) {
         return row;
     const started = ctx.now();
     const verdict = await sonarQualityGate(ctx, { cwd: ctx.cwd, host: gate.provider.host, token: gate.env.SONAR_TOKEN });
-    const failed = (verdict.conditions ?? []).map((line) => `  failed: ${line}\n`).join('');
-    fs.appendFileSync(row.log, `\nquality gate: ${verdict.detail}\n${failed}`);
-    return { ...row, pass: verdict.pass, detail: verdict.detail, seconds: row.seconds + Math.round((ctx.now() - started) / 1000), logSha256: sha256(row.log) };
+    const detail = redactGateText(gate, verdict.detail);
+    const failed = (verdict.conditions ?? []).map((line) => `  failed: ${redactGateText(gate, line)}\n`).join('');
+    fs.appendFileSync(row.log, `\nquality gate: ${detail}\n${failed}`);
+    return { ...row, pass: verdict.pass, detail, seconds: row.seconds + Math.round((ctx.now() - started) / 1000), logSha256: sha256(row.log) };
+}
+/** Scanner output and the later server verdict share one redaction boundary. */
+function redactGateText(gate, text) {
+    const values = gate.provider ? [gate.env.SONAR_TOKEN, ...(gate.provider.privateHost ? [gate.env.SONAR_HOST_URL] : [])].filter((value) => Boolean(value)) : [];
+    return values.reduce((redacted, value) => redacted.replaceAll(value, '[REDACTED]'), text);
 }
 export const withoutCredentials = (values, credentialNames) => {
-    const selected = new Set(credentialNames);
+    const selected = new Set([...credentialNames, 'SOPS_AGE_KEY', 'SOPS_AGE_KEY_FILE'].map((name) => name.toUpperCase()));
     return Object.fromEntries(Object.entries(values ?? {}).filter(([key]) => !selected.has(key.toUpperCase())));
 };
 export function runGate(ctx, gate, { dir, platform, credentialNames, preface = '' }) {
@@ -308,11 +367,10 @@ export function runGate(ctx, gate, { dir, platform, credentialNames, preface = '
     const env = { ...ctx.env, ...(gate.provider ? gate.env : withoutCredentials(gate.env, credentialNames)), ...RELEASE_CACHE_ENV };
     const run = tool(ctx, command, args, { cwd: ctx.cwd, env });
     const output = `${run.stdout ?? ''}${run.stderr ?? ''}`;
-    const text = gate.name === 'sonar' && gate.env.SONAR_TOKEN ? output.replaceAll(gate.env.SONAR_TOKEN, '[REDACTED]') : output;
+    const text = redactGateText(gate, output);
     fs.writeFileSync(log, preface + text);
     const verdict = judgeVerdict(run, gate, text);
-    if (gate.name === 'sonar' && gate.env.SONAR_TOKEN)
-        verdict.detail = verdict.detail.replaceAll(gate.env.SONAR_TOKEN, '[REDACTED]');
+    verdict.detail = redactGateText(gate, verdict.detail);
     const seconds = Math.round((ctx.now() - started) / 1000);
     return {
         name: gate.name, command: gate.command.join(' '), pass: verdict.pass, detail: verdict.detail, seconds,
@@ -459,7 +517,7 @@ function backfillRed(ctx, { common, urgent, failed, openTicket }) {
 export async function releaseGate(ctx, config, options = {}) {
     // Sonar is a row of the managed CI, so it is a row of the local gate whenever the app declares services.sonar; a missing token is a refusal, never a skip.
     if (config.services?.sonar)
-        config = { ...config, gates: [...config.gates.filter((gate) => gate.name !== 'sonar'), sonarGate(config.services, ctx.env)] };
+        config = { ...config, gates: [...config.gates.filter((gate) => gate.name !== 'sonar'), sonarGate(config.services, ctx, options.execute === true)] };
     const credentialNames = config.gates.find(gate => gate.provider)?.credentialNames ?? ['SONAR_TOKEN', config.services?.sonar?.token].filter(Boolean);
     ctx = Object.create(ctx, { env: { value: withoutCredentials(ctx.env, credentialNames) } });
     // The CI verdict of a release is the candidate run of its own sha, judged by `starci app release push` (candidate-ci.mjs, OWNER RULING candidate-ci 2026-10-18):

package/release/index.d.mts

@@ -42,13 +42,13 @@ export declare function contextOf(io?: VerbIo): VerbContext;
 export declare function readDeclaration(root: string): Record<string, any>;
 /** The normalised `release:` block (tolerant of absence) with the package version: { root, version, gates, tagPrefix, defaultBranch, requireCi }. */
 export declare function loadReleaseConfig(root: string): {
+    services: any;
     root: string;
     version: any;
     gates: import("./gate.mjs").Gate[];
     tagPrefix: string;
     defaultBranch: string;
     requireCi: boolean;
-    services: any;
 };
 /** Parses the flags, runs `run(ctx, flags, positional)` and prints its result; returns the exit code. Only StackError is mapped, anything else is a bug and propagates. */
 export declare function runVerb({ label, name, io, argv, spec, run, code }: {

package/release/index.mjs

@@ -10,11 +10,13 @@ import path from 'node:path';
 import { isPlainObject as plain } from '../runtime/engine/plain-object.mjs';
 import { parseYaml } from '../runtime/engine/yaml.mjs';
 import { isRuntimeExampleApp } from '../runtime/scripts/lib/runtime-example.mjs';
+import { repositoryName, identityQueryEnvironment } from '../runtime/scripts/hfs/repo-identity.mjs';
+import { serviceCredentialNames } from '../runtime/scripts/hfs/ci-declaration.mjs';
 import { hasEntityList } from '../db/entity-list.mjs';
 import { STACKS_DIR, STACKS_FILE } from '../stack/config.mjs';
 import { stackContext } from '../stack/context.mjs';
 import { EXIT, StackError, refusal } from '../stack/errors.mjs';
-import { RELEASE_CODE, VERSION, normalizeRelease, releaseGate } from './gate.mjs';
+import { RELEASE_CODE, VERSION, normalizeRelease, releaseGate, withoutCredentials } from './gate.mjs';
 import { releasePush } from './push.mjs';
 import { releaseUrgentPush } from './urgent.mjs';
 const IO_KEYS = ['cwd', 'stdout', 'stderr', 'env', 'sops', 'hostIdentity'];
@@ -77,10 +79,11 @@ export function loadReleaseConfig(root) {
     if (typeof pkg.version !== 'string' || !VERSION.test(pkg.version))
         throw refusal(RELEASE_CODE, 'package.json needs a version like 1.2.3 (the release tag derives from it)');
     const declaration = readDeclaration(root);
-    const { config, problems } = normalizeRelease(declaration.release, pkg.scripts, declaration.services, { example: isRuntimeExampleApp(root), entities: hasEntityList(root) });
+    const { config, problems } = normalizeRelease(declaration.release, pkg.scripts, declaration.services, { example: isRuntimeExampleApp(root), entities: hasEntityList(root),
+        repository: repositoryName(root, { env: identityQueryEnvironment(process.env, serviceCredentialNames(declaration)) }) });
     if (!config)
         throw refusal(RELEASE_CODE, `${problems.length} problem(s) in release: ${problems.slice(0, 6).join('; ')}`);
-    return { root, version: pkg.version, ...config };
+    return { root, version: pkg.version, ...config, services: { ...config.services, declaration } };
 }
 function print(ctx, name, flags, result) {
     if (flags.json)
@@ -119,6 +122,7 @@ const ACTIONS = {
             if (flags.reason !== undefined && flags.urgent !== true)
                 throw refusal('RELEASE_USAGE', '--reason belongs to an urgent release (--urgent)');
             const config = loadReleaseConfig(ctx.cwd);
+            ctx = Object.create(ctx, { env: { value: withoutCredentials(ctx.env, serviceCredentialNames(config.services?.declaration)) } });
             if (flags.urgent === true)
                 return releaseUrgentPush(ctx, config, { execute: flags.execute === true, remote: flags.remote, reason: flags.reason, role: harness?.role ?? ctx.env.STARCI_ROLE });
             return releasePush(ctx, config, { execute: flags.execute === true, remote: flags.remote });

package/runtime/knowledge/grammars/index.yaml

@@ -69,7 +69,17 @@ families:
       entry: '@starci/grammar/common'
       styleEntry: '@starci/grammar/common.css'
       semanticRoles:
-        page: { export: Page, entries: ['@starci/grammar/common', '@starci/grammar/<family>'], segment: { attribute: header, member: tabs }, bodyContainers: [PaneGrid, Pane] }
+        page:
+          export: Page
+          entries: ['@starci/grammar/common', '@starci/grammar/<family>']
+          segment: { attribute: header, member: tabs }
+          bodyContainers: [PaneGrid, Pane, Stack, PaneSection, Section]
+          # Native body transparency follows the renderer's exact context, status and intrinsic-element API.
+          bodyContainerConstraints:
+            Pane: { providesContext: pane }
+            Stack: { literalProps: { as: [div, header, footer] } }
+            PaneSection: { requiresContext: pane, absentProps: [error], literalProps: { as: [div, header, footer] } }
+            Section: { absentProps: [error], literalProps: { kind: [region] } }
       peers: [react, '@heroui/react', '@xyflow/react', react-aria-components]
     packageSnapshot: common/DNA.yaml
     scope: |

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -31,35 +31,35 @@ pins:
     source: packages/event-stream/package.json
     why: 'the one server-sent-events client of every front end (fe-stack event-stream, owner:event-stream-package): the transport client layer (modules/api/sse/clients) creates one instance for the app with the bearer token source and the stream operations follow on it; it carries Last-Event-ID resume, the capped doubling backoff, the heartbeat timeout, the single 401 renewal and the useSWRSubscription adapter, so no app keeps a hand-written reader.'
   '@starci/grammar':
-    version: 0.21.8
+    version: 0.21.10
     group: starci
     install: registry
     side: fe
     source: packages/grammar/package.json
     why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.11.15
+    version: 3.11.17
     group: starci
     install: registry
     side: be
     source: packages/eslint-canon-be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 9.9.8
+    version: 9.9.10
     group: starci
     install: registry
     side: fe
     source: packages/eslint-canon-fe/package.json
     why: 'the front-end ESLint canon: `loadHfs(import.meta.url)` of fe/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the fe side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; the front end has no tests (FE_NO_TESTS R97 in hfs) and no-vietnamese-in-source (R91) applies.'
   '@starci/eslint-grammar-core':
-    version: 0.21.8
+    version: 0.21.10
     group: starci
     install: registry
     side: fe
     source: packages/eslint-grammar-core/package.json
     why: 'the StarCi Grammar component API lint, versioned with @starci/grammar; front ends compose this family package with the universal FE canon.'
   '@starci/eslint-grammar-offset-pop':
-    version: 0.21.8
+    version: 0.21.10
     group: starci
     install: registry
     side: fe
@@ -106,7 +106,7 @@ pins:
     source: packages/ai-router/package.json
     why: 'the AI pool router of a back end: a NestJS module that routes OpenAI-compatible chat, stream and embeddings calls across keys, models and providers, with @starci/ai-router/testing for its specs; @starci/jest-preset compiles it as an ESM-only dependency.'
   '@starci/hfs':
-    version: 5.0.4
+    version: 5.0.6
     group: starci
     install: registry
     side: both

package/runtime/knowledge/hfs/rules.yaml

@@ -5107,7 +5107,7 @@ rules:
       - {path: packages/eslint/be/module-shape.spec.mjs, editions: [lite, full], codes: [BE_MODULE_DEFINITION_MISSING]}
   - id: R296
     code: "CI_SECRET_SEALED"
-    law: "A name declared in ci.secrets or ci.dependabot.secrets never names a key stored inside an app sealed .starcistacks/<env>/secrets/<member>.enc member. App runtime and CI custody are separate; checks inspect key names without decrypting or printing values."
+    law: "A sealed CI credential copy names an explicit service credential bound to the selected product project, environment, member and key; required product Sonar analysis uses sonar.enc.yaml and an app runtime key never becomes a CI credential. Checks inspect names without decrypting or printing values."
     kinds: [check]
     gates: [settle, land, ci]
     failureCodes: ["CI_SECRET_SEALED"]
@@ -5129,7 +5129,7 @@ rules:
       - {path: packages/hfs/src/ci-custody.spec.mjs, editions: [lite, full], codes: [CI_SECRET_SEALED]}
   - id: R297
     code: "APP_SECRET_IN_CI"
-    law: "A sealed member key granted to an app container by a deploy grant never appears in ci.secrets or ci.vars. The grant environment, member and selected key determine app custody; online GitHub custody is verified by starci app ci verify."
+    law: "A sealed member key selected by an app runtime secret declaration or deploy grant never appears in ci.secrets or ci.vars. The consumer environment, member and selected key determine app custody; online GitHub custody is verified by starci app ci verify."
     kinds: [check]
     gates: [settle, land, ci]
     failureCodes: ["APP_SECRET_IN_CI"]

package/runtime/modules/kernel/failure-codes.yaml

@@ -1742,12 +1742,12 @@ CI_DECLARATION_DRIFT:
   kind: check-finding
 
 CI_SECRET_SEALED:
-  title: "CI name overlaps sealed app custody"
+  title: "CI credential lacks exact project service custody"
   title_vi: "Tên CI trùng khóa bí mật đã niêm phong"
-  meaning_vi: "Tên CI hoặc Dependabot cũng là khóa trong thành viên .enc của ứng dụng."
+  meaning_vi: "Bản sao khóa CI không trỏ đúng dịch vụ, dự án, môi trường, thành viên và khóa đã niêm phong; khóa chạy ứng dụng không thuộc CI."
   causes_vi:
-    - "Tên CI hoặc Dependabot cũng là khóa trong thành viên .enc của ứng dụng."
-  nextStep_vi: "Bỏ khóa ứng dụng khỏi khai báo CI; đưa bí mật CI vào kho GitHub tương ứng."
+    - "Thiếu liên kết credential của dịch vụ, sai dự án hoặc dùng khóa được cấp cho container ứng dụng."
+  nextStep_vi: "Giữ khóa runtime ngoài CI; khai báo đúng credential.project và liên kết services.<id>.ci.secrets cho bản sao khóa công cụ."
   owner: op-retry
   kind: check-finding
 

package/runtime/modules/schemas/application-stacks.schema.yaml

@@ -196,7 +196,7 @@ $defs:
           local: {type: string, pattern: '^https?://[^\s]+$'}
           public: {type: string, pattern: '^https://[^\s]+$'}
           fromCredential:
-            description: A hosted endpoint carried inside a credential (a Sentry DSN) - the credential id, never the value.
+            description: A private connection URL carried inside a sealed credential - its credential id, never the value. Public local or hosted URLs use local or public.
             type: string
             pattern: '^[a-z][a-z0-9-]*$'
       stack: {$ref: '#/$defs/serviceStack'}
@@ -432,17 +432,19 @@ $defs:
       publishedBy: {type: string, minLength: 1}
   serviceCredential:
     description: >-
-      A custody reference, never a value - the repository whose stack holds it and the plaintext
-      member's path from that repository's root; the tracked <path>.enc twin must exist. The field env is the
-      variable the consuming tool reads; `key` is the field inside a structured custody file (app.yaml)
-      when the application reads the file itself. At least one of env and key is named. Sonar
-      convention (scripts/gates/sonar-local.mjs reads it): id `admin` creates projects and mints
-      tokens; a credential whose id is a project key is that project's analysis token.
+      A name-only connection or credential reference: its repository, actual sealed member path and key.
+      env names the consuming tool's variable. project references projects[].key for project-scoped tooling;
+      ids identify references independently of provider project-key syntax. Username, password and private
+      endpoint keys use separate references; operator/admin login lives in a separate authority member and
+      is never an implicit scanner or CI credential. Product Sonar analysis names exactly
+      .starcistacks/<declared-env>/secrets/sonar.enc.yaml; ci-declaration.mjs enforces that service-specific member.
+      Legacy plaintext paths with .enc twins require migration.
     type: object
     additionalProperties: false
     required: [id, custody]
     properties:
       id: {type: string, pattern: '^[a-z][a-z0-9-]*$'}
+      project: {type: string, minLength: 1, description: "The exact projects[].key this credential serves; execution selects the entry by the actual consumer repository."}
       purpose: {type: string, minLength: 1}
       env: {type: string, pattern: '^[A-Z][A-Z0-9_]*$'}
       key: {type: string, minLength: 1}
@@ -469,6 +471,7 @@ $defs:
       workflow: {type: string, minLength: 1}
       permissions: {type: array, items: {type: string, minLength: 1}}
       secrets:
+        description: Explicit credential-to-CI execution-copy links; names are declared in the top-level ci block. ci.token selects the analysis copy.
         type: array
         items:
           type: object

package/runtime/scripts/api/node/run-node.d.mts

@@ -1,3 +1,32 @@
 import type { SpawnSyncOptions, SpawnSyncReturns } from 'node:child_process';
+/** A concrete Node child whose admission belongs to the CLI's machine-wide governor. */
+export interface HeavyNodeRequest {
+    readonly kind: 'tsc' | 'eslint' | 'test';
+    readonly label: string;
+    readonly args: readonly string[];
+    readonly cwd: string;
+    /** When supplied, this is the entire child environment, not an overlay. */
+    readonly env?: NodeJS.ProcessEnv | undefined;
+    readonly timeoutMs?: number | undefined;
+    readonly maxBuffer: number;
+}
+/** Normal red exits are measurements; an interrupted child is not one. */
+export interface HeavyNodeResult {
+    readonly status: number | null;
+    readonly signal: NodeJS.Signals | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly error?: NodeJS.ErrnoException | undefined;
+}
+/** The CLI admits and captures each actual child, never the composite app command. */
+export type HeavyNodeRun = (request: HeavyNodeRequest) => Promise<HeavyNodeResult>;
+/** A real governor hold reached no verdict; transports preserve its CLI exit instead of treating it as linter output. */
+export declare const isHostHeld: (error: unknown) => boolean;
+/** Execution infrastructure reached no complete measurement; the contract finder cannot turn it into a cacheable source finding. */
+export declare const isNodeExecutionRefusal: (error: unknown) => boolean;
+/** Keeps the runtime's mutation fence and temporary-directory custody before crossing the CLI execution port. */
+export declare function runHeavyNode(run: HeavyNodeRun | undefined, request: HeavyNodeRequest): Promise<HeavyNodeResult>;
+/** A partial compiler/test report cannot be interpreted or stored as a completed measurement. */
+export declare function completedNode(result: HeavyNodeResult, label: string): HeavyNodeResult;
 /** Runs `node <args>`; options (cwd, env, timeout, input, maxBuffer, stdio) pass through. */
 export declare const runNode: (args: readonly string[], options?: SpawnSyncOptions) => SpawnSyncReturns<string>;

package/runtime/scripts/api/node/run-node.mjs

@@ -1,3 +1,22 @@
 import { nodeSpawn } from './lib.mjs';
+import { assertMutationFence } from '../../lib/mutation-fence.mjs';
+import { withTempEnv } from '../../../engine/temp-root.mjs';
+/** A real governor hold reached no verdict; transports preserve its CLI exit instead of treating it as linter output. */
+export const isHostHeld = (error) => error instanceof Error && 'code' in error && error.code === 'HOST_HELD' && 'exitCode' in error && error.exitCode === 75;
+/** Execution infrastructure reached no complete measurement; the contract finder cannot turn it into a cacheable source finding. */
+export const isNodeExecutionRefusal = (error) => error instanceof Error && 'code' in error && typeof error.code === 'string' && ['HOST_HELD', 'HEAVY_DEFERRED', 'CLI_TOOL_INCOMPLETE', 'CLI_TOOL_MISSING', 'CLI_TOOL_NOT_STARTED', 'HFS_NODE_GOVERNOR_MISSING', 'HFS_NODE_INCOMPLETE'].includes(error.code);
+/** Keeps the runtime's mutation fence and temporary-directory custody before crossing the CLI execution port. */
+export async function runHeavyNode(run, request) {
+    if (run === undefined)
+        throw Object.assign(new Error('HFS_NODE_GOVERNOR_MISSING: run this check through starci-harness'), { code: 'HFS_NODE_GOVERNOR_MISSING' });
+    assertMutationFence({ kind: 'node-effect', args: request.args });
+    return run({ ...request, env: withTempEnv({ env: request.env ?? process.env }).env });
+}
+/** A partial compiler/test report cannot be interpreted or stored as a completed measurement. */
+export function completedNode(result, label) {
+    if (result.error !== undefined || result.signal !== null || result.status === null)
+        throw Object.assign(new Error(`${label} did not complete`), { code: 'HFS_NODE_INCOMPLETE' });
+    return result;
+}
 /** Runs `node <args>`; options (cwd, env, timeout, input, maxBuffer, stdio) pass through. */
 export const runNode = (args, options = {}) => nodeSpawn(args, options);

package/runtime/scripts/gates/starcistacks-ci.mjs

@@ -22,7 +22,7 @@ export const catalogOf = (id) => {
 export const checkServiceForm = (service, id, entry, at, kind, add, ambiguous) => {
     if (service.provider && !catalogOf(id).providers.includes(service.provider))
         add('refuse', 'STACKS_PROVIDER_UNKNOWN', `${at}.provider`, `${service.provider} is not a ${id} provider (${catalogOf(id).providers.join(', ')})`);
-    if (Object.hasOwn(entry?.ci ?? {}, 'secrets') || Object.hasOwn(entry?.ci ?? {}, 'vars'))
+    if (Object.hasOwn(entry?.ci ?? {}, 'vars') || service.ci.secrets.some((item) => !item.credential))
         add('suspect', 'STACKS_CI_LEGACY_FORM', `${at}.ci`, 'move the names to the top-level ci block and name them by services.<id>.ci.token / hostVar');
     if (id === 'sonar' && service.provider === 'sonarcloud' && !service.organization
         && !(kind === 'example' && service.runtimeSecrets.length && !service.credentials.length && service.ci.organizationVar))
@@ -56,6 +56,8 @@ export function checkQualityService(service, id, at, context, checkServiceCi) {
             ambiguous('codecov auth must be oidc or token');
         if (id === 'codecov' && service.auth === 'token' && !service.ci.token)
             ambiguous('codecov auth token requires ci.token');
+        if (id === 'codecov' && service.auth === 'oidc' && (service.ci.token || service.credentials.length || service.ci.secrets.length))
+            ambiguous('codecov OIDC has no token, credential or sealed member');
         checkServiceCi(service, id, at, context);
         return true;
     }

package/runtime/scripts/gates/starcistacks-form.d.mts

@@ -6,6 +6,7 @@ export interface ServiceCredential {
     env: string | null;
     key: string | null;
     purpose: string | null;
+    project?: string | null;
     custody: {
         repository: string | null;
         path: string | null;

package/runtime/scripts/gates/starcistacks.d.mts

@@ -119,6 +119,7 @@ declare function summary(service: ServiceLike): {
         id: string | null;
         env: string | null;
         key: string | null;
+        project: string | null | undefined;
         custody: string;
         present: boolean | null;
     }[];

package/runtime/scripts/gates/starcistacks.mjs

@@ -42,6 +42,8 @@ import { readProperties } from '../lib/properties.mjs';
 import { escapeRegExp } from '../lib/regex.mjs';
 import { isInfrastructureValueFile } from './starcistacks-value-file.mjs';
 import { STACK_DECLARATION_TEMPLATE } from '../lib/example-refs.mjs';
+import { isSealedName } from '../lib/sealed-member.mjs';
+import { serviceBindings } from '../hfs/ci-declaration.mjs';
 import { checkSecretForm, kindOf } from './starcistacks-form.mjs';
 import { SERVICE_CATALOG, catalogOf, checkServiceForm, checkCiDeclaration, checkQualityService } from './starcistacks-ci.mjs';
 import { applicationStackFindings } from './starcistacks-runtime.mjs';
@@ -165,9 +167,10 @@ const normalizeCredential = (credential, declaringRepo) => {
     const repo = resolveDeclaredRepository(custody.repository, { fromRepo: declaringRepo });
     const rel = text(custody.path);
     const abs = resolveCustodyFile(repo, rel);
-    return { id: text(credential.id), env: text(credential.env), key: text(credential.key), purpose: text(credential.purpose),
+    const sealed = rel && isSealedName(rel) ? abs : abs ? `${abs}.enc` : null;
+    return { id: text(credential.id), env: text(credential.env), key: text(credential.key), purpose: text(credential.purpose), project: text(credential.project),
         custody: { repository: text(custody.repository), path: rel, resolved: Boolean(repo), file: abs,
-            encPresent: abs ? isFile(`${abs}.enc`) : null, plainPresent: abs ? isFile(abs) : null } };
+            encPresent: sealed ? isFile(sealed) : null, plainPresent: abs && !isSealedName(abs) ? isFile(abs) : false } };
 };
 const ownerActionOf = (s) => {
     const noAction = s.ownerAction === 'none' ? 'none' : null;
@@ -239,12 +242,9 @@ export function resolveStackService(repoRoot, serviceId) {
         const listed = service.projects.some((project) => project.repository === name);
         if (declaration.sourceHost && !listed)
             continue;
-        // Through the source host a product gets the shared server, its shared credentials and its own project
-        // token (a credential whose id is a project key); other projects' tokens and the host's CI wiring are not its.
-        const ownKey = service.projects.find((project) => project.repository === name)?.key;
-        const projectKeys = new Set(service.projects.map((project) => project.key));
+        // A source host lends public server settings only; analysis credentials stay in the selected product's custody.
         if (declaration.sourceHost)
-            service = { ...service, credentials: service.credentials.filter((credential) => !projectKeys.has(credential.id) || credential.id === ownKey),
+            service = { ...service, credentials: [],
                 ci: { wiring: null, workflow: null, permissions: [], secrets: [], vars: [], provisioning: null } };
         return { declaration: declaration.file, declaringRepo: declaration.repo, sourceHost: Boolean(declaration.sourceHost),
             repository: name, projectKey: service.projects.find((project) => project.repository === name)?.key ?? null, ...service };
@@ -304,7 +304,7 @@ const checkServiceCredentials = (service, at, add, ambiguous) => {
         if (!credential.custody.resolved)
             add('suspect', 'STACKS_CUSTODY_UNVERIFIED', where, `custody repository ${credential.custody.repository} is not checked out on this machine`);
         else if (!credential.custody.encPresent)
-            add('refuse', 'STACKS_CUSTODY_MISSING', where, `${credential.custody.repository}/${credential.custody.path}.enc is not in custody; repair the stack custody (secret:gen / stack-secret) - never ask the owner for a value the declaration says the runtime holds`);
+            add('refuse', 'STACKS_CUSTODY_MISSING', where, `${credential.custody.repository}/${credential.custody.path} is not sealed in custody; repair the declared member through starci app secret`);
     }
     return ids;
 };
@@ -371,6 +371,18 @@ const checkService = (id, entry, { schema, declFile, declaration, governing, nam
     checkServiceForm(service, id, entry, at, kind, add, ambiguous);
     if (checkDisabledService(service, id, at, ciUses, ambiguous, add))
         return;
+    let product = false;
+    try {
+        product = JSON.parse(fs.readFileSync(path.join(declaration?.repo ?? '', 'hfs.json'), 'utf8')).kind === 'app';
+    }
+    catch { /* other checks own a missing app declaration */ }
+    if (id === 'sonar' && product) {
+        const selected = serviceBindings(declaration?.doc, name);
+        for (const problem of selected.problems.filter((problem) => problem.at.startsWith('services.sonar')))
+            ambiguous(problem.message);
+        if (service.ci.wiring === 'required' && !selected.bindings.some((binding) => binding.service === 'sonar' && binding.name === service.ci.token))
+            ambiguous('required Sonar analysis needs this product project credential in its declared environment sonar.enc.yaml member');
+    }
     if (checkQualityService(service, id, at, { governing, name, ciUses, ciText, add, ambiguous }, checkServiceCi))
         return;
     checkEnabledService(service, id, at, { governing, name, ciUses, ciText, add, kind }, ambiguous);
@@ -546,7 +558,7 @@ export function checkStarciStacks(repoRoot, { newRepo = false, examplesRoot = pa
 function summary(service) {
     return { provider: service.provider, mode: service.mode, auth: service.auth, host: service.host,
         stack: service.stack ? { owner: service.stack.owner ?? null, repository: service.stack.repository, root: service.stack.root, environment: service.stack.environment, compose: service.stack.compose, container: service.stack.container } : null,
-        projects: service.projects, credentials: service.credentials.map((credential) => ({ id: credential.id, env: credential.env, key: credential.key,
+        projects: service.projects, credentials: service.credentials.map((credential) => ({ id: credential.id, env: credential.env, key: credential.key, project: credential.project,
             custody: `${credential.custody.repository}/${credential.custody.path}`, present: credential.custody.encPresent ?? null })),
         ci: service.ci, ownerAction: service.ownerAction };
 }
@@ -575,7 +587,7 @@ export function ownerAskConflict({ repo, question } = {}) {
             continue;
         const custody = service.credentials.map((credential) => `${credential.custody.repository}/${credential.custody.path}`);
         const custodyNote = custody.length ? ` and its credentials in custody (${custody.join(', ')})` : ` and auth ${service.auth}`;
-        const sonarNote = id === 'sonar' ? 'Run starci gate sonar (status, ensure-project, scan) - it reads host, project and token from the declaration and custody. ' : '';
+        const sonarNote = id === 'sonar' ? 'The native app release gate selects this product project credential; analysis never provisions projects or rotates credentials. ' : '';
         const provisioningNote = service.ci.provisioning ? ` (${service.ci.provisioning})` : '';
         return { service: id, provider: service.provider, declaration: slash(service.declaration), matched: byName ?? byWord,
             message: `${id} (${service.provider}, ${service.mode}) is declared in ${slash(service.declaration)} with ownerAction none${custodyNote}; the owner is never asked for it. ${sonarNote}CI wiring is ${service.ci.wiring ?? 'undeclared'}${provisioningNote}.` };

package/runtime/scripts/hfs/app-wiring.d.mts

@@ -1,3 +1,4 @@
+import { type HeavyNodeRun, type HeavyNodeResult } from '../api/node/run-node.mjs';
 export declare const BOOT_PROOF_CODE = "BE_APP_BOOT_PROOF_MISSING";
 export declare const BOOT_PROOF_TIMEOUT = "BOOT_PROOF_TIMEOUT";
 export declare const BOOT_PROOF_TIMEOUT_ENV = "STARCI_BOOT_PROOF_TIMEOUT_MS";
@@ -6,7 +7,7 @@ export declare const wiringFixturePath: (app: string) => string;
 export type WorkerResult = {
     status?: number | null;
     signal?: string | null;
-    error?: NodeJS.ErrnoException;
+    error?: HeavyNodeResult['error'];
     stdout?: string;
 } | null | undefined;
 /** The injectable spawn seam of the worker. */
@@ -62,7 +63,12 @@ export interface AppWiringInput {
     timeout?: number;
     run?: WorkerRun;
 }
-export declare function appWiring({ repoRoot, repo, files, fixtures, timeout, run }: AppWiringInput): WiringResult;
+/** The synchronous finder and its existing worker doubles drive the same proof program as app check. */
+export declare function appWiring(input: AppWiringInput): WiringResult;
+/** The cache's asynchronous execution seam admits each boot attempt, with the same validation, timeout retry and result judgement. */
+export declare function appWiringAsync(input: Omit<AppWiringInput, 'run'> & {
+    execute?: HeavyNodeRun | undefined;
+}): Promise<WiringResult>;
 /** Optional standalone entry; coordinator connects the same seam to app check --gate wiring. */
 export interface AppWiringMainIo {
     cwd?: string;