@bamr87/fleet-engines 0.1.0

package/dist/github/telemetry.js

@@ -0,0 +1,131 @@
+// Pure telemetry mapping + stats (seed 04).
+// NO network I/O: this consumes already-fetched FactoryRun[] (from the transport client's
+// listFactoryRuns) and derives LED states + dashboard/per-line statistics. Keeping it pure
+// keeps it deterministic and trivially testable — same rules as the compiler and the deploy
+// planner (CLAUDE.md golden rule #3).
+//
+// Everything here parses fixed ISO strings only; no Date.now()/new Date() (argless) so the
+// same input always yields the same output.
+/** Conclusions that light a machine/line LED red (ARCHITECTURE §6): a run that failed to succeed. */
+const BAD_CONCLUSIONS = new Set([
+    'failure',
+    'timed_out',
+    'startup_failure',
+    'stale',
+]);
+/**
+ * Conclusions counted as a hard failure in aggregate stats. Narrower than {@link BAD_CONCLUSIONS}:
+ * `stale` glows red on a LED but is not a run-the-numbers failure (it never really executed).
+ */
+const FAILURE_CONCLUSIONS = new Set([
+    'failure',
+    'timed_out',
+    'startup_failure',
+]);
+/**
+ * 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 function ledForRun(run) {
+    if (!run)
+        return 'idle';
+    if (run.status !== 'completed')
+        return 'warn';
+    if (run.conclusion === 'success')
+        return 'on';
+    if (BAD_CONCLUSIONS.has(run.conclusion))
+        return 'bad';
+    return 'idle';
+}
+/** True when `a` is newer than `b`: later createdAt, tie-broken by larger runId. */
+function isNewer(a, b) {
+    if (a.createdAt !== b.createdAt)
+        return a.createdAt > b.createdAt;
+    return a.runId > b.runId;
+}
+/**
+ * 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 function latestBySlug(runs) {
+    const latest = new Map();
+    for (const run of runs) {
+        const current = latest.get(run.slug);
+        if (!current || isNewer(run, current))
+            latest.set(run.slug, run);
+    }
+    return latest;
+}
+/** The LED colour for each line's latest run. */
+export function statusBySlug(runs) {
+    const statuses = new Map();
+    for (const [slug, run] of latestBySlug(runs))
+        statuses.set(slug, ledForRun(run));
+    return statuses;
+}
+/**
+ * Wall-clock seconds a run took: `updatedAt - (runStartedAt ?? createdAt)`, clamped to `>= 0`
+ * (a run whose start stamp lands after its update stamp reports 0 rather than a negative). Parses
+ * fixed ISO strings only.
+ */
+function durationSec(run) {
+    const start = Date.parse(run.runStartedAt ?? run.createdAt);
+    const end = Date.parse(run.updatedAt);
+    return Math.max(0, (end - start) / 1000);
+}
+/** The p50 (median) of a set of numbers, or null if empty. Even counts average the two middles. */
+function median(values) {
+    if (values.length === 0)
+        return null;
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 1 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+/** Success rate (0..1, or null with no completed runs) + p50 duration over a run group's completed runs. */
+function rateAndP50(runs) {
+    const completed = runs.filter((r) => r.status === 'completed');
+    const success = completed.filter((r) => r.conclusion === 'success').length;
+    return {
+        successRate: completed.length ? success / completed.length : null,
+        p50DurationSec: median(completed.map(durationSec)),
+    };
+}
+/** Aggregate stats across all runs. Pure; counts derive from the run `status`/`conclusion` fields. */
+export function dashboardStats(runs) {
+    const completedRuns = runs.filter((r) => r.status === 'completed');
+    const success = completedRuns.filter((r) => r.conclusion === 'success').length;
+    const failure = completedRuns.filter((r) => FAILURE_CONCLUSIONS.has(r.conclusion)).length;
+    const inProgress = runs.filter((r) => r.status !== 'completed').length;
+    const { successRate, p50DurationSec } = rateAndP50(runs);
+    return {
+        total: runs.length,
+        completed: completedRuns.length,
+        success,
+        failure,
+        inProgress,
+        successRate,
+        p50DurationSec,
+    };
+}
+/** One {@link LineStat} per slug, sorted by slug ascending. Pure and deterministic. */
+export function statsByLine(runs) {
+    const groups = new Map();
+    for (const run of runs) {
+        const group = groups.get(run.slug);
+        if (group)
+            group.push(run);
+        else
+            groups.set(run.slug, [run]);
+    }
+    const rows = [];
+    for (const [slug, groupRuns] of groups) {
+        const { successRate, p50DurationSec } = rateAndP50(groupRuns);
+        rows.push({ slug, total: groupRuns.length, successRate, p50DurationSec });
+    }
+    rows.sort((a, b) => (a.slug < b.slug ? -1 : a.slug > b.slug ? 1 : 0));
+    return rows;
+}

package/dist/github/types.d.ts

@@ -0,0 +1,240 @@
+/** An `owner/repo` pair. */
+export interface RepoRef {
+    owner: string;
+    repo: string;
+}
+/** Parse `"owner/repo"` (tolerating a full GitHub URL or surrounding whitespace). */
+export declare function parseRepo(input: string): RepoRef | null;
+/** `owner/repo` string form. */
+export declare function repoSlug(r: RepoRef): string;
+/** Per-permission preflight state. `unknown` = we could not determine it. */
+export type PermState = 'ok' | 'missing' | 'unknown';
+/**
+ * Result of checking a fine-grained PAT against a specific repo. The app needs, at a
+ * minimum, Contents (RW) + Workflows (RW) to deploy; the rest gate optional features.
+ */
+export interface Preflight {
+    repo: RepoRef;
+    contents: PermState;
+    workflows: PermState;
+    issues: PermState;
+    pullRequests: PermState;
+    actions: PermState;
+    secrets: PermState;
+    /** True when the minimum-to-deploy permissions (contents + workflows) are present. */
+    canDeploy: boolean;
+}
+/** A file read from the repo. `sha` is the blob sha required to update or delete it. */
+export interface RepoFile {
+    path: string;
+    /** Decoded UTF-8 text. */
+    content: string;
+    sha: string;
+}
+/** One entry in a directory listing. */
+export interface RepoDirEntry {
+    path: string;
+    name: string;
+    sha: string;
+    type: 'file' | 'dir';
+}
+/** GitHub Actions repo public key for sealed-box secret encryption. */
+export interface ActionsPublicKey {
+    key: string;
+    keyId: string;
+}
+/** Where a deploy commit lands. `commit` = default branch; `pr` = new branch + PR. */
+export type DeployMode = 'commit' | 'pr';
+/** A single file the deploy will create or update. */
+export interface DeployWrite {
+    path: string;
+    content: string;
+    /** Blob sha of the existing file, when updating; omitted when creating. */
+    sha?: string;
+    reason: 'blueprint' | 'workflow' | 'prompt';
+}
+/** A file the deploy will delete (an assembly line that no longer exists). */
+export interface DeployDelete {
+    path: string;
+    sha: string;
+    reason: 'stale-workflow';
+}
+/**
+ * The full set of changes a deploy will make, computed by diffing freshly compiled
+ * output against what is currently in the repo. Rendered as a review diff before commit.
+ */
+export interface DeployPlan {
+    writes: DeployWrite[];
+    deletes: DeployDelete[];
+    /** Non-fatal notes, e.g. a referenced prompt file that is missing from the repo. */
+    warnings: string[];
+}
+/**
+ * Drift for one deployed workflow: the blueprint hash embedded in its generated header
+ * versus the hash of the current blueprint's freshly compiled output.
+ */
+export interface DriftItem {
+    path: string;
+    /** Hash parsed from the deployed file's header, or null if unparseable/absent. */
+    deployedHash: string | null;
+    compiledHash: string;
+    drifted: boolean;
+}
+/** Machine/line LED semantics (ARCHITECTURE §6): success / running / failed / never-ran. */
+export type LedState = 'on' | 'warn' | 'bad' | 'idle';
+/** A conclusion string from the Actions API, or null while a run is still in progress. */
+export type RunConclusion = 'success' | 'failure' | 'cancelled' | 'timed_out' | 'skipped' | 'action_required' | 'neutral' | 'stale' | 'startup_failure' | null;
+/** One GitHub Actions run of a `factory--*` workflow. */
+export interface FactoryRun {
+    /** Workflow file path, e.g. `.github/workflows/factory--issue-triage-line.yml`. */
+    path: string;
+    /** Slug parsed from the path, e.g. `issue-triage-line`. */
+    slug: string;
+    runId: number;
+    runNumber: number;
+    status: 'queued' | 'in_progress' | 'completed' | (string & {});
+    conclusion: RunConclusion;
+    event: string;
+    htmlUrl: string;
+    /** ISO timestamps; runStartedAt is null before the run actually starts. */
+    runStartedAt: string | null;
+    updatedAt: string;
+    createdAt: string;
+    /** 1 for a first attempt; >1 means the run was re-run (the rework signal). */
+    runAttempt: number;
+}
+/** One registered workflow from the Actions workflows API (id needed to enable/disable). */
+export interface RepoWorkflow {
+    id: number;
+    name: string;
+    /** `.github/workflows/<file>.yml`, or `dynamic/…` for GitHub-injected workflows. */
+    path: string;
+    /** `active` | `disabled_manually` | `disabled_inactivity` | … */
+    state: string;
+    htmlUrl: string;
+}
+/** Result of a conditional (ETag) runs poll. A 304 sets `notModified` and empty `runs`. */
+export interface RunsPoll {
+    runs: FactoryRun[];
+    etag: string | null;
+    notModified: boolean;
+    /** `x-ratelimit-remaining` header value when present, for polite backoff. */
+    rateRemaining: number | null;
+}
+/** One step of a run job (drill-down detail). */
+export interface RunJobStep {
+    number: number;
+    name: string;
+    status: string;
+    conclusion: RunConclusion;
+}
+/** One job of a workflow run — the Monitor tab's drill-down unit. */
+export interface RunJob {
+    jobId: number;
+    name: string;
+    status: 'queued' | 'in_progress' | 'completed' | (string & {});
+    conclusion: RunConclusion;
+    startedAt: string | null;
+    completedAt: string | null;
+    htmlUrl: string;
+    steps: RunJobStep[];
+}
+/**
+ * Transport surface. Implemented by a thin fetch-based client (no Octokit dep — keeps
+ * the static bundle lean and trivially mockable via `globalThis.fetch`). Every method
+ * rejects with a {@link GithubError} on non-2xx.
+ */
+export interface GithubClient {
+    /** Authenticated login (from GET /user at connect time). */
+    readonly login: string;
+    /** Best-effort permission check for a repo. Never throws for permission gaps; maps them to `missing`. */
+    preflight(repo: RepoRef): Promise<Preflight>;
+    /** Read a file, or `null` if it does not exist (404). Throws on other errors. */
+    getFile(repo: RepoRef, path: string, ref?: string): Promise<RepoFile | null>;
+    /** List a directory, or `[]` if it does not exist. */
+    listDir(repo: RepoRef, path: string, ref?: string): Promise<RepoDirEntry[]>;
+    /** Create or update a file (Contents API). Pass `sha` to update, `branch` to target a branch. */
+    putFile(repo: RepoRef, path: string, content: string, message: string, opts?: {
+        sha?: string;
+        branch?: string;
+    }): Promise<void>;
+    /** Delete a file (Contents API). */
+    deleteFile(repo: RepoRef, path: string, sha: string, message: string, opts?: {
+        branch?: string;
+    }): Promise<void>;
+    /** Default branch name (e.g. `main`). */
+    getDefaultBranch(repo: RepoRef): Promise<string>;
+    /** Create a new branch `newBranch` pointing at the tip of `fromBranch`. */
+    createBranch(repo: RepoRef, newBranch: string, fromBranch: string): Promise<void>;
+    /** Open a pull request; returns the html_url. */
+    createPullRequest(repo: RepoRef, args: {
+        title: string;
+        head: string;
+        base: string;
+        body?: string;
+    }): Promise<string>;
+    /** Repo public key for sealed-box secret encryption. */
+    getActionsPublicKey(repo: RepoRef): Promise<ActionsPublicKey>;
+    /** Whether an Actions secret with this name exists (metadata only; value never returned). */
+    hasSecret(repo: RepoRef, name: string): Promise<boolean>;
+    /** Create/update an Actions secret with an already sealed-box-encrypted value. */
+    putSecret(repo: RepoRef, name: string, encryptedValue: string, keyId: string): Promise<void>;
+    /**
+     * List recent runs of `factory--*` workflows, newest first. Pass a prior `etag` for a
+     * conditional request — a 304 returns `{ notModified: true, runs: [] }` and costs no
+     * rate quota. Never throws for an empty/absent Actions history.
+     */
+    listFactoryRuns(repo: RepoRef, opts?: {
+        etag?: string | null;
+        perPage?: number;
+        pathPrefix?: string;
+    }): Promise<RunsPoll>;
+    /** Jobs (with steps) for one run — the Monitor drill-down. */
+    listRunJobs(repo: RepoRef, runId: number): Promise<RunJob[]>;
+    /** Fire a workflow_dispatch for a workflow file (e.g. `factory--x.yml`). Defaults to the default branch. */
+    dispatchWorkflow(repo: RepoRef, workflowFile: string, ref?: string): Promise<void>;
+    /** Cancel an in-progress run. */
+    cancelRun(repo: RepoRef, runId: number): Promise<void>;
+    /**
+     * Registered workflows for a repo (id, path, `state` — the disable/enable handle).
+     * Never throws for a repo without Actions — returns `[]` on 403/404.
+     */
+    listRepoWorkflows(repo: RepoRef): Promise<RepoWorkflow[]>;
+    /** Re-run a completed run (all jobs) — the "clear the jam" maintain action. */
+    rerunRun(repo: RepoRef, runId: number): Promise<void>;
+    /** Enable or disable a workflow by id — powering a machine on/off from the cockpit. */
+    setWorkflowEnabled(repo: RepoRef, workflowId: number, enabled: boolean): Promise<void>;
+    /** Open an issue (the audit's "file a work order" action); returns the html_url. */
+    createIssue(repo: RepoRef, args: {
+        title: string;
+        body: string;
+        labels?: string[];
+    }): Promise<string>;
+    /**
+     * List repository Actions variables (the enablement-gate kill switches). Never throws for
+     * an empty/absent list or missing permission — returns `[]`. Values are readable (unlike
+     * secrets), which is exactly what lets the app show a line as armed or idle.
+     */
+    /**
+     * Repo Actions variables, or `null` when they could not be read (no permission,
+     * no Actions). `null` is NOT the same as `[]`: an empty list means the repo really
+     * has no variables, so a kill switch is genuinely off, while `null` means we do not
+     * know — and a cockpit must not draw a running loop as stopped.
+     */
+    listVariables(repo: RepoRef): Promise<RepoVariable[] | null>;
+    /** Read one Actions variable, or `null` if unset. */
+    getVariable(repo: RepoRef, name: string): Promise<RepoVariable | null>;
+    /** Create or update an Actions variable (PATCH if it exists, else POST). */
+    setVariable(repo: RepoRef, name: string, value: string): Promise<void>;
+}
+/** A repository Actions variable — an enablement-gate kill switch. Values are plaintext. */
+export interface RepoVariable {
+    name: string;
+    value: string;
+}
+/** Error carrying the HTTP status so callers can branch on 401/403/404/422. */
+export declare class GithubError extends Error {
+    readonly status: number;
+    readonly url: string;
+    constructor(message: string, status: number, url: string);
+}

package/dist/github/types.js

@@ -0,0 +1,36 @@
+// Shared contract for the GitHub I/O layer (seed 03).
+// This file is the seam between the transport client, the crypto helper, and the
+// deploy planner — each is implemented against these types. No I/O here; pure types
+// + a couple of tiny pure helpers so the modules agree on shapes.
+//
+// Security (CLAUDE.md golden rule #7): the PAT lives in sessionStorage at most and is
+// held in a closure by the client; it never appears in these types, in the blueprint,
+// or in any persisted state. The Claude auth secret (CLAUDE_CODE_OAUTH_TOKEN or the
+// ANTHROPIC_API_KEY fallback) plaintext is passed straight into sealSecret and never stored.
+/** Parse `"owner/repo"` (tolerating a full GitHub URL or surrounding whitespace). */
+export function parseRepo(input) {
+    const cleaned = input
+        .trim()
+        .replace(/^https?:\/\/github\.com\//i, '')
+        .replace(/\.git$/i, '')
+        .replace(/\/$/, '');
+    const m = /^([A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?)\/([A-Za-z0-9._-]+)$/.exec(cleaned);
+    if (!m)
+        return null;
+    return { owner: m[1], repo: m[2] };
+}
+/** `owner/repo` string form. */
+export function repoSlug(r) {
+    return `${r.owner}/${r.repo}`;
+}
+/** Error carrying the HTTP status so callers can branch on 401/403/404/422. */
+export class GithubError extends Error {
+    status;
+    url;
+    constructor(message, status, url) {
+        super(message);
+        this.status = status;
+        this.url = url;
+        this.name = 'GithubError';
+    }
+}

package/dist/harness/health.d.ts

@@ -0,0 +1,135 @@
+export interface UsageWorkflow {
+    repo?: string;
+    workflow?: string;
+    path?: string;
+    avg_min?: number;
+    runs?: number;
+    success?: number;
+    external?: boolean;
+}
+export interface ActionsUsage {
+    generated_at?: string;
+    totals?: {
+        success_rate_pct?: number;
+        effectiveness_pct?: number;
+        total_min?: number;
+        waste_min?: number;
+        waste_hours?: number;
+    };
+    workflows?: UsageWorkflow[];
+}
+export interface FleetTriage {
+    generated_at?: string;
+    totals?: {
+        failing_workflows?: number;
+        repos_red?: number;
+    };
+}
+export interface IssuePipeline {
+    generated_at?: string;
+    totals?: {
+        pipeline_prs?: number;
+        stages?: Record<string, number>;
+    };
+}
+export interface RotationToken {
+    name?: string;
+    oldest_age_days?: number;
+    max_age_days?: number;
+}
+export interface TokenRotation {
+    generated_at?: string;
+    tokens?: RotationToken[];
+}
+/** The four signals. `null`/`undefined` (or `{}`) means "missing" — the hub's `{}`. */
+export interface HarnessSignals {
+    actions_usage?: ActionsUsage | null;
+    fleet_triage?: FleetTriage | null;
+    issue_pipeline?: IssuePipeline | null;
+    token_rotation?: TokenRotation | null;
+}
+export declare const SIGNAL_NAMES: readonly ['actions_usage', 'fleet_triage', 'issue_pipeline', 'token_rotation'];
+export type SignalName = (typeof SIGNAL_NAMES)[number];
+export interface HarnessConfig {
+    scorecard: {
+        completion_rate_min_pct: number;
+        effectiveness_min_pct: number;
+    };
+    trip_wires: {
+        stale_data_days: number;
+        pass_rate_floor_pct: number;
+        waste_ceiling_pct: number;
+        cost_spike_multiplier: number;
+        cost_spike_min_runs: number;
+        cost_spike_min_avg_min: number;
+        standing_failures_max: number;
+        credential_grace_days: number;
+    };
+}
+/** The hub's defaults (harness.py `DEFAULT_SCORECARD` / `DEFAULT_TRIP_WIRES`). */
+export declare const DEFAULT_CONFIG: HarnessConfig;
+/** A finite number, or null. Strings that are numbers are accepted (YAML round-trips them). */
+export declare function num(v: unknown): number | null;
+/**
+ * Read the `harness:` block out of a parsed `fleet.yml` (or the block itself), with the
+ * hub's defaults for every absent key — an absent block degrades to sane behaviour.
+ */
+export declare function parseHarnessConfig(fleetYml: unknown): HarnessConfig;
+/** The generators stamp `%Y-%m-%d %H:%M UTC`; ISO and bare dates are tolerated (harness.py). */
+export declare function parseGeneratedAt(value: unknown): Date | null;
+export declare function sourceAgeDays(data: unknown, now: Date): number | null;
+export declare function median(values: number[]): number | null;
+export type Direction = 'up' | 'down' | 'steady';
+export type MetricStatus = 'ok' | 'warn' | 'unknown';
+export interface Metric {
+    value: number | null;
+    direction: Direction;
+    threshold?: number;
+    status?: MetricStatus;
+}
+export declare const SCORECARD_KEYS: readonly ['completion_rate_pct', 'effectiveness_pct', 'waste_hours', 'cost_min_per_verified_run', 'standing_failures', 'repos_red', 'escalations_open', 'agent_prs_open', 'oldest_credential_age_days'];
+export type ScorecardKey = (typeof SCORECARD_KEYS)[number];
+export type Scorecard = Record<ScorecardKey, Metric>;
+/** The playbook's health scorecard, from the signals the fleet already keeps. */
+export declare function buildScorecard(cfg: HarnessConfig, usage: ActionsUsage | null | undefined, triage: FleetTriage | null | undefined, pipeline: IssuePipeline | null | undefined, rotation: TokenRotation | null | undefined): Scorecard;
+export type WireId = 'stale-data' | 'pass-rate-floor' | 'waste-ceiling' | 'cost-spike' | 'standing-failures' | 'credential-overdue';
+export declare const WIRE_IDS: WireId[];
+export interface TripWire {
+    id: WireId;
+    tripped: boolean;
+    summary: string;
+    detail?: Record<string, unknown>[];
+}
+/** Every wire is reported, tripped or not — a quiet panel and a lost panel must not look the same. */
+export declare function evaluateTripWires(cfg: HarnessConfig, usage: ActionsUsage | null | undefined, triage: FleetTriage | null | undefined, pipeline: IssuePipeline | null | undefined, rotation: TokenRotation | null | undefined, now: Date): TripWire[];
+/** Python's str() for an int-typed value the summaries interpolate (`None` when absent). */
+export declare function fmt(v: number | null): string;
+/**
+ * Python's str() for a float-typed value: an integral float prints with `.0` (`3.0`, `90.0`).
+ * The hub's rates, percentages, medians, and the multiplier/floor thresholds are floats there
+ * (`round(x, 1)` results and `3.0` / `5.0` in fleet.yml), so their summaries carry the decimal.
+ */
+export declare function fmtFloat(v: number | null): string;
+export interface HarnessHealth {
+    generated_at: string;
+    sources: Record<SignalName, {
+        present: boolean;
+        age_days: number | null;
+    }>;
+    scorecard: Scorecard;
+    trip_wires: TripWire[];
+    tripped_count: number;
+    note: string;
+}
+export declare const HARNESS_NOTE = "Six-layer harness health: scorecard + trip wires computed offline from the committed fleet signals (docs/HARNESS.md). Thresholds live in _data/fleet.yml `harness:`. A tripped wire is an attention item; the doctor and issue-pipeline loops own the fixes.";
+/** `%Y-%m-%d %H:%M UTC`, the hub's stamp. */
+export declare function stampUtc(now: Date): string;
+/** The hub's `run()`: the committed `harness_health.yml`, as data. */
+export declare function harnessHealth(signals: HarnessSignals, cfg?: HarnessConfig, now?: Date): HarnessHealth;
+/** Keep only the fields the engine reads (untrusted YAML never travels further). */
+export declare function toActionsUsage(v: unknown): ActionsUsage | null;
+export declare function toFleetTriage(v: unknown): FleetTriage | null;
+export declare function toIssuePipeline(v: unknown): IssuePipeline | null;
+export declare function toTokenRotation(v: unknown): TokenRotation | null;
+/** The hub's committed `harness_health.yml` as data, or null when the document is not one. */
+export declare function toHarnessHealth(v: unknown): HarnessHealth | null;