@geminix/gxpm 0.1.0

package/core/wiki.ts

@@ -0,0 +1,27 @@
+export {
+  buildNativeWikiIndex,
+  ensureNativeWikiCurrent,
+  evaluateNativeWiki,
+  extractCitedFiles,
+  getNativeWikiContextForIssue,
+  getNativeWikiStatus,
+  initializeNativeWiki,
+  queryNativeWiki,
+  updateNativeWiki,
+} from "./wiki-native";
+
+export type {
+  NativeWikiBuildResult,
+  NativeWikiDimensions,
+  NativeWikiEvalReport,
+  NativeWikiFileDimensions,
+  NativeWikiFileEntry,
+  NativeWikiGraph,
+  NativeWikiGraphEdge,
+  NativeWikiIndex,
+  NativeWikiIssueContext,
+  NativeWikiQueryResult,
+  NativeWikiState,
+  NativeWikiStatus,
+  WikiPageSummary,
+} from "./wiki-native";

package/core/workflow-event-emitter.ts

@@ -0,0 +1,163 @@
+/**
+ * WorkflowEventEmitter — typed event emitter for gxpm execution observability.
+ *
+ * Design:
+ * - Singleton via getWorkflowEventEmitter()
+ * - Fire-and-forget: listener errors never propagate to the emitter
+ * - Issue-scoped subscriptions via subscribeForIssue()
+ * - Built on Node.js EventEmitter (zero external deps)
+ */
+import { EventEmitter } from "node:events";
+
+// ---------------------------------------------------------------------------
+// Event types
+// ---------------------------------------------------------------------------
+
+export interface PhaseTransitionEvent {
+  type: "phase_transition";
+  issueId: string;
+  fromPhase: string | null;
+  toPhase: string;
+  timestamp: string;
+}
+
+export interface ArtifactWrittenEvent {
+  type: "artifact_written";
+  issueId: string;
+  artifactType: string;
+  timestamp: string;
+}
+
+export interface RunStartedEvent {
+  type: "run_started";
+  issueId: string;
+  runId: string;
+  status: string;
+  timestamp: string;
+}
+
+export interface RunCompletedEvent {
+  type: "run_completed";
+  issueId: string;
+  runId: string;
+  status: string;
+  timestamp: string;
+}
+
+export interface RunFailedEvent {
+  type: "run_failed";
+  issueId: string;
+  runId: string;
+  failureReason?: string;
+  timestamp: string;
+}
+
+export interface IssueCreatedEvent {
+  type: "issue_created";
+  issueId: string;
+  issueType?: string;
+  timestamp: string;
+}
+
+export interface IssueTransitionedEvent {
+  type: "issue_transitioned";
+  issueId: string;
+  fromPhase: string | null;
+  toPhase: string;
+  timestamp: string;
+}
+
+export type WorkflowEmitterEvent =
+  | PhaseTransitionEvent
+  | ArtifactWrittenEvent
+  | RunStartedEvent
+  | RunCompletedEvent
+  | RunFailedEvent
+  | IssueCreatedEvent
+  | IssueTransitionedEvent;
+
+// ---------------------------------------------------------------------------
+// Emitter class
+// ---------------------------------------------------------------------------
+
+export type WorkflowEventListener = (event: WorkflowEmitterEvent) => void;
+
+const WORKFLOW_EVENT = "workflow_event";
+
+export class WorkflowEventEmitter {
+  private emitter = new EventEmitter();
+
+  constructor() {
+    this.emitter.setMaxListeners(50);
+  }
+
+  /**
+   * Emit a workflow event. Fire-and-forget: errors are caught and logged to stderr.
+   */
+  emit(event: WorkflowEmitterEvent): void {
+    try {
+      this.emitter.emit(WORKFLOW_EVENT, event);
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      console.error(`[workflow-event-emitter] emit error: ${err.message}`);
+    }
+  }
+
+  /**
+   * Subscribe to all workflow events. Returns an unsubscribe function.
+   */
+  subscribe(listener: WorkflowEventListener): () => void {
+    const safeListener = (event: WorkflowEmitterEvent): void => {
+      try {
+        listener(event);
+      } catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        console.error(`[workflow-event-emitter] listener error: ${err.message}`);
+      }
+    };
+
+    this.emitter.on(WORKFLOW_EVENT, safeListener);
+    return (): void => {
+      this.emitter.removeListener(WORKFLOW_EVENT, safeListener);
+    };
+  }
+
+  /**
+   * Subscribe to events for a specific issue only. Returns an unsubscribe function.
+   */
+  subscribeForIssue(issueId: string, listener: WorkflowEventListener): () => void {
+    return this.subscribe((event: WorkflowEmitterEvent) => {
+      if ("issueId" in event && event.issueId === issueId) {
+        listener(event);
+      }
+    });
+  }
+
+  /**
+   * Remove all listeners. Useful for graceful shutdown.
+   */
+  clear(): void {
+    this.emitter.removeAllListeners();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Singleton
+// ---------------------------------------------------------------------------
+
+let instance: WorkflowEventEmitter | null = null;
+
+export function getWorkflowEventEmitter(): WorkflowEventEmitter {
+  if (!instance) {
+    instance = new WorkflowEventEmitter();
+  }
+  return instance;
+}
+
+/**
+ * Reset singleton for testing.
+ */
+export function resetWorkflowEventEmitter(): void {
+  instance?.clear();
+  instance = null;
+}

package/core/workflows/engine.ts

@@ -0,0 +1,273 @@
+// WORKFLOW ENGINE — declarative workflow runtime.
+// Loads YAML definitions, executes step-by-step, supports resume.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import YAML from "yaml";
+import type {
+  WorkflowDefinition,
+  StepConfig,
+  StepBase,
+  StepContext,
+  StepResult,
+  RunState,
+  RunStatus,
+  StepStatus,
+} from "./types";
+import { evaluateCondition, evaluateExpression } from "./expressions";
+
+export class StepRegistry {
+  private steps = new Map<string, StepBase>();
+
+  register(step: StepBase): void {
+    if (this.steps.has(step.typeKey)) {
+      throw new Error(`Step type ${step.typeKey} already registered`);
+    }
+    this.steps.set(step.typeKey, step);
+  }
+
+  get(typeKey: string): StepBase | undefined {
+    return this.steps.get(typeKey);
+  }
+
+  has(typeKey: string): boolean {
+    return this.steps.has(typeKey);
+  }
+
+  list(): string[] {
+    return Array.from(this.steps.keys());
+  }
+}
+
+export class WorkflowEngine {
+  private registry = new StepRegistry();
+  private definitions = new Map<string, WorkflowDefinition>();
+
+  constructor(private projectRoot: string) {}
+
+  getRegistry(): StepRegistry {
+    return this.registry;
+  }
+
+  registerStep(step: StepBase): void {
+    this.registry.register(step);
+  }
+
+  loadYaml(yamlPath: string): WorkflowDefinition {
+    const absPath = join(this.projectRoot, yamlPath);
+    const text = readFileSync(absPath, "utf8");
+    const def = parseWorkflowYaml(text);
+    this.definitions.set(def.id, def);
+    return def;
+  }
+
+  createRun(workflowId: string, inputs: Record<string, unknown>): RunState {
+    const def = this.definitions.get(workflowId);
+    if (!def) throw new Error(`Workflow ${workflowId} not loaded`);
+
+    const runId = randomUUID();
+    return {
+      runId,
+      workflowId,
+      status: "created",
+      currentStepIndex: -1,
+      stepIndexStack: [],
+      stepResults: {},
+      inputs,
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    };
+  }
+
+  async run(state: RunState): Promise<RunState> {
+    const def = this.definitions.get(state.workflowId);
+    if (!def) throw new Error(`Workflow ${state.workflowId} not loaded`);
+
+    state.status = "running";
+    state.updatedAt = new Date().toISOString();
+
+    const ctx: StepContext = {
+      inputs: state.inputs,
+      steps: state.stepResults,
+      runId: state.runId,
+      projectRoot: this.projectRoot,
+    };
+
+    while (state.currentStepIndex < def.steps.length - 1) {
+      state.currentStepIndex++;
+      const stepConfig = def.steps[state.currentStepIndex];
+
+      if (stepConfig.type === "if") {
+        const condition = stepConfig.config.condition as string;
+        const shouldRun = evaluateCondition(condition, ctx);
+        if (!shouldRun) {
+          state.stepResults[stepConfig.id] = { status: "skipped", output: {} };
+          continue;
+        }
+        state.stepIndexStack.push(state.currentStepIndex);
+        continue;
+      }
+
+      if (stepConfig.type === "endif") {
+        state.stepIndexStack.pop();
+        continue;
+      }
+
+      if (stepConfig.type === "foreach") {
+        state.stepIndexStack.push(state.currentStepIndex);
+        const collection = resolveValue(stepConfig.config.collection, ctx) as unknown[];
+        if (!Array.isArray(collection) || collection.length === 0) {
+          state.stepResults[stepConfig.id] = { status: "skipped", output: {} };
+          state.stepIndexStack.pop();
+          continue;
+        }
+        const results: StepResult[] = [];
+        for (const item of collection) {
+          const subSteps = stepConfig.config.steps as StepConfig[];
+          for (const subStep of subSteps) {
+            const result = await this.executeStep(subStep, { ...ctx, item }, state);
+            results.push(result);
+          }
+        }
+        state.stepResults[stepConfig.id] = {
+          status: "completed",
+          output: { results },
+        };
+        state.stepIndexStack.pop();
+        continue;
+      }
+
+      const result = await this.executeStep(stepConfig, ctx, state);
+      ctx.steps = state.stepResults;
+
+      if (result.status === "failed") {
+        state.status = "failed";
+        state.updatedAt = new Date().toISOString();
+        return state;
+      }
+
+      if (result.status === "paused") {
+        state.status = "paused";
+        state.updatedAt = new Date().toISOString();
+        this.saveState(state);
+        return state;
+      }
+    }
+
+    state.status = "completed";
+    state.updatedAt = new Date().toISOString();
+    return state;
+  }
+
+  /**
+   * Persist run state to disk so it can survive process restarts.
+   */
+  saveState(state: RunState): string {
+    const runsDir = join(this.projectRoot, ".gxpm", "workflows", "runs", state.runId);
+    mkdirSync(runsDir, { recursive: true });
+    const statePath = join(runsDir, "state.json");
+    writeFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`);
+    return statePath;
+  }
+
+  /**
+   * Load a previously persisted run state from disk.
+   */
+  loadState(runId: string): RunState {
+    const statePath = join(this.projectRoot, ".gxpm", "workflows", "runs", runId, "state.json");
+    if (!existsSync(statePath)) {
+      throw new Error(`Workflow run state not found: ${statePath}`);
+    }
+    const raw = JSON.parse(readFileSync(statePath, "utf8")) as RunState;
+    return raw;
+  }
+
+  async resume(state: RunState): Promise<RunState> {
+    if (state.status !== "paused") {
+      throw new Error(`Cannot resume run in status ${state.status}`);
+    }
+    const lastStep = this.getLastStep(state);
+    if (lastStep && lastStep.status === "paused") {
+      const handler = this.registry.get(lastStep.stepId);
+      if (handler?.canResume && !handler.canResume(lastStep)) {
+        throw new Error(`Step ${lastStep.stepId} cannot be resumed`);
+      }
+    }
+    return this.run(state);
+  }
+
+  async resumeFromDisk(runId: string): Promise<RunState> {
+    const state = this.loadState(runId);
+    return this.resume(state);
+  }
+
+  private async executeStep(
+    stepConfig: StepConfig,
+    ctx: StepContext,
+    state: RunState,
+  ): Promise<StepResult> {
+    const handler = this.registry.get(stepConfig.type);
+    if (!handler) {
+      const err = new Error(`Unknown step type: ${stepConfig.type}`);
+      const result: StepResult = {
+        status: "failed",
+        output: {},
+        error: err.message,
+      };
+      state.stepResults[stepConfig.id] = result;
+      return result;
+    }
+
+    // Validate config
+    if (handler.validate) {
+      const errors = handler.validate(stepConfig.config);
+      if (errors.length > 0) {
+        const result: StepResult = {
+          status: "failed",
+          output: {},
+          error: `Validation: ${errors.join("; ")}`,
+        };
+        state.stepResults[stepConfig.id] = result;
+        return result;
+      }
+    }
+
+    try {
+      const result = await handler.execute(stepConfig.config, ctx);
+      state.stepResults[stepConfig.id] = result;
+      return result;
+    } catch (err) {
+      const result: StepResult = {
+        status: "failed",
+        output: {},
+        error: err instanceof Error ? err.message : String(err),
+      };
+      state.stepResults[stepConfig.id] = result;
+      return result;
+    }
+  }
+
+  private getLastStep(state: RunState): { stepId: string; status: StepStatus } | null {
+    const entries = Object.entries(state.stepResults);
+    if (entries.length === 0) return null;
+    const [lastId, lastResult] = entries[entries.length - 1];
+    return { stepId: lastId, status: lastResult.status };
+  }
+}
+
+function resolveValue(template: unknown, context: StepContext): unknown {
+  if (typeof template === "string") {
+    return evaluateExpression(template, context);
+  }
+  return template;
+}
+
+// Parse workflow YAML using the 'yaml' library.
+export function parseWorkflowYaml(text: string): WorkflowDefinition {
+  const doc = YAML.parse(text);
+  if (!doc || typeof doc !== "object") {
+    throw new Error("Invalid YAML: document is not an object");
+  }
+  return doc as WorkflowDefinition;
+}

package/core/workflows/expressions.ts

@@ -0,0 +1,76 @@
+// EXPRESSION ENGINE — minimal Jinja2-like evaluator.
+// Supports variable interpolation ${var} and simple conditions.
+// NO eval / new Function. Whitelist only.
+
+import type { StepContext } from "./types";
+
+const ALLOWED_NAMESPACES = new Set([
+  "inputs",
+  "steps",
+  "issue",
+  "artifacts",
+  "item",
+  "fan_in",
+  "env",
+]);
+
+export function evaluateExpression(template: string, context: StepContext): unknown {
+  // Simple variable interpolation: ${namespace.key} or ${namespace.key.subkey}
+  const interpolated = template.replace(/\$\{([^}]+)\}/g, (_match, path) => {
+    const value = resolvePath(path.trim(), context);
+    return value !== undefined ? String(value) : "";
+  });
+  return interpolated;
+}
+
+export function evaluateCondition(condition: string, context: StepContext): boolean {
+  const evaluated = evaluateExpression(condition, context);
+  if (typeof evaluated === "boolean") return evaluated;
+  if (typeof evaluated === "string") {
+    const normalized = evaluated.trim().toLowerCase();
+    return normalized === "true" || normalized === "yes" || normalized === "1";
+  }
+  if (typeof evaluated === "number") return evaluated !== 0;
+  return Boolean(evaluated);
+}
+
+function resolvePath(path: string, context: StepContext): unknown {
+  const parts = path.split(".");
+  const namespace = parts[0];
+
+  if (!ALLOWED_NAMESPACES.has(namespace)) {
+    return undefined;
+  }
+
+  let value: unknown;
+  switch (namespace) {
+    case "inputs":
+      value = context.inputs;
+      break;
+    case "steps":
+      value = context.steps;
+      break;
+    case "item":
+      value = context.item;
+      break;
+    case "fan_in":
+      value = context.fanIn;
+      break;
+    case "env":
+      value = process.env;
+      break;
+    default:
+      return undefined;
+  }
+
+  for (let i = 1; i < parts.length; i++) {
+    if (value === null || value === undefined) return undefined;
+    if (typeof value === "object") {
+      value = (value as Record<string, unknown>)[parts[i]];
+    } else {
+      return undefined;
+    }
+  }
+
+  return value;
+}

package/core/workflows/index.ts

@@ -0,0 +1,38 @@
+// WORKFLOW ENGINE — public API.
+
+export {
+  WorkflowEngine,
+  StepRegistry,
+  parseWorkflowYaml,
+} from "./engine";
+export {
+  evaluateExpression,
+  evaluateCondition,
+} from "./expressions";
+export type {
+  WorkflowDefinition,
+  WorkflowInputSchema,
+  StepConfig,
+  StepBase,
+  StepContext,
+  StepResult,
+  RunState,
+  RunStatus,
+  StepStatus,
+} from "./types";
+
+// Built-in step types
+export { CommandStep } from "./steps/command";
+export { LinearStep } from "./steps/linear";
+export { GxpmStep } from "./steps/gxpm";
+export { GateStep } from "./steps/gate";
+export { ShellStep } from "./steps/shell";
+
+// Convenience: register all built-in steps
+export function registerBuiltinSteps(engine: WorkflowEngine): void {
+  engine.registerStep(CommandStep);
+  engine.registerStep(LinearStep);
+  engine.registerStep(GxpmStep);
+  engine.registerStep(GateStep);
+  engine.registerStep(ShellStep);
+}

package/core/workflows/steps/command.ts

@@ -0,0 +1,43 @@
+// COMMAND STEP — execute a shell command.
+
+import { execSync } from "node:child_process";
+import type { StepBase, StepResult, StepContext } from "../types";
+
+export const CommandStep: StepBase = {
+  typeKey: "command",
+
+  validate(config) {
+    const errors: string[] = [];
+    if (!config.command || typeof config.command !== "string") {
+      errors.push("'command' is required and must be a string");
+    }
+    return errors;
+  },
+
+  execute(config, context) {
+    const command = config.command as string;
+    const cwd = config.cwd ? String(config.cwd).replace("${projectRoot}", context.projectRoot) : context.projectRoot;
+    const capture = config.captureOutput !== false;
+
+    try {
+      const output = execSync(command, {
+        cwd,
+        encoding: "utf8",
+        stdio: capture ? ["pipe", "pipe", "pipe"] : "inherit",
+        timeout: (config.timeout as number) || 60000,
+      });
+
+      return {
+        status: "completed",
+        output: capture ? { stdout: output, command } : { command },
+      };
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : String(err);
+      return {
+        status: config.ignoreFailure ? "completed" : "failed",
+        output: { command },
+        error: errorMessage,
+      };
+    }
+  },
+};

package/core/workflows/steps/gate.ts

@@ -0,0 +1,47 @@
+// GATE STEP — pause workflow execution for human review/approval.
+// When the engine reaches a gate step, it persists state and returns
+// status "paused". The workflow can be resumed via `gxpm workflow resume`.
+
+import type { StepBase, StepResult, StepContext } from "../types";
+
+export const GateStep: StepBase = {
+  typeKey: "gate",
+
+  validate(config) {
+    const errors: string[] = [];
+    if (!config.message || typeof config.message !== "string") {
+      errors.push("'message' is required and must be a string");
+    }
+    return errors;
+  },
+
+  execute(config, context) {
+    const message = config.message as string;
+    const condition = config.condition as string | undefined;
+
+    // If a condition is provided and evaluates to false, skip the gate
+    if (condition) {
+      const { evaluateCondition } = require("../expressions");
+      const shouldGate = evaluateCondition(condition, context);
+      if (!shouldGate) {
+        return {
+          status: "skipped",
+          output: { message, reason: "condition evaluated to false" },
+        };
+      }
+    }
+
+    return {
+      status: "paused",
+      output: {
+        message,
+        runId: context.runId,
+        pausedAt: new Date().toISOString(),
+      },
+    };
+  },
+
+  canResume() {
+    return true;
+  },
+};