@bamr87/fleet-engines 0.1.0

package/dist/fleet/parse.js

@@ -0,0 +1,298 @@
+// Pure reverse-import parser for GitHub Actions workflow YAML — the engine behind
+// GitFactory's observe mode. `parseWorkflow` turns one workflow file into an
+// ImportedWorkflow; `buildFleet` stitches a repo's workflows into a Fleet graph
+// (workflow_run chains + cross-repo emissions). No I/O, never throws on bad YAML.
+//
+// Structure (name + the `on:` block) is read via the `yaml` parser when possible, but
+// every agent/sink/cross-repo/gate signal comes from a raw-text regex scan. Text
+// scanning is far more robust than deep YAML walking across the many shapes real
+// workflows take: composite actions, matrices, heredocs, reusable-workflow calls, and
+// even syntactically broken files (which the scan still mines for signals).
+import { parse } from 'yaml';
+import { externalNodeId } from './types.js';
+// ── path helpers ────────────────────────────────────────────────────────────
+/** Basename of a path with a trailing `.yml`/`.yaml` stripped. */
+function baseNoExt(path) {
+    const base = path.split('/').pop() ?? path;
+    return base.replace(/\.ya?ml$/i, '');
+}
+// ── `on:` → triggers ──────────────────────────────────────────────────────────
+/** Join a string/number array field (e.g. `types:`) of an event config into a detail. */
+function joinField(value, field) {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        const raw = value[field];
+        if (Array.isArray(raw)) {
+            const parts = raw
+                .filter((x) => typeof x === 'string' || typeof x === 'number')
+                .map((x) => String(x));
+            if (parts.length > 0)
+                return parts.join(', ');
+        }
+    }
+    return undefined;
+}
+/** Cron strings from a `schedule:` value (`[{ cron: '…' }, …]`). */
+function cronsOf(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const entry of value) {
+        if (entry && typeof entry === 'object' && !Array.isArray(entry)) {
+            const cron = entry.cron;
+            if (typeof cron === 'string')
+                out.push(cron);
+        }
+        else if (typeof entry === 'string') {
+            out.push(entry);
+        }
+    }
+    return out;
+}
+/** The `workflows:` name list from a `workflow_run:` value. */
+function workflowsOf(value) {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        const raw = value.workflows;
+        if (Array.isArray(raw)) {
+            return raw.filter((x) => typeof x === 'string');
+        }
+    }
+    return [];
+}
+/** Map a single `on:` key (not schedule/workflow_run, which fan out) to a summary. */
+function triggerForKey(key, value) {
+    switch (key) {
+        case 'push':
+            return { kind: 'push' };
+        case 'pull_request': {
+            const detail = joinField(value, 'types');
+            return detail ? { kind: 'pull_request', detail } : { kind: 'pull_request' };
+        }
+        case 'issues': {
+            const detail = joinField(value, 'types');
+            return detail ? { kind: 'issues', detail } : { kind: 'issues' };
+        }
+        case 'issue_comment':
+            return { kind: 'issue_comment' };
+        case 'workflow_dispatch':
+            return { kind: 'workflow_dispatch' };
+        case 'repository_dispatch':
+            return { kind: 'repository_dispatch' };
+        default:
+            return { kind: key };
+    }
+}
+/** Expand an `on:` block (string | array | object) into triggers + workflow_run names. */
+function triggersFromOn(on) {
+    const triggers = [];
+    const runAfterNames = [];
+    if (on == null)
+        return { triggers, runAfterNames };
+    if (typeof on === 'string') {
+        triggers.push(triggerForKey(on, undefined));
+        return { triggers, runAfterNames };
+    }
+    if (Array.isArray(on)) {
+        for (const item of on) {
+            if (typeof item === 'string')
+                triggers.push(triggerForKey(item, undefined));
+        }
+        return { triggers, runAfterNames };
+    }
+    if (typeof on === 'object') {
+        for (const [key, value] of Object.entries(on)) {
+            if (key === 'schedule') {
+                for (const cron of cronsOf(value))
+                    triggers.push({ kind: 'schedule', detail: cron });
+            }
+            else if (key === 'workflow_run') {
+                const workflows = workflowsOf(value);
+                for (const w of workflows)
+                    runAfterNames.push(w);
+                triggers.push(workflows.length > 0
+                    ? { kind: 'workflow_run', detail: workflows.join(', ') }
+                    : { kind: 'workflow_run' });
+            }
+            else {
+                triggers.push(triggerForKey(key, value));
+            }
+        }
+    }
+    return { triggers, runAfterNames };
+}
+// ── raw-text signal scans ─────────────────────────────────────────────────────
+/** First capture group across `patterns`, or undefined. Patterns must be non-global. */
+function firstCapture(text, patterns) {
+    for (const re of patterns) {
+        const m = re.exec(text);
+        if (m && m[1])
+            return m[1];
+    }
+    return undefined;
+}
+/** Detect the AI runner + its role/model/tools, or undefined if the workflow runs none. */
+function detectAgent(text) {
+    let runner;
+    if (text.includes('./.github/actions/claude-run') || text.includes('actions/claude-run')) {
+        runner = 'claude-run';
+    }
+    else if (text.includes('anthropics/claude-code-action')) {
+        runner = 'claude-code-action';
+    }
+    else if (text.includes('scripts/ai/run.sh') || text.includes('claude -p')) {
+        runner = 'run-sh';
+    }
+    if (!runner)
+        return undefined;
+    const agent = { runner };
+    const agentName = firstCapture(text, [
+        /agent:\s*['"]?([A-Za-z0-9_-]+)/,
+        /--agent\s+([A-Za-z0-9_-]+)/,
+    ]);
+    if (agentName)
+        agent.agentName = agentName;
+    const model = firstCapture(text, [
+        /--model\s+([A-Za-z0-9_.-]+)/,
+        /model:\s*['"]?([A-Za-z0-9_.-]+)/,
+    ]);
+    if (model)
+        agent.model = model;
+    const tools = firstCapture(text, [
+        /tools:\s*['"]([^'"]+)['"]/,
+        /--allowedTools\s+['"]?([^'"\n]+)/,
+    ]);
+    if (tools)
+        agent.tools = tools;
+    return agent;
+}
+/** Coarse-classify what a workflow writes, deduped and in a stable order. */
+function detectSinks(text) {
+    const sinks = [];
+    const add = (k) => {
+        if (!sinks.includes(k))
+            sinks.push(k);
+    };
+    if (/gh pr create/.test(text))
+        add('pr');
+    if (/gh issue create/.test(text))
+        add('issue');
+    if (/gh (pr|issue) comment/.test(text))
+        add('comment');
+    if (/gh (issue|pr) edit[^\n]*--add-label/.test(text))
+        add('label');
+    if (/git push/.test(text))
+        add('commit');
+    if (/deploy-pages|actions\/deploy-pages|environment:\s*\n?\s*name:\s*github-pages/.test(text)) {
+        add('deploy');
+    }
+    if (/gh issue create[^\n]*--repo\s+\S+\/\S+/.test(text))
+        add('cross_repo_issue');
+    if (/repository_dispatch|gh workflow run|gh api[^\n]*dispatches/.test(text))
+        add('dispatch');
+    return sinks;
+}
+/** Unique `owner/name` repos targeted via `gh … --repo owner/name`. */
+function detectCrossRepoTargets(text) {
+    const out = [];
+    const re = /--repo\s+([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)/g;
+    let m;
+    while ((m = re.exec(text)) !== null) {
+        if (!out.includes(m[1]))
+            out.push(m[1]);
+    }
+    return out;
+}
+/** A `*_ENABLED`-style kill-switch variable name, if the workflow references one. */
+function detectGate(text) {
+    const m = /([A-Z][A-Z0-9_]*_ENABLED)/.exec(text);
+    return m ? m[1] : undefined;
+}
+// ── public API ────────────────────────────────────────────────────────────────
+/**
+ * Reverse-import one workflow file into an {@link ImportedWorkflow}. PURE and total:
+ * never throws. Name + `on:` come from the YAML parser when the file parses; all
+ * agent/sink/cross-repo/gate signals come from a raw-text scan, so odd YAML shapes
+ * (and even unparseable files) still yield useful data.
+ */
+export function parseWorkflow(path, yamlText) {
+    const slug = baseNoExt(path);
+    let docName;
+    let on;
+    try {
+        const parsed = parse(yamlText);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            const doc = parsed;
+            const n = doc.name;
+            if (typeof n === 'string' && n.trim() !== '')
+                docName = n;
+            // The `on:` key round-trips as the string 'on' under YAML 1.2, but a YAML-1.1
+            // bool resolver hands it back under the boolean-`true` key. Read it defensively.
+            on = doc.on ?? doc[true] ?? doc['on'];
+        }
+    }
+    catch {
+        // Unparseable YAML: fall through to the filename name + text-only signal scan.
+    }
+    const { triggers, runAfterNames } = triggersFromOn(on);
+    const agent = detectAgent(yamlText);
+    const gate = detectGate(yamlText);
+    const wf = {
+        path,
+        name: docName ?? slug,
+        slug,
+        triggers,
+        hasAgent: agent !== undefined,
+        sinks: detectSinks(yamlText),
+        runAfterNames,
+        crossRepoTargets: detectCrossRepoTargets(yamlText),
+    };
+    if (agent)
+        wf.agent = agent;
+    if (gate)
+        wf.gate = gate;
+    return wf;
+}
+/**
+ * Stitch a repo's parsed workflows into a {@link Fleet}: workflow_run belts (a workflow
+ * whose `on.workflow_run.workflows` names another workflow in the same repo) and
+ * cross-repo belts (a `gh … --repo owner/name` targeting a *different* repo). PURE.
+ */
+export function buildFleet(repo, parsed) {
+    const nameToPath = new Map();
+    for (const wf of parsed)
+        nameToPath.set(wf.name, wf.path);
+    const edges = [];
+    const warnings = [];
+    const externalRepos = [];
+    const self = `${repo.owner}/${repo.repo}`.toLowerCase();
+    for (const wf of parsed) {
+        for (const name of wf.runAfterNames) {
+            const sourcePath = nameToPath.get(name);
+            if (sourcePath) {
+                edges.push({
+                    id: `wr:${sourcePath}->${wf.path}`,
+                    from: sourcePath,
+                    to: wf.path,
+                    kind: 'workflow_run',
+                    label: 'after',
+                });
+            }
+            else {
+                warnings.push(`${wf.slug}: runs after unknown workflow '${name}'`);
+            }
+        }
+        for (const target of wf.crossRepoTargets) {
+            if (target.toLowerCase() === self)
+                continue;
+            if (!externalRepos.includes(target))
+                externalRepos.push(target);
+            edges.push({
+                id: `cr:${wf.path}->${target}`,
+                from: wf.path,
+                to: externalNodeId(target),
+                kind: 'cross_repo',
+                label: 'files issues',
+            });
+        }
+    }
+    return { repo, workflows: parsed, externalRepos, edges, warnings };
+}

package/dist/fleet/types.d.ts

@@ -0,0 +1,250 @@
+import type { RepoRef } from '../github/types.js';
+import type { FleetLane, FleetManifest } from '../harness/lanes.js';
+/** Coarse classification of what a workflow writes. */
+export type SinkKind = 'pr' | 'issue' | 'comment' | 'label' | 'commit' | 'merge' | 'deploy' | 'cross_repo_issue' | 'dispatch';
+/** One entry from a workflow's `on:` block, summarized for display. */
+export interface TriggerSummary {
+    /** e.g. push | pull_request | issues | issue_comment | schedule | workflow_dispatch | workflow_run | repository_dispatch */
+    kind: string;
+    /** cron string, workflow_run source names, event types, etc. */
+    detail?: string;
+}
+/** The AI step a workflow runs, if any. */
+export interface AgentInfo {
+    runner: 'claude-run' | 'claude-code-action' | 'run-sh' | 'unknown';
+    /** named role from .claude/agents/<name> when passed via the `agent:` input. */
+    agentName?: string;
+    model?: string;
+    /** --allowedTools string, when discoverable. */
+    tools?: string;
+}
+/** One workflow file, reverse-imported. Node id on the canvas === `path`. */
+export interface ImportedWorkflow {
+    path: string;
+    name: string;
+    slug: string;
+    triggers: TriggerSummary[];
+    hasAgent: boolean;
+    agent?: AgentInfo;
+    sinks: SinkKind[];
+    /** workflow NAMES this runs after (on.workflow_run.workflows); resolved to edges by buildFleet. */
+    runAfterNames: string[];
+    /** owner/name repos this workflow writes to via `gh … --repo`. */
+    crossRepoTargets: string[];
+    /** a `*_ENABLED`-style kill-switch variable, if the workflow gates on one. */
+    gate?: string;
+    /** The `fleet/v1` lane the repo's committed `fleet.manifest.yml` records for this file (specs/014). */
+    lane?: FleetLane;
+}
+export type FleetEdgeKind = 'workflow_run' | 'cross_repo';
+/** A belt between two fleet nodes. `to` is a workflow path or an external repo id `ext:owner/name`. */
+export interface FleetEdge {
+    id: string;
+    from: string;
+    to: string;
+    kind: FleetEdgeKind;
+    label?: string;
+}
+/** The full reverse-imported picture of one repo's automation. */
+export interface Fleet {
+    repo: RepoRef;
+    workflows: ImportedWorkflow[];
+    /** external repos targeted cross-repo, as `owner/name`. Canvas node id === `ext:owner/name`. */
+    externalRepos: string[];
+    edges: FleetEdge[];
+    /** non-fatal parse notes (e.g. a workflow whose YAML could not be parsed). */
+    warnings: string[];
+    /** The repo's committed `fleet.manifest.yml` — the hub's interchange contract — when it has one. */
+    manifest?: FleetManifest | null;
+}
+/** Stable canvas node id for an external repo target. */
+export declare const externalNodeId: (ownerName: string) => string;
+/** Coarse cost-grouping type — port of the dash's ordered-substring classifier. */
+export type DashType = 'dependencies' | 'security' | 'ai' | 'release' | 'deploy' | 'docs' | 'automation' | 'ci' | 'other';
+/** Fleet workflow archetype — the design-pattern taxonomy observed across the fleet. */
+export type Archetype = 'standard-ci-caller' | 'mention-handler' | 'prose-kit' | 'ci-gate' | 'pr-gate' | 'pr-editor' | 'reusable-library' | 'content-factory' | 'issue-to-content' | 'agent-gatekeeper' | 'agentic-validator' | 'perfection-loop' | 'auto-merge-bot' | 'self-repair' | 'issue-autopilot' | 'nightly-audit' | 'autonomy-loop' | 'cross-repo-filer' | 'scout' | 'meta-loop' | 'ledger' | 'dispatch-hub' | 'generated-line' | 'release' | 'security-gate' | 'deploy' | 'data-sync' | 'dependency-bot' | 'other';
+/** How a `uses:` reference is pinned. */
+export type PinStyle = 'sha' | 'tag' | 'branch' | 'local' | 'unpinned';
+/** One `uses:` reference (marketplace action, local composite, or reusable workflow). */
+export interface ActionUse {
+    /** e.g. `actions/checkout`, `./.github/actions/claude-run`, `bamr87/bamr87/.github/workflows/standard-ci.yml`. */
+    action: string;
+    /** The `@ref` part, or null for local `./` uses. */
+    ref: string | null;
+    pin: PinStyle;
+}
+/** The Claude-auth wiring convention an AI workflow follows. */
+export type AuthMode = 'oauth-first' | 'oauth-only' | 'api-key-only' | 'none';
+/** Loop-safety / governance guard mechanisms actually used in the fleet. */
+export type GuardKind = 'attempt-limit' | 'label-opt-in' | 'actor-guard' | 'rate-limiter' | 'synchronize-skip' | 'smuggle-guard' | 'sticky-marker' | 'same-repo-only' | 'mention-phrase' | 'gate-job' | 'concurrency-singleton';
+/** AI usage found in one workflow (per-file rollup; a file can mix runners). */
+export interface AiFacts {
+    present: boolean;
+    /**
+     * Which invocation shapes appear (a workflow can use several).
+     * `agentic-engine` = a bare `@anthropic-ai/claude-code` CLI / `agentic_validate.py`
+     * driver — the it-journey quest engine, the fleet's single biggest AI cost center.
+     */
+    runners: ('claude-code-action' | 'claude-cli' | 'claude-run' | 'run-sh' | 'agentic-engine' | 'other')[];
+    /** Models named in the file; empty when the model lives in a composite/config (common). */
+    models: string[];
+    /** Largest --max-turns found, or null. */
+    maxTurns: number | null;
+    /** Hard dollar spend cap (`--max-cost-usd N`) — the fleet's only per-run cost ceiling, or null. */
+    maxCostUsd: number | null;
+    authMode: AuthMode;
+    /** Named agent roles (`agent: x` / `--agent x`). */
+    agents: string[];
+}
+/** Everything the cockpit knows about one workflow file. */
+export interface WorkflowFacts {
+    path: string;
+    name: string;
+    dashType: DashType;
+    archetype: Archetype;
+    triggers: TriggerSummary[];
+    /** Active cron strings from parsed `on.schedule`. */
+    crons: string[];
+    /** Cron strings present only in comments — dormant/disabled automation. */
+    dormantCrons: string[];
+    /** True when `on:` includes `workflow_call` (a reusable library). */
+    isReusable: boolean;
+    /** Reusable workflows this one calls (`uses: owner/repo/.github/workflows/x.yml@ref`). */
+    reusableCalls: string[];
+    jobCount: number;
+    hasMatrix: boolean;
+    /** True when a matrix is computed at runtime (`matrix: fromJSON(needs.*.outputs.*)`) — unknown fan-out width. */
+    matrixDynamic: boolean;
+    /** Same-repo reusable-workflow calls (`uses: ./.github/workflows/x.yml`) — intra-repo belts. */
+    localWorkflowCalls: string[];
+    /**
+     * True when the workflow spends its minutes WAITING (a `sleep` + `gh pr checks` poll
+     * loop), not computing — its "cost" is wall-clock, retireable with `--auto` + required checks.
+     */
+    waitBound: boolean;
+    /** Max declared job `timeout-minutes`, or null when none declared anywhere. */
+    timeoutMinutes: number | null;
+    runners: string[];
+    concurrency: {
+        present: boolean;
+        group: string | null;
+        cancelInProgress: 'always' | 'never' | 'conditional' | 'unset';
+    };
+    permissions: {
+        /** True when any permissions block (top or job level) is declared. */
+        declared: boolean;
+        /** True when the top level declares read-only contents. */
+        topLevelRead: boolean;
+        /** True when the TOP level grants any write scope (prefer job-level grants). */
+        topLevelWrite: boolean;
+        /** Union of `scope: write` grants anywhere in the file. */
+        writeScopes: string[];
+    };
+    /** All `uses:` references with pin style. */
+    actions: ActionUse[];
+    /** Local composite actions used (`./.github/actions/*`). */
+    compositeLocals: string[];
+    ai: AiFacts;
+    /** Repo-variable kill switches referenced anywhere (if/env/run), e.g. CONTENT_FACTORY_ENABLED. */
+    killSwitches: string[];
+    /** True when the workflow exposes a plan/apply (dry-run) dispatch input. */
+    planApply: boolean;
+    guards: GuardKind[];
+    /** Token fallback chain in privilege order, e.g. ['FLEET_TOKEN','github.token']. */
+    tokenChain: string[];
+    /** All `secrets.*` names referenced. */
+    secretsUsed: string[];
+    /** All `vars.*` names referenced. */
+    varsUsed: string[];
+    sinks: SinkKind[];
+    crossRepoTargets: string[];
+    /** Set when the file carries the ⚙ GENERATED BY GITFACTORY header. */
+    generated: {
+        blueprintPath: string | null;
+        hash: string | null;
+    } | null;
+    /** Count of "MANUAL EDIT" markers in a generated file (blueprint drift risk). */
+    manualEditMarkers: number;
+}
+export type AuditSeverity = 'fail' | 'warn' | 'info';
+/** Rule catalog entry — what the fleet standard is, for the UI's rulebook. */
+export interface AuditRuleMeta {
+    id: string;
+    title: string;
+    severity: AuditSeverity;
+    /** One-sentence statement of the fleet convention this rule encodes. */
+    standard: string;
+}
+/** One violation found in one workflow (or repo-wide when `path` is null). */
+export interface AuditFinding {
+    ruleId: string;
+    severity: AuditSeverity;
+    /** Workflow path, or null for a repo-level finding. */
+    path: string | null;
+    message: string;
+    /** The concrete fix, phrased as an actionable instruction. */
+    fix: string;
+}
+/** Factorio-style certification grade. */
+export type Grade = 'S' | 'A' | 'B' | 'C' | 'D';
+/** The audit result for one repo's whole workflow fleet. */
+export interface RepoAudit {
+    /** 0–100 conformance score (weighted: fail 10, warn 3, info 1). */
+    score: number;
+    grade: Grade;
+    findings: AuditFinding[];
+    /** Rule ids that were applicable and fully passed. */
+    passedRules: string[];
+    /** Per-workflow finding counts for the matrix view. */
+    byWorkflow: Record<string, {
+        fails: number;
+        warns: number;
+        infos: number;
+    }>;
+}
+export type MetricFlag = 'high-cost-low-value' | 'failing' | 'flaky' | 'slow' | 'cancel-heavy' | 'cron-heavy' | 'rework-heavy';
+/** Windowed run metrics for one workflow. Cost = wall-clock minutes (shadow price). */
+export interface WorkflowMetrics {
+    path: string;
+    name: string;
+    dashType: DashType;
+    runs: number;
+    totalMin: number;
+    avgMin: number;
+    p95Min: number;
+    wasteMin: number;
+    runsPerWeek: number;
+    success: number;
+    failure: number;
+    cancelled: number;
+    other: number;
+    successRatePct: number;
+    effectivenessPct: number;
+    schedPct: number;
+    /** Runs with runAttempt > 1 — the rework signal (not in the dash; gitorio addition). */
+    reworkRuns: number;
+    reworkPct: number;
+    /** Median queue latency in seconds (createdAt → runStartedAt), or null. */
+    queueP50Sec: number | null;
+    events: Record<string, number>;
+    flags: MetricFlag[];
+    /** Triage priority = wasteMin + totalMin × (1 − effectiveness/100). */
+    priority: number;
+}
+/** Rollup across a group of workflows (a repo, a type, or the whole fleet). */
+export interface MetricsRollup {
+    runs: number;
+    totalMin: number;
+    wasteMin: number;
+    effectivenessPct: number;
+    successRatePct: number;
+    reworkPct: number;
+}
+/** One repo in the fleet roster. Slugs only — never tokens (golden rule #7). */
+export interface RosterEntry {
+    /** `owner/name`. */
+    slug: string;
+    source: 'manual' | 'gitmodules';
+    /** Tracked branch when known (from .gitmodules). */
+    branch: string | null;
+}

package/dist/fleet/types.js

@@ -0,0 +1,7 @@
+// Observe-mode data model. A "fleet" is a read-only reverse-import of a repo's
+// .github/workflows/*.yml — one node per workflow, belts for workflow_run chains and
+// cross-repo `--repo` emissions. This is how GitFactory plugs into ANY repo (including
+// hand-built ones like lifehacker.dev) without shoehorning them into the authoring
+// machine types. Nothing here writes to the target repo.
+/** Stable canvas node id for an external repo target. */
+export const externalNodeId = (ownerName) => `ext:${ownerName}`;

package/dist/github/telemetry.d.ts

@@ -0,0 +1,40 @@
+import type { FactoryRun, LedState } from './types.js';
+/**
+ * Map a single run (or its absence) to a LED colour.
+ * - no run yet → `idle`
+ * - still queued/in progress → `warn`
+ * - completed successfully → `on`
+ * - completed with a failing conclusion → `bad`
+ * - completed but cancelled/skipped/neutral/action_required/unknown → `idle`
+ */
+export declare function ledForRun(run: FactoryRun | undefined): LedState;
+/**
+ * The newest run per assembly-line slug. "Newest" = max ISO `createdAt` (lexical compare is
+ * correct for well-formed UTC timestamps), tie-broken by the larger `runId`. Deterministic.
+ */
+export declare function latestBySlug(runs: FactoryRun[]): Map<string, FactoryRun>;
+/** The LED colour for each line's latest run. */
+export declare function statusBySlug(runs: FactoryRun[]): Map<string, LedState>;
+/** Top-of-dashboard rollup across every polled run. */
+export interface DashboardStats {
+    total: number;
+    completed: number;
+    success: number;
+    failure: number;
+    inProgress: number;
+    /** success / completed, in 0..1, or null when nothing has completed yet. */
+    successRate: number | null;
+    /** Median completed-run duration in seconds, or null when nothing has completed. */
+    p50DurationSec: number | null;
+}
+/** Aggregate stats across all runs. Pure; counts derive from the run `status`/`conclusion` fields. */
+export declare function dashboardStats(runs: FactoryRun[]): DashboardStats;
+/** Per-assembly-line rollup row. */
+export interface LineStat {
+    slug: string;
+    total: number;
+    successRate: number | null;
+    p50DurationSec: number | null;
+}
+/** One {@link LineStat} per slug, sorted by slug ascending. Pure and deterministic. */
+export declare function statsByLine(runs: FactoryRun[]): LineStat[];