@gajae-code/coding-agent 0.13.2 → 0.14.0

package/src/setup/paseo/json-publisher.ts

@@ -0,0 +1,263 @@
+/**
+ * Byte-safe JSON publication for files another application owns.
+ *
+ * Paseo owns `~/.paseo/config.json` and offers no lock API, so every write here
+ * is conservative by construction:
+ *
+ * - A round-trip fidelity self-check re-serializes the UNMODIFIED parse and
+ *   refuses to write unless it is byte-identical to the original. Paseo writes
+ *   2-space JSON with a trailing newline; anything else means our formatting
+ *   assumption no longer holds and guessing would silently rewrite the file.
+ * - A compare-and-swap re-reads the file immediately before publishing, so a
+ *   concurrent write between our read and our rename is detected, not clobbered.
+ * - Publication is temp-write plus rename, never a direct write to the target.
+ * - Backups land beside the original at mode 0600, because `config.json` holds
+ *   `daemon.auth.password`.
+ *
+ * This module carries NO ownership, seeding, or removal policy. Those live in
+ * the per-target adapters so this file stays small enough to audit.
+ */
+import * as nodeCrypto from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+
+/** Serialization Paseo itself produces. Verified byte-identical against the live config. */
+export function serializeJson(value: unknown): string {
+	return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+export function hashBytes(bytes: string): string {
+	return nodeCrypto.createHash("sha256").update(bytes).digest("hex");
+}
+
+/** Marker recorded when a target did not exist at preflight. */
+export const ABSENT_IDENTITY = "absent";
+
+export type PublishRefusal =
+	| { readonly reason: "parse-refusal"; readonly detail: string }
+	| { readonly reason: "format-drift"; readonly detail: string }
+	| { readonly reason: "cas-conflict"; readonly expected: string; readonly actual: string };
+
+export class PaseoPublishError extends Error {
+	readonly refusal: PublishRefusal;
+	readonly targetPath: string;
+
+	constructor(targetPath: string, refusal: PublishRefusal) {
+		super(describeRefusal(targetPath, refusal));
+		this.name = "PaseoPublishError";
+		this.refusal = refusal;
+		this.targetPath = targetPath;
+	}
+}
+
+function describeRefusal(targetPath: string, refusal: PublishRefusal): string {
+	switch (refusal.reason) {
+		case "parse-refusal":
+			return `Refusing to write ${targetPath}: it is not parseable JSON (${refusal.detail}). Fix or remove the file, then re-run.`;
+		case "format-drift":
+			return `Refusing to write ${targetPath}: ${refusal.detail}. GJC only edits files it can rewrite byte-for-byte, so it will not reformat a file it did not author.`;
+		case "cas-conflict":
+			return `Refusing to write ${targetPath}: the file changed while GJC was preparing its update. Re-run to pick up the current contents.`;
+	}
+}
+
+export interface ReadTargetResult {
+	readonly exists: boolean;
+	/** Raw bytes as read, or `""` when absent. */
+	readonly raw: string;
+	/** Hash of `raw`, or `ABSENT_IDENTITY` when absent. */
+	readonly identity: string;
+	/** Parsed object; `{}` when absent. */
+	readonly parsed: Record<string, unknown>;
+}
+
+/**
+ * Read and validate a target without writing anything.
+ *
+ * Throws `PaseoPublishError` on unparseable JSON or on a formatting mismatch,
+ * so callers never have to decide whether a file is safe to touch.
+ */
+export async function readTarget(targetPath: string): Promise<ReadTargetResult> {
+	let raw: string;
+	try {
+		raw = await Bun.file(targetPath).text();
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+			return { exists: false, raw: "", identity: ABSENT_IDENTITY, parsed: {} };
+		}
+		throw error;
+	}
+
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (error) {
+		throw new PaseoPublishError(targetPath, {
+			reason: "parse-refusal",
+			detail: error instanceof Error ? error.message : String(error),
+		});
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+		throw new PaseoPublishError(targetPath, { reason: "parse-refusal", detail: "root is not a JSON object" });
+	}
+
+	// Round-trip fidelity self-check: re-serialize the UNMODIFIED parse. If that
+	// is not byte-identical, our formatting assumption is wrong and any write
+	// would silently reformat regions we do not own.
+	const roundTrip = serializeJson(parsed);
+	if (roundTrip !== raw) {
+		throw new PaseoPublishError(targetPath, {
+			reason: "format-drift",
+			detail:
+				"re-serializing the file's own contents did not reproduce it byte-for-byte (expected 2-space indentation with a trailing newline)",
+		});
+	}
+
+	return { exists: true, raw, identity: hashBytes(raw), parsed: parsed as Record<string, unknown> };
+}
+
+export interface PublishPlan {
+	/** Bytes that will be published. */
+	readonly nextRaw: string;
+	/** Hash of `nextRaw` -- the expected post-publish identity, computable before any rename. */
+	readonly expectedIdentity: string;
+	/** True when the mutation produced no change and publication can be skipped. */
+	readonly unchanged: boolean;
+}
+
+/**
+ * Apply `mutate` to a validated read and compute the exact bytes to publish.
+ *
+ * Split out from {@link publishPlan} so the install saga can record the expected
+ * post-publish identity in its durable intent BEFORE anything is written.
+ */
+export function planPublish(current: ReadTargetResult, mutate: (draft: Record<string, unknown>) => void): PublishPlan {
+	const draft = structuredClone(current.parsed);
+	mutate(draft);
+	const nextRaw = serializeJson(draft);
+	return { nextRaw, expectedIdentity: hashBytes(nextRaw), unchanged: nextRaw === current.raw };
+}
+
+export interface PublishOptions {
+	/** Identity the target must still carry at publication time. */
+	readonly expectedIdentity: string;
+	/** Take a mode-0600 backup beside the original before replacing it. */
+	readonly backup: boolean;
+	readonly now: Date;
+}
+
+export interface PublishResult {
+	readonly published: boolean;
+	readonly backupPath?: string;
+	readonly identity: string;
+}
+
+function backupSuffix(now: Date): string {
+	return now.toISOString().replace(/[:.]/g, "-");
+}
+
+/**
+ * Publish `plan.nextRaw` to `targetPath` under a compare-and-swap on
+ * `options.expectedIdentity`.
+ *
+ * The CAS is re-read immediately before the rename, which is the narrowest
+ * window GJC can achieve. It does not defend against Paseo re-writing the file
+ * later from its own stale in-memory copy -- Paseo exposes no lock or version
+ * API, so that remains a documented residual risk detected by `--check`.
+ */
+export async function publishPlan(
+	targetPath: string,
+	plan: PublishPlan,
+	options: PublishOptions,
+): Promise<PublishResult> {
+	if (plan.unchanged) return { published: false, identity: options.expectedIdentity };
+
+	const directory = path.dirname(targetPath);
+	await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+
+	// Compare-and-swap: re-read right before publishing so an external write
+	// between our original read and this rename is refused, not overwritten.
+	const observed = await currentIdentity(targetPath);
+	if (observed !== options.expectedIdentity) {
+		throw new PaseoPublishError(targetPath, {
+			reason: "cas-conflict",
+			expected: options.expectedIdentity,
+			actual: observed,
+		});
+	}
+
+	let backupPath: string | undefined;
+	if (options.backup && observed !== ABSENT_IDENTITY) {
+		backupPath = `${targetPath}.gjc-bak-${backupSuffix(options.now)}`;
+		await copyPrivately(targetPath, backupPath);
+	}
+
+	// Never write the final path directly: a crash mid-write would leave the
+	// user's config truncated. Stage beside the target, fsync, then rename.
+	const tempPath = path.join(directory, `.${path.basename(targetPath)}.${process.pid}.${nodeCrypto.randomUUID()}.tmp`);
+	const mode = await sourceMode(targetPath);
+	try {
+		const handle = await fs.open(tempPath, "wx", mode);
+		try {
+			await handle.writeFile(plan.nextRaw, "utf8");
+			await handle.sync();
+		} finally {
+			await handle.close();
+		}
+		await fs.rename(tempPath, targetPath);
+	} finally {
+		await fs.rm(tempPath, { force: true }).catch(() => undefined);
+	}
+
+	return { published: true, backupPath, identity: plan.expectedIdentity };
+}
+
+/** Current on-disk identity, or {@link ABSENT_IDENTITY} when the file does not exist. */
+export async function currentIdentity(targetPath: string): Promise<string> {
+	try {
+		return hashBytes(await Bun.file(targetPath).text());
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return ABSENT_IDENTITY;
+		throw error;
+	}
+}
+
+/**
+ * Preserve the target's own permissions when republishing it.
+ *
+ * Narrowed to at most 0600 for group and other, never widened: a file that was
+ * already private must stay private, and one that was world-readable must not
+ * become more permissive because we rewrote it.
+ */
+async function sourceMode(targetPath: string): Promise<number> {
+	try {
+		const stat = await fs.stat(targetPath);
+		return stat.mode & 0o777;
+	} catch {
+		return 0o600;
+	}
+}
+
+/**
+ * Backups are ALWAYS 0600, regardless of the source mode.
+ *
+ * A backup of `~/.paseo/config.json` contains `daemon.auth.password`, and a
+ * backup generally duplicates content into a new path the user did not choose,
+ * so it must never inherit a permissive source mode.
+ */
+const BACKUP_MODE = 0o600;
+
+async function copyPrivately(from: string, to: string): Promise<void> {
+	const bytes = await Bun.file(from).text();
+	const mode = BACKUP_MODE;
+	const handle = await fs.open(to, "w", mode);
+	try {
+		await handle.writeFile(bytes, "utf8");
+		await handle.sync();
+	} finally {
+		await handle.close();
+	}
+	// `fs.open` honors the mode only on creation, so an existing backup path
+	// keeps its old permissions unless we set them explicitly.
+	await fs.chmod(to, mode);
+}

package/src/setup/paseo/orchestration-preferences.ts

@@ -0,0 +1,86 @@
+import { ORCHESTRATION_ROLE_KEYS, PROVIDER_KEY } from "./setup-deps";
+
+/** Every newly seeded orchestration role points at the base provider this setup registers. */
+export const SEEDED_ROLE_VALUE = PROVIDER_KEY;
+
+/** Paseo nests its role assignments under `providers`; the file's other top-level keys are not ours. */
+const PROVIDERS_KEY = "providers";
+
+export interface OrchestrationSeed {
+	readonly mutate: (draft: Record<string, unknown>) => void;
+	readonly seededKeys: readonly string[];
+	readonly seededValues: Record<string, string>;
+}
+
+function readRoles(preferences: Record<string, unknown>): Record<string, unknown> | undefined {
+	const providers = preferences[PROVIDERS_KEY];
+	if (!providers || typeof providers !== "object" || Array.isArray(providers)) return undefined;
+	return providers as Record<string, unknown>;
+}
+
+/**
+ * A role is empty only when it is absent, `""`, or `[]`.
+ *
+ * Every other value, including `null`, belongs to the user and is left alone --
+ * seeding must never overwrite an assignment somebody already made.
+ */
+function isEmpty(roles: Record<string, unknown> | undefined, key: string): boolean {
+	if (!roles || !(key in roles)) return true;
+	const value = roles[key];
+	return value === "" || (Array.isArray(value) && value.length === 0);
+}
+
+/**
+ * Plan the seeding of `providers.{impl,ui,research,planning,audit}`.
+ *
+ * Only empty roles are seeded. `preferences[]` and any other top-level key are
+ * never read or assigned, so an existing array keeps its identity and content.
+ */
+/** Read a role's current value, or `undefined` when unset. Shared by seeding and removal. */
+export function readRoleValue(preferences: Record<string, unknown>, key: string): string | undefined {
+	const roles = readRoles(preferences);
+	const value = roles?.[key];
+	return typeof value === "string" ? value : undefined;
+}
+
+/**
+ * Delete seeded roles from the nested `providers` map.
+ *
+ * `shouldDelete` gates each key on provenance, so a role the user reassigned
+ * after install is left alone. The `providers` object itself is removed only
+ * when it becomes empty, so a file GJC fully seeded returns to its prior shape.
+ */
+export function removeSeededRoles(
+	draft: Record<string, unknown>,
+	keys: readonly string[],
+	shouldDelete: (key: string, currentValue: string | undefined) => boolean,
+): void {
+	const roles = readRoles(draft);
+	if (!roles) return;
+	for (const key of keys) {
+		const value = roles[key];
+		if (shouldDelete(key, typeof value === "string" ? value : undefined)) delete roles[key];
+	}
+	if (Object.keys(roles).length === 0) delete draft[PROVIDERS_KEY];
+}
+
+export function createOrchestrationSeed(preferences: Record<string, unknown>): OrchestrationSeed {
+	const roles = readRoles(preferences);
+	const seededKeys = ORCHESTRATION_ROLE_KEYS.filter(key => isEmpty(roles, key));
+	const seededValues = Object.fromEntries(seededKeys.map(key => [key, SEEDED_ROLE_VALUE]));
+
+	return {
+		mutate: draft => {
+			if (seededKeys.length === 0) return;
+			const existing = draft[PROVIDERS_KEY];
+			const target =
+				existing && typeof existing === "object" && !Array.isArray(existing)
+					? (existing as Record<string, unknown>)
+					: {};
+			for (const key of seededKeys) target[key] = SEEDED_ROLE_VALUE;
+			draft[PROVIDERS_KEY] = target;
+		},
+		seededKeys,
+		seededValues,
+	};
+}

package/src/setup/paseo/paseo-ownership.ts

@@ -0,0 +1,224 @@
+/**
+ * GJC-side ownership provenance and crash-recovery intent.
+ *
+ * Both records live under the GJC agent directory, never inside the user's
+ * Paseo files. Two separate concerns share this module because both answer the
+ * same question -- "did GJC actually do this?" -- and both are consumed by the
+ * install saga and by `--remove`.
+ *
+ * Provenance exists because "the current value equals what we would write" is
+ * NOT evidence that we wrote it: a user who hand-authored the same value would
+ * otherwise have it silently deleted by `--remove`.
+ *
+ * The intent record exists because a target file and the provenance ledger are
+ * separate files and cannot be renamed atomically together. It is written
+ * BEFORE either mutation and carries enough identity to classify the target on
+ * its own after a crash, without needing any later update.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { ABSENT_IDENTITY, currentIdentity, serializeJson } from "./json-publisher";
+
+export const PROVENANCE_VERSION = 1;
+export const INTENT_VERSION = 1;
+
+export interface ProvenanceLedger {
+	readonly version: number;
+	/** `agents.providers` keys GJC created, mapped to the value hash it wrote. */
+	readonly providerKeys: Record<string, string>;
+	/** Orchestration role keys GJC actually seeded, mapped to the value it wrote. */
+	readonly seededOrchestrationKeys: Record<string, string>;
+	/** Bridge directory path GJC created, when it created it. */
+	readonly bridgePath?: string;
+	/** Bridge entries GJC created, so the inverse removes exactly those. */
+	readonly bridgeEntries?: readonly string[];
+	/** True when GJC created the bridge directory itself (as opposed to populating an existing one). */
+	readonly bridgeDirCreated?: boolean;
+}
+
+export const EMPTY_LEDGER: ProvenanceLedger = {
+	version: PROVENANCE_VERSION,
+	providerKeys: {},
+	seededOrchestrationKeys: {},
+};
+
+export async function readProvenance(provenancePath: string): Promise<ProvenanceLedger> {
+	let raw: string;
+	try {
+		raw = await Bun.file(provenancePath).text();
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return EMPTY_LEDGER;
+		throw error;
+	}
+	try {
+		const parsed = JSON.parse(raw) as Partial<ProvenanceLedger>;
+		return {
+			version: typeof parsed.version === "number" ? parsed.version : PROVENANCE_VERSION,
+			providerKeys: isStringRecord(parsed.providerKeys) ? parsed.providerKeys : {},
+			seededOrchestrationKeys: isStringRecord(parsed.seededOrchestrationKeys) ? parsed.seededOrchestrationKeys : {},
+			...(typeof parsed.bridgePath === "string" ? { bridgePath: parsed.bridgePath } : {}),
+			...(Array.isArray(parsed.bridgeEntries)
+				? { bridgeEntries: parsed.bridgeEntries.filter((entry): entry is string => typeof entry === "string") }
+				: {}),
+			...(typeof parsed.bridgeDirCreated === "boolean" ? { bridgeDirCreated: parsed.bridgeDirCreated } : {}),
+		};
+	} catch {
+		// A corrupt GJC-side ledger must not brick removal: treat it as empty so
+		// nothing is deleted on unproven ownership, which is the safe direction.
+		return EMPTY_LEDGER;
+	}
+}
+
+function isStringRecord(value: unknown): value is Record<string, string> {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+export async function writeProvenance(provenancePath: string, ledger: ProvenanceLedger): Promise<void> {
+	await fs.mkdir(path.dirname(provenancePath), { recursive: true, mode: 0o700 });
+	await Bun.write(provenancePath, serializeJson(ledger));
+	await fs.chmod(provenancePath, 0o600);
+}
+
+/**
+ * True only when GJC recorded this provider key AND the value still hashes to
+ * what GJC wrote. A user edit after install makes this false, which is what
+ * keeps `--remove` from destroying their change.
+ */
+export function isProvenancedProvider(ledger: ProvenanceLedger, key: string, currentValueHash: string): boolean {
+	const recorded = ledger.providerKeys[key];
+	return recorded !== undefined && recorded === currentValueHash;
+}
+
+export function isProvenancedOrchestrationKey(ledger: ProvenanceLedger, key: string, currentValue: string): boolean {
+	const recorded = ledger.seededOrchestrationKeys[key];
+	return recorded !== undefined && recorded === currentValue;
+}
+
+/** Every `gjc`/`gjc-<preset>` key GJC recorded, so a plain `--remove` cleans up earlier `--mpreset` runs. */
+export function provenancedProviderKeys(ledger: ProvenanceLedger): readonly string[] {
+	return Object.keys(ledger.providerKeys).sort();
+}
+
+export type IntentStep = "provider-config" | "orchestration-preferences";
+
+/**
+ * Durable, credential-free intent record.
+ *
+ * Written before either the target publish or the ledger commit, and carrying
+ * BOTH identities for BOTH files, so recovery can classify each file as
+ * before / intended-after / divergent from this record alone. It stores only
+ * paths, key names, and hashes -- never file contents, diffs, or values -- so
+ * it stays credential-free even though `config.json` holds a bcrypt password.
+ */
+export interface IntentRecord {
+	readonly version: number;
+	readonly step: IntentStep;
+	readonly targetPath: string;
+	readonly ownedKeys: readonly string[];
+	readonly targetPreflightIdentity: string;
+	readonly targetExpectedIdentity: string;
+	readonly provenancePath: string;
+	readonly provenancePreflightIdentity: string;
+	readonly provenanceExpectedIdentity: string;
+	/**
+	 * The exact ledger this step intended to commit.
+	 *
+	 * Carried so recovery can finish the commit without re-running the step. That
+	 * matters for seed-if-empty work: once the target publish has landed the roles
+	 * are no longer empty, so a retry would skip the step and the ledger would
+	 * never be written. Contains only key names and hashes, never values from the
+	 * user's files, so the record stays credential-free.
+	 */
+	readonly provenancePayload?: ProvenanceLedger;
+	readonly startedAt: string;
+}
+
+export async function writeIntent(intentPath: string, intent: IntentRecord): Promise<void> {
+	await fs.mkdir(path.dirname(intentPath), { recursive: true, mode: 0o700 });
+	await Bun.write(intentPath, serializeJson(intent));
+	await fs.chmod(intentPath, 0o600);
+}
+
+export async function readIntent(intentPath: string): Promise<IntentRecord | undefined> {
+	let raw: string;
+	try {
+		raw = await Bun.file(intentPath).text();
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+		throw error;
+	}
+	try {
+		const parsed = JSON.parse(raw) as IntentRecord;
+		if (typeof parsed?.targetPath !== "string" || typeof parsed?.targetExpectedIdentity !== "string")
+			return undefined;
+		return parsed;
+	} catch {
+		return undefined;
+	}
+}
+
+export async function clearIntent(intentPath: string): Promise<void> {
+	await fs.rm(intentPath, { force: true }).catch(() => undefined);
+}
+
+/** Rebuild the ledger an interrupted step intended to commit, when it recorded one. */
+export function pendingLedgerOf(intent: IntentRecord): ProvenanceLedger | undefined {
+	return intent.provenancePayload;
+}
+
+/** Where a file sits relative to an interrupted step. */
+export type IntentFileState = "before" | "intended-after" | "divergent";
+
+export function classifyIdentity(observed: string, preflight: string, expected: string): IntentFileState {
+	if (observed === expected) return "intended-after";
+	if (observed === preflight) return "before";
+	return "divergent";
+}
+
+export type IntentRecovery =
+	| { readonly action: "discard"; readonly detail: string }
+	| { readonly action: "complete-ledger"; readonly detail: string }
+	| { readonly action: "refuse"; readonly detail: string };
+
+/**
+ * Classify BOTH the target and the ledger before deciding what to do.
+ *
+ * Deliberately exhaustive over the nine combinations: a divergent ledger always
+ * refuses, because replaying a recorded ledger output over a third party's
+ * change would destroy it.
+ */
+export async function classifyIntent(intent: IntentRecord): Promise<IntentRecovery> {
+	const [targetObserved, ledgerObserved] = await Promise.all([
+		currentIdentity(intent.targetPath),
+		currentIdentity(intent.provenancePath),
+	]);
+	const target = classifyIdentity(targetObserved, intent.targetPreflightIdentity, intent.targetExpectedIdentity);
+	const ledger = classifyIdentity(
+		ledgerObserved,
+		intent.provenancePreflightIdentity,
+		intent.provenanceExpectedIdentity,
+	);
+
+	if (ledger === "divergent") {
+		return {
+			action: "refuse",
+			detail: `the provenance ledger at ${intent.provenancePath} changed unexpectedly; GJC will not overwrite it`,
+		};
+	}
+	if (target === "divergent") {
+		return {
+			action: "refuse",
+			detail: `${intent.targetPath} was changed by another writer during an interrupted GJC step; GJC will not touch it`,
+		};
+	}
+	if (target === "intended-after" && ledger === "before") {
+		return { action: "complete-ledger", detail: `${intent.targetPath} was published; recording its provenance` };
+	}
+	if (target === "intended-after" && ledger === "intended-after") {
+		return { action: "discard", detail: "both writes landed; clearing the stale intent" };
+	}
+	// target === "before": the publish never landed, so nothing was mutated.
+	return { action: "discard", detail: `${intent.targetPath} was never modified; discarding the stale intent` };
+}
+
+export { ABSENT_IDENTITY };