@geminix/gxpm 0.1.0

package/core/artifacts.ts

@@ -0,0 +1,313 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import {
+  appendIssueEvent,
+  buildOwnershipChangedEvent,
+  getIssuePaths,
+  readIssueState,
+  touchIssueOwnership,
+  type StateEvent,
+} from "./state";
+import { resolveSessionId } from "./session";
+import { getWorkflowEventEmitter } from "./workflow-event-emitter";
+
+export const ARTIFACT_TYPES = [
+  "issue-intake",
+  "triage-report",
+  "autopilot-grant",
+  "acceptance-contract",
+  "implementation-plan",
+  "dispatch-handoff",
+  "behavior-spec",
+  "wiki-context",
+  "local-verify",
+  "acceptance-check",
+  "self-review",
+  "review-report",
+  "cleanup-report",
+  "ship-readiness",
+  "ship-audit-report",
+  "pr-check",
+  "verify-findings",
+  "qa-findings",
+  "land-findings",
+  "feedback-description",
+] as const;
+
+export type ArtifactType = (typeof ARTIFACT_TYPES)[number];
+
+export interface ArtifactRecord {
+  schemaVersion: 1;
+  type: ArtifactType;
+  path: string;
+  writtenAt: string;
+}
+
+export interface StoredArtifact {
+  schemaVersion: 1;
+  issueId: string;
+  type: ArtifactType;
+  writtenAt: string;
+  payload: unknown;
+}
+
+interface ArtifactInput {
+  root?: string;
+  issueId: string;
+}
+
+interface WriteArtifactInput extends ArtifactInput {
+  type: ArtifactType | string;
+  payload: unknown;
+}
+
+interface RewriteArtifactInput extends WriteArtifactInput {
+  timestamp?: string;
+  event?: StateEvent;
+}
+
+interface ReadArtifactInput extends ArtifactInput {
+  type: ArtifactType | string;
+}
+
+function getGitDiffFiles(worktreeRoot: string): string[] {
+  try {
+    const result = Bun.spawnSync({
+      cmd: ["git", "diff", "--name-only", "HEAD"],
+      cwd: worktreeRoot,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    if (result.exitCode !== 0) return [];
+    return result.stdout
+      .toString()
+      .split("\n")
+      .map((line) => line.trim())
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function validateLocalVerifyPayload(
+  payload: unknown,
+  worktreeRoot: string,
+  now: string,
+): unknown {
+  if (!payload || typeof payload !== "object") return payload;
+  const p = payload as Record<string, unknown>;
+  const changedFiles = Array.isArray(p.changedFiles) ? (p.changedFiles as string[]) : [];
+  if (changedFiles.length === 0) return payload;
+
+  const gitDiffFiles = getGitDiffFiles(worktreeRoot);
+  if (gitDiffFiles.length === 0) return payload;
+
+  const gitSet = new Set(gitDiffFiles);
+  const extraneous = changedFiles.filter((f) => !gitSet.has(f));
+  if (extraneous.length === 0) return payload;
+
+  const log = Array.isArray(p.verificationLog) ? [...p.verificationLog] : [];
+  log.push(`[${now}] SCOPE_DRIFT_WARNING: changedFiles contains ${extraneous.length} file(s) not in git diff: ${extraneous.join(", ")}`);
+  return { ...p, verificationLog: log };
+}
+
+export function writeArtifact(input: WriteArtifactInput): ArtifactRecord {
+  const root = input.root ?? process.cwd();
+  const type = assertValidArtifactType(input.type);
+  const paths = getIssuePaths(root, input.issueId);
+  const state = readIssueState({ root, issueId: input.issueId });
+
+  const now = new Date().toISOString();
+  const sessionId = resolveSessionId();
+  const relativePath = `artifacts/${type}.json`;
+
+  let payload = input.payload;
+  if (type === "local-verify") {
+    const worktreeRoot = resolve(root, ".gxpm", "worktrees", `gxpm-${input.issueId}`);
+    payload = validateLocalVerifyPayload(payload, worktreeRoot, now);
+  }
+
+  const artifact: StoredArtifact = {
+    schemaVersion: 1,
+    issueId: input.issueId,
+    type,
+    writtenAt: now,
+    payload,
+  };
+  writeFileSync(join(paths.issueDir, relativePath), `${JSON.stringify(artifact, null, 2)}\n`);
+
+  const record: ArtifactRecord = {
+    schemaVersion: 1,
+    type,
+    path: relativePath,
+    writtenAt: now,
+  };
+  writeArtifactIndex(
+    paths.artifactIndexPath,
+    input.issueId,
+    upsertRecord(listArtifacts({ root, issueId: input.issueId }), record),
+  );
+  const nextState = touchIssueOwnership({
+    state: { ...state, updatedAt: now },
+    sessionId,
+  });
+  if (JSON.stringify(nextState) !== JSON.stringify(state)) {
+    writeFileSync(paths.statePath, `${JSON.stringify(nextState, null, 2)}\n`);
+  }
+  const ownershipEvent = buildOwnershipChangedEvent({
+    issueId: input.issueId,
+    timestamp: now,
+    previousState: state,
+    nextState,
+    sessionId,
+  });
+  if (ownershipEvent) {
+    appendIssueEvent({ issueDir: paths.issueDir, event: ownershipEvent });
+  }
+  appendIssueEvent({
+    issueDir: paths.issueDir,
+    event: artifactWrittenEvent(input.issueId, type, now, relativePath, sessionId),
+  });
+
+  getWorkflowEventEmitter().emit({
+    type: "artifact_written",
+    issueId: input.issueId,
+    artifactType: type,
+    timestamp: now,
+  });
+
+  // Fire-and-forget sync to external issue tracker
+  import("./issue-sync")
+    .then(({ maybeSyncIssue }) =>
+      maybeSyncIssue({
+        root,
+        issueId: input.issueId,
+        action: "artifact-written",
+        meta: { artifactType: type },
+      }),
+    )
+    .catch(() => {
+      // Silently fail — local state is truth
+    });
+
+  return record;
+}
+
+export function rewriteArtifact(input: RewriteArtifactInput): ArtifactRecord {
+  const root = input.root ?? process.cwd();
+  const type = assertValidArtifactType(input.type);
+  const paths = getIssuePaths(root, input.issueId);
+  readIssueState({ root, issueId: input.issueId });
+
+  const artifactPath = join(paths.issueDir, "artifacts", `${type}.json`);
+  if (!existsSync(artifactPath)) {
+    throw new Error(`Artifact not found: ${type}`);
+  }
+
+  const now = input.timestamp ?? new Date().toISOString();
+  const relativePath = `artifacts/${type}.json`;
+  const artifact: StoredArtifact = {
+    schemaVersion: 1,
+    issueId: input.issueId,
+    type,
+    writtenAt: now,
+    payload: input.payload,
+  };
+  writeFileSync(artifactPath, `${JSON.stringify(artifact, null, 2)}\n`);
+
+  const record: ArtifactRecord = {
+    schemaVersion: 1,
+    type,
+    path: relativePath,
+    writtenAt: now,
+  };
+  writeArtifactIndex(
+    paths.artifactIndexPath,
+    input.issueId,
+    upsertRecord(listArtifacts({ root, issueId: input.issueId }), record),
+  );
+  if (input.event) {
+    appendIssueEvent({ issueDir: paths.issueDir, event: input.event });
+  }
+
+  return record;
+}
+
+export function readArtifact(input: ReadArtifactInput): StoredArtifact {
+  const root = input.root ?? process.cwd();
+  const type = assertValidArtifactType(input.type);
+  const paths = getIssuePaths(root, input.issueId);
+  const artifactPath = join(paths.issueDir, "artifacts", `${type}.json`);
+
+  if (!existsSync(artifactPath)) {
+    throw new Error(`Artifact not found: ${type}`);
+  }
+
+  return JSON.parse(readFileSync(artifactPath, "utf8")) as StoredArtifact;
+}
+
+export function listArtifacts(input: ArtifactInput): ArtifactRecord[] {
+  const root = input.root ?? process.cwd();
+  const paths = getIssuePaths(root, input.issueId);
+
+  if (!existsSync(paths.artifactIndexPath)) {
+    throw new Error(`Artifact index not found: ${input.issueId}`);
+  }
+
+  const index = JSON.parse(readFileSync(paths.artifactIndexPath, "utf8")) as {
+    artifacts?: ArtifactRecord[];
+  };
+  return Array.isArray(index.artifacts) ? index.artifacts : [];
+}
+
+export function hasArtifact(input: ReadArtifactInput): boolean {
+  const root = input.root ?? process.cwd();
+  const type = assertValidArtifactType(input.type);
+  const paths = getIssuePaths(root, input.issueId);
+  return existsSync(join(paths.issueDir, "artifacts", `${type}.json`));
+}
+
+function writeArtifactIndex(path: string, issueId: string, artifacts: ArtifactRecord[]) {
+  writeFileSync(
+    path,
+    `${JSON.stringify(
+      {
+        schemaVersion: 1,
+        issueId,
+        artifacts,
+      },
+      null,
+      2,
+    )}\n`,
+  );
+}
+
+function upsertRecord(records: ArtifactRecord[], record: ArtifactRecord) {
+  return [...records.filter((item) => item.type !== record.type), record].sort((a, b) =>
+    a.type.localeCompare(b.type),
+  );
+}
+
+function artifactWrittenEvent(
+  issueId: string,
+  artifactType: ArtifactType,
+  timestamp: string,
+  path: string,
+  sessionId: string,
+): StateEvent {
+  return {
+    schemaVersion: 1,
+    type: "artifact.written",
+    issueId,
+    timestamp,
+    sessionId,
+    payload: { artifactType, path },
+  };
+}
+
+function assertValidArtifactType(value: string): ArtifactType {
+  if (!ARTIFACT_TYPES.includes(value as ArtifactType)) {
+    throw new Error(`Invalid artifact type: ${value}`);
+  }
+  return value as ArtifactType;
+}

package/core/autopilot.ts

@@ -0,0 +1,250 @@
+import { randomUUID } from "node:crypto";
+import { readArtifact, writeArtifact } from "./artifacts";
+import { listIssues } from "./issues";
+import { readIssueState, type GxpmPhase } from "./state";
+import { resolveSessionId } from "./session";
+
+export const AUTOPILOT_PROFILES = ["full-delivery"] as const;
+
+export type AutopilotProfile = (typeof AUTOPILOT_PROFILES)[number];
+export type AutopilotGrantStatus = "active" | "stopped" | "completed" | "blocked";
+
+export interface AutopilotGrant {
+  schemaVersion: 1;
+  mode: "autopilot";
+  issueId: string;
+  runId: string;
+  profile: AutopilotProfile;
+  status: AutopilotGrantStatus;
+  startedAt: string;
+  updatedAt: string;
+  startedBySession: string;
+  prompt?: string;
+  expiresAt?: string;
+  stoppedAt?: string;
+  stopReason?: string;
+  allowedActions: string[];
+  hardStops: string[];
+  terminalPhases: GxpmPhase[];
+}
+
+export interface ActiveAutopilotGrant {
+  issueId: string;
+  currentPhase: GxpmPhase;
+  grant: AutopilotGrant;
+}
+
+interface StartAutopilotGrantInput {
+  root?: string;
+  issueId: string;
+  profile?: AutopilotProfile;
+  prompt?: string;
+  ttlMinutes?: number;
+  now?: Date;
+}
+
+interface StopAutopilotGrantInput {
+  root?: string;
+  issueId: string;
+  reason?: string;
+  now?: Date;
+}
+
+const DEFAULT_PROFILE: AutopilotProfile = "full-delivery";
+
+const FULL_DELIVERY_ALLOWED_ACTIONS = [
+  "issue.triage",
+  "issue.plan",
+  "issue.dispatch",
+  "workspace.ensure",
+  "code.modify",
+  "artifact.write",
+  "verification.run",
+  "review.self",
+  "git.commit",
+  "git.push",
+  "pull-request.create",
+  "pull-request.update",
+  "pull-request.merge",
+  "issue.land",
+  "cleanup.land",
+];
+
+const DEFAULT_HARD_STOPS = [
+  "user.explicit_stop",
+  "secrets_or_credentials_required",
+  "paid_external_api_required",
+  "production_data_or_destructive_data_migration",
+  "irrecoverable_conflict_or_failed_verification",
+  "policy_or_permission_boundary",
+];
+
+const TERMINAL_PHASES: GxpmPhase[] = ["land"];
+
+export function startAutopilotGrant(input: StartAutopilotGrantInput): AutopilotGrant {
+  const root = input.root ?? process.cwd();
+  const profile = input.profile ?? DEFAULT_PROFILE;
+  assertAutopilotProfile(profile);
+  readIssueState({ root, issueId: input.issueId });
+
+  const existing = readAutopilotGrant({ root, issueId: input.issueId });
+  if (existing && isAutopilotGrantActive(existing, input.now)) {
+    throw new Error(`Autopilot grant already active for ${input.issueId}`);
+  }
+
+  const now = input.now ?? new Date();
+  const nowIso = now.toISOString();
+  const grant: AutopilotGrant = {
+    schemaVersion: 1,
+    mode: "autopilot",
+    issueId: input.issueId,
+    runId: randomUUID(),
+    profile,
+    status: "active",
+    startedAt: nowIso,
+    updatedAt: nowIso,
+    startedBySession: resolveSessionId(),
+    ...(input.prompt ? { prompt: input.prompt } : {}),
+    ...(input.ttlMinutes ? { expiresAt: new Date(now.getTime() + input.ttlMinutes * 60_000).toISOString() } : {}),
+    allowedActions: [...FULL_DELIVERY_ALLOWED_ACTIONS],
+    hardStops: [...DEFAULT_HARD_STOPS],
+    terminalPhases: [...TERMINAL_PHASES],
+  };
+
+  writeArtifact({ root, issueId: input.issueId, type: "autopilot-grant", payload: grant });
+  return grant;
+}
+
+export function stopAutopilotGrant(input: StopAutopilotGrantInput): AutopilotGrant {
+  const root = input.root ?? process.cwd();
+  readIssueState({ root, issueId: input.issueId });
+  const existing = readAutopilotGrant({ root, issueId: input.issueId });
+  if (!existing) {
+    throw new Error(`Autopilot grant not found for ${input.issueId}`);
+  }
+
+  const now = input.now ?? new Date();
+  const stopped: AutopilotGrant = {
+    ...existing,
+    status: "stopped",
+    updatedAt: now.toISOString(),
+    stoppedAt: now.toISOString(),
+    stopReason: input.reason ?? "manual_stop",
+  };
+  writeArtifact({ root, issueId: input.issueId, type: "autopilot-grant", payload: stopped });
+  return stopped;
+}
+
+export function readAutopilotGrant(input: { root?: string; issueId: string }): AutopilotGrant | null {
+  const root = input.root ?? process.cwd();
+  try {
+    const artifact = readArtifact({ root, issueId: input.issueId, type: "autopilot-grant" });
+    return normalizeAutopilotGrant(artifact.payload);
+  } catch {
+    return null;
+  }
+}
+
+export function listActiveAutopilotGrants(input: {
+  root?: string;
+  issueId?: string;
+  limit?: number;
+  now?: Date;
+} = {}): ActiveAutopilotGrant[] {
+  const root = input.root ?? process.cwd();
+  const issueIds = input.issueId
+    ? [input.issueId]
+    : listIssues({ root, includeAll: true }).map((entry) => entry.issueId);
+  const active: ActiveAutopilotGrant[] = [];
+
+  for (const issueId of issueIds) {
+    const grant = readAutopilotGrant({ root, issueId });
+    if (!grant || !isAutopilotGrantActive(grant, input.now)) continue;
+    let state;
+    try {
+      state = readIssueState({ root, issueId });
+    } catch {
+      continue;
+    }
+    if (grant.terminalPhases.includes(state.currentPhase)) continue;
+    active.push({ issueId, currentPhase: state.currentPhase, grant });
+    if (input.limit && active.length >= input.limit) break;
+  }
+
+  return active;
+}
+
+export function isAutopilotGrantActive(grant: AutopilotGrant, now: Date = new Date()): boolean {
+  if (grant.status !== "active") return false;
+  if (!grant.expiresAt) return true;
+  return Date.parse(grant.expiresAt) > now.getTime();
+}
+
+export function isAutopilotProfile(value: string): value is AutopilotProfile {
+  return AUTOPILOT_PROFILES.includes(value as AutopilotProfile);
+}
+
+export function assertAutopilotProfile(value: string): asserts value is AutopilotProfile {
+  if (!isAutopilotProfile(value)) {
+    throw new Error(`Unsupported autopilot profile: ${value}`);
+  }
+}
+
+export function formatAutopilotGrantContext(active: ActiveAutopilotGrant[]): string {
+  if (active.length === 0) return "";
+  const lines = ["gxpm autopilot grant active:"];
+  for (const item of active) {
+    lines.push(
+      `- ${item.issueId}: profile=${item.grant.profile}, phase=${item.currentPhase}, runId=${item.grant.runId}`,
+    );
+  }
+  lines.push("");
+  lines.push("Autopilot Grant means the user pre-authorized gxpm workflow steps inside the profile.");
+  lines.push("Do not ask for confirmation or clarification for allowed actions; plan, implement, verify, PR, merge/land, and cleanup autonomously.");
+  lines.push("Stop only on hard stops, and persist the blocker/evidence in the current gxpm artifact before reporting.");
+  lines.push("Useful commands: gxpm autopilot status <issue-id>; gxpm issue next <issue-id>.");
+  return lines.join("\n");
+}
+
+export function buildAutopilotStopContinuation(active: ActiveAutopilotGrant[]): string {
+  const context = formatAutopilotGrantContext(active);
+  if (!context) return "";
+  return `${context}\n\nContinue the gxpm workflow now. Do not produce a final answer while an active grant still has non-terminal work.`;
+}
+
+function normalizeAutopilotGrant(payload: unknown): AutopilotGrant | null {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return null;
+  const value = payload as Partial<AutopilotGrant>;
+  if (value.schemaVersion !== 1) return null;
+  if (value.mode !== "autopilot") return null;
+  if (typeof value.issueId !== "string") return null;
+  if (typeof value.runId !== "string") return null;
+  if (typeof value.profile !== "string" || !isAutopilotProfile(value.profile)) return null;
+  if (!["active", "stopped", "completed", "blocked"].includes(value.status ?? "")) return null;
+  if (!Array.isArray(value.allowedActions)) return null;
+  if (!Array.isArray(value.hardStops)) return null;
+  return {
+    schemaVersion: 1,
+    mode: "autopilot",
+    issueId: value.issueId,
+    runId: value.runId,
+    profile: value.profile,
+    status: value.status as AutopilotGrantStatus,
+    startedAt: stringOrNow(value.startedAt),
+    updatedAt: stringOrNow(value.updatedAt),
+    startedBySession: typeof value.startedBySession === "string" ? value.startedBySession : "",
+    ...(typeof value.prompt === "string" ? { prompt: value.prompt } : {}),
+    ...(typeof value.expiresAt === "string" ? { expiresAt: value.expiresAt } : {}),
+    ...(typeof value.stoppedAt === "string" ? { stoppedAt: value.stoppedAt } : {}),
+    ...(typeof value.stopReason === "string" ? { stopReason: value.stopReason } : {}),
+    allowedActions: value.allowedActions.filter((item): item is string => typeof item === "string"),
+    hardStops: value.hardStops.filter((item): item is string => typeof item === "string"),
+    terminalPhases: Array.isArray(value.terminalPhases)
+      ? value.terminalPhases.filter((item): item is GxpmPhase => item === "land")
+      : [...TERMINAL_PHASES],
+  };
+}
+
+function stringOrNow(value: unknown): string {
+  return typeof value === "string" ? value : new Date().toISOString();
+}