@geminix/gxpm 0.1.0

package/core/workflows/steps/gxpm.ts

@@ -0,0 +1,44 @@
+// GXPM STEP — invoke gxpm CLI commands within a workflow.
+
+import { execSync } from "node:child_process";
+import type { StepBase, StepResult, StepContext } from "../types";
+
+export const GxpmStep: StepBase = {
+  typeKey: "gxpm",
+
+  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 fullCommand = `bun run bin/gxpm ${command}`;
+    const cwd = context.projectRoot;
+    const capture = config.captureOutput !== false;
+
+    try {
+      const output = execSync(fullCommand, {
+        cwd,
+        encoding: "utf8",
+        stdio: capture ? ["pipe", "pipe", "pipe"] : "inherit",
+        timeout: (config.timeout as number) || 120000,
+      });
+
+      return {
+        status: "completed",
+        output: capture ? { stdout: output, command: fullCommand } : { command: fullCommand },
+      };
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : String(err);
+      return {
+        status: config.ignoreFailure ? "completed" : "failed",
+        output: { command: fullCommand },
+        error: errorMessage,
+      };
+    }
+  },
+};

package/core/workflows/steps/linear.ts

@@ -0,0 +1,31 @@
+// LINEAR STEP — interact with Linear issues.
+// Thin wrapper; actual Linear integration delegates to existing core/linear module.
+
+import type { StepBase, StepResult, StepContext } from "../types";
+
+export const LinearStep: StepBase = {
+  typeKey: "linear",
+
+  validate(config) {
+    const errors: string[] = [];
+    if (!config.action || typeof config.action !== "string") {
+      errors.push("'action' is required");
+    }
+    const valid = ["create", "update", "list", "transition"];
+    if (!valid.includes(config.action as string)) {
+      errors.push(`'action' must be one of: ${valid.join(", ")}`);
+    }
+    return errors;
+  },
+
+  async execute(config, _context) {
+    const action = config.action as string;
+
+    // Placeholder: will delegate to core/linear.ts when available
+    // For now, return a mock result to keep workflow engine testable
+    return {
+      status: "completed",
+      output: { action, mock: true, id: config.id as string },
+    };
+  },
+};

package/core/workflows/steps/shell.ts

@@ -0,0 +1,65 @@
+// SHELL STEP — execute an arbitrary shell command within a workflow.
+// Captures stdout, stderr, and exitCode for downstream steps.
+
+import { execSync } from "node:child_process";
+import type { StepBase, StepResult, StepContext } from "../types";
+
+export const ShellStep: StepBase = {
+  typeKey: "shell",
+
+  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;
+    const timeout = (config.timeout as number) || 60000;
+
+    try {
+      const output = execSync(command, {
+        cwd,
+        encoding: "utf8",
+        stdio: capture ? ["pipe", "pipe", "pipe"] : "inherit",
+        timeout,
+      });
+
+      return {
+        status: "completed",
+        output: capture
+          ? { stdout: output, exitCode: 0, command }
+          : { exitCode: 0, command },
+      };
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : String(err);
+      // execSync throws on non-zero exit; try to capture stdout/stderr from the error object
+      const stdout =
+        err && typeof err === "object" && "stdout" in err
+          ? String((err as { stdout?: unknown }).stdout)
+          : "";
+      const stderr =
+        err && typeof err === "object" && "stderr" in err
+          ? String((err as { stderr?: unknown }).stderr)
+          : "";
+      const exitCode =
+        err && typeof err === "object" && "status" in err
+          ? Number((err as { status?: unknown }).status)
+          : 1;
+
+      return {
+        status: config.ignoreFailure ? "completed" : "failed",
+        output: capture
+          ? { stdout, stderr, exitCode, command }
+          : { exitCode, command },
+        error: errorMessage,
+      };
+    }
+  },
+};

package/core/workflows/types.ts

@@ -0,0 +1,62 @@
+// WORKFLOW ENGINE — core types and interfaces.
+// Zero external dependencies beyond Node.js builtins.
+
+export type RunStatus = "created" | "running" | "paused" | "completed" | "failed" | "aborted";
+export type StepStatus = "pending" | "running" | "completed" | "failed" | "skipped" | "paused";
+
+export interface WorkflowDefinition {
+  schemaVersion: string;
+  id: string;
+  name: string;
+  version: string;
+  description?: string;
+  inputs: Record<string, WorkflowInputSchema>;
+  steps: StepConfig[];
+}
+
+export interface WorkflowInputSchema {
+  type: "string" | "boolean" | "number" | "array";
+  required?: boolean;
+  default?: unknown;
+}
+
+export interface StepConfig {
+  id: string;
+  type: string;
+  config: Record<string, unknown>;
+}
+
+export interface StepContext {
+  inputs: Record<string, unknown>;
+  steps: Record<string, StepResult>;
+  runId: string;
+  projectRoot: string;
+  item?: unknown;
+  fanIn?: unknown[];
+}
+
+export interface StepResult {
+  status: StepStatus;
+  output: Record<string, unknown>;
+  nextSteps?: StepConfig[];
+  error?: string;
+}
+
+export interface RunState {
+  runId: string;
+  workflowId: string;
+  status: RunStatus;
+  currentStepIndex: number;
+  stepIndexStack: number[];
+  stepResults: Record<string, StepResult>;
+  inputs: Record<string, unknown>;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface StepBase {
+  readonly typeKey: string;
+  execute(config: Record<string, unknown>, context: StepContext): StepResult | Promise<StepResult>;
+  validate?(config: Record<string, unknown>): string[];
+  canResume?(state: StepResult): boolean;
+}

package/core/workspace-runtime.ts

@@ -0,0 +1,227 @@
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  rmSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { getResolvedConfigValue } from "./config";
+import { resolveDevPort } from "./port-allocation";
+import { readIssueState } from "./state";
+import {
+  IsolationResolver,
+  createFileSystemStore,
+  createGitProvider,
+  type IsolationHints,
+  type IsolationMethod,
+  type IsolationResolution,
+} from "./isolation-resolver";
+import { runWorktreeInit, type WorktreeInitContext } from "./worktree-init";
+import "./worktree-init-steps"; // side-effect: registers built-in init steps
+
+export interface WorkspacePlanInput {
+  root?: string;
+  issueId: string;
+  workspaceRoot?: string;
+}
+
+export interface WorkspacePlan {
+  issueId: string;
+  workspaceKey: string;
+  workspaceRoot: string;
+  workspacePath: string;
+  exists: boolean;
+  devPort: number;
+}
+
+export interface WorkspaceEnsureResult extends WorkspacePlan {
+  created: boolean;
+}
+
+export interface WorkspaceIsolationResult extends WorkspaceEnsureResult {
+  method?: IsolationMethod;
+  warnings?: string[];
+  userMessage?: string;
+  resolution?: IsolationResolution;
+}
+
+export interface WorkspaceCleanupResult extends WorkspacePlan {
+  removed: boolean;
+}
+
+export function planIssueWorkspace(input: WorkspacePlanInput): WorkspacePlan {
+  const root = input.root ?? process.cwd();
+  const state = readIssueState({ root, issueId: input.issueId });
+  const workspaceRoot = resolveWorkspaceRoot({ root, workspaceRoot: input.workspaceRoot });
+  const workspaceKey = sanitizeWorkspaceKey(state.issueId);
+  const workspacePath = join(workspaceRoot, workspaceKey);
+  assertPathInsideRoot(workspaceRoot, workspacePath);
+
+  const plan = {
+    issueId: state.issueId,
+    workspaceKey,
+    workspaceRoot,
+    workspacePath,
+    exists: existsSync(workspacePath),
+  };
+
+  return {
+    ...plan,
+    devPort: resolveDevPort({ workspacePath, root }),
+  };
+}
+
+export function ensureIssueWorkspace(input: WorkspacePlanInput): WorkspaceEnsureResult {
+  const plan = planIssueWorkspace(input);
+  mkdirSync(plan.workspaceRoot, { recursive: true });
+  assertPathInsideRoot(plan.workspaceRoot, plan.workspacePath);
+
+  const existed = existsSync(plan.workspacePath);
+  if (existed && !lstatSync(plan.workspacePath).isDirectory()) {
+    throw new Error(`Workspace path exists but is not a directory: ${plan.workspacePath}`);
+  }
+  if (!existed) {
+    mkdirSync(plan.workspacePath, { recursive: true });
+  }
+
+  return { ...plan, exists: true, created: !existed };
+}
+
+export async function ensureIssueWorkspaceWithResolver(
+  input: WorkspacePlanInput & { hints?: IsolationHints },
+): Promise<WorkspaceIsolationResult> {
+  const root = input.root ?? process.cwd();
+  const issueId = input.issueId;
+  const configuredBaseBranch = String(getResolvedConfigValue({ root, key: "worktree.baseBranch" }).value);
+  const hints: IsolationHints = {
+    ...input.hints,
+    baseBranch: input.hints?.baseBranch ?? configuredBaseBranch,
+  };
+
+  // Run resolver first
+  const store = createFileSystemStore(root);
+  const provider = createGitProvider();
+  const resolver = new IsolationResolver({ store, provider });
+  const resolution = await resolver.resolve({ issueId, root, hints });
+
+  let plan: WorkspacePlan;
+  let created = false;
+
+  let initWarnings: string[] = [];
+
+  if (resolution.status === "resolved" && resolution.env) {
+    // Use the resolved workspace path
+    const workspacePath = resolution.env.workspacePath;
+    const workspaceRoot = resolveWorkspaceRoot({ root, workspaceRoot: input.workspaceRoot });
+    plan = {
+      issueId,
+      workspaceKey: sanitizeWorkspaceKey(issueId),
+      workspaceRoot,
+      workspacePath,
+      exists: existsSync(workspacePath),
+      devPort: resolveDevPort({ workspacePath, root }),
+    };
+    if (!plan.exists) {
+      mkdirSync(workspacePath, { recursive: true });
+      created = true;
+    }
+
+    // Run worktree init pipeline for reused worktrees (new worktrees are
+    // already initialized inside the provider). Idempotent — safe to re-run.
+    const repoResult = Bun.spawnSync({
+      cmd: ["git", "rev-parse", "--show-toplevel"],
+      cwd: root,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    if (repoResult.exitCode === 0) {
+      const canonicalRepoPath = repoResult.stdout.toString().trim();
+      const initCtx: WorktreeInitContext = {
+        canonicalRepoPath,
+        worktreePath: workspacePath,
+        branchName: resolution.env.branchName ?? `gxpm-${issueId}`,
+        issueId,
+      };
+      const initResult = await runWorktreeInit(initCtx);
+      initWarnings = initResult.warnings;
+      if (!initResult.ok) {
+        initWarnings.push(...initResult.errors);
+      }
+    }
+  } else if (resolution.status === "none") {
+    // No git repo: fall back to plain directory workspace
+    plan = planIssueWorkspace(input);
+    mkdirSync(plan.workspaceRoot, { recursive: true });
+    assertPathInsideRoot(plan.workspaceRoot, plan.workspacePath);
+    const existed = existsSync(plan.workspacePath);
+    if (!existed) {
+      mkdirSync(plan.workspacePath, { recursive: true });
+      created = true;
+    }
+  } else {
+    // blocked or stale_cleaned — return as-is with minimal plan
+    plan = planIssueWorkspace(input);
+  }
+
+  return {
+    ...plan,
+    exists: true,
+    created,
+    method: resolution.method,
+    warnings: [...(resolution.warnings ?? []), ...initWarnings],
+    userMessage: resolution.userMessage,
+    resolution,
+  };
+}
+
+export function cleanupIssueWorkspace(input: WorkspacePlanInput): WorkspaceCleanupResult {
+  const plan = planIssueWorkspace(input);
+  if (!plan.exists) {
+    return { ...plan, removed: false };
+  }
+  if (!lstatSync(plan.workspacePath).isDirectory()) {
+    throw new Error(`Workspace path exists but is not a directory: ${plan.workspacePath}`);
+  }
+  assertPathInsideRoot(plan.workspaceRoot, plan.workspacePath);
+  rmSync(plan.workspacePath, { recursive: true, force: true });
+  return { ...plan, exists: false, removed: true };
+}
+
+export function sanitizeWorkspaceKey(identifier: string) {
+  const safe = identifier.replace(/[^A-Za-z0-9._-]/g, "_");
+  return safe || "issue";
+}
+
+export function isPathInsideRoot(
+  root: string,
+  candidate: string,
+  pathApi = { isAbsolute, relative, resolve },
+) {
+  const relativePath = pathApi.relative(pathApi.resolve(root), pathApi.resolve(candidate));
+  return relativePath === "" || (!relativePath.startsWith("..") && !pathApi.isAbsolute(relativePath));
+}
+
+function resolveWorkspaceRoot(input: { root: string; workspaceRoot?: string }) {
+  const configured =
+    input.workspaceRoot ??
+    String(getResolvedConfigValue({ root: input.root, key: "workspace.root" }).value);
+  const expanded = expandHome(configured);
+  return isAbsolute(expanded) ? resolve(expanded) : resolve(input.root, expanded);
+}
+
+function expandHome(path: string) {
+  if (path === "~") {
+    return homedir();
+  }
+  if (path.startsWith("~/")) {
+    return join(homedir(), path.slice(2));
+  }
+  return path;
+}
+
+function assertPathInsideRoot(root: string, candidate: string) {
+  if (!isPathInsideRoot(root, candidate)) {
+    throw new Error(`Workspace path escapes workspace root: ${resolve(candidate)}`);
+  }
+}