@bamr87/fleet-engines 0.1.0

package/dist/harness/lanes.js

@@ -0,0 +1,92 @@
+// The `fleet/v1` lane — the fleet's interchange contract. Every fleet repo commits a
+// `fleet.manifest.yml` in this vocabulary (bamr87/wtd's FLEET-SPEC; `wtd fleet adopt`
+// derives it, the hub and its consoles read it), so a lane designed in one tool and
+// inventoried in another is the same record. `parseFleetManifest` reads any repo's manifest
+// tolerantly; the blueprint → lanes direction lives with GitFactory's compiler, not here.
+// Pure; manifest text is untrusted data.
+import { parse as parseYaml } from 'yaml';
+export const LANE_KINDS = [
+    'content',
+    'triage',
+    'review',
+    'maintenance',
+    'analysis',
+    'orchestrator',
+    'fanout',
+    'mention',
+    'other',
+];
+export const LANE_HARNESSES = ['claude-code-action', 'claude-cli', 'wtd-fleet', 'engine', 'none'];
+// ── manifest → lanes ────────────────────────────────────────────────────────
+const isRecord = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const strList = (v) => Array.isArray(v) ? v.filter((x) => typeof x === 'string') : [];
+function laneFrom(v) {
+    if (!isRecord(v) || typeof v.id !== 'string' || !v.id.trim())
+        return null;
+    const kind = LANE_KINDS.includes(v.kind) ? v.kind : 'other';
+    const harness = LANE_HARNESSES.includes(v.harness)
+        ? v.harness
+        : 'none';
+    const triggers = [];
+    for (const t of Array.isArray(v.triggers) ? v.triggers : []) {
+        if (!isRecord(t))
+            continue;
+        if (t.kind === 'schedule' && typeof t.cron === 'string')
+            triggers.push({ kind: 'schedule', cron: t.cron });
+        else if (t.kind === 'dispatch')
+            triggers.push({ kind: 'dispatch' });
+        else if (t.kind === 'event')
+            triggers.push({ kind: 'event', events: strList(t.events) });
+    }
+    const g = isRecord(v.guardrails) ? v.guardrails : {};
+    const guardrails = { never_merges: g.never_merges !== false };
+    if (typeof g.opens_pull_requests === 'boolean')
+        guardrails.opens_pull_requests = g.opens_pull_requests;
+    if (Array.isArray(g.writable_paths))
+        guardrails.writable_paths = strList(g.writable_paths);
+    if (typeof g.max_writes_per_run === 'number')
+        guardrails.max_writes_per_run = g.max_writes_per_run;
+    return {
+        id: v.id.trim(),
+        kind,
+        harness,
+        implementation: typeof v.implementation === 'string' ? v.implementation : '',
+        description: typeof v.description === 'string' ? v.description : v.id.trim(),
+        triggers,
+        switch: typeof v.switch === 'string' && v.switch.trim() ? v.switch.trim() : null,
+        uses_tokens: strList(v.uses_tokens).sort(),
+        guardrails,
+        ...(Array.isArray(v.state_paths) ? { state_paths: strList(v.state_paths) } : {}),
+    };
+}
+/** Parse a `fleet.manifest.yml`. Never throws: junk yields an empty manifest with `skipped`. */
+export function parseFleetManifest(text) {
+    let doc = null;
+    try {
+        doc = parseYaml(text);
+    }
+    catch {
+        doc = null;
+    }
+    const root = isRecord(doc) ? doc : {};
+    const rawLanes = Array.isArray(root.lanes) ? root.lanes : [];
+    const lanes = rawLanes.map(laneFrom).filter((l) => !!l);
+    const provenance = root.provenance === 'declared' || root.provenance === 'derived' ? root.provenance : 'unknown';
+    return {
+        spec_version: typeof root.spec_version === 'string' ? root.spec_version : '',
+        repo: typeof root.repo === 'string' ? root.repo : '',
+        provenance,
+        summary: typeof root.summary === 'string' ? root.summary : '',
+        lanes,
+        skipped: rawLanes.length - lanes.length,
+    };
+}
+/** The lane whose implementation is this workflow path, or whose id is its basename. */
+export function laneForPath(manifest, path) {
+    if (!manifest)
+        return null;
+    const base = path.split('/').pop()?.replace(/\.ya?ml$/i, '') ?? path;
+    return (manifest.lanes.find((l) => l.implementation === path) ??
+        manifest.lanes.find((l) => l.id === base) ??
+        null);
+}

package/dist/harness/manifest-yaml.d.ts

@@ -0,0 +1,12 @@
+import type { FleetLane } from './lanes.js';
+export interface ManifestMeta {
+    repo: string;
+    summary: string;
+    provenance?: 'declared' | 'derived';
+    /** Comment lines (without `# `) written above the document. */
+    header?: string[];
+}
+/** A `fleet.manifest.yml` document for a set of lanes (lanes + the token contract), as text. */
+export declare function toFleetManifestYaml(lanes: FleetLane[], meta: ManifestMeta): string;
+/** A small, deterministic YAML emitter for the manifest (block style, quoted where needed). */
+export declare function yamlDump(value: unknown, indent?: number): string;

package/dist/harness/manifest-yaml.js

@@ -0,0 +1,69 @@
+// The fleet/v1 manifest as text: a `fleet.manifest.yml` document for a set of lanes, and the
+// small deterministic YAML emitter behind it. Kept apart from lanes.ts so a reader that only
+// parses does not carry the emitter.
+/** A `fleet.manifest.yml` document for a set of lanes (lanes + the token contract), as text. */
+export function toFleetManifestYaml(lanes, meta) {
+    const { repo } = meta;
+    const tokens = [...new Set(lanes.flatMap((l) => l.uses_tokens))].sort();
+    const doc = {
+        spec_version: 'fleet/v1',
+        repo,
+        provenance: meta.provenance ?? 'derived',
+        summary: meta.summary,
+        lanes,
+        tokens: tokens.map((name) => ({
+            name,
+            scope: 'fleet',
+            required: name === 'CLAUDE_CODE_OAUTH_TOKEN',
+            purpose: TOKEN_PURPOSE[name] ?? 'Declared by a machine on the floor.',
+            used_by: lanes.filter((l) => l.uses_tokens.includes(name)).map((l) => l.id),
+        })),
+    };
+    const header = meta.header ?? ["fleet.manifest.yml — this repository's AI fleet, in the shared 'fleet/v1' vocabulary."];
+    return `${header.map((h) => `# ${h}\n`).join('')}${yamlDump(doc)}`;
+}
+const TOKEN_PURPOSE = {
+    CLAUDE_CODE_OAUTH_TOKEN: 'Preferred Claude auth (house convention: OAuth first). Produced by `claude setup-token`.',
+    ANTHROPIC_API_KEY: 'Fallback Claude auth, used only when the OAuth token is absent.',
+    FLEET_TOKEN: 'Fine-grained PAT for cross-repo writes.',
+};
+/** A small, deterministic YAML emitter for the manifest (block style, quoted where needed). */
+export function yamlDump(value, indent = 0) {
+    const pad = '  '.repeat(indent);
+    if (Array.isArray(value)) {
+        if (!value.length)
+            return `${pad}[]\n`;
+        return value
+            .map((item) => {
+            if (item && typeof item === 'object') {
+                const body = yamlDump(item, indent + 1).replace(/^\s*/, '');
+                return `${pad}- ${body}`;
+            }
+            return `${pad}- ${scalar(item)}\n`;
+        })
+            .join('');
+    }
+    if (value && typeof value === 'object') {
+        return Object.entries(value)
+            .map(([k, v]) => {
+            if (v && typeof v === 'object') {
+                if (Array.isArray(v) && !v.length)
+                    return `${pad}${k}: []\n`;
+                return `${pad}${k}:\n${yamlDump(v, indent + 1)}`;
+            }
+            return `${pad}${k}: ${scalar(v)}\n`;
+        })
+            .join('');
+    }
+    return `${pad}${scalar(value)}\n`;
+}
+function scalar(v) {
+    if (v === null || v === undefined)
+        return 'null';
+    if (typeof v === 'boolean' || typeof v === 'number')
+        return String(v);
+    const s = String(v);
+    return /^[A-Za-z0-9_./@-][A-Za-z0-9_./@ -]*$/.test(s) && !/^(true|false|null|yes|no)$/i.test(s)
+        ? s
+        : JSON.stringify(s);
+}

package/dist/harness/signals.d.ts

@@ -0,0 +1,32 @@
+import type { FactoryRun } from '../github/types.js';
+import type { MetricsRollup } from '../fleet/types.js';
+import type { ActionsUsage, FleetTriage, HarnessSignals } from './health.js';
+/** The slice of a Fleet Ops metrics row the adapter needs (`FleetWorkflowMetrics` fits). */
+export interface LiveWorkflowMetrics {
+    repo: string;
+    displayPath: string;
+    name: string;
+    runs: number;
+    avgMin: number;
+    success: number;
+}
+/** The slice of a scanned repo the adapter needs (`RepoSnapshot` fits). */
+export interface LiveRepo {
+    slug: string;
+    status: 'idle' | 'loading' | 'ready' | 'error';
+    runs: FactoryRun[];
+}
+export interface LiveScan {
+    /** Fleet-wide rollup (Fleet Ops' `fleetMetrics` rollup). */
+    rollup: MetricsRollup | null;
+    workflows: LiveWorkflowMetrics[];
+    repos: LiveRepo[];
+    /** When the scan finished; becomes every signal's `generated_at`. */
+    scannedAt: Date;
+}
+/** The hub's `actions_usage.yml` totals + per-workflow rows, from a live scan. */
+export declare function liveActionsUsage(scan: LiveScan): ActionsUsage | null;
+/** The hub's `fleet_triage.yml` totals the scorecard reads: standing red workflows and red repos. */
+export declare function liveFleetTriage(scan: LiveScan): FleetTriage | null;
+/** All four signals from a live scan; the hub-only loops are honestly absent. */
+export declare function liveSignals(scan: LiveScan): HarnessSignals;

package/dist/harness/signals.js

@@ -0,0 +1,74 @@
+// Live signals (specs/014-harness-parity, FR-3): the hub's four signal shapes, built from a
+// Fleet Ops scan instead of the hub's committed files, so the same `harnessHealth()` runs
+// over a live fleet. Only `actions_usage` and `fleet_triage` can be derived from a scan;
+// `issue_pipeline` and `token_rotation` are the hub's own loops and report as missing —
+// exactly what the hub's generator would say if those files were absent. Pure.
+import { stampUtc } from './health.js';
+const round1 = (x) => Math.round(x * 10) / 10;
+/** The hub's `actions_usage.yml` totals + per-workflow rows, from a live scan. */
+export function liveActionsUsage(scan) {
+    if (!scan.rollup)
+        return null;
+    const r = scan.rollup;
+    const workflows = scan.workflows.map((w) => ({
+        repo: w.repo.split('/').pop() ?? w.repo,
+        workflow: w.name,
+        path: w.displayPath,
+        avg_min: round1(w.avgMin),
+        runs: w.runs,
+        success: w.success,
+        external: false,
+    }));
+    return {
+        generated_at: stampUtc(scan.scannedAt),
+        totals: {
+            success_rate_pct: round1(r.successRatePct),
+            effectiveness_pct: round1(r.effectivenessPct),
+            total_min: round1(r.totalMin),
+            waste_min: round1(r.wasteMin),
+            waste_hours: round1(r.wasteMin / 60),
+        },
+        workflows,
+    };
+}
+/** Newest run per workflow path, per repo. */
+function latestByPath(runs) {
+    const m = new Map();
+    for (const run of runs) {
+        const cur = m.get(run.path);
+        if (!cur || run.createdAt > cur.createdAt)
+            m.set(run.path, run);
+    }
+    return m;
+}
+/** The hub's `fleet_triage.yml` totals the scorecard reads: standing red workflows and red repos. */
+export function liveFleetTriage(scan) {
+    const ready = scan.repos.filter((r) => r.status === 'ready');
+    if (!ready.length)
+        return null;
+    let failing = 0;
+    let reposRed = 0;
+    for (const repo of ready) {
+        let red = 0;
+        for (const run of latestByPath(repo.runs).values()) {
+            if (run.status === 'completed' && run.conclusion === 'failure')
+                red += 1;
+        }
+        failing += red;
+        if (red > 0)
+            reposRed += 1;
+    }
+    return {
+        generated_at: stampUtc(scan.scannedAt),
+        totals: { failing_workflows: failing, repos_red: reposRed },
+    };
+}
+/** All four signals from a live scan; the hub-only loops are honestly absent. */
+export function liveSignals(scan) {
+    return {
+        actions_usage: liveActionsUsage(scan),
+        fleet_triage: liveFleetTriage(scan),
+        issue_pipeline: null,
+        token_rotation: null,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export * from './github/types.js';
+export * from './github/telemetry.js';
+export * from './fleet/types.js';
+export * from './fleet/manifest.js';
+export * from './fleet/parse.js';
+export * from './fleet/facts.js';
+export * from './fleet/audit.js';
+export * from './fleet/metrics.js';
+export * from './fleet/import.js';
+export * from './harness/lanes.js';
+export * from './harness/manifest-yaml.js';
+export * from './harness/health.js';
+export * from './harness/signals.js';
+export * from './harness/hub-paths.js';
+export * from './harness/hubread.js';

package/dist/index.js

@@ -0,0 +1,19 @@
+// @bamr87/fleet-engines — the fleet's pure engines, versioned once and consumed by dependency:
+// the fleet/v1 manifest, workflow facts, the audit rulebook, metrics, the harness scorecard
+// and trip wires, and the GithubClient contract every console implements over its own fetch.
+// No I/O of its own: everything that reads GitHub takes a client you provide.
+export * from './github/types.js';
+export * from './github/telemetry.js';
+export * from './fleet/types.js';
+export * from './fleet/manifest.js';
+export * from './fleet/parse.js';
+export * from './fleet/facts.js';
+export * from './fleet/audit.js';
+export * from './fleet/metrics.js';
+export * from './fleet/import.js';
+export * from './harness/lanes.js';
+export * from './harness/manifest-yaml.js';
+export * from './harness/health.js';
+export * from './harness/signals.js';
+export * from './harness/hub-paths.js';
+export * from './harness/hubread.js';

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@bamr87/fleet-engines",
+  "version": "0.1.0",
+  "description": "The fleet's pure engines, versioned once: fleet/v1 manifest parse + emit, workflow facts, the audit rulebook, metrics, the harness scorecard and trip wires, and the GithubClient contract every console implements over its own fetch. Consumed by dependency by GitFactory and zer0-CMS.",
+  "license": "MIT",
+  "author": "bamr87",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bamr87/bamr87.git",
+    "directory": "templates/fleet-engines"
+  },
+  "homepage": "https://github.com/bamr87/bamr87/tree/main/templates/fleet-engines",
+  "keywords": [
+    "fleet",
+    "github-actions",
+    "harness",
+    "audit",
+    "fleet-manifest"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "VERSION"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "yaml": ">=2.9.0"
+  },
+  "devDependencies": {
+    "@types/node": ">=22",
+    "typescript": ">=5.9",
+    "vitest": ">=3"
+  }
+}