@geminix/gxpm 0.1.0

package/scripts/gxpm.ts

@@ -0,0 +1,216 @@
+import { runCleanupLandCommand } from "./cleanup";
+import { formatDoctorReport, runDoctor } from "./doctor";
+import { runGlobalDiscover } from "./global-discover";
+import { findPhaseArtifactCommand } from "./phase-artifact-commands";
+import { runScaffoldCheck } from "./scaffold-check";
+import { readGxpmVersion } from "./version";
+import { resolveSessionId } from "../core/session";
+import { getWorkflowEventEmitter } from "../core/workflow-event-emitter";
+import { runArtifactCommand } from "./commands/artifact";
+import { runCapabilityCommand } from "./commands/capability";
+import { runConfigCommand, runWorktreePolicyCommand } from "./commands/config";
+import { runGateCommand } from "./commands/gate";
+import { runIssueCommand } from "./commands/issue";
+import { runOrchestratorCommand, runRunCommand, runWorkspaceCommand } from "./commands/runtime";
+import { runWikiCommand } from "./commands/wiki";
+import { runInitCommand } from "./commands/init";
+import { runPostUpgradeCommand, runUpgradeCommand } from "./commands/upgrade";
+import { runVerifyCommand } from "./commands/verify";
+import { runDagCommand } from "./commands/dag";
+import { runHookCommand } from "./commands/hook";
+import { runWorkflowCommand } from "./commands/workflow";
+import { runPresetCommand } from "./commands/preset";
+import { runPhaseCommand } from "./commands/phase";
+import { runSpecifyCommand } from "./commands/specify";
+import { runFeedbackCommand } from "./commands/feedback";
+
+async function main(argv: string[]) {
+  if (argv.includes("--verbose-events")) {
+    argv = argv.filter((arg) => arg !== "--verbose-events");
+    getWorkflowEventEmitter().subscribe((event) => {
+      console.error(`[event] ${JSON.stringify(event)}`);
+    });
+  }
+  // Filter out flags like --army before positional parsing
+  const positional = argv.filter((arg) => !arg.startsWith("--"));
+  const [command, subcommand, issueId, value] = positional;
+
+  if (!command || command === "check") {
+    console.log(runScaffoldCheck());
+    return;
+  }
+
+  if (command === "version" || command === "--version" || command === "-v") {
+    console.log(readGxpmVersion());
+    return;
+  }
+
+  if (command === "session-id") {
+    console.log(resolveSessionId());
+    return;
+  }
+
+  if (command === "config") {
+    runConfigCommand(argv, subcommand, issueId, value);
+    return;
+  }
+
+  if (command === "worktree") {
+    runWorktreePolicyCommand(argv, subcommand);
+    return;
+  }
+
+  if (command === "capability") {
+    runCapabilityCommand(argv, subcommand, issueId);
+    return;
+  }
+
+  if (command === "wiki") {
+    runWikiCommand(argv, subcommand);
+    return;
+  }
+
+  if (command === "init") {
+    runInitCommand(argv.slice(1));
+    return;
+  }
+
+  if (command === "doctor") {
+    const json = argv.includes("--json");
+    const fix = argv.includes("--fix");
+    const report = runDoctor({ fix });
+    if (json) {
+      console.log(JSON.stringify(report, null, 2));
+    } else {
+      console.log(formatDoctorReport(report));
+    }
+    return;
+  }
+
+  if (command === "upgrade") {
+    runUpgradeCommand(argv.slice(1));
+    return;
+  }
+
+  if (command === "post-upgrade") {
+    runPostUpgradeCommand(argv.slice(1));
+    return;
+  }
+
+  if (command === "verify") {
+    // gxpm verify qa <id> is a phase artifact command; do not shadow it.
+    const phaseArtifactCommand = findPhaseArtifactCommand(command, subcommand);
+    if (!phaseArtifactCommand) {
+      runVerifyCommand(argv.slice(1));
+      return;
+    }
+  }
+
+  if (command === "run") {
+    runRunCommand(argv, subcommand, issueId, value);
+    return;
+  }
+
+  if (command === "workspace") {
+    await runWorkspaceCommand(argv, subcommand, issueId);
+    return;
+  }
+
+  if (command === "orchestrator") {
+    runOrchestratorCommand(argv, subcommand);
+    return;
+  }
+
+  if (command === "global-discover") {
+    const entries = runGlobalDiscover();
+    if (argv.includes("--json")) {
+      console.log(JSON.stringify(entries, null, 2));
+    } else {
+      for (const entry of entries) {
+        console.log(`${entry.key}\t${entry.repos.join(",")}`);
+      }
+    }
+    return;
+  }
+
+  if (command === "issue") {
+    await runIssueCommand(argv, subcommand, issueId, value);
+    return;
+  }
+
+  if (command === "artifact") {
+    runArtifactCommand(argv, subcommand, issueId, value);
+    return;
+  }
+
+  if (command === "autopilot") {
+    const { runAutopilotCommand } = await import("./commands/autopilot");
+    runAutopilotCommand(argv, subcommand, issueId);
+    return;
+  }
+
+  if (command === "gate") {
+    runGateCommand(argv, subcommand, issueId);
+    return;
+  }
+
+  if (command === "dag") {
+    runDagCommand(argv);
+    return;
+  }
+
+  if (command === "workflow") {
+    runWorkflowCommand(argv);
+    return;
+  }
+
+  if (command === "hook") {
+    await runHookCommand(argv);
+    return;
+  }
+
+  if (command === "preset") {
+    runPresetCommand(argv, subcommand, issueId);
+    return;
+  }
+
+  if (command === "specify" && subcommand !== "init") {
+    runSpecifyCommand(argv, subcommand, issueId);
+    return;
+  }
+
+  if (command === "feedback") {
+    await runFeedbackCommand(argv, subcommand);
+    return;
+  }
+
+  if (command === "phase") {
+    runPhaseCommand(argv, subcommand);
+    return;
+  }
+
+  if (command === "cleanup" && subcommand === "land") {
+    if (!issueId) {
+      throw new Error("Usage: gxpm cleanup land <issue-id> [--execute] [--force]");
+    }
+    runCleanupLandCommand(argv, issueId);
+    return;
+  }
+
+  const phaseArtifactCommand = findPhaseArtifactCommand(command, subcommand);
+  if (phaseArtifactCommand) {
+    if (!issueId) {
+      throw new Error(`Usage: ${phaseArtifactCommand.command}`);
+    }
+    phaseArtifactCommand.initialize({ issueId });
+    console.log(phaseArtifactCommand.successMessage(issueId));
+    return;
+  }
+
+  throw new Error(`Unknown command: ${[command, subcommand].filter(Boolean).join(" ")}`);
+}
+
+main(Bun.argv.slice(2)).catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/scripts/host-config.ts

@@ -0,0 +1,62 @@
+import type { HostConfig } from "../core/contracts/host";
+
+export type { FrontmatterConfig, HostConfig } from "../core/contracts/host";
+
+const HOST_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+const CLI_PATTERN = /^[a-z][a-z0-9-]*$/;
+const SAFE_RELATIVE_PATH = /^(?!\/)(?!.*(?:^|\/)\.\.(?:\/|$))(?!.*\/\/).+$/;
+
+export function validateHostConfig(config: HostConfig): string[] {
+  const errors: string[] = [];
+
+  if (!HOST_NAME_PATTERN.test(config.name)) {
+    errors.push(`${config.name || "<missing>"}: host name must be lowercase kebab-case`);
+  }
+
+  if (!config.displayName.trim()) {
+    errors.push(`${config.name}: displayName is required`);
+  }
+
+  if (!CLI_PATTERN.test(config.cliCommand)) {
+    errors.push(`${config.name}: cliCommand must be a simple executable name`);
+  }
+
+  for (const [field, value] of [
+    ["hostSubdir", config.hostSubdir],
+    ["globalRoot", config.globalRoot],
+    ["localSkillRoot", config.localSkillRoot],
+  ] as const) {
+    if (!SAFE_RELATIVE_PATH.test(value)) {
+      errors.push(`${config.name}: ${field} must be a safe relative path`);
+    }
+  }
+
+  if (config.frontmatter.mode === "allowlist" && config.frontmatter.keys.length === 0) {
+    errors.push(`${config.name}: frontmatter allowlist needs at least one key`);
+  }
+
+  if (!["copy", "symlink"].includes(config.install.strategy)) {
+    errors.push(`${config.name}: unsupported install strategy ${config.install.strategy}`);
+  }
+
+  return errors;
+}
+
+export function validateAllConfigs(configs: readonly HostConfig[]): string[] {
+  const errors = configs.flatMap(validateHostConfig);
+
+  for (const field of ["name", "hostSubdir", "globalRoot"] as const) {
+    const seen = new Map<string, string>();
+    for (const config of configs) {
+      const value = config[field];
+      const owner = seen.get(value);
+      if (owner) {
+        errors.push(`${config.name}: ${field} duplicates ${owner} (${value})`);
+      } else {
+        seen.set(value, config.name);
+      }
+    }
+  }
+
+  return errors;
+}

package/scripts/install-claude-hooks.ts

@@ -0,0 +1,138 @@
+/**
+ * Install Claude Code hooks that call the unified `gxpm hook` entry point.
+ *
+ * Writes/merges a `hooks` block into `.claude/settings.json` (repo scope)
+ * or `~/.claude/settings.json` (user scope).
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+interface InstallClaudeHooksOptions {
+  /** "repo" → <target>/.claude/ (default), "user" → ~/.claude/ */
+  scope?: "user" | "repo";
+  target?: string;
+  home?: string;
+}
+
+interface InstallResult {
+  settingsJsonPath: string;
+  rootDir: string;
+}
+
+export function installClaudeHooks(options: InstallClaudeHooksOptions = {}): InstallResult {
+  const scope = options.scope ?? "repo";
+  const home = options.home ?? homedir();
+
+  const rootDir =
+    scope === "user" ? join(home, ".claude") : join(resolve(options.target ?? process.cwd()), ".claude");
+  mkdirSync(rootDir, { recursive: true });
+
+  const settingsJsonPath = join(rootDir, "settings.json");
+
+  const newConfig = {
+    hooks: {
+      SessionStart: [
+        {
+          matcher: "startup|clear|compact",
+          hooks: [
+            {
+              type: "command",
+              command: "gxpm hook SessionStart --host claude",
+              async: false,
+              statusMessage: "gxpm: loading capability hint",
+            },
+          ],
+        },
+      ],
+      UserPromptSubmit: [
+        {
+          hooks: [
+            {
+              type: "command",
+              command: "gxpm hook UserPromptSubmit --host claude",
+              async: false,
+              statusMessage: "gxpm: resolving referenced issue",
+            },
+          ],
+        },
+      ],
+      PreToolUse: [
+        {
+          matcher: "ExitPlanMode",
+          hooks: [
+            {
+              type: "command",
+              command: "gxpm hook PreToolUse --host claude",
+              async: false,
+              statusMessage: "gxpm: recording plan payload",
+            },
+          ],
+        },
+      ],
+    },
+  };
+
+  const merged = mergeWithExisting(settingsJsonPath, newConfig);
+  writeFileSync(settingsJsonPath, JSON.stringify(merged, null, 2) + "\n");
+
+  return { settingsJsonPath, rootDir };
+}
+
+function mergeWithExisting(path: string, fresh: Record<string, any>) {
+  if (!existsSync(path)) return fresh;
+  let existing: Record<string, any> = {};
+  try {
+    existing = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return fresh;
+  }
+
+  const eventNames = Object.keys(fresh.hooks ?? {});
+  const existingHooks = existing.hooks ?? {};
+
+  for (const event of eventNames) {
+    const ourEntries = (fresh.hooks as Record<string, any[]>)[event] ?? [];
+    const ourCommands = new Set(
+      ourEntries.flatMap((e: any) => (e.hooks ?? []).map((h: any) => h.command)),
+    );
+    const otherEntries: any[] = [];
+    for (const entry of existingHooks[event] ?? []) {
+      const filteredHooks = (entry.hooks ?? []).filter((h: any) => !ourCommands.has(h.command));
+      if (filteredHooks.length > 0) {
+        otherEntries.push({ ...entry, hooks: filteredHooks });
+      }
+    }
+    existingHooks[event] = [...otherEntries, ...ourEntries];
+  }
+
+  return { ...existing, hooks: existingHooks };
+}
+
+function parseArgs(argv: string[]): InstallClaudeHooksOptions {
+  const opts: InstallClaudeHooksOptions = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--scope") opts.scope = argv[++i] as "user" | "repo";
+    else if (a === "--target") opts.target = argv[++i];
+    else if (a === "--home") opts.home = argv[++i];
+    else throw new Error(`Unknown argument: ${a}`);
+  }
+  return opts;
+}
+
+if (import.meta.main) {
+  try {
+    const result = installClaudeHooks(parseArgs(Bun.argv.slice(2)));
+    console.log(`wrote: ${result.settingsJsonPath}`);
+    console.log(
+      "scope:",
+      result.rootDir.includes(homedir() + "/.claude") ? "user (~/.claude/)" : "repo (<repo>/.claude/)",
+    );
+    console.log("Restart Claude Code to activate hooks.");
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}

package/scripts/install-codex-hooks.ts

@@ -0,0 +1,271 @@
+/**
+ * Install Codex CLI hooks that call the unified `gxpm hook` entry point.
+ *
+ * Instead of installing per-event bash scripts, we write a single hooks.json
+ * that delegates to `gxpm hook <event> --host codex`. All business logic lives
+ * in core/hook-engine.ts and is shared across Claude, Codex, Kimi, and Cursor.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+interface InstallCodexHooksOptions {
+  /** "repo" → <target>/.codex/ (default), "user" → ~/.codex/ */
+  scope?: "user" | "repo";
+  target?: string;
+  home?: string;
+  enableFeatureFlag?: boolean;
+}
+
+interface InstallResult {
+  hooksJsonPath: string;
+  rootDir: string;
+  featureFlagEnabled: "already-set" | "enabled-now" | "config-missing" | "skipped";
+}
+
+const DEFAULT_GXPM_ROOT = resolve(import.meta.dir, "..");
+const GXPM_CODEX_HOOK_CONFIG = {
+  hooks: {
+    SessionStart: [
+      {
+        matcher: "startup|clear|compact",
+        hooks: [
+          {
+            type: "command",
+            command: "gxpm hook SessionStart --host codex",
+            statusMessage: "gxpm: loading capability hint",
+          },
+        ],
+      },
+    ],
+    UserPromptSubmit: [
+      {
+        hooks: [
+          {
+            type: "command",
+            command: "gxpm hook UserPromptSubmit --host codex",
+            statusMessage: "gxpm: resolving referenced issue",
+          },
+        ],
+      },
+    ],
+    PreToolUse: [
+      {
+        hooks: [
+          {
+            type: "command",
+            command: "gxpm hook PreToolUse --host codex",
+            statusMessage: "gxpm: recording update_plan payload",
+          },
+        ],
+      },
+    ],
+    Stop: [
+      {
+        hooks: [
+          {
+            type: "command",
+            command: "gxpm hook Stop --host codex",
+            statusMessage: "gxpm: checking autopilot grant",
+          },
+        ],
+      },
+    ],
+  },
+};
+const LEGACY_GXPM_CODEX_HOOK_MARKERS: Record<string, string[]> = {
+  SessionStart: [
+    ".codex/hooks/gxpm-session-start.sh",
+    "gxpm-session-start.sh",
+  ],
+  UserPromptSubmit: [
+    ".codex/hooks/gxpm-user-prompt-submit.sh",
+    "gxpm-user-prompt-submit.sh",
+  ],
+  PreToolUse: [
+    ".codex/hooks/gxpm-pre-tool-use.sh",
+    "gxpm-pre-tool-use.sh",
+  ],
+  Stop: [
+    ".codex/hooks/gxpm-stop.sh",
+    "gxpm-stop.sh",
+  ],
+};
+
+export function installCodexHooks(options: InstallCodexHooksOptions = {}): InstallResult {
+  const scope = options.scope ?? "repo";
+  const home = options.home ?? homedir();
+
+  const rootDir =
+    scope === "user" ? join(home, ".codex") : join(resolve(options.target ?? process.cwd()), ".codex");
+  mkdirSync(rootDir, { recursive: true });
+
+  const hooksJsonPath = join(rootDir, "hooks.json");
+
+  const merged = mergeWithExisting(hooksJsonPath, GXPM_CODEX_HOOK_CONFIG);
+  writeFileSync(hooksJsonPath, JSON.stringify(merged, null, 2) + "\n");
+  const userHooksJsonPath = join(home, ".codex", "hooks.json");
+  if (scope === "repo" && resolve(hooksJsonPath) !== resolve(userHooksJsonPath)) {
+    removeGxpmOwnedHooksFrom(userHooksJsonPath, GXPM_CODEX_HOOK_CONFIG);
+  }
+
+  const featureFlagEnabled = (options.enableFeatureFlag ?? true)
+    ? ensureCodexHooksFeatureFlag(home)
+    : "skipped";
+
+  return { hooksJsonPath, rootDir, featureFlagEnabled };
+}
+
+function ensureCodexHooksFeatureFlag(home: string): "already-set" | "enabled-now" | "config-missing" {
+  const configPath = join(home, ".codex", "config.toml");
+  if (!existsSync(configPath)) return "config-missing";
+
+  const content = readFileSync(configPath, "utf8");
+  if (/^codex_hooks\s*=\s*true\s*$/m.test(content)) return "already-set";
+
+  const ts = new Date().toISOString().replace(/[-:.TZ]/g, "").slice(0, 14);
+  const backup = `${configPath}.bak-codex-hooks-${ts}`;
+  writeFileSync(backup, content);
+
+  const featuresMatch = content.match(/^\[features\]\s*$/m);
+  let updated: string;
+  if (featuresMatch) {
+    const lines = content.split("\n");
+    const idx = lines.findIndex((line) => /^\[features\]\s*$/.test(line));
+    let endIdx = lines.length;
+    for (let i = idx + 1; i < lines.length; i += 1) {
+      if (/^\[/.test(lines[i])) { endIdx = i; break; }
+    }
+    let insertAt = endIdx;
+    while (insertAt > idx + 1 && lines[insertAt - 1].trim() === "") insertAt -= 1;
+    lines.splice(insertAt, 0, "codex_hooks = true");
+    updated = lines.join("\n");
+  } else {
+    updated = content.replace(/\n*$/, "\n\n[features]\ncodex_hooks = true\n");
+  }
+  writeFileSync(configPath, updated);
+  return "enabled-now";
+}
+
+function mergeWithExisting(path: string, fresh: Record<string, any>) {
+  if (!existsSync(path)) return fresh;
+  let existing: Record<string, any> = {};
+  try {
+    existing = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return fresh;
+  }
+
+  const eventNames = Object.keys(fresh.hooks ?? {});
+  const existingHooks = existing.hooks ?? {};
+
+  for (const event of eventNames) {
+    const ourEntries = (fresh.hooks as Record<string, any[]>)[event] ?? [];
+    const ourCommands = new Set(
+      ourEntries.flatMap((e: any) => (e.hooks ?? []).map((h: any) => h.command)),
+    );
+    const otherEntries: any[] = [];
+    for (const entry of existingHooks[event] ?? []) {
+      const filteredHooks = (entry.hooks ?? []).filter(
+        (h: any) => !isGxpmOwnedCodexHook(event, h.command, ourCommands),
+      );
+      if (filteredHooks.length > 0) {
+        otherEntries.push({ ...entry, hooks: filteredHooks });
+      }
+    }
+    existingHooks[event] = [...otherEntries, ...ourEntries];
+  }
+
+  return { ...existing, hooks: existingHooks };
+}
+
+function removeGxpmOwnedHooksFrom(path: string, fresh: Record<string, any>) {
+  if (!existsSync(path)) return;
+  let existing: Record<string, any> = {};
+  try {
+    existing = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return;
+  }
+  if (!existing.hooks || typeof existing.hooks !== "object") return;
+
+  const eventNames = Object.keys(fresh.hooks ?? {});
+  for (const event of eventNames) {
+    const entries = Array.isArray(existing.hooks[event]) ? existing.hooks[event] : [];
+    const freshEntries = (fresh.hooks as Record<string, any[]>)[event] ?? [];
+    const freshCommands = new Set(
+      freshEntries.flatMap((e: any) => (e.hooks ?? []).map((h: any) => h.command)),
+    );
+    const nextEntries = entries
+      .map((entry: any) => {
+        const hooks = Array.isArray(entry?.hooks) ? entry.hooks : [];
+        const keptHooks = hooks.filter(
+          (hook: any) => !isGxpmOwnedCodexHook(event, hook.command, freshCommands),
+        );
+        return { ...entry, hooks: keptHooks };
+      })
+      .filter((entry: any) => Array.isArray(entry.hooks) && entry.hooks.length > 0);
+
+    if (nextEntries.length > 0) {
+      existing.hooks[event] = nextEntries;
+    } else {
+      delete existing.hooks[event];
+    }
+  }
+
+  writeFileSync(path, JSON.stringify(existing, null, 2) + "\n");
+}
+
+function isGxpmOwnedCodexHook(event: string, command: unknown, currentCommands: Set<unknown>) {
+  if (currentCommands.has(command)) return true;
+  if (typeof command !== "string") return false;
+  return (LEGACY_GXPM_CODEX_HOOK_MARKERS[event] ?? []).some((marker) =>
+    command.includes(marker),
+  );
+}
+
+function parseArgs(argv: string[]): InstallCodexHooksOptions {
+  const opts: InstallCodexHooksOptions = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--scope") opts.scope = argv[++i] as "user" | "repo";
+    else if (a === "--target") opts.target = argv[++i];
+    else if (a === "--home") opts.home = argv[++i];
+    else if (a === "--no-feature-flag") opts.enableFeatureFlag = false;
+    else throw new Error(`Unknown argument: ${a}`);
+  }
+  return opts;
+}
+
+if (import.meta.main) {
+  try {
+    const result = installCodexHooks(parseArgs(Bun.argv.slice(2)));
+    console.log(`wrote: ${result.hooksJsonPath}`);
+    console.log(
+      "scope:",
+      result.rootDir.includes(homedir() + "/.codex") ? "user (~/.codex/)" : "repo (<repo>/.codex/)",
+    );
+
+    switch (result.featureFlagEnabled) {
+      case "already-set":
+        console.log("feature flag: codex_hooks = true (already enabled)");
+        break;
+      case "enabled-now":
+        console.log("feature flag: codex_hooks = true (enabled now; backup written)");
+        break;
+      case "config-missing":
+        console.log("feature flag: ⚠️  ~/.codex/config.toml not found; create it with [features]\ncodex_hooks = true");
+        break;
+      case "skipped":
+        console.log("feature flag: skipped per --no-feature-flag");
+        break;
+    }
+    console.log("");
+    console.log("For repo-scope hooks: trust the .codex/ layer when Codex prompts.");
+    console.log("Restart Codex to activate hooks.");
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}