@ultimat3/cli 27.14.0 → 27.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "27.14.0",
+  "version": "27.15.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -39,33 +39,33 @@
   },
   "dependencies": {
     "@babel/core": "^8.0.1",
-    "@ultimat3/action": "27.14.0",
-    "@ultimat3/admin": "27.14.0",
-    "@ultimat3/ai": "27.14.0",
-    "@ultimat3/auth": "27.14.0",
-    "@ultimat3/cache": "27.14.0",
-    "@ultimat3/core": "27.14.0",
-    "@ultimat3/db": "27.14.0",
-    "@ultimat3/entity": "27.14.0",
-    "@ultimat3/flags": "27.14.0",
-    "@ultimat3/http": "27.14.0",
-    "@ultimat3/i18n": "27.14.0",
-    "@ultimat3/jobs": "27.14.0",
-    "@ultimat3/mail": "27.14.0",
-    "@ultimat3/manifest": "27.14.0",
-    "@ultimat3/mcp": "27.14.0",
-    "@ultimat3/money": "27.14.0",
-    "@ultimat3/notify": "27.14.0",
-    "@ultimat3/policy": "27.14.0",
-    "@ultimat3/pwa": "27.14.0",
-    "@ultimat3/query": "27.14.0",
-    "@ultimat3/realtime": "27.14.0",
-    "@ultimat3/render": "27.14.0",
-    "@ultimat3/schema": "27.14.0",
-    "@ultimat3/seo": "27.14.0",
-    "@ultimat3/storage": "27.14.0",
-    "@ultimat3/testing": "27.14.0",
-    "@ultimat3/time": "27.14.0",
+    "@ultimat3/action": "27.15.0",
+    "@ultimat3/admin": "27.15.0",
+    "@ultimat3/ai": "27.15.0",
+    "@ultimat3/auth": "27.15.0",
+    "@ultimat3/cache": "27.15.0",
+    "@ultimat3/core": "27.15.0",
+    "@ultimat3/db": "27.15.0",
+    "@ultimat3/entity": "27.15.0",
+    "@ultimat3/flags": "27.15.0",
+    "@ultimat3/http": "27.15.0",
+    "@ultimat3/i18n": "27.15.0",
+    "@ultimat3/jobs": "27.15.0",
+    "@ultimat3/mail": "27.15.0",
+    "@ultimat3/manifest": "27.15.0",
+    "@ultimat3/mcp": "27.15.0",
+    "@ultimat3/money": "27.15.0",
+    "@ultimat3/notify": "27.15.0",
+    "@ultimat3/policy": "27.15.0",
+    "@ultimat3/pwa": "27.15.0",
+    "@ultimat3/query": "27.15.0",
+    "@ultimat3/realtime": "27.15.0",
+    "@ultimat3/render": "27.15.0",
+    "@ultimat3/schema": "27.15.0",
+    "@ultimat3/seo": "27.15.0",
+    "@ultimat3/storage": "27.15.0",
+    "@ultimat3/testing": "27.15.0",
+    "@ultimat3/time": "27.15.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/ci-runs.ts

@@ -121,11 +121,17 @@ export function latestPerWorkflow(runs: readonly CiRun[]): readonly CiRun[] {
   return [...newest.values()];
 }
 
+/**
+ * The branch's runs, newest first. `filters` narrows the ask to one workflow or one event; with
+ * neither given, the argv is byte-for-byte the one `x ci` has always sent — cmd-ci.test.ts pins
+ * it, so a filter may only ever insert its pair between `--branch` and `--limit`.
+ */
 export async function listRuns(
   host: GhHost,
   repo: GhRepo,
   branch: string,
   limit: number,
+  filters?: { readonly workflow?: string | undefined; readonly event?: string | undefined },
 ): Promise<readonly CiRun[]> {
   const rows = await ghJson(
     host,
@@ -136,6 +142,8 @@ export async function listRuns(
       repo.slug,
       '--branch',
       branch,
+      ...(filters?.workflow === undefined ? [] : ['--workflow', filters.workflow]),
+      ...(filters?.event === undefined ? [] : ['--event', filters.event]),
       '--limit',
       String(limit),
       '--json',

package/src/cmd-ci-spec.ts

@@ -6,10 +6,17 @@ import type { CommandSpec } from './parse';
 /** Log lines kept per failed job. Enough to hold a findings block, short enough to read. */
 export const TAIL_LINES = 40;
 
+/**
+ * The events `--event` accepts, closed: `cmd-ci.ts` refuses every other value against this same
+ * constant, so the summary, the refusal and the `gh` filter can never name different sets.
+ */
+export const CI_EVENTS = ['push', 'pull_request', 'workflow_dispatch'] as const;
+
 export const ciSpec: CommandSpec = {
   name: 'ci',
   summary: 'the workflow runs for this branch, and the findings inside the failed steps log',
-  usage: 'x ci [--branch <name>] [--run <id>] [--repo owner/name] [--tail <n>] [--full] [--json]',
+  usage:
+    'x ci [--branch <name>] [--run <id>] [--repo owner/name] [--tail <n>] [--full] [--workflow <name>] [--event <push|pull_request|workflow_dispatch>] [--json]',
   flags: [
     { name: 'repo', type: 'string', summary: 'owner/name; the checkout own remote by default' },
     { name: 'branch', type: 'string', summary: 'branch to read runs for; this one by default' },
@@ -20,5 +27,15 @@ export const ciSpec: CommandSpec = {
       summary: `log lines kept per failed job (default ${TAIL_LINES})`,
     },
     { name: 'full', type: 'boolean', summary: 'the whole failed-step log, not the tail' },
+    {
+      name: 'workflow',
+      type: 'string',
+      summary: 'only this workflow name or filename (e.g. ci.yml)',
+    },
+    {
+      name: 'event',
+      type: 'string',
+      summary: 'only runs of this event (push, pull_request, workflow_dispatch)',
+    },
   ],
 };

package/src/cmd-ci.ts

@@ -9,8 +9,9 @@ import type { CiLogLine } from './ci-log';
 import { findingKey, findingsFrom, jobsInLog, parseLogLines, tailOf } from './ci-log';
 import type { CiJob, CiRun } from './ci-runs';
 import { failedLog, isFailed, isRunning, latestPerWorkflow, listRuns, viewRun } from './ci-runs';
-import { ciSpec, TAIL_LINES } from './cmd-ci-spec';
+import { CI_EVENTS, ciSpec, TAIL_LINES } from './cmd-ci-spec';
 import type { CliCommand, CommandContext } from './command';
+import { BadFlagError } from './errors';
 import { parseIntFlag } from './flag-number';
 import { commentBlock } from './foreign-text';
 import type { GhRepo } from './gh-target';
@@ -18,6 +19,7 @@ import { currentBranch, resolveRepo } from './gh-target';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue } from './output';
 import { flagBool, flagString } from './parse';
+import { quoteArg } from './shell-quote';
 
 export { TAIL_LINES } from './cmd-ci-spec';
 
@@ -43,10 +45,22 @@ export const RUN_LOOKBACK = 20;
 
 /** No run to triage. The remedy is a branch that has one, or the id of the run in question. */
 export class CiRunNotFoundError extends UltimateError {
-  constructor(input: { branch: string; repo: string }) {
+  constructor(input: {
+    branch: string;
+    repo: string;
+    workflow?: string | undefined;
+    event?: string | undefined;
+  }) {
+    // A filter beside --branch makes an empty list two different situations — a branch never
+    // pushed, or a filter that matched nothing. Naming what was asked keeps the diagnosis right.
+    const given = [
+      input.workflow !== undefined ? `--workflow ${input.workflow}` : undefined,
+      input.event !== undefined ? `--event ${input.event}` : undefined,
+    ].filter((clause) => clause !== undefined);
+    const matching = given.length > 0 ? ` matching ${given.join(' ')}` : '';
     super({
       code: 'X_CI_RUN_NOT_FOUND',
-      cause: `no workflow run on ${input.repo} for branch "${input.branch}"`,
+      cause: `no workflow run on ${input.repo} for branch "${input.branch}"${matching}`,
       fix: `x ci --branch main --repo ${input.repo} --json`,
     });
   }
@@ -55,11 +69,39 @@ export class CiRunNotFoundError extends UltimateError {
 const RUN_FLAG = { name: 'run', command: 'ci', min: 1, example: 'x ci --run 32484583944 --json' };
 const TAIL_FLAG = { name: 'tail', command: 'ci', min: 1, example: 'x ci --tail 80 --json' };
 
+/**
+ * `--event`, read against the spec's own closed set: a typo is a refusal naming the events that
+ * exist, never an empty run list a reader would take for a red branch.
+ */
+function readEvent(raw: string | undefined): (typeof CI_EVENTS)[number] | undefined {
+  if (raw === undefined) return undefined;
+  const known: readonly string[] = CI_EVENTS;
+  if (known.includes(raw)) return raw as (typeof CI_EVENTS)[number];
+  throw new BadFlagError({
+    flag: 'event',
+    command: 'ci',
+    reason: `${quoteArg(raw)} is not a workflow event — one of ${CI_EVENTS.join(', ')}`,
+    fix: 'x ci --event push --json',
+  });
+}
+
 export const ciCommand: CliCommand = {
   spec: ciSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
-    const repo = await resolveRepo(ctx, 'ci', flagString(ctx.args, 'repo'));
+    // Filters are validated, and crossed with --run, before any subprocess runs: a refusal must
+    // not cost a gh round trip, and a filter beside --run would otherwise be silently ignored.
     const rawRun = flagString(ctx.args, 'run');
+    const workflow = flagString(ctx.args, 'workflow');
+    const event = readEvent(flagString(ctx.args, 'event'));
+    if (rawRun !== undefined && (workflow !== undefined || event !== undefined)) {
+      throw new BadFlagError({
+        flag: workflow !== undefined ? 'workflow' : 'event',
+        command: 'ci',
+        reason: 'filters the run list, and --run names one run already',
+        fix: 'x ci --run <id> --json',
+      });
+    }
+    const repo = await resolveRepo(ctx, 'ci', flagString(ctx.args, 'repo'));
     const rawTail = flagString(ctx.args, 'tail');
     const limit = flagBool(ctx.args, 'full')
       ? Number.POSITIVE_INFINITY
@@ -71,8 +113,11 @@ export const ciCommand: CliCommand = {
       return report(repo, viewed.run.branch, [await inspect(ctx, repo, viewed, limit)]);
     }
     const branch = flagString(ctx.args, 'branch') ?? (await currentBranch(ctx));
-    const runs = latestPerWorkflow(await listRuns(ctx, repo, branch, RUN_LOOKBACK));
-    if (runs.length === 0) throw new CiRunNotFoundError({ branch, repo: repo.slug });
+    const runs = latestPerWorkflow(
+      await listRuns(ctx, repo, branch, RUN_LOOKBACK, { workflow, event }),
+    );
+    if (runs.length === 0)
+      throw new CiRunNotFoundError({ branch, repo: repo.slug, workflow, event });
     const inspected: RunReport[] = [];
     for (const run of runs) {
       // Only a failed run is opened. A green run's jobs are 35 rows saying `success`, and fetching

package/src/island-realtime-state.ts

@@ -18,6 +18,8 @@ export const FOLLOW_ONLY_EXPORTS: readonly string[] = [
   'usePresence',
   'useConnection',
   'hasPageSocket',
+  // Hears THAT records moved and renders none of them, so a restored store contradicts nothing.
+  'useRecordChanges',
   'readPresence',
   'channel',
   'channelRef',

package/src/serve-retire.ts

@@ -37,8 +37,10 @@ const NOTHING: WorkerRetire = Object.freeze({ adopt: () => undefined, disarm: ()
 
 /**
  * Listen for `RETIRE_SIGNAL` NOW, before the boot: Bun's default for an unhandled SIGUSR2 ends the
- * process, so a `preStop` that lands while the pod still boots must meet this listener, which waits
- * for the worker and then retires it. One retire per process; a second signal joins it.
+ * process — except as PID 1 (a container's ENTRYPOINT), where the kernel DROPS a signal with no
+ * listener, so a `preStop` that lands before this line runs is lost. The chart's preStop therefore
+ * re-sends it every 5 s until PID 1 is gone; this listener waits for the worker and then retires it.
+ * One retire per process; a second signal joins it.
  *
  * Exits rather than holds, decided 2026-10-07: the `preStop` has no channel back but PID 1 itself,
  * so "retired" has to be observable as "PID 1 is gone" — and a pod that has stopped claiming serves

package/src/templates/scaffold-helm-templates.ts

@@ -172,7 +172,9 @@ nobody bound. Derived here rather than stated twice in values.yaml, where the tw
   The worker's retire, opt-in: roles.worker.retireSeconds > 0. The preStop sends PID 1 SIGUSR2 —
   the framework's retire: stop claiming, finish every held job however long it takes, abort
   nothing, then drain and exit 0 — and waits until PID 1 is gone, so the SIGTERM that follows finds
-  nothing left to cut off. bun -e, never kill/sleep: bun is the image's ENTRYPOINT (exec form, so it
+  nothing left to cut off. It re-sends the signal every 5 s while it waits: PID 1 has no default
+  signal action, so a preStop that lands before the boot arms the listener is dropped by the kernel
+  (the pod then idles to its grace); a repeat joins the retire in flight. bun -e, never kill/sleep: bun is the image's ENTRYPOINT (exec form, so it
   IS PID 1). The kubelet counts the preStop against the grace period, so retireSeconds is added to
   it and is the longest a retire may take.
   */}}
@@ -183,7 +185,7 @@ nobody bound. Derived here rather than stated twice in values.yaml, where the tw
         command:
           - bun
           - -e
-          - "process.kill(1, 'SIGUSR2'); for (;;) { try { process.kill(1, 0); } catch { break; } await Bun.sleep(1000); }"
+          - "process.kill(1, 'SIGUSR2'); for (let n = 1; ; n++) { try { process.kill(1, n % 5 === 0 ? 'SIGUSR2' : 0); } catch { break; } await Bun.sleep(1000); }"
   {{- end }}
   {{- end }}
   resources: {{- toYaml $cfg.resources | nindent 4 }}