@gajae-code/coding-agent 0.2.5 → 0.3.1

package/src/gjc-runtime/state-migrations.ts

@@ -0,0 +1,179 @@
+import * as fs from "node:fs/promises";
+import type { CanonicalGjcWorkflowSkill } from "../skill-state/active-state";
+import { initialPhaseForSkill } from "../skill-state/initial-phase";
+import {
+	canonicalWorkflowSkill,
+	WORKFLOW_STATE_RECEIPT_VERSION,
+	WORKFLOW_STATE_VERSION,
+} from "../skill-state/workflow-state-contract";
+import { writeWorkflowEnvelopeAtomic } from "./state-writer";
+import { getSkillManifest } from "./workflow-manifest";
+
+export interface NormalizeLegacyStateResult {
+	state: Record<string, unknown>;
+	changed: boolean;
+}
+
+export interface MigrateAndPersistLegacyStateArgs {
+	cwd: string;
+	skill: string;
+	statePath: string;
+	sessionId?: string;
+}
+
+export interface MigrateAndPersistLegacyStateResult {
+	migrated: boolean;
+	path: string;
+}
+export interface MigrateWorkflowStateResult {
+	state: Record<string, unknown>;
+	fromVersion: number;
+	toVersion: number;
+	changed: boolean;
+}
+
+export type WorkflowStateMigration = (
+	state: Record<string, unknown>,
+	skill: CanonicalGjcWorkflowSkill,
+) => Record<string, unknown>;
+
+const RECEIPT_STRING_FIELDS = [
+	"command",
+	"state_path",
+	"storage_path",
+	"mutated_at",
+	"fresh_until",
+	"mutation_id",
+] as const;
+
+function cloneRecord(record: Record<string, unknown>): Record<string, unknown> {
+	return { ...record };
+}
+
+function canonicalSkillOrThrow(skill: string): CanonicalGjcWorkflowSkill {
+	const canonical = canonicalWorkflowSkill(skill);
+	if (!canonical) throw new Error(`Unsupported GJC workflow skill: ${skill}`);
+	return canonical;
+}
+
+function safeString(value: unknown): string {
+	return typeof value === "string" ? value : "";
+}
+
+function legacyPhaseForSkill(skill: CanonicalGjcWorkflowSkill, phase: string): string {
+	if (phase === "planning") return initialPhaseForSkill(skill);
+	return phase;
+}
+
+function normalizePhase(skill: CanonicalGjcWorkflowSkill, value: unknown): string {
+	const manifest = getSkillManifest(skill);
+	const manifestStates = new Set(manifest.states.map(state => state.id));
+	const phase = legacyPhaseForSkill(skill, safeString(value).trim());
+	return manifestStates.has(phase) ? phase : manifest.initialState;
+}
+
+function receiptWithRequiredFields(raw: unknown, skill: CanonicalGjcWorkflowSkill): Record<string, unknown> {
+	const receipt =
+		raw && typeof raw === "object" && !Array.isArray(raw) ? cloneRecord(raw as Record<string, unknown>) : {};
+	receipt.version = WORKFLOW_STATE_RECEIPT_VERSION;
+	receipt.skill = skill;
+	if (receipt.owner !== "gjc-state-cli" && receipt.owner !== "gjc-runtime" && receipt.owner !== "gjc-hook") {
+		receipt.owner = "gjc-state-cli";
+	}
+	if (receipt.status !== "fresh" && receipt.status !== "stale") receipt.status = "stale";
+	for (const field of RECEIPT_STRING_FIELDS) {
+		if (typeof receipt[field] !== "string") receipt[field] = "";
+	}
+	return receipt;
+}
+
+function recordsEqual(left: Record<string, unknown>, right: Record<string, unknown>): boolean {
+	return JSON.stringify(left) === JSON.stringify(right);
+}
+function migrateV1ToV2(state: Record<string, unknown>, skill: CanonicalGjcWorkflowSkill): Record<string, unknown> {
+	const migrated = cloneRecord(state);
+	migrated.version = WORKFLOW_STATE_VERSION;
+	migrated.skill = skill;
+
+	const sourcePhase = typeof migrated.current_phase === "string" ? migrated.current_phase : migrated.phase;
+	const normalizedPhase = normalizePhase(skill, sourcePhase);
+	migrated.current_phase = normalizedPhase;
+	if ("phase" in migrated && typeof migrated.phase === "string") migrated.phase = normalizedPhase;
+
+	return migrated;
+}
+
+const MIGRATIONS: Record<number, WorkflowStateMigration> = {
+	1: migrateV1ToV2,
+};
+
+export function migrateWorkflowState(raw: Record<string, unknown>, skill: string): MigrateWorkflowStateResult {
+	const canonicalSkill = canonicalSkillOrThrow(skill);
+	const fromVersion = typeof raw.version === "number" ? raw.version : 1;
+	if (fromVersion >= WORKFLOW_STATE_VERSION) {
+		return { state: raw, fromVersion, toVersion: fromVersion, changed: false };
+	}
+
+	let version = fromVersion;
+	let state = raw;
+	let changed = false;
+	while (version < WORKFLOW_STATE_VERSION && MIGRATIONS[version]) {
+		state = MIGRATIONS[version](state, canonicalSkill);
+		version += 1;
+		changed = true;
+	}
+
+	return { state, fromVersion, toVersion: version, changed };
+}
+
+/**
+ * Pure legacy state normalizer for background/internal readers.
+ *
+ * Readers that need compatibility with old on-disk workflow state shapes must call
+ * this in-memory helper and must never call `migrateAndPersistLegacyState`. The
+ * persist variant is reserved for explicit state migration commands because it is
+ * the only path allowed to write normalized upgrades back to `.gjc/state/**`.
+ */
+export function normalizeLegacyState(raw: Record<string, unknown>, skill: string): NormalizeLegacyStateResult {
+	const canonicalSkill = canonicalSkillOrThrow(skill);
+	const state = cloneRecord(raw);
+	state.skill = canonicalSkill;
+	if (typeof state.version !== "number") state.version = 1;
+	if (typeof state.active !== "boolean") state.active = true;
+	if (typeof state.updated_at !== "string") state.updated_at = new Date().toISOString();
+	state.receipt = receiptWithRequiredFields(state.receipt, canonicalSkill);
+
+	const migrated = migrateWorkflowState(state, canonicalSkill).state;
+	return { state: migrated, changed: !recordsEqual(raw, migrated) };
+}
+
+export async function migrateAndPersistLegacyState(
+	args: MigrateAndPersistLegacyStateArgs,
+): Promise<MigrateAndPersistLegacyStateResult> {
+	const canonicalSkill = canonicalSkillOrThrow(args.skill);
+	const raw = JSON.parse(await fs.readFile(args.statePath, "utf-8")) as unknown;
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+		throw new Error(`Workflow state file must contain a JSON object: ${args.statePath}`);
+	}
+	const { state, changed } = normalizeLegacyState(raw as Record<string, unknown>, canonicalSkill);
+	if (!changed) return { migrated: false, path: args.statePath };
+
+	const persistedPath = await writeWorkflowEnvelopeAtomic(args.statePath, state, {
+		cwd: args.cwd,
+		receipt: {
+			cwd: args.cwd,
+			skill: canonicalSkill,
+			owner: "gjc-state-cli",
+			command: `gjc state ${canonicalSkill} migrate`,
+			sessionId: args.sessionId,
+		},
+		audit: {
+			cwd: args.cwd,
+			skill: canonicalSkill,
+			verb: "migrate",
+			owner: "gjc-state-cli",
+			category: "state",
+		},
+	});
+	return { migrated: true, path: persistedPath };
+}

package/src/gjc-runtime/state-renderer.ts

@@ -0,0 +1,345 @@
+import type { CanonicalGjcWorkflowSkill } from "../skill-state/active-state";
+import type { SkillManifest } from "./workflow-manifest";
+
+function scalar(value: unknown): string | undefined {
+	if (typeof value === "string") return value.trim() || undefined;
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	return undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function stateObject(stateJson: Record<string, unknown>): Record<string, unknown> {
+	const nested = stateJson.state;
+	return isRecord(nested) ? nested : stateJson;
+}
+
+function receiptObject(state: Record<string, unknown>): Record<string, unknown> | undefined {
+	return isRecord(state.receipt) ? state.receipt : undefined;
+}
+
+function artifactLinks(state: Record<string, unknown>): string[] {
+	const links = new Set<string>();
+	for (const key of [
+		"artifact",
+		"artifact_path",
+		"artifact_url",
+		"plan_path",
+		"spec_path",
+		"ledger_path",
+		"storage_path",
+		"state_path",
+	]) {
+		const value = scalar(state[key]);
+		if (value) links.add(value);
+	}
+	const artifacts = state.artifacts;
+	if (Array.isArray(artifacts)) {
+		for (const artifact of artifacts) {
+			const value = scalar(artifact);
+			if (value) links.add(value);
+			if (isRecord(artifact)) {
+				for (const key of ["path", "url", "href"]) {
+					const nested = scalar(artifact[key]);
+					if (nested) links.add(nested);
+				}
+			}
+		}
+	}
+	return [...links];
+}
+
+function keyStateFields(state: Record<string, unknown>, manifest: SkillManifest): Array<[string, string]> {
+	const keys = new Set<string>([
+		"active",
+		"current_phase",
+		"phase",
+		"status",
+		"updated_at",
+		"session_id",
+		...manifest.hudFields,
+	]);
+	const fields: Array<[string, string]> = [];
+	for (const key of keys) {
+		const value = scalar(state[key]);
+		if (value !== undefined) fields.push([key, value]);
+		if (fields.length >= 10) break;
+	}
+	return fields;
+}
+
+const COMPACT_ELIDE_KEYS = new Set([
+	"rounds",
+	"ontology_snapshots",
+	"architect_findings",
+	"new_requirements",
+	"ci_gates",
+	"research_findings",
+]);
+
+export const STATE_FIELD_ALLOWLIST = [
+	"skill",
+	"phase",
+	"current_phase",
+	"next",
+	"active",
+	"status",
+	"fresh",
+	"fresh_until",
+	"receipt",
+	"artifact_path",
+	"plan_path",
+	"spec_path",
+	"run_id",
+	"stage",
+	"stage_n",
+	"session_id",
+	"updated_at",
+	"handoff_to",
+	"handoff_from",
+	"counts",
+	"hud",
+] as const;
+
+export type StateProjectionField = (typeof STATE_FIELD_ALLOWLIST)[number];
+
+export interface StateStatusSummary {
+	skill: CanonicalGjcWorkflowSkill;
+	phase: string;
+	active: boolean;
+	fresh: boolean;
+	fresh_until?: string;
+	next: string[];
+	receipt_status: string;
+	storage_path: string;
+}
+
+function compactStateFields(state: Record<string, unknown>): Array<[string, string]> {
+	const fields: Array<[string, string]> = [];
+	for (const key of COMPACT_ELIDE_KEYS) {
+		const value = state[key];
+		if (Array.isArray(value)) fields.push([key, `${value.length} entries (elided)`]);
+	}
+	return fields;
+}
+
+export function compactProjectStateJson(
+	skill: CanonicalGjcWorkflowSkill,
+	stateJson: Record<string, unknown>,
+	manifest: SkillManifest,
+): Record<string, unknown> {
+	const state = stateObject(stateJson);
+	const compact = projectStateFields(skill, stateJson, manifest, STATE_FIELD_ALLOWLIST);
+	const elisions: Record<string, unknown> = {};
+	for (const key of COMPACT_ELIDE_KEYS) {
+		const value = state[key];
+		if (Array.isArray(value)) elisions[key] = { type: "array", count: value.length, pointer: `/${key}` };
+	}
+	if (Object.keys(elisions).length) compact.elided = elisions;
+	return compact;
+}
+
+export function projectStateFields(
+	skill: CanonicalGjcWorkflowSkill,
+	stateJson: Record<string, unknown>,
+	manifest: SkillManifest,
+	fields: readonly StateProjectionField[],
+): Record<string, unknown> {
+	const state = stateObject(stateJson);
+	const phase = scalar(state.current_phase) ?? scalar(state.phase) ?? manifest.initialState;
+	const receipt = receiptObject(state);
+	const freshUntil = receipt ? scalar(receipt.fresh_until) : undefined;
+	const projected: Record<string, unknown> = {};
+	for (const field of fields) {
+		switch (field) {
+			case "skill":
+				projected.skill = skill;
+				break;
+			case "phase":
+			case "current_phase":
+				projected[field] = phase;
+				break;
+			case "next":
+				projected.next = manifest.transitions
+					.filter(transition => transition.from === phase)
+					.map(transition => transition.to);
+				break;
+			case "fresh":
+				projected.fresh = freshUntil ? Date.parse(freshUntil) > Date.now() : false;
+				break;
+			case "fresh_until":
+				projected.fresh_until = freshUntil;
+				break;
+			case "receipt":
+				projected.receipt = receipt;
+				break;
+			default:
+				projected[field] = state[field];
+		}
+	}
+	return projected;
+}
+
+export function buildStateStatusSummary(
+	skill: CanonicalGjcWorkflowSkill,
+	stateJson: Record<string, unknown>,
+	manifest: SkillManifest,
+	storagePath: string,
+): StateStatusSummary {
+	const state = stateObject(stateJson);
+	const phase = scalar(state.current_phase) ?? scalar(state.phase) ?? manifest.initialState;
+	const receipt = receiptObject(state);
+	const freshUntil = receipt ? scalar(receipt.fresh_until) : undefined;
+	return {
+		skill,
+		phase,
+		active: state.active !== false,
+		fresh: freshUntil ? Date.parse(freshUntil) > Date.now() : false,
+		...(freshUntil ? { fresh_until: freshUntil } : {}),
+		next: manifest.transitions.filter(transition => transition.from === phase).map(transition => transition.to),
+		receipt_status: receipt ? (scalar(receipt.status) ?? "present") : "missing",
+		storage_path: storagePath,
+	};
+}
+
+export function renderStateStatusLine(summary: StateStatusSummary): string {
+	const freshness = summary.fresh ? "fresh" : "stale";
+	return `${summary.skill}: phase=${summary.phase} ${freshness} next=${summary.next.length ? summary.next.join(",") : "none"}\n`;
+}
+
+export function renderContractMarkdown(skill: CanonicalGjcWorkflowSkill, contract: unknown): string {
+	const record = isRecord(contract) ? contract : {};
+	const lines = [`# ${skill} state contract`, ""];
+	for (const [key, value] of Object.entries(record)) {
+		if (Array.isArray(value)) lines.push(`- ${key}: ${value.length} entries (--json for full)`);
+		else if (isRecord(value)) lines.push(`- ${key}: object (${Object.keys(value).length} keys, --json for full)`);
+		else if (value !== undefined) lines.push(`- ${key}: ${String(value)}`);
+	}
+	return `${lines.join("\n")}\n`;
+}
+
+export function renderHistoryMarkdown(history: {
+	entries: unknown[];
+	limit: number;
+	since?: string;
+	truncated: boolean;
+}): string {
+	const lines = ["# state audit history", "", `- entries: ${history.entries.length}`, `- limit: ${history.limit}`];
+	if (history.since) lines.push(`- since: ${history.since}`);
+	lines.push(`- truncated: ${history.truncated ? "yes" : "no"}`);
+	for (const entry of history.entries) {
+		if (!isRecord(entry)) continue;
+		const ts = scalar(entry.ts) ?? "unknown-time";
+		const skill = scalar(entry.skill) ?? "unknown-skill";
+		const verb = scalar(entry.verb) ?? "unknown-verb";
+		lines.push(`- ${ts} ${skill} ${verb}`);
+	}
+	return `${lines.join("\n")}\n`;
+}
+
+export function renderUltragoalStatusMarkdown(summary: {
+	exists: boolean;
+	status: string;
+	paths: { goalsPath: string; ledgerPath?: string };
+	gjcObjective?: string;
+	currentGoal?: { id: string; status: string; title?: string; objective?: string };
+	counts: Record<string, number>;
+	goals: unknown[];
+}): string {
+	if (!summary.exists)
+		return `# ultragoal status\n\n- status: missing\n- No ultragoal plan found at ${summary.paths.goalsPath}. Run \`gjc ultragoal create-goals --brief "..."\` first.\n`;
+	const counts = Object.entries(summary.counts)
+		.map(([key, value]) => `${key}=${value}`)
+		.join(" ");
+	const lines = [
+		"# ultragoal status",
+		"",
+		`- status: ${summary.status}`,
+		`- goals: ${summary.goals.length} (${counts})`,
+	];
+	if (summary.gjcObjective) lines.push(`- objective: ${summary.gjcObjective}`);
+	if (summary.currentGoal) lines.push(`- current: ${summary.currentGoal.id} (${summary.currentGoal.status})`);
+	lines.push(`- goals_path: ${summary.paths.goalsPath}`);
+	if (summary.paths.ledgerPath) lines.push(`- ledger_path: ${summary.paths.ledgerPath}`);
+	return `${lines.join("\n")}\n`;
+}
+
+export function renderTeamStatusMarkdown(snapshot: {
+	team_name: string;
+	phase: string;
+	tmux_target?: string;
+	tmux_session?: string;
+	state_dir: string;
+	task_total: number;
+	task_counts: Record<string, number>;
+	workers: Array<{ id: string; status: string }>;
+	notification_summary?: { total: number; replay_eligible: number; by_state: Record<string, number> };
+	integration_by_worker?: Record<string, { status?: string; conflict_files?: string[] }>;
+}): string {
+	const counts = Object.entries(snapshot.task_counts)
+		.map(([key, value]) => `${key}=${value}`)
+		.join(" ");
+	const lines = [
+		"# team status",
+		"",
+		`- team: ${snapshot.team_name}`,
+		`- phase: ${snapshot.phase}`,
+		`- tmux: ${snapshot.tmux_target || snapshot.tmux_session || "none"}`,
+		`- state: ${snapshot.state_dir}`,
+		`- tasks: ${snapshot.task_total} (${counts})`,
+		`- workers: ${snapshot.workers.length} (${snapshot.workers.map(worker => `${worker.id}:${worker.status}`).join(" ")})`,
+	];
+	if (snapshot.notification_summary) {
+		lines.push(
+			`- notifications: total=${snapshot.notification_summary.total} replay_eligible=${snapshot.notification_summary.replay_eligible}`,
+		);
+	}
+	const integrations = Object.entries(snapshot.integration_by_worker ?? {});
+	if (integrations.length)
+		lines.push(
+			`- integrations: ${integrations.map(([worker, state]) => `${worker}:${state.status ?? "unknown"}`).join(" ")}`,
+		);
+	return `${lines.join("\n")}\n`;
+}
+
+export function renderStateMarkdown(
+	skill: CanonicalGjcWorkflowSkill,
+	stateJson: Record<string, unknown>,
+	manifest: SkillManifest,
+): string {
+	const state = stateObject(stateJson);
+	const phase = scalar(state.current_phase) ?? scalar(state.phase) ?? manifest.initialState;
+	const next = manifest.transitions.filter(transition => transition.from === phase).map(transition => transition.to);
+	const receipt = receiptObject(state);
+	const receiptStatus = receipt ? (scalar(receipt.status) ?? "present") : "missing";
+	const artifacts = artifactLinks(state);
+	const fields = keyStateFields(state, manifest);
+
+	const lines = [`# ${skill} state`, "", `- Current phase: ${phase}`];
+	lines.push(`- Valid next transitions: ${next.length ? next.join(", ") : "none"}`);
+	if (fields.length) {
+		lines.push("- Key fields:");
+		for (const [key, value] of fields) lines.push(`  - ${key}: ${value}`);
+	} else {
+		lines.push("- Key fields: none");
+	}
+	lines.push(`- Receipt: ${receiptStatus}`);
+	if (receipt) {
+		const mutationId = scalar(receipt.mutation_id);
+		const freshUntil = scalar(receipt.fresh_until);
+		if (mutationId) lines.push(`  - mutation_id: ${mutationId}`);
+		if (freshUntil) lines.push(`  - fresh_until: ${freshUntil}`);
+	}
+	if (artifacts.length) {
+		lines.push("- Artifacts:");
+		for (const artifact of artifacts) lines.push(`  - ${artifact}`);
+	}
+	const compactFields = compactStateFields(state);
+	if (compactFields.length) {
+		lines.push("- Compact elisions:");
+		for (const [key, value] of compactFields) lines.push(`  - ${key}: ${value}`);
+	}
+	return `${lines.join("\n")}\n`;
+}