@khorsheed/dsh-ankh-guard 0.2.0 → 0.3.0

package/lib/state-4f7yny39.js

@@ -1,286 +0,0 @@
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-//#region lib/types/state-files.js
-/**
-* The guard's state-directory protocol: every file that lives in the state
-* dir, named exactly once. Five writers in three languages (this package's
-* TS, the watchdog's bash, the schedule-exit exit agent's inline JS, and the
-* two supervisor installers) read and write these — a literal drifting in
-* any one of them splits the protocol silently (three review rounds of path
-* bugs came from exactly that). The bash sides are pinned by
-* tests/state-files.spec.ts, which asserts every state-dir literal in the
-* watchdog and both installers appears here, and that no script re-derives
-* the directory from the home.
-*/
-/** Every state-directory file name, keyed by role. */
-const STATE_FILES = {
-	/** The guard's credential/checkpoint/audit state (state.ts). */
-	guard: "self-restart-guard.json",
-	/** Watchdog-stamped last deployment-proven revision. */
-	lastGoodBoot: "last-good-boot.json",
-	/** schedule-exit → watchdog: an intentional restart, run the canary. */
-	restartRequested: "restart-requested.json",
-	/** The exit agent's restart outcome record (the report's source). */
-	lastRestart: "last-restart.json",
-	/** The SIGTERM snapshot of interrupted sessions. */
-	interruptedSessions: "interrupted-sessions.json",
-	/** The supervising watchdog's pidfile. */
-	watchdogPid: "watchdog.pid",
-	/** Cross-session mutual exclusion for the restart verb. */
-	restartLock: "restart.lock",
-	/** The detached restart driver's log. */
-	restartLog: "restart.log",
-	/** Marker: exit the watchdog without respawn. */
-	watchdogStop: "watchdog-stop",
-	/** Marker: the watchdog gave up; a crash page holds the port. */
-	watchdogGaveUp: "watchdog-gave-up",
-	/** The current boot attempt's captured output. */
-	bootAttemptLog: "boot-attempt.log",
-	/** The watchdog's own log. */
-	watchdogLog: "watchdog.log",
-	/** The watchdog's stderr, captured separately by the supervisor installers. */
-	watchdogStderrLog: "watchdog.stderr.log",
-	/** The exit agent's log. */
-	scheduleExitLog: "schedule-exit.log",
-	/** How the current instance was launched (recorded by the plugin at apply). */
-	instanceLaunch: "instance-launch.json",
-	/** The atomically selected full launch configuration (stable or in cutover). */
-	launchSpec: "launch-spec.json",
-	/** Redacted durable receipt for the latest launch-configuration cutover. */
-	launchCutover: "launch-cutover.json",
-	/** Legacy combined operator-control marker, retained for rolling upgrades. */
-	cutoverControl: "launch-cutover-control.json",
-	/** Operator → watchdog: abort according to the pre-approved recovery policy. */
-	cutoverAbort: "launch-cutover-abort.json",
-	/** Monotonic stronger operator action: explicitly restore the previous spec. */
-	cutoverRestorePrevious: "launch-cutover-restore-previous.json",
-	/** Original browser-tab registry: per-tab capability hashes only; retained through terminal recovery. */
-	browserHandoffRequest: "browser-handoff-request.json",
-	/** Browser → watchdog acknowledgement for one proven final process. */
-	browserHandoffAck: "browser-handoff-ack.json",
-	/** Whether the restart-protocol skill registered at apply (and why not). */
-	skillRegistration: "skill-registration.json",
-	/** Directory: the healthy-boot snapshot of the profile composition inputs. */
-	lastGoodComposition: "last-good-composition",
-	/** Directory prefix: a failing composition backed up before rollback restores over it. */
-	compositionBackup: "composition-backup-"
-};
-/** Absolute path of a state file inside a state directory. */
-function stateFile(stateDir, role) {
-	return join(stateDir, STATE_FILES[role]);
-}
-/**
-* The last deployment-proven revision, stamped by the watchdog on every
-* healthy boot, or undefined. Lives here rather than in the credential core:
-* the stamp is written by the watchdog and proves the deployment composed and
-* came up — a green credential only ever proves build+test passed.
-* @param stateDir - state directory.
-* @returns the stamped revision, or undefined.
-*/
-function lastGoodBootRevision(stateDir) {
-	try {
-		const stamp = JSON.parse(readFileSync(stateFile(stateDir, "lastGoodBoot"), "utf8"));
-		return typeof stamp.revision === "string" && stamp.revision !== "" ? stamp.revision : void 0;
-	} catch {
-		return;
-	}
-}
-//#endregion
-//#region lib/types/state.js
-/**
-* Pure credential/checkpoint state core for the self-restart guard.
-*
-* The guard records one "green build" credential — bound to the git HEAD it
-* was recorded on and to a freshness window — and answers `verify()` against
-* the CURRENT head and wall clock. A later fully gated boot may promote that
-* credential into a deployment proof whose exact runtime fingerprint can be
-* reused by the same-launch restart path. Framework-free: the cordis plugin,
-* the CLI, and the invariant companion all share this module.
-*/
-/** Absolute path of the state file inside a state directory. */
-function stateFilePath(stateDir) {
-	return stateFile(stateDir, "guard");
-}
-/** A fresh, credential-less state. */
-function emptyState() {
-	return { audit: [] };
-}
-function isCredential(value) {
-	if (typeof value !== "object" || value === null) return false;
-	const c = value;
-	return typeof c.scope === "string" && typeof c.revision === "string" && typeof c.recordedAt === "number" && typeof c.command === "string";
-}
-function isCheckpoint(value) {
-	if (typeof value !== "object" || value === null) return false;
-	const c = value;
-	return typeof c.revision === "string" && typeof c.recordedAt === "number" && typeof c.message === "string";
-}
-function isSha256(value) {
-	return typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
-}
-function isProvenDeployment(value) {
-	if (typeof value !== "object" || value === null) return false;
-	const proof = value;
-	const credential = proof.credential;
-	const fingerprint = proof.fingerprint;
-	return proof.version === 1 && typeof proof.provenAt === "number" && credential !== void 0 && typeof credential.revision === "string" && credential.revision !== "" && typeof credential.recordedAt === "number" && typeof credential.scope === "string" && isSha256(credential.commandSha256) && fingerprint?.version === 1 && typeof fingerprint.credentialRevision === "string" && fingerprint.credentialRevision !== "" && typeof fingerprint.harnessRevision === "string" && fingerprint.harnessRevision !== "" && isSha256(fingerprint.launchSpecSha256) && isSha256(fingerprint.profileSha256) && isSha256(fingerprint.hostRuntimeSha256) && isSha256(proof.fingerprintSha256);
-}
-function isAuditEntry(value) {
-	if (typeof value !== "object" || value === null) return false;
-	const e = value;
-	return (e.action === "record" || e.action === "clear" || e.action === "checkpoint" || e.action === "prove-deployment") && typeof e.ts === "number" && typeof e.detail === "string";
-}
-/**
-* Read the state file; an absent file is an empty state, a malformed one is a
-* loud misconfiguration error (never silently ignored).
-* @param stateDir - directory holding the state file.
-* @returns the parsed state.
-*/
-function loadState(stateDir) {
-	try {
-		const raw = readFileSync(stateFilePath(stateDir), "utf8");
-		const parsed = JSON.parse(raw);
-		if (parsed === null || typeof parsed !== "object") return emptyState();
-		const state = { audit: Array.isArray(parsed.audit) ? parsed.audit.filter(isAuditEntry) : [] };
-		if (isCredential(parsed.credential)) state.credential = parsed.credential;
-		if (isProvenDeployment(parsed.provenDeployment)) state.provenDeployment = parsed.provenDeployment;
-		if (isCheckpoint(parsed.checkpoint)) state.checkpoint = parsed.checkpoint;
-		return state;
-	} catch (error) {
-		if (error?.code === "ENOENT") return emptyState();
-		throw new Error(`ankh-guard: unreadable state file ${stateFilePath(stateDir)}: ${String(error)}`);
-	}
-}
-/** Persist a state (creates the directory as needed). */
-function saveState(stateDir, state) {
-	mkdirSync(stateDir, { recursive: true });
-	const file = stateFilePath(stateDir);
-	const tmp = `${file}.${process.pid}.tmp`;
-	writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`);
-	renameSync(tmp, file);
-}
-function withAudit(state, entry) {
-	return {
-		...state,
-		audit: [...state.audit, entry].slice(-50)
-	};
-}
-/**
-* Record a green-build credential bound to {@link RecordInput.revision}.
-* @param stateDir - state directory.
-* @param input - scope, the git HEAD, and the command that went green.
-* @param now - epoch milliseconds (injected for deterministic tests).
-* @returns the persisted state.
-*/
-function recordCredential(stateDir, input, now) {
-	const credential = {
-		...input,
-		recordedAt: now
-	};
-	const { provenDeployment: _oldProof, ...withoutOldProof } = withAudit(loadState(stateDir), {
-		action: "record",
-		ts: now,
-		detail: `${input.scope} @ ${input.revision}`
-	});
-	const updated = {
-		...withoutOldProof,
-		credential
-	};
-	saveState(stateDir, updated);
-	return updated;
-}
-/**
-* Drop the credential (checkpoint and audit survive).
-* @param stateDir - state directory.
-* @param now - epoch milliseconds (injected for deterministic tests).
-* @returns the persisted state.
-*/
-function clearCredential(stateDir, now) {
-	const audited = withAudit(loadState(stateDir), {
-		action: "clear",
-		ts: now,
-		detail: "credential cleared"
-	});
-	const updated = { audit: audited.audit };
-	if (audited.checkpoint !== void 0) updated.checkpoint = audited.checkpoint;
-	saveState(stateDir, updated);
-	return updated;
-}
-/** Persist a deployment proof after the watchdog has completed its canary. */
-function setProvenDeployment(stateDir, proof, now) {
-	const updated = {
-		...withAudit(loadState(stateDir), {
-			action: "prove-deployment",
-			ts: now,
-			detail: `${proof.credential.revision} ${proof.fingerprintSha256.slice(0, 16)}`
-		}),
-		provenDeployment: proof
-	};
-	saveState(stateDir, updated);
-	return updated;
-}
-/**
-* Persist a pre-batch checkpoint commit reference.
-* @param stateDir - state directory.
-* @param input - the checkpoint commit SHA and its message.
-* @param now - epoch milliseconds (injected for deterministic tests).
-* @returns the persisted state.
-*/
-function setCheckpoint(stateDir, input, now) {
-	const checkpoint = {
-		...input,
-		recordedAt: now
-	};
-	const updated = {
-		...withAudit(loadState(stateDir), {
-			action: "checkpoint",
-			ts: now,
-			detail: `${input.revision} ${input.message}`
-		}),
-		checkpoint
-	};
-	saveState(stateDir, updated);
-	return updated;
-}
-/**
-* Answer the gate: a credential is valid only when present, recorded on the
-* CURRENT revision, and younger than {@link maxAgeMinutes}.
-* @param state - the loaded state.
-* @param currentRevision - the git HEAD of the checkout, or null when unavailable.
-* @param now - epoch milliseconds (injected for deterministic tests).
-* @param maxAgeMinutes - freshness window.
-* @param workingTreeClean - whether staged, unstaged, and untracked inputs are absent.
-* @returns ok plus a human reason either way.
-*/
-function verifyCredential(state, currentRevision, now, maxAgeMinutes, workingTreeClean = true) {
-	const credential = state.credential;
-	if (credential === void 0) return {
-		ok: false,
-		reason: "no green-build credential recorded"
-	};
-	if (currentRevision === null) return {
-		ok: false,
-		reason: "current git HEAD unavailable (not inside a git repository?)"
-	};
-	if (!workingTreeClean) return {
-		ok: false,
-		reason: "working tree is dirty (staged, unstaged, or untracked changes exist) — commit or remove them, then rebuild and re-record"
-	};
-	if (credential.revision !== currentRevision) return {
-		ok: false,
-		reason: `green credential is bound to revision ${credential.revision}, but current HEAD is ${currentRevision} — the tree changed since it was recorded; rebuild and re-record`
-	};
-	const ageMs = now - credential.recordedAt;
-	const maxMs = maxAgeMinutes * 6e4;
-	if (ageMs > maxMs) return {
-		ok: false,
-		reason: `green credential is stale (${Math.round(ageMs / 6e4)} min old, limit ${maxAgeMinutes} min) — rebuild and re-record`
-	};
-	const leftMs = Math.max(0, maxMs - ageMs);
-	return {
-		ok: true,
-		reason: `green credential valid (${credential.scope} @ ${credential.revision}, ${Math.round(leftMs / 6e4)} min left)`
-	};
-}
-//#endregion
-export { setProvenDeployment as a, lastGoodBootRevision as c, setCheckpoint as i, stateFile as l, loadState as n, stateFilePath as o, recordCredential as r, verifyCredential as s, clearCredential as t };

package/lib/test-seam-DnvLWTeO.js

@@ -1,119 +0,0 @@
-import { o as processGroupId, s as processIdentity } from "./processes-BjZgJjQr.js";
-import { createHash } from "node:crypto";
-import { appendFileSync, mkdirSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-//#region lib/types/test-seam.js
-/**
-* Explicit test-only process/event registration seam. Production execution is
-* inert unless a test runner supplies all ANKH_GUARD_TEST_* ownership values.
-*/
-const TEST_RUN_DIR_ENV = "ANKH_GUARD_TEST_RUN_DIR";
-const TEST_RUN_TOKEN_ENV = "ANKH_GUARD_TEST_RUN_TOKEN";
-const TEST_PROCESS_ROLE_ENV = "ANKH_GUARD_TEST_PROCESS_ROLE";
-const TEST_PROCESS_PORT_ENV = "ANKH_GUARD_TEST_PROCESS_PORT";
-const TEST_PROCESS_TEMP_ROOT_ENV = "ANKH_GUARD_TEST_PROCESS_TEMP_ROOT";
-const TEST_REGISTER_BIN_ENV = "ANKH_GUARD_TEST_REGISTER_BIN";
-const TEST_SLEEP_SCALE_ENV = "ANKH_GUARD_TEST_SLEEP_SCALE";
-function testCoordinates(env) {
-	const runDir = env[TEST_RUN_DIR_ENV];
-	const runToken = env[TEST_RUN_TOKEN_ENV];
-	if (runDir === void 0 || runDir === "" || runToken === void 0 || !/^[a-f0-9-]{16,}$/.test(runToken)) return null;
-	return {
-		runDir,
-		runToken
-	};
-}
-function safeRole(value) {
-	const role = value.trim().replace(/[^a-zA-Z0-9._-]+/g, "-").slice(0, 80);
-	return role === "" ? "unknown" : role;
-}
-function appendTestLifecycleEventForProcess(subjectPid, roleValue, event, detail, source = "child-self", env = process.env) {
-	const coordinates = testCoordinates(env);
-	if (coordinates === null) return;
-	const role = safeRole(roleValue);
-	const identity = processIdentity(subjectPid);
-	const pgid = processGroupId(subjectPid);
-	const record = {
-		version: 1,
-		runToken: coordinates.runToken,
-		source,
-		role,
-		event: safeRole(event),
-		pid: subjectPid,
-		...pgid === null ? {} : { pgid },
-		...identity === null ? {} : { startToken: identity.startToken },
-		wallTimeMs: Date.now(),
-		monotonicNs: process.hrtime.bigint().toString(),
-		...detail === void 0 ? {} : { detail }
-	};
-	try {
-		const dir = join(coordinates.runDir, "events");
-		mkdirSync(dir, {
-			recursive: true,
-			mode: 448
-		});
-		appendFileSync(join(dir, `${subjectPid}-${source}.jsonl`), `${JSON.stringify(record)}\n`, { mode: 384 });
-	} catch {}
-}
-/** Record one credential-free event in this process's append-only event file. */
-function appendTestLifecycleEvent(event, detail, source = "child-self", env = process.env) {
-	appendTestLifecycleEventForProcess(process.pid, env["ANKH_GUARD_TEST_PROCESS_ROLE"] ?? "unknown", event, detail, source, env);
-}
-/**
-* Atomically publish an immutable PID/PGID/start-identity lease. The same PID
-* may be observed by its parent and then self-register; the first complete
-* record wins because both describe the same kernel start identity.
-*/
-function registerTestProcess(pid, role, options = {}) {
-	const env = options.env ?? process.env;
-	const coordinates = testCoordinates(env);
-	if (coordinates === null) return null;
-	const identity = options.identity ?? processIdentity(pid);
-	const pgid = processGroupId(pid);
-	if (identity === null || pgid === null) return null;
-	const portText = env[TEST_PROCESS_PORT_ENV];
-	const envPort = portText === void 0 ? void 0 : Number(portText);
-	const port = options.port ?? (Number.isInteger(envPort) && (envPort ?? 0) > 0 ? envPort : void 0);
-	const tempRoot = options.tempRoot ?? env["ANKH_GUARD_TEST_PROCESS_TEMP_ROOT"];
-	const record = {
-		version: 1,
-		runToken: coordinates.runToken,
-		role: safeRole(role),
-		pid,
-		pgid,
-		startToken: identity.startToken,
-		groupRoot: pgid === pid,
-		registeredAt: Date.now(),
-		source: options.source ?? (pid === process.pid ? "child-self" : "parent-observer"),
-		...tempRoot === void 0 || tempRoot === "" ? {} : { tempRoot },
-		...port === void 0 ? {} : { port }
-	};
-	try {
-		const dir = join(coordinates.runDir, "processes");
-		mkdirSync(dir, {
-			recursive: true,
-			mode: 448
-		});
-		const identityHash = createHash("sha256").update(identity.startToken).digest("hex").slice(0, 16);
-		writeFileSync(join(dir, `${pid}-${identityHash}.json`), `${JSON.stringify(record)}\n`, {
-			flag: "wx",
-			mode: 384
-		});
-	} catch (error) {
-		if (error.code !== "EEXIST") return null;
-	}
-	return record;
-}
-/** Self-register only when an explicit test role accompanies the run lease. */
-function registerCurrentTestProcess(env = process.env) {
-	const role = env[TEST_PROCESS_ROLE_ENV];
-	if (role === void 0 || role === "") return null;
-	const record = registerTestProcess(process.pid, role, {
-		env,
-		source: "child-self"
-	});
-	if (record !== null) appendTestLifecycleEvent("process-registered", { pgid: record.pgid }, "child-self", env);
-	return record;
-}
-//#endregion
-export { TEST_RUN_DIR_ENV as a, appendTestLifecycleEvent as c, registerTestProcess as d, TEST_REGISTER_BIN_ENV as i, appendTestLifecycleEventForProcess as l, TEST_PROCESS_ROLE_ENV as n, TEST_RUN_TOKEN_ENV as o, TEST_PROCESS_TEMP_ROOT_ENV as r, TEST_SLEEP_SCALE_ENV as s, TEST_PROCESS_PORT_ENV as t, registerCurrentTestProcess as u };