@groundnuty/macf 0.2.37 → 0.2.39

package/dist/cli/commands/registry-prune.d.ts

@@ -0,0 +1,81 @@
+import type { AgentInfo, HealthResponse } from '@groundnuty/macf-core';
+/** A registry entry's liveness verdict. `alive` = keep, `dead` = remove. */
+export type PruneVerdict = 'alive' | 'dead';
+/**
+ * Why an entry got its verdict — surfaced in the report so the operator sees the
+ * basis before consenting (DR-031, groundnuty/macf#568):
+ *  - `'responding'`      — a /health probe answered → keep (a successful probe
+ *                          ALWAYS means alive, regardless of heartbeat state).
+ *  - `'recent-heartbeat'`— probes failed BUT `last_heartbeat` is fresh (< TTL) →
+ *                          keep; the instance beat within the TTL, so an
+ *                          unreachable /health is treated as a transient blip.
+ *  - `'stale-heartbeat'` — probes failed AND `last_heartbeat` aged past the TTL →
+ *                          remove; the stale beat reinforces the dead verdict.
+ *  - `'unreachable'`     — probes failed AND there is no heartbeat data (pre-DR-031
+ *                          or heartbeat-disabled) → remove (the legacy verdict).
+ */
+export type PruneReason = 'responding' | 'recent-heartbeat' | 'stale-heartbeat' | 'unreachable';
+/** One classified registry entry. */
+export interface PruneEntry {
+    readonly name: string;
+    readonly host: string;
+    readonly port: number;
+    readonly verdict: PruneVerdict;
+    readonly reason: PruneReason;
+}
+/** Probe a single endpoint's `/health` — returns the body or null on failure. */
+export type ProbeFn = (host: string, port: number) => Promise<HealthResponse | null>;
+/** Options governing the liveness classification. */
+export interface ClassifyOptions {
+    /** Extra probe attempts after the first failure (default 1 → 2 total). */
+    readonly retries?: number;
+    /** Delay between attempts in ms (default 0; the CLI uses a brief pause). */
+    readonly delayMs?: number;
+    /**
+     * Staleness TTL in ms for the DR-031 heartbeat signal (default
+     * `DEFAULT_REGISTRY_TTL_MS` = 15 min). An entry with a `last_heartbeat` older
+     * than this is treated as a (reinforcing) dead-signal.
+     */
+    readonly ttlMs?: number;
+    /** Injectable epoch-ms clock for deterministic staleness tests (default `Date.now()`). */
+    readonly now?: number;
+}
+/**
+ * Classify each peer as alive (keep) / dead (remove) via `probe`, with the
+ * DR-031 (groundnuty/macf#568) registry-heartbeat staleness as a COMPLEMENTARY
+ * dead-signal. A peer is removed only when:
+ *
+ *   dead = (ALL liveness probes fail) AND (isStaleEntry OR no-heartbeat-data)
+ *
+ * Two conservative invariants fall out of that formula:
+ *  - A SUCCESSFUL probe ALWAYS means alive — a responding agent is NEVER pruned,
+ *    regardless of a stale heartbeat (a fresh process may not have beaten yet).
+ *  - A FRESH heartbeat (beat within the TTL) keeps an entry even when /health is
+ *    momentarily unreachable — the recent beat is a second, independent liveness
+ *    signal that guards against pruning on a transient probe blip.
+ * A stale heartbeat only ever REINFORCES the dead verdict an unreachable probe
+ * already reaches (it never overrides a live probe). Entries with no
+ * `last_heartbeat` (pre-DR-031 / heartbeat-disabled) keep the legacy
+ * "dead iff all probes fail" behavior, since `isStaleEntry` is false for absence.
+ *
+ * PURE w.r.t. `probe`, `ttlMs`, and `now` — tests inject fakes. The probe retry
+ * is the "never remove on a single flaky read" guard.
+ */
+export declare function classifyEntries(peers: readonly {
+    readonly name: string;
+    readonly info: AgentInfo;
+}[], probe: ProbeFn, opts?: ClassifyOptions): Promise<readonly PruneEntry[]>;
+/** Format a verdict line for the report (pure — exported for tests). */
+export declare function formatVerdictLine(e: PruneEntry): string;
+/** Options for `runRegistryPrune`. */
+export interface RunRegistryPruneOptions {
+    /** Skip the confirmation prompt (non-interactive). */
+    readonly yes?: boolean;
+}
+/**
+ * `macf registry prune` entry point. Returns the shell exit code. Lists the
+ * registry, probes each entry over mTLS (with retry), prints per-entry
+ * verdicts, then removes ONLY confirmed-dead entries after consent.
+ */
+export declare function runRegistryPrune(projectDir: string, opts?: RunRegistryPruneOptions): Promise<number>;
+//# sourceMappingURL=registry-prune.d.ts.map

package/dist/cli/commands/registry-prune.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-prune.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/registry-prune.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvE,4EAA4E;AAC5E,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,MAAM,CAAC;AAE5C;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,WAAW,GACnB,YAAY,GACZ,kBAAkB,GAClB,iBAAiB,GACjB,aAAa,CAAC;AAElB,qCAAqC;AACrC,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED,iFAAiF;AACjF,MAAM,MAAM,OAAO,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;AAErF,qDAAqD;AACrD,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,0FAA0F;IAC1F,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAKD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,EAAE,EACrE,KAAK,EAAE,OAAO,EACd,IAAI,CAAC,EAAE,eAAe,GACrB,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC,CAoChC;AAED,wEAAwE;AACxE,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,UAAU,GAAG,MAAM,CAYvD;AAaD,sCAAsC;AACtC,MAAM,WAAW,uBAAuB;IACtC,sDAAsD;IACtD,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE,uBAAuB,GAC7B,OAAO,CAAC,MAAM,CAAC,CA8DjB"}

package/dist/cli/commands/registry-prune.js

@@ -0,0 +1,163 @@
+/**
+ * `macf registry prune` — confirm-before-destroy registry maintenance (macf#556).
+ *
+ * Root hazard: a blind registry `DELETE` orphaned LIVE channel servers. This
+ * command mTLS-`/health`-checks each `MACF_AGENT_*` entry and removes ONLY
+ * confirmed-dead ones — and only after explicit operator consent (default No;
+ * `--yes` bypasses for automation). "Confirmed dead" means the probe failed
+ * across a brief retry: a single flaky read NEVER removes an entry.
+ *
+ * Reuses the existing building blocks: the mTLS `/health` ping
+ * (`pingAgentHealth`), the registry list/remove surface
+ * (`createRegistryFromConfig`), the CA-cert read (`createClientFromConfig`),
+ * and the consent-prompt pattern from `doctor.ts`.
+ */
+import { createInterface } from 'node:readline';
+import { readAgentConfig, tokenSourceFromConfig, agentCertPath, agentKeyPath, } from '../config.js';
+import { createClientFromConfig } from '../registry-helper.js';
+import { createRegistryFromConfig, generateToken, pingAgentHealth, toVariableSegment, isStaleEntry, DEFAULT_REGISTRY_TTL_MS, } from '@groundnuty/macf-core';
+const sleep = (ms) => ms > 0 ? new Promise((r) => setTimeout(r, ms)) : Promise.resolve();
+/**
+ * Classify each peer as alive (keep) / dead (remove) via `probe`, with the
+ * DR-031 (groundnuty/macf#568) registry-heartbeat staleness as a COMPLEMENTARY
+ * dead-signal. A peer is removed only when:
+ *
+ *   dead = (ALL liveness probes fail) AND (isStaleEntry OR no-heartbeat-data)
+ *
+ * Two conservative invariants fall out of that formula:
+ *  - A SUCCESSFUL probe ALWAYS means alive — a responding agent is NEVER pruned,
+ *    regardless of a stale heartbeat (a fresh process may not have beaten yet).
+ *  - A FRESH heartbeat (beat within the TTL) keeps an entry even when /health is
+ *    momentarily unreachable — the recent beat is a second, independent liveness
+ *    signal that guards against pruning on a transient probe blip.
+ * A stale heartbeat only ever REINFORCES the dead verdict an unreachable probe
+ * already reaches (it never overrides a live probe). Entries with no
+ * `last_heartbeat` (pre-DR-031 / heartbeat-disabled) keep the legacy
+ * "dead iff all probes fail" behavior, since `isStaleEntry` is false for absence.
+ *
+ * PURE w.r.t. `probe`, `ttlMs`, and `now` — tests inject fakes. The probe retry
+ * is the "never remove on a single flaky read" guard.
+ */
+export async function classifyEntries(peers, probe, opts) {
+    const retries = opts?.retries ?? 1;
+    const delayMs = opts?.delayMs ?? 0;
+    const ttlMs = opts?.ttlMs ?? DEFAULT_REGISTRY_TTL_MS;
+    const now = opts?.now ?? Date.now();
+    const results = [];
+    for (const peer of peers) {
+        let probeAlive = false;
+        for (let attempt = 0; attempt <= retries; attempt++) {
+            const health = await probe(peer.info.host, peer.info.port);
+            if (health) {
+                probeAlive = true;
+                break;
+            }
+            if (attempt < retries)
+                await sleep(delayMs);
+        }
+        const stale = isStaleEntry(peer.info, ttlMs, now);
+        const hasHeartbeat = peer.info.last_heartbeat !== undefined;
+        // dead = !probeAlive && (stale || !hasHeartbeat). A live probe wins always;
+        // a fresh heartbeat keeps an unreachable entry; absence keeps legacy behavior.
+        let reason;
+        if (probeAlive)
+            reason = 'responding';
+        else if (stale)
+            reason = 'stale-heartbeat';
+        else if (!hasHeartbeat)
+            reason = 'unreachable';
+        else
+            reason = 'recent-heartbeat';
+        const verdict = reason === 'responding' || reason === 'recent-heartbeat' ? 'alive' : 'dead';
+        results.push({
+            name: peer.name,
+            host: peer.info.host,
+            port: peer.info.port,
+            verdict,
+            reason,
+        });
+    }
+    return results;
+}
+/** Format a verdict line for the report (pure — exported for tests). */
+export function formatVerdictLine(e) {
+    const where = `${e.host}:${e.port}`;
+    const note = e.reason === 'responding'
+        ? 'alive → keep'
+        : e.reason === 'recent-heartbeat'
+            ? 'unreachable but heartbeat fresh → keep'
+            : e.reason === 'stale-heartbeat'
+                ? 'confirmed-dead (heartbeat stale) → remove'
+                : 'confirmed-dead → remove';
+    const glyph = e.verdict === 'alive' ? '✓' : '✗';
+    return `  ${glyph} ${e.name.padEnd(28)} ${where.padEnd(24)} ${note}`;
+}
+/** Prompt the operator for a y/N confirmation on stdin. Default = No. */
+function promptYesNo(question) {
+    return new Promise((resolveAnswer) => {
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        rl.question(`${question} [y/N] `, (answer) => {
+            rl.close();
+            resolveAnswer(/^y(es)?$/i.test(answer.trim()));
+        });
+    });
+}
+/**
+ * `macf registry prune` entry point. Returns the shell exit code. Lists the
+ * registry, probes each entry over mTLS (with retry), prints per-entry
+ * verdicts, then removes ONLY confirmed-dead entries after consent.
+ */
+export async function runRegistryPrune(projectDir, opts) {
+    const config = readAgentConfig(projectDir);
+    if (!config) {
+        console.error('No macf-agent.json found. Run `macf init` first.');
+        return 1;
+    }
+    if (config.registry.type === 'local') {
+        console.error('registry prune targets GitHub-backed registries; local-registry mode (DR-024) ' +
+            'is not supported. Edit the local JSON registry file directly.');
+        return 1;
+    }
+    const token = await generateToken(tokenSourceFromConfig(projectDir, config));
+    const registry = createRegistryFromConfig(config.registry, config.project, token);
+    const client = createClientFromConfig(config.registry, token);
+    const caCertPem = await client.readVariable(`${toVariableSegment(config.project)}_CA_CERT`);
+    if (!caCertPem) {
+        console.error('CA certificate not found in registry. Run `macf certs init` first.');
+        return 1;
+    }
+    const peers = await registry.list('');
+    if (peers.length === 0) {
+        console.log('No registry entries to check.');
+        return 0;
+    }
+    const certPath = agentCertPath(projectDir);
+    const keyPath = agentKeyPath(projectDir);
+    const probe = (host, port) => pingAgentHealth({ host, port, caCertPem, certPath, keyPath });
+    console.log(`Probing ${peers.length} registry entr${peers.length === 1 ? 'y' : 'ies'} via mTLS /health …\n`);
+    const results = await classifyEntries(peers, probe, { retries: 1, delayMs: 750 });
+    for (const e of results)
+        console.log(formatVerdictLine(e));
+    const dead = results.filter((e) => e.verdict === 'dead');
+    if (dead.length === 0) {
+        console.log('\nAll entries responded — nothing to prune.');
+        return 0;
+    }
+    console.log(`\n${dead.length} confirmed-dead entr${dead.length === 1 ? 'y' : 'ies'} would be REMOVED:`);
+    for (const e of dead) {
+        const why = e.reason === 'stale-heartbeat' ? ' (heartbeat stale)' : '';
+        console.log(`  - ${e.name}${why}`);
+    }
+    const consent = opts?.yes ? true : await promptYesNo('\nRemove these registry entries?');
+    if (!consent) {
+        console.log('Aborted — no entries removed.');
+        return 0;
+    }
+    for (const e of dead) {
+        await registry.remove(e.name);
+        console.log(`  removed ${e.name}`);
+    }
+    console.log(`\nPruned ${dead.length} dead registry entr${dead.length === 1 ? 'y' : 'ies'}.`);
+    return 0;
+}
+//# sourceMappingURL=registry-prune.js.map

package/dist/cli/commands/registry-prune.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-prune.js","sourceRoot":"","sources":["../../../src/cli/commands/registry-prune.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/restart-self.d.ts

@@ -0,0 +1,111 @@
+/** The three restart drivers (DR-031 §"Be-replaceable" — fault / upgrade / manual). */
+export declare const RESTART_REASONS: readonly ["fault", "upgrade", "manual"];
+export type RestartReason = (typeof RESTART_REASONS)[number];
+/** Coerce an arbitrary `--reason` string to a known reason; defaults to `manual`. */
+export declare function coerceReason(raw: string | undefined): RestartReason;
+/** Result of a stash attempt. `stashed: false` when there was nothing to stash. */
+export interface StashResult {
+    readonly stashed: boolean;
+    readonly ref?: string;
+}
+/**
+ * Every side effect `runRestartSelf` performs, injected so tests verify the
+ * orchestration WITHOUT real stashes / kills / spawns. The git READS (branch,
+ * HEAD, dirty-state) are side effects too, so they live here as well.
+ */
+export interface RestartSelfDeps {
+    readonly now: () => Date;
+    readonly hasUncommittedTrackedChanges: () => boolean;
+    readonly currentBranch: () => string;
+    readonly headSha: () => string;
+    readonly stash: (label: string) => StashResult;
+    readonly writeFile: (path: string, content: string, mode?: number) => void;
+    readonly mkdirp: (path: string) => void;
+    readonly spawnDetached: (scriptPath: string, args: readonly string[]) => void;
+    readonly killSession: (session: string) => void;
+}
+/** Options for `runRestartSelf` (already-resolved identity; pure orchestrator input). */
+export interface RunRestartSelfOptions {
+    /** Absolute workspace dir (holds `claude.sh` + `.claude/.macf/`). */
+    readonly workspaceDir: string;
+    /** Project name (for the `<project>@<agent>` session derivation). */
+    readonly project?: string;
+    /** Agent name (for the `<project>@<agent>` session derivation). */
+    readonly agentName?: string;
+    /** Explicit session override; when set it wins over the derived form. */
+    readonly session?: string;
+    readonly reason: RestartReason;
+    /** Without this, the command is DRY-RUN regardless. */
+    readonly confirm: boolean;
+    /** Force dry-run even with `--confirm` (the safer of the two wins). */
+    readonly dryRun: boolean;
+    readonly json: boolean;
+}
+/** The `--json` state-record (mirrors `fleet doctor`'s versioned shape). */
+export declare const RESTART_SELF_JSON_SCHEMA_VERSION = 1;
+export interface RestartSelfPlan {
+    readonly schema_version: number;
+    readonly dry_run: boolean;
+    readonly reason: RestartReason;
+    readonly session: string;
+    readonly stash_ref: string | null;
+    readonly resume_note_path: string;
+    readonly relauncher_path: string;
+    readonly killed: boolean;
+}
+/** Derive `<project>@<agent>` (the canonical claude.sh self-wrap session), or null. */
+export declare function resolveSession(opts: RunRestartSelfOptions): string | null;
+/** The marked-stash label: `macf-restart-self/<ISO-8601-ts>/<reason>`. */
+export declare function stashLabel(iso: string, reason: RestartReason): string;
+/** The RESUME-note body — what a future session needs to pick the work back up. */
+export declare function buildResumeNote(args: {
+    readonly reason: RestartReason;
+    readonly iso: string;
+    readonly branch: string;
+    readonly head: string;
+    readonly stashRef: string | null;
+}): string;
+/**
+ * The detached relauncher script. Waits for the OLD session to die (up to ~30s),
+ * then `cd`s to the workspace, sources the host-prelude IF it exists (decoupled
+ * from DR-031 piece 4 — proceed if absent), and `exec`s the launcher. Uses
+ * absolute paths so it does not depend on the dying session's env beyond what it
+ * re-establishes.
+ */
+export declare function buildRelauncherScript(args: {
+    readonly workspaceDir: string;
+    readonly session: string;
+    readonly iso: string;
+}): string;
+/**
+ * Pure orchestrator. Returns the shell exit code. DRY-RUN BY DEFAULT — only a
+ * `--confirm` (and not `--dry-run`) run stashes / writes / spawns / kills.
+ * Refuses (exit 1) when the session name cannot be resolved.
+ */
+export declare function runRestartSelf(opts: RunRestartSelfOptions, deps: RestartSelfDeps): Promise<number>;
+/**
+ * Real side-effect implementations bound to a workspace dir. Git reads/stash run
+ * in `workspaceDir`; the spawn is FULLY DETACHED (`detached: true` opens a new
+ * session — the Node equivalent of `setsid` — plus `stdio: 'ignore'` + `unref()`
+ * so the relauncher outlives this process when its session is killed).
+ */
+export declare function createRealDeps(workspaceDir: string): RestartSelfDeps;
+export interface RestartSelfCliOptions {
+    readonly reason?: string;
+    readonly confirm?: boolean;
+    readonly dryRun?: boolean;
+    readonly json?: boolean;
+}
+/**
+ * Resolve identity (workspace / project / agent) from env first (the running
+ * agent's `claude.sh`-exported values), falling back to `.macf/macf-agent.json`.
+ * The canonical session claude.sh self-wraps into is `${MACF_PROJECT}@${MACF_AGENT_NAME}`.
+ */
+export declare function resolveIdentity(projectDir: string, env?: NodeJS.ProcessEnv): {
+    readonly workspaceDir: string;
+    readonly project?: string;
+    readonly agentName?: string;
+};
+/** `macf restart-self` entry point — resolves config, wires real deps, runs. */
+export declare function runRestartSelfCommand(projectDir: string, cliOpts: RestartSelfCliOptions): Promise<number>;
+//# sourceMappingURL=restart-self.d.ts.map

package/dist/cli/commands/restart-self.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"restart-self.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/restart-self.ts"],"names":[],"mappings":"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"}