@geminix/gxpm 0.1.0

package/scripts/commands/phase.ts

@@ -0,0 +1,61 @@
+import { rewindPhase } from "../../core/phase-rewind";
+
+function parseRewindArgs(argv: string[]): {
+  issueId: string;
+  toPhase: string;
+  reason: string;
+} {
+  // Expected: gxpm phase rewind <issue-id> --to <phase> --reason "<text>"
+  // argv slice already starts after "phase rewind"
+  const issueId = argv[0];
+  if (!issueId) {
+    throw new Error(
+      'usage: gxpm phase rewind <issue-id> --to <phase> --reason "<text>"',
+    );
+  }
+
+  let toPhase: string | undefined;
+  let reason: string | undefined;
+
+  for (let i = 1; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--to") {
+      toPhase = argv[++i];
+      continue;
+    }
+    if (arg.startsWith("--to=")) {
+      toPhase = arg.slice("--to=".length);
+      continue;
+    }
+    if (arg === "--reason") {
+      reason = argv[++i];
+      continue;
+    }
+    if (arg.startsWith("--reason=")) {
+      reason = arg.slice("--reason=".length);
+      continue;
+    }
+  }
+
+  if (!toPhase) {
+    throw new Error("phase rewind requires --to <phase>");
+  }
+  if (!reason || !reason.trim()) {
+    throw new Error("phase rewind requires --reason \"<text>\"");
+  }
+
+  return { issueId, toPhase, reason };
+}
+
+export function runPhaseCommand(argv: string[], subcommand: string | undefined) {
+  if (subcommand !== "rewind") {
+    throw new Error(`unknown phase subcommand: ${subcommand ?? "<none>"}; expected rewind`);
+  }
+  // Strip "phase rewind" prefix; remaining argv has [<issue-id>, --to, <phase>, --reason, <text>]
+  const args = argv.slice(2);
+  const { issueId, toPhase, reason } = parseRewindArgs(args);
+  const result = rewindPhase({ issueId, toPhase, reason });
+  console.log(
+    `rewound ${issueId}: ${result.fromPhase} -> ${result.toPhase} (${result.timestamp})`,
+  );
+}

package/scripts/commands/preset.ts

@@ -0,0 +1,159 @@
+// PRESET CLI — gxpm preset add/remove/list/show/init
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { PresetResolver } from "../../core/preset-system/preset-resolver";
+
+const PRESET_DIR = ".gxpm/presets";
+const REGISTRY_FILE = ".registry";
+
+function getPresetDir(root: string): string {
+  return join(root, PRESET_DIR);
+}
+
+function readRegistry(root: string): { active: string[] } {
+  const path = join(getPresetDir(root), REGISTRY_FILE);
+  if (!existsSync(path)) return { active: [] };
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as { active: string[] };
+  } catch {
+    return { active: [] };
+  }
+}
+
+function writeRegistry(root: string, registry: { active: string[] }): void {
+  const dir = getPresetDir(root);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, REGISTRY_FILE), JSON.stringify(registry, null, 2) + "\n");
+}
+
+function readManifest(root: string, id: string) {
+  const path = join(getPresetDir(root), id, "manifest.json");
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as {
+      id: string;
+      name: string;
+      version: string;
+      description?: string;
+      rules: unknown[];
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function runPresetCommand(
+  _argv: string[],
+  subcommand: string | undefined,
+  id: string | undefined,
+): void {
+  const root = process.cwd();
+
+  switch (subcommand) {
+    case "list": {
+      const resolver = new PresetResolver(root);
+      resolver.load();
+      const active = resolver.listActive();
+      const all = resolver.listPresets();
+
+      if (all.length === 0) {
+        console.log("No presets found.");
+        return;
+      }
+
+      console.log("Presets:");
+      for (const presetId of all) {
+        const manifest = resolver.getPreset(presetId);
+        const isActive = active.includes(presetId);
+        const marker = isActive ? "*" : " ";
+        console.log(`  [${marker}] ${presetId}: ${manifest?.name ?? "(unknown)"} (${manifest?.version ?? "?"})`);
+      }
+      if (active.length > 0) {
+        console.log(`\nActive order: ${active.join(" > ")}`);
+      }
+      return;
+    }
+
+    case "add": {
+      if (!id) {
+        throw new Error("Usage: gxpm preset add <preset-id>");
+      }
+      const manifest = readManifest(root, id);
+      if (!manifest) {
+        throw new Error(`Preset '${id}' not found. Run 'gxpm preset init ${id}' to create it.`);
+      }
+      const registry = readRegistry(root);
+      if (registry.active.includes(id)) {
+        console.log(`Preset '${id}' is already active.`);
+        return;
+      }
+      registry.active.push(id);
+      writeRegistry(root, registry);
+      console.log(`Added preset '${id}' to active list.`);
+      return;
+    }
+
+    case "remove": {
+      if (!id) {
+        throw new Error("Usage: gxpm preset remove <preset-id>");
+      }
+      const registry = readRegistry(root);
+      if (!registry.active.includes(id)) {
+        console.log(`Preset '${id}' is not active.`);
+        return;
+      }
+      registry.active = registry.active.filter((x) => x !== id);
+      writeRegistry(root, registry);
+      console.log(`Removed preset '${id}' from active list.`);
+      return;
+    }
+
+    case "show": {
+      if (!id) {
+        throw new Error("Usage: gxpm preset show <preset-id>");
+      }
+      const manifest = readManifest(root, id);
+      if (!manifest) {
+        throw new Error(`Preset '${id}' not found.`);
+      }
+      console.log(`ID: ${manifest.id}`);
+      console.log(`Name: ${manifest.name}`);
+      console.log(`Version: ${manifest.version}`);
+      if (manifest.description) console.log(`Description: ${manifest.description}`);
+      console.log(`Rules: ${manifest.rules.length}`);
+      for (const rule of manifest.rules) {
+        const r = rule as { target: string; strategy: string; source: string };
+        console.log(`  - ${r.target} [${r.strategy}] <- ${r.source}`);
+      }
+      return;
+    }
+
+    case "init": {
+      if (!id) {
+        throw new Error("Usage: gxpm preset init <preset-id>");
+      }
+      const presetPath = join(getPresetDir(root), id);
+      if (existsSync(presetPath)) {
+        throw new Error(`Preset '${id}' already exists at ${presetPath}`);
+      }
+      mkdirSync(presetPath, { recursive: true });
+      const manifest = {
+        id,
+        name: id,
+        version: "1.0.0",
+        description: `Preset '${id}'`,
+        rules: [],
+      };
+      writeFileSync(join(presetPath, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
+      console.log(`Initialized preset '${id}' at ${presetPath}`);
+      console.log(`Edit ${join(presetPath, "manifest.json")} and add source files.`);
+      return;
+    }
+
+    default:
+      throw new Error(
+        `Unknown preset command: ${subcommand ?? ""}\nUsage: gxpm preset <list|add|remove|show|init> [id]`,
+      );
+  }
+}

package/scripts/commands/runtime.ts

@@ -0,0 +1,199 @@
+import { appendRunEvent, deleteRun, listRuns, readRun, RUN_STATUSES, startRun } from "../../core/runs";
+import { cleanupIssueWorkspace, ensureIssueWorkspace, ensureIssueWorkspaceWithResolver, planIssueWorkspace } from "../../core/workspace-runtime";
+import { dryRunOrchestratorTick } from "../../core/orchestrator";
+import { claimIssue } from "../../core/issue-readiness";
+import { optionValue, parsePositiveIntegerOption } from "./helpers";
+
+export function runRunCommand(
+  argv: string[],
+  subcommand: string | undefined,
+  issueId: string | undefined,
+  runId: string | undefined,
+) {
+  if (!issueId) {
+    throw new Error("Usage: gxpm run start|list|status|event <issue-id> ...");
+  }
+
+  if (subcommand === "start") {
+    const status = optionValue(argv, "--status") ?? undefined;
+    if (status && !RUN_STATUSES.includes(status as (typeof RUN_STATUSES)[number])) {
+      throw new Error(`Invalid run status: ${status}`);
+    }
+    const attempt = parsePositiveIntegerOption(argv, "--attempt");
+    const workspacePath = optionValue(argv, "--workspace") ?? undefined;
+    const message = optionValue(argv, "--message") ?? undefined;
+    const shouldClaim = argv.includes("--claim");
+    let run = startRun({
+      issueId,
+      attempt,
+      status,
+      workspacePath,
+      message,
+    });
+    const claim = shouldClaim
+      ? claimRunOrRollback({
+          issueId,
+          runId: run.runId,
+          actor: optionValue(argv, "--actor") ?? undefined,
+        })
+      : null;
+    if (claim) {
+      run = appendRunEvent({
+        issueId,
+        runId: run.runId,
+        type: "run.claimed",
+        status: run.status,
+        payload: {
+          actor: claim.claim.actor,
+          claimedBySession: claim.claim.claimedBySession,
+          workspacePath: run.workspacePath,
+        },
+      });
+    }
+    if (argv.includes("--json")) {
+      console.log(JSON.stringify(claim ? { run, claim } : run, null, 2));
+    } else {
+      console.log(`started ${run.runId} for ${issueId}`);
+      console.log(`status: ${run.status}`);
+      if (claim) console.log("claim: claimed");
+    }
+    return;
+  }
+
+  if (subcommand === "list") {
+    const runs = listRuns({ issueId });
+    if (argv.includes("--json")) {
+      console.log(JSON.stringify(runs, null, 2));
+      return;
+    }
+    if (runs.length === 0) {
+      console.log("no runs");
+      return;
+    }
+    for (const run of runs) {
+      console.log(`${run.runId}\t${run.status}\tattempt=${run.attempt}\tupdated=${run.updatedAt}`);
+    }
+    return;
+  }
+
+  if (subcommand === "status") {
+    if (!runId) {
+      throw new Error("Usage: gxpm run status <issue-id> <run-id> [--json]");
+    }
+    const run = readRun({ issueId, runId });
+    if (argv.includes("--json")) {
+      console.log(JSON.stringify(run, null, 2));
+    } else {
+      console.log(`runId: ${run.runId}`);
+      console.log(`issueId: ${run.issueId}`);
+      console.log(`status: ${run.status}`);
+      console.log(`attempt: ${run.attempt}`);
+      console.log(`sessionId: ${run.sessionId}`);
+      if (run.workspacePath) console.log(`workspacePath: ${run.workspacePath}`);
+      if (run.failureReason) console.log(`failureReason: ${run.failureReason}`);
+    }
+    return;
+  }
+
+  if (subcommand === "event") {
+    if (!runId) {
+      throw new Error("Usage: gxpm run event <issue-id> <run-id> --type <event> [--status <status>] [--message <text>] [--reason <text>]");
+    }
+    const eventType = optionValue(argv, "--type");
+    if (!eventType) {
+      throw new Error("gxpm run event requires --type <event>");
+    }
+    const run = appendRunEvent({
+      issueId,
+      runId,
+      type: eventType,
+      status: optionValue(argv, "--status") ?? undefined,
+      message: optionValue(argv, "--message") ?? undefined,
+      failureReason: optionValue(argv, "--reason") ?? undefined,
+    });
+    if (argv.includes("--json")) {
+      console.log(JSON.stringify(run, null, 2));
+    } else {
+      console.log(`updated ${run.runId} for ${issueId}`);
+      console.log(`status: ${run.status}`);
+    }
+    return;
+  }
+
+  throw new Error(`Usage: gxpm run start <issue-id> [--attempt N] [--status ${RUN_STATUSES.join("|")}] [--workspace <path>] [--claim] [--actor <name>] [--json]
+       gxpm run list <issue-id> [--json]
+       gxpm run status <issue-id> <run-id> [--json]
+       gxpm run event <issue-id> <run-id> --type <event> [--status <status>] [--message <text>] [--reason <text>]`);
+}
+
+function claimRunOrRollback(input: { issueId: string; runId: string; actor?: string }) {
+  try {
+    const claim = claimIssue({
+      issueId: input.issueId,
+      actor: input.actor,
+      runId: input.runId,
+    });
+    if (!claim.claimed) {
+      deleteRun({ issueId: input.issueId, runId: input.runId });
+      throw new Error(`Issue already claimed: ${input.issueId}; no run started`);
+    }
+    return claim;
+  } catch (error) {
+    deleteRun({ issueId: input.issueId, runId: input.runId });
+    throw error;
+  }
+}
+
+export async function runWorkspaceCommand(argv: string[], subcommand: string | undefined, issueId: string | undefined) {
+  if (!issueId) {
+    throw new Error("Usage: gxpm workspace plan|ensure|cleanup <issue-id> [--root <path>] [--json]");
+  }
+  const workspaceRoot = optionValue(argv, "--root") ?? undefined;
+  const result =
+    subcommand === "plan"
+      ? planIssueWorkspace({ issueId, workspaceRoot })
+      : subcommand === "ensure"
+        ? await ensureIssueWorkspaceWithResolver({ issueId, workspaceRoot })
+        : subcommand === "cleanup"
+          ? cleanupIssueWorkspace({ issueId, workspaceRoot })
+          : null;
+
+  if (!result) {
+    throw new Error("Usage: gxpm workspace plan|ensure|cleanup <issue-id> [--root <path>] [--json]");
+  }
+  if (argv.includes("--json")) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(`issueId: ${result.issueId}`);
+  console.log(`workspaceRoot: ${result.workspaceRoot}`);
+  console.log(`workspacePath: ${result.workspacePath}`);
+  console.log(`exists: ${result.exists}`);
+  if ("devPort" in result) console.log(`devPort: ${result.devPort}`);
+  if ("created" in result) console.log(`created: ${result.created}`);
+  if ("removed" in result) console.log(`removed: ${result.removed}`);
+  if ("method" in result && result.method) console.log(`method: ${result.method.type}`);
+  if ("warnings" in result && result.warnings) console.log(`warnings: ${result.warnings.join("; ")}`);
+}
+
+export function runOrchestratorCommand(argv: string[], subcommand: string | undefined) {
+  if (subcommand !== "tick" || !argv.includes("--dry-run")) {
+    throw new Error("Usage: gxpm orchestrator tick --dry-run [--json] [--include-all]");
+  }
+  const report = dryRunOrchestratorTick({ includeAll: argv.includes("--include-all") });
+  if (argv.includes("--json")) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+  console.log(`gxpm orchestrator dry-run ${report.generatedAt}`);
+  console.log(
+    `dispatchable=${report.summary.dispatchable} blocked=${report.summary.blocked} ignored=${report.summary.ignored}`,
+  );
+  if (report.issues.length === 0) {
+    console.log("no candidate issues");
+    return;
+  }
+  for (const issue of report.issues) {
+    console.log(`${issue.issueId}\t${issue.currentPhase}\t${issue.decision}\t${issue.reason}`);
+  }
+}

package/scripts/commands/specify.ts

@@ -0,0 +1,71 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { confirmSpecify, reviseSpecify } from "../../core/specify";
+
+function specPath(issueId: string): string {
+  return join(process.cwd(), ".gxpm", "issues", issueId, "artifacts", "behavior-spec.json");
+}
+
+function runConfirm(issueId: string) {
+  if (!issueId) {
+    throw new Error("usage: gxpm specify confirm <issue-id>");
+  }
+  confirmSpecify({ issueId });
+  console.log(`confirmed behavior-spec for ${issueId}`);
+}
+
+function runRevise(issueId: string) {
+  if (!issueId) {
+    throw new Error("usage: gxpm specify revise <issue-id>");
+  }
+  reviseSpecify({ issueId });
+  console.log(`revised behavior-spec for ${issueId} (confirmedAt cleared)`);
+}
+
+function runShow(issueId: string) {
+  if (!issueId) {
+    throw new Error("usage: gxpm specify show <issue-id>");
+  }
+  const path = specPath(issueId);
+  if (!existsSync(path)) {
+    throw new Error(`behavior-spec.json not found for ${issueId}`);
+  }
+  const stored = JSON.parse(readFileSync(path, "utf8"));
+  const spec = stored.payload;
+  console.log(`Feature: ${spec.feature.title}`);
+  console.log(`  As a ${spec.feature.asA}`);
+  console.log(`  I want ${spec.feature.iWant}`);
+  console.log(`  So that ${spec.feature.soThat}`);
+  console.log("");
+  for (const scn of spec.scenarios) {
+    console.log(`Scenario (${scn.id}): ${scn.name}`);
+    for (const g of scn.given) console.log(`  Given ${g}`);
+    console.log(`  When ${scn.when}`);
+    for (const t of scn.then) console.log(`  Then ${t}`);
+    console.log(`  Stub: ${scn.stubPath}`);
+    console.log("");
+  }
+  console.log(`confirmedAt: ${spec.confirmedAt ?? "(not confirmed)"}`);
+}
+
+export function runSpecifyCommand(
+  _argv: string[],
+  subcommand: string | undefined,
+  issueId: string | undefined,
+) {
+  switch (subcommand) {
+    case "confirm":
+      runConfirm(issueId ?? "");
+      return;
+    case "revise":
+      runRevise(issueId ?? "");
+      return;
+    case "show":
+      runShow(issueId ?? "");
+      return;
+    default:
+      throw new Error(
+        `unknown specify subcommand: ${subcommand ?? "<none>"}; expected confirm|revise|show`,
+      );
+  }
+}