@starci/hfs 4.11.22 → 4.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.11.22",
+  "version": "4.12.0",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "type": "module",
   "license": "MIT",
@@ -16,8 +16,14 @@
   },
   "private": false,
   "exports": {
-    ".": "./src/main.mjs",
-    "./form-bounds": "./emit/form-bounds.mjs",
+    ".": {
+      "types": "./src/main.d.mts",
+      "default": "./src/main.mjs"
+    },
+    "./form-bounds": {
+      "types": "./emit/form-bounds.d.mts",
+      "default": "./emit/form-bounds.mjs"
+    },
     "./package.json": "./package.json",
     "./runtime/*": "./runtime/*"
   },
@@ -32,6 +38,8 @@
     "@nestjs/core": "11.2.5",
     "@nestjs/graphql": "13.4.5",
     "@nestjs/testing": "11.2.5",
+    "@starci/tsconfig": "file:../tsconfig",
+    "@types/node": "24.19.2",
     "@typescript-eslint/eslint-plugin": "8.71.0",
     "@typescript-eslint/parser": "8.71.0",
     "class-validator": "0.15.1",
@@ -49,6 +57,7 @@
   "files": [
     "LICENSE",
     "src/main.mjs",
+    "src/main.d.mts",
     "emit/**",
     "stack/**",
     "release/**",
@@ -63,6 +72,9 @@
     "sync/**",
     "upgrade/**",
     "templates/**",
+    "!**/*.mts",
+    "!**/*.cts",
+    "**/*.d.mts",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -73,6 +85,11 @@
     "access": "public"
   },
   "scripts": {
-    "test": "node --test \"src/*.spec.mjs\""
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "bundles": "npm run build && node scripts/sync-bundles.mjs",
+    "bundles:check": "npm run build && node scripts/sync-bundles.mjs --check",
+    "test": "npm run typecheck && npm run build && node --test \"src/*.spec.mts\""
   }
 }

package/release/candidate-ci.d.mts

@@ -0,0 +1,46 @@
+import type { VerbContext } from './index.mjs';
+/** The candidate ref of the release tag `tag` with the app's tag prefix: refs/heads/release/candidate-<version>. */
+export declare const candidateRef: (tag: unknown, prefix?: string) => string;
+/** A run of the ci.yml workflow as `gh run list --json` answers it. */
+interface CiRun {
+    databaseId?: number | string;
+    headSha?: string;
+    status?: string;
+    conclusion?: string;
+    url?: string;
+    event?: string;
+    createdAt?: string;
+}
+/** The verdict over the runs of one sha. */
+interface Verdict {
+    state: string;
+    run: CiRun | null;
+}
+/** The wait of the candidate run. */
+interface CandidateWait {
+    pollSeconds: number;
+    graceMinutes: number;
+    waitMinutes: number;
+}
+/** pending (no run) | running | green | red over the runs of the sha; a cancelled run is no verdict. Pure. */
+export declare function candidateVerdict(rows: readonly CiRun[] | null | undefined): Verdict;
+/** The failing jobs and steps of a run: ['job (conclusion): step, step']; [] when unreadable. */
+export declare function failingJobs(ctx: VerbContext, runRow: CiRun | null | undefined): string[];
+/** Poll the candidate run of `sha` until green or red, or the grace (no run) or the wait passes: {state: green|red|timeout|unstarted|unknown, run}. */
+export declare function waitForCandidate(ctx: VerbContext, sha: string, wait?: CandidateWait): Promise<Verdict>;
+/**
+ * The candidate step of the push: push HEAD to the candidate ref (through the pre-push hook), wait for its CI. {ok, lines, data: {ref, state, run, failing}}.
+ * ok only on green.
+ */
+export declare function candidateStep(ctx: VerbContext, { head, tag, prefix, remote, wait }: {
+    head: string;
+    tag: string;
+    prefix: string;
+    remote: string;
+    wait?: CandidateWait | undefined;
+}): Promise<{
+    ok: boolean;
+    lines: string[];
+    data: Record<string, unknown>;
+}>;
+export {};

package/release/candidate-ci.mjs

@@ -1,103 +1,109 @@
-// candidate-ci.mjs - the candidate CI of `starci app release push` (OWNER RULING candidate-ci, 2026-10-18: "never again have main receive a release whose CI is
-// red, with the owner confirming afterwards"). The push sends the exact release sha to refs/heads/release/candidate-<version> first (the managed ci.yml triggers on
-// release/candidate-*), waits for the ci.yml run of THAT sha, and moves the default branch and the tag only when it is green:
-//   green     the newest non-cancelled run of the sha concluded success and none of its jobs was skipped
-//   red       "candidate CI red" (a run or a job that concluded skipped is red, never a pass: owner ruling 2026-10-22, a skip is a loosening) with the run URL and the failing jobs and steps; nothing reaches the default branch. The candidate ref stays for diagnosis
-//   timeout   "candidate CI timeout": no run listed within the grace (a queued run is listed), or it did not end within the wait
-//   unknown   candidate CI unknown: GitHub could not be read to the end; a release never proceeds blind
-// There is no override: a red candidate never passes (owner ruling 2026-10-22: a loosening is always red).
-// Every process goes through ctx.spawn (git, gh); the wait through ctx.sleep and ctx.now.
-
 const CANDIDATE_PREFIX = 'refs/heads/release/candidate-';
 /** The wait of the candidate run: poll interval, the grace for a run to appear, the wait for it to end (an app's ci.yml jobs time out within 45 minutes). */
 // A queued run is listed (running): the grace only covers a run GitHub has not created yet, and the wait, counted from the push, bounds grace, queue and run.
 const CANDIDATE_WAIT = Object.freeze({ pollSeconds: 30, graceMinutes: 45, waitMinutes: 150 });
 const FIELDS = 'databaseId,headSha,status,conclusion,url,event,createdAt';
-const SHA = /^[a-f0-9]{40}$/u;
 const PASSING = new Set(['success', 'neutral']);
-
 /** The candidate ref of the release tag `tag` with the app's tag prefix: refs/heads/release/candidate-<version>. */
 export const candidateRef = (tag, prefix = 'v') => `${CANDIDATE_PREFIX}${String(tag).startsWith(prefix) ? String(tag).slice(prefix.length) : String(tag)}`;
-
 function run(ctx, command, args) {
-  try { return ctx.spawn(command, args, { cwd: ctx.cwd }); } catch { return { status: null }; }
+    try {
+        return ctx.spawn(command, args, { cwd: ctx.cwd });
+    }
+    catch {
+        return { status: null };
+    }
 }
-
+// reason: gh answers JSON; callers check the shape they read
 function jsonOf(result) {
-  if (!result || result.error || result.status !== 0) return null;
-  try { return JSON.parse(result.stdout); } catch { return null; }
+    if (!result || result.error || result.status !== 0)
+        return null;
+    try {
+        return JSON.parse(result.stdout);
+    }
+    catch {
+        return null;
+    }
 }
-
 /** pending (no run) | running | green | red over the runs of the sha; a cancelled run is no verdict. Pure. */
 export function candidateVerdict(rows) {
-  const runs = (rows ?? []).filter((row) => row && row.conclusion !== 'cancelled');
-  runs.sort((a, b) => Date.parse(b.createdAt ?? 0) - Date.parse(a.createdAt ?? 0) || Number(b.databaseId) - Number(a.databaseId));
-  const newest = runs[0];
-  if (!newest) return { state: 'pending', run: null };
-  if (newest.status !== 'completed') return { state: 'running', run: newest };
-  return { state: newest.conclusion === 'success' ? 'green' : 'red', run: newest };
+    const runs = (rows ?? []).filter((row) => row && row.conclusion !== 'cancelled');
+    runs.sort((a, b) => Date.parse(b.createdAt ?? 0) - Date.parse(a.createdAt ?? 0) || Number(b.databaseId) - Number(a.databaseId));
+    const newest = runs[0];
+    if (!newest)
+        return { state: 'pending', run: null };
+    if (newest.status !== 'completed')
+        return { state: 'running', run: newest };
+    return { state: newest.conclusion === 'success' ? 'green' : 'red', run: newest };
 }
-
 /** The jobs of a run ([{name, conclusion, steps}]), or null when unreadable. */
 function runJobsOf(ctx, runRow) {
-  if (!/^\d+$/u.test(String(runRow?.databaseId ?? ''))) return null;
-  const reply = jsonOf(run(ctx, 'gh', ['run', 'view', String(runRow.databaseId), '--json', 'jobs']));
-  return Array.isArray(reply?.jobs) ? reply.jobs : null;
+    if (!/^\d+$/u.test(String(runRow?.databaseId ?? '')))
+        return null;
+    const reply = jsonOf(run(ctx, 'gh', ['run', 'view', String(runRow.databaseId), '--json', 'jobs']));
+    return Array.isArray(reply?.jobs) ? reply.jobs : null;
 }
-
 /** One read of the ci.yml runs of `sha`: {ok, state, run} or {ok: false}. A green run is read job by job: a skipped job makes it red. */
 function readCandidateRun(ctx, sha) {
-  const rows = jsonOf(run(ctx, 'gh', ['run', 'list', '--workflow', 'ci.yml', '--commit', sha, '--limit', '20', '--json', FIELDS]));
-  if (!Array.isArray(rows)) return { ok: false };
-  const seen = candidateVerdict(rows.filter((row) => !row.headSha || row.headSha === sha));
-  if (seen.state !== 'green') return { ok: true, ...seen };
-  const jobs = runJobsOf(ctx, seen.run);
-  if (!jobs) return { ok: false };
-  return { ok: true, ...seen, state: jobs.some((job) => job.conclusion === 'skipped') ? 'red' : 'green' };
+    const rows = jsonOf(run(ctx, 'gh', ['run', 'list', '--workflow', 'ci.yml', '--commit', sha, '--limit', '20', '--json', FIELDS]));
+    if (!Array.isArray(rows))
+        return { ok: false };
+    const seen = candidateVerdict(rows.filter((row) => !row.headSha || row.headSha === sha));
+    if (seen.state !== 'green')
+        return { ok: true, ...seen };
+    const jobs = runJobsOf(ctx, seen.run);
+    if (!jobs)
+        return { ok: false };
+    return { ok: true, ...seen, state: jobs.some((job) => job.conclusion === 'skipped') ? 'red' : 'green' };
 }
-
 /** The failing jobs and steps of a run: ['job (conclusion): step, step']; [] when unreadable. */
 export function failingJobs(ctx, runRow) {
-  return (runJobsOf(ctx, runRow) ?? []).filter((job) => job.conclusion && !PASSING.has(job.conclusion)).map((job) => {
-    const steps = (job.steps ?? []).filter((step) => step.conclusion && !PASSING.has(step.conclusion)).map((step) => step.name);
-    return `${job.name} (${job.conclusion})${steps.length ? `: ${steps.join(', ')}` : ''}`;
-  });
+    return (runJobsOf(ctx, runRow) ?? []).filter((job) => job.conclusion && !PASSING.has(job.conclusion)).map((job) => {
+        const steps = (job.steps ?? []).filter((step) => step.conclusion && !PASSING.has(step.conclusion)).map((step) => step.name);
+        return `${job.name} (${job.conclusion})${steps.length ? `: ${steps.join(', ')}` : ''}`;
+    });
 }
-
 /** Poll the candidate run of `sha` until green or red, or the grace (no run) or the wait passes: {state: green|red|timeout|unstarted|unknown, run}. */
 export async function waitForCandidate(ctx, sha, wait = CANDIDATE_WAIT) {
-  const started = ctx.now();
-  let readable = null;
-  for (;;) {
-    const seen = readCandidateRun(ctx, sha);
-    if (seen.ok) readable = seen;
-    if (seen.ok && (seen.state === 'green' || seen.state === 'red')) return seen;
-    const elapsed = ctx.now() - started;
-    if (seen.ok && seen.state === 'pending' && elapsed >= wait.graceMinutes * 60_000) return { state: 'unstarted', run: null };
-    if (elapsed >= wait.waitMinutes * 60_000) return readable ? { state: 'timeout', run: readable.run } : { state: 'unknown', run: null };
-    await ctx.sleep(wait.pollSeconds * 1000);
-  }
+    const started = ctx.now();
+    let readable = null;
+    for (;;) {
+        const seen = readCandidateRun(ctx, sha);
+        if (seen.ok)
+            readable = seen;
+        if (seen.ok && (seen.state === 'green' || seen.state === 'red'))
+            return seen;
+        const elapsed = ctx.now() - started;
+        if (seen.ok && seen.state === 'pending' && elapsed >= wait.graceMinutes * 60_000)
+            return { state: 'unstarted', run: null };
+        if (elapsed >= wait.waitMinutes * 60_000)
+            return readable ? { state: 'timeout', run: readable.run } : { state: 'unknown', run: null };
+        await ctx.sleep(wait.pollSeconds * 1000);
+    }
 }
-
 /**
  * The candidate step of the push: push HEAD to the candidate ref (through the pre-push hook), wait for its CI. {ok, lines, data: {ref, state, run, failing}}.
  * ok only on green.
  */
 export async function candidateStep(ctx, { head, tag, prefix, remote, wait = CANDIDATE_WAIT }) {
-  const ref = candidateRef(tag, prefix);
-  const lines = [];
-  const pushed = run(ctx, 'git', ['push', remote, `+${head}:${ref}`]);
-  if (pushed.status !== 0) return { ok: false, lines: [`candidate      push of ${head.slice(0, 10)} to ${ref} failed: ${String(pushed.stderr ?? '').trim().split('\n')[0]}`], data: { ref, state: 'push-failed' } };
-  lines.push(`candidate      pushed ${head.slice(0, 10)} to ${remote} ${ref}; waiting for its ci.yml run`);
-  const seen = await waitForCandidate(ctx, head, wait);
-  const url = seen.run?.url ? ` ${seen.run.url}` : '';
-  if (seen.state === 'green') return { ok: true, lines: [...lines, `candidate CI   green${url}`], data: { ref, state: 'green', run: seen.run } };
-  if (seen.state === 'red') {
-    const failing = failingJobs(ctx, seen.run);
-    const detail = failing.length ? failing.join('; ') : 'the failing jobs could not be read';
-    return { ok: false, lines: [...lines, `candidate CI red: the ci.yml run of ${head.slice(0, 10)} on ${ref} is red${url}; failing: ${detail}. Nothing reached the default branch; the candidate ref stays for diagnosis`], data: { ref, state: 'red', run: seen.run, failing } };
-  }
-  if (seen.state === 'unstarted') return { ok: false, lines: [...lines, `candidate CI timeout: no ci.yml run started for ${head.slice(0, 10)} on ${ref} within ${wait.graceMinutes} minutes (does .github/workflows/ci.yml trigger on release/candidate-*? run starci app sync)`], data: { ref, state: 'unstarted' } };
-  if (seen.state === 'timeout') return { ok: false, lines: [...lines, `candidate CI timeout: the ci.yml run of ${head.slice(0, 10)} did not end within ${wait.waitMinutes} minutes${url}`], data: { ref, state: 'timeout', run: seen.run } };
-  return { ok: false, lines: [...lines, `candidate CI unknown: GitHub could not be read for the candidate ${head.slice(0, 10)} on ${ref}; a release never proceeds blind`], data: { ref, state: 'unknown' } };
+    const ref = candidateRef(tag, prefix);
+    const lines = [];
+    const pushed = run(ctx, 'git', ['push', remote, `+${head}:${ref}`]);
+    if (pushed.status !== 0)
+        return { ok: false, lines: [`candidate      push of ${head.slice(0, 10)} to ${ref} failed: ${String(pushed.stderr ?? '').trim().split('\n')[0]}`], data: { ref, state: 'push-failed' } };
+    lines.push(`candidate      pushed ${head.slice(0, 10)} to ${remote} ${ref}; waiting for its ci.yml run`);
+    const seen = await waitForCandidate(ctx, head, wait);
+    const url = seen.run?.url ? ` ${seen.run.url}` : '';
+    if (seen.state === 'green')
+        return { ok: true, lines: [...lines, `candidate CI   green${url}`], data: { ref, state: 'green', run: seen.run } };
+    if (seen.state === 'red') {
+        const failing = failingJobs(ctx, seen.run);
+        const detail = failing.length ? failing.join('; ') : 'the failing jobs could not be read';
+        return { ok: false, lines: [...lines, `candidate CI red: the ci.yml run of ${head.slice(0, 10)} on ${ref} is red${url}; failing: ${detail}. Nothing reached the default branch; the candidate ref stays for diagnosis`], data: { ref, state: 'red', run: seen.run, failing } };
+    }
+    if (seen.state === 'unstarted')
+        return { ok: false, lines: [...lines, `candidate CI timeout: no ci.yml run started for ${head.slice(0, 10)} on ${ref} within ${wait.graceMinutes} minutes (does .github/workflows/ci.yml trigger on release/candidate-*? run starci app sync)`], data: { ref, state: 'unstarted' } };
+    if (seen.state === 'timeout')
+        return { ok: false, lines: [...lines, `candidate CI timeout: the ci.yml run of ${head.slice(0, 10)} did not end within ${wait.waitMinutes} minutes${url}`], data: { ref, state: 'timeout', run: seen.run } };
+    return { ok: false, lines: [...lines, `candidate CI unknown: GitHub could not be read for the candidate ${head.slice(0, 10)} on ${ref}; a release never proceeds blind`], data: { ref, state: 'unknown' } };
 }

package/release/gate.d.mts

@@ -0,0 +1,120 @@
+import type { VerbContext, VerbResult } from './index.mjs';
+/** One gate of the release: a name, an argument array (never a shell string), an optional jest summary and extra environment. */
+export interface Gate {
+    name: string;
+    command: string[];
+    summary: string | null;
+    env: Record<string, string>;
+    provider?: SonarProvider;
+    credentialNames?: string[];
+    teardownOf?: string;
+}
+type Services = any;
+type SonarProvider = any;
+/** The release block normalised, with the package version: what `release gate` and `release push` run. */
+export interface ReleaseConfig {
+    root?: string;
+    version?: string;
+    gates: Gate[];
+    tagPrefix: string;
+    defaultBranch: string;
+    requireCi: boolean;
+    services: Services;
+}
+/** What running (or reusing) a gate answers: the row the L4 and urgent records carry. */
+export interface GateRow {
+    name: string;
+    command: string | null;
+    pass: boolean;
+    detail: string;
+    log: string | null;
+    logSha256: string | null;
+    seconds?: number;
+    summary?: unknown;
+    env?: string[];
+    reused?: boolean;
+    note?: string;
+}
+/** What a git call answers. */
+export interface GitResult {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+}
+/** The tag the release uses and whether it is on HEAD, free or taken. */
+export interface ChosenTag {
+    tag: string;
+    state: 'on-head' | 'taken' | 'free';
+}
+/** The facts known before a gate runs. */
+export interface Facts {
+    head: string;
+    chosen: ChosenTag;
+    red: string[];
+    out: string[];
+}
+/** The options of one gate run. */
+export interface RunOptions {
+    dir: string;
+    platform: string;
+    credentialNames: string[];
+    preface?: string;
+}
+export declare const RELEASE_CODE = "RELEASE_CONFIG_INVALID";
+/** The note a release that does not wait for CI carries in its L4 record and its push output (owner ruling release-require-ci-per-project). */
+export declare const CI_NOT_REQUIRED = "CI not required by release.requireCi=false (owner ruling release-require-ci-per-project): the local release gate, this L4 record and the annotated tag, is the release proof";
+export declare const VERSION: RegExp;
+/** True for a branch or remote name git can take as one argument (no leading dash, only path-like characters). */
+export declare const refName: (value: unknown) => value is string;
+/** Judges the optional `release:` block. Absence is fine (defaults). Returns { config } or { problems }. */
+export declare function normalizeRelease(block: unknown, scripts?: Record<string, unknown> | undefined, services?: Services, options?: {
+    example?: boolean;
+    entities?: boolean;
+}): {
+    config: ReleaseConfig;
+    problems?: undefined;
+} | {
+    config?: undefined;
+    problems: string[];
+};
+/** Runs git in the app root; a missing git or (unless allowFail) a non-zero exit is a failure whose message names the first stderr line. */
+export declare function git(ctx: VerbContext, args: string[], { allowFail }?: {
+    allowFail?: boolean;
+}): GitResult;
+/** The directory that holds the L4 records: <git common dir>/starci-release. */
+export declare const releaseDir: (ctx: VerbContext) => string;
+/** Annotated tags `<prefix><digit>*` that point at HEAD (lightweight tags do not count: the hook ignores them). */
+export declare function annotatedOnHead(ctx: VerbContext, prefix: string): string[];
+/**
+ * The paths that make the tree dirty: every changed tracked path and every untracked one, except an untracked file the app's slots declare a dev
+ * server rewrites (`rewrittenBy`, e.g. the AGENTS.md `next dev` writes): that one is known generated output, never a change of the release.
+ */
+export declare function dirtyPaths(ctx: VerbContext): string[];
+/** [command, args] to start an argv; on Windows npm and npx are .cmd files, so they start through cmd.exe (words are validated, never a shell string). */
+export declare function launch(argv: readonly string[], platform: string): [string, string[]];
+/** An unreachable Sonar host stays a red row with a real log and no scan invocation. */
+export declare function runAvailableGate(ctx: VerbContext, gate: Gate, options: RunOptions): Promise<GateRow>;
+export declare const withoutCredentials: (values: Record<string, string | undefined> | undefined, credentialNames: readonly string[]) => Record<string, string | undefined>;
+export declare function runGate(ctx: VerbContext, gate: Gate, { dir, platform, credentialNames, preface }: RunOptions): GateRow;
+/** Everything that can be known without running a gate: the facts, the red preconditions and the lines that describe them. */
+export declare function inspect(ctx: VerbContext, config: ReleaseConfig, options: {
+    source?: string | boolean | undefined;
+    tagPrefix?: string | boolean | undefined;
+}): Facts;
+export declare function assertUnmoved(ctx: VerbContext, head: string): void;
+export declare function summaryOf(result: GateRow): string;
+/**
+ * `starci app release gate`: dry run prints the preconditions, the gate list, the head and the tag; --execute runs every gate and, only if required gates pass,
+ * writes the L4 record and creates the annotated tag. options: { execute, source (the --sha ref), tagPrefix, platform, backfill, openTicket }.
+ * With `backfill` (a tag pushed by `release push --urgent`, checked out at HEAD) the same full gate judges that commit: green writes its L4 record
+ * (promotedFrom the urgent record) and marks the urgent record promoted, with no new tag and no push; red opens a fix ticket through `openTicket`.
+ */
+export declare function releaseGate(ctx: VerbContext, config: ReleaseConfig, options?: {
+    execute?: boolean;
+    source?: string | boolean | undefined;
+    tagPrefix?: string | boolean | undefined;
+    platform?: string;
+    backfill?: string | boolean | undefined;
+    openTicket?: unknown;
+}): Promise<VerbResult>;
+export {};