@geminix/gxpm 0.1.0

package/scripts/commands/feedback.ts

@@ -0,0 +1,123 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import {
+  createIssueState,
+  getIssuePaths,
+  isIssueType,
+  ISSUE_TYPES,
+  type IssueType,
+} from "../../core/state";
+import { writeArtifact } from "../../core/artifacts";
+import { getResolvedConfigValue } from "../../core/config";
+import { getNextAvailableIssueId } from "../../core/issues";
+import { optionRequiredValue, optionValue } from "./helpers";
+
+const ISSUE_TYPE_USAGE = ISSUE_TYPES.join("|");
+const FEEDBACK_CREATE_USAGE = `Usage: gxpm feedback create <issue-id>|--auto-id [--title <title>] [--description <text>] [--type ${ISSUE_TYPE_USAGE}]`;
+
+export async function runFeedbackCommand(argv: string[], subcommand: string | undefined) {
+  if (subcommand === "create") {
+    await runFeedbackCreate(argv);
+    return;
+  }
+
+  console.log(`Usage: gxpm feedback <subcommand>
+
+Subcommands:
+  create <issue-id>|--auto-id [--title <title>] [--description <text>] [--type meta|feature|spike]`);
+}
+
+async function runFeedbackCreate(argv: string[]) {
+  const sourceRoot = resolveFeedbackSourceRoot();
+  const args = argv.slice(2);
+
+  const hasAutoId = args.includes("--auto-id");
+  const positional: string[] = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--auto-id") continue;
+    if (arg === "--title" || arg === "--description" || arg === "--type") {
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      throw new Error(`Unknown option for gxpm feedback create: ${arg}`);
+    }
+    positional.push(arg);
+  }
+
+  if (hasAutoId && positional.length > 0) {
+    throw new Error(FEEDBACK_CREATE_USAGE);
+  }
+  if (positional.length > 1) {
+    throw new Error(FEEDBACK_CREATE_USAGE);
+  }
+
+  const issueId = positional[0] ?? (hasAutoId ? getNextAvailableIssueId({ root: sourceRoot }) : undefined);
+  if (!issueId) {
+    throw new Error(FEEDBACK_CREATE_USAGE);
+  }
+
+  const title = optionValue(argv, "--title") ?? undefined;
+  const description = optionValue(argv, "--description") ?? undefined;
+  const issueType = parseFeedbackIssueType(argv);
+
+  // Ensure .gxpm directory exists in source root
+  const gxpmDir = join(sourceRoot, ".gxpm");
+  if (!existsSync(gxpmDir)) {
+    throw new Error(
+      `Feedback source root does not appear to be a gxpm repository: ${sourceRoot}\n` +
+        `Missing .gxpm directory. Set feedback.gxpmSourceRoot to a valid gxpm repo path.`,
+    );
+  }
+
+  const state = createIssueState({ root: sourceRoot, issueId, issueType });
+
+  // Write feedback-description artifact when title or description is provided
+  if (title || description) {
+    writeArtifact({
+      root: sourceRoot,
+      issueId,
+      type: "feedback-description",
+      payload: {
+        title: title ?? "",
+        description: description ?? "",
+        reportedFrom: process.cwd(),
+        reportedAt: new Date().toISOString(),
+      },
+    });
+  }
+
+  console.log(`created feedback issue ${state.issueId} at ${state.currentPhase}`);
+  console.log(`type: ${state.issueType}`);
+  console.log(`sourceRoot: ${sourceRoot}`);
+  console.log(`statePath: ${getIssuePaths(sourceRoot, issueId).statePath}`);
+  if (title) {
+    console.log(`title: ${title}`);
+  }
+  if (description) {
+    console.log(`description: ${description}`);
+  }
+}
+
+function resolveFeedbackSourceRoot(): string {
+  const resolved = getResolvedConfigValue({ key: "feedback.gxpmSourceRoot" });
+  const raw = String(resolved.value ?? "").trim();
+  if (!raw) {
+    throw new Error(
+      `feedback.gxpmSourceRoot is not configured.\n` +
+        `Set it with: gxpm config set feedback.gxpmSourceRoot </absolute/path/to/gxpm/repo>`,
+    );
+  }
+  return resolve(raw);
+}
+
+function parseFeedbackIssueType(argv: string[]): IssueType {
+  const raw = optionValue(argv, "--type");
+  if (!raw) return "meta";
+  if (!isIssueType(raw)) {
+    throw new Error(`Invalid issue type: ${raw}; expected ${ISSUE_TYPE_USAGE}`);
+  }
+  return raw;
+}

package/scripts/commands/gate.ts

@@ -0,0 +1,291 @@
+import { existsSync, readFileSync } from "node:fs";
+import { appendIssueEvent, getIssuePaths, readIssueState, transitionIssuePhase, type StateEvent } from "../../core/state";
+import { hasArtifact, readArtifact } from "../../core/artifacts";
+import { evaluateBranchPolicy, evaluateCommitMsg, evaluatePostMerge, evaluatePreCommit, evaluatePrePush } from "../../core/gate";
+import { initializeLandFindings, reconcileLandFindings } from "../../core/land";
+import { runPostLandSkillSync } from "../post-land-sync";
+import { asRecord, currentGitBranch, currentGitRoot, detectCanonicalMainRoot, optionValue } from "./helpers";
+import { getResolvedConfigValue } from "../../core/config";
+
+export function runGateCommand(argv: string[], subcommand: string | undefined, issueId: string | undefined) {
+  if (subcommand === "pre-commit") {
+    runPreCommitGate(argv, issueId);
+    return;
+  }
+  if (subcommand === "branch-policy") {
+    runBranchPolicyGate(argv);
+    return;
+  }
+  if (subcommand === "commit-msg") {
+    runCommitMsgGate(argv, issueId);
+    return;
+  }
+  if (subcommand === "pre-push") {
+    runPrePushGate(issueId);
+    return;
+  }
+  if (subcommand === "post-merge") {
+    runPostMergeGate(issueId);
+    return;
+  }
+  if (subcommand === "post-merge-reconcile") {
+    runPostMergeReconcileGate(argv, issueId);
+    return;
+  }
+  if (subcommand === "brainstorm-skip") {
+    runBrainstormSkipGate(argv, issueId);
+    return;
+  }
+  throw new Error(`Unknown command: ${["gate", subcommand].filter(Boolean).join(" ")}`);
+}
+
+function runBrainstormSkipGate(argv: string[], issueId: string | undefined) {
+  if (!issueId) {
+    throw new Error("Usage: gxpm gate brainstorm-skip <issue-id> --reason <text>");
+  }
+  const reason = optionValue(argv, "--reason");
+  if (!reason) {
+    throw new Error("Usage: gxpm gate brainstorm-skip <issue-id> --reason <text>");
+  }
+
+  const stateRoot = process.cwd();
+  const paths = getIssuePaths(stateRoot, issueId);
+  const intake = readArtifact({ root: stateRoot, issueId, type: "issue-intake" });
+  const payload = asRecord(intake.payload);
+  const acceptance = Array.isArray(payload.acceptance) ? payload.acceptance : [];
+  const antiPatterns = Array.isArray(payload.verified_pitfalls_to_avoid)
+    ? payload.verified_pitfalls_to_avoid
+    : [];
+
+  const event: StateEvent = {
+    schemaVersion: 1,
+    type: "gate.brainstorm.skipped",
+    issueId,
+    timestamp: new Date().toISOString(),
+    payload: {
+      reason,
+      intake_completeness_score: acceptance.length > 0 ? 1 : 0,
+      ac_count: acceptance.length,
+      anti_pattern_count: antiPatterns.length,
+    },
+  };
+
+  appendIssueEvent({ issueDir: paths.issueDir, event });
+  console.log(`[gxpm gate brainstorm-skip] gate.brainstorm.skipped: ${reason}`);
+}
+
+function gateEvent(verdict: { allowed: boolean; code: string; reason: string; details?: Record<string, unknown> }, gate: string, issueId: string): StateEvent {
+  return {
+    schemaVersion: 1,
+    type: verdict.allowed ? "gate.passed" : "gate.blocked",
+    issueId,
+    timestamp: new Date().toISOString(),
+    payload: { gate, code: verdict.code, reason: verdict.reason, ...(verdict.details ?? {}) },
+  };
+}
+
+function runBranchPolicyGate(argv: string[]) {
+  const currentRoot = currentGitRoot() ?? process.cwd();
+  const currentBranch = optionValue(argv, "--branch") ?? currentGitBranch();
+  const canonicalMainRoot =
+    optionValue(argv, "--canonical-main") ??
+    process.env.GXPM_CANONICAL_MAIN ??
+    detectCanonicalMainRoot() ??
+    currentRoot;
+  const allowedWorktreeRoot = optionValue(argv, "--worktree-root") ?? process.env.GXPM_WORKTREE_ROOT ?? undefined;
+  const baseBranch = getResolvedConfigValue({ key: "worktree.baseBranch" }).value as string;
+  const verdict = evaluateBranchPolicy({
+    currentRoot,
+    currentBranch,
+    canonicalMainRoot,
+    allowedWorktreeRoot,
+    baseBranch,
+    env: process.env,
+  });
+
+  if (!verdict.allowed) {
+    console.error(`[gxpm gate branch-policy] ${verdict.code}: ${verdict.reason}`);
+    console.error(`Use a dedicated git worktree for feature branches; keep the canonical checkout on ${baseBranch}.`);
+    console.error("Escape: GXPM_GATE_DISABLE=1 git ...");
+    process.exit(1);
+  }
+
+  console.log(`[gxpm gate branch-policy] ${verdict.code}: ${verdict.reason}`);
+}
+
+function runPreCommitGate(argv: string[], issueId: string | undefined) {
+  if (!issueId) {
+    throw new Error("Usage: gxpm gate pre-commit <issue-id> --staged <files...>");
+  }
+  const dashStaged = argv.indexOf("--staged");
+  const stagedFiles = dashStaged >= 0 ? argv.slice(dashStaged + 1) : [];
+
+  const stateRoot = process.cwd();
+  const paths = getIssuePaths(stateRoot, issueId);
+  if (!existsSync(paths.statePath)) {
+    console.log(`no-state: ${issueId} not tracked by gxpm`);
+    return;
+  }
+
+  const state = readIssueState({ root: stateRoot, issueId });
+  const verdict = evaluatePreCommit(state, stagedFiles, process.env);
+  appendIssueEvent({ issueDir: paths.issueDir, event: gateEvent(verdict, "pre-commit", issueId) });
+
+  if (!verdict.allowed) {
+    console.error(`[gxpm gate pre-commit] ${verdict.code}: ${verdict.reason}`);
+    const hits = verdict.details?.protectedHits;
+    if (Array.isArray(hits)) {
+      for (const f of hits) console.error(`  - ${f}`);
+    }
+    console.error("Escape: GXPM_GATE_DISABLE=1 git commit ...");
+    process.exit(1);
+  }
+  console.log(`[gxpm gate pre-commit] ${verdict.code}: ${verdict.reason}`);
+}
+
+function runCommitMsgGate(argv: string[], firstArg: string | undefined) {
+  const msgFile = firstArg;
+  if (!msgFile) {
+    throw new Error("Usage: gxpm gate commit-msg <msg-file> [--issue <id>]");
+  }
+  const dashIssue = argv.indexOf("--issue");
+  const explicitIssue = dashIssue >= 0 ? argv[dashIssue + 1] : null;
+  const message = readFileSync(msgFile, "utf8");
+
+  const inferred =
+    explicitIssue ??
+    (message.match(/\b(GXG|GXPM)-\d+\b/i)?.[0]?.toUpperCase() ?? null);
+  if (!inferred) {
+    console.error(
+      "[gxpm gate commit-msg] missing-issue-ref: commit message must reference GXG-NNN or GXPM-NNN",
+    );
+    process.exit(1);
+  }
+
+  const stateRoot = process.cwd();
+  const paths = getIssuePaths(stateRoot, inferred);
+  if (!existsSync(paths.statePath)) {
+    console.log(`no-state: ${inferred} not tracked by gxpm`);
+    return;
+  }
+
+  const state = readIssueState({ root: stateRoot, issueId: inferred });
+  const verdict = evaluateCommitMsg(message, state, process.env);
+  if (!verdict.allowed) {
+    console.error(`[gxpm gate commit-msg] ${verdict.code}: ${verdict.reason}`);
+    process.exit(1);
+  }
+  console.log(`[gxpm gate commit-msg] ${verdict.code}: ${verdict.reason}`);
+}
+
+function runPrePushGate(issueId: string | undefined) {
+  if (!issueId) {
+    throw new Error("Usage: gxpm gate pre-push <issue-id>");
+  }
+  const stateRoot = process.cwd();
+  const paths = getIssuePaths(stateRoot, issueId);
+  if (!existsSync(paths.statePath)) {
+    console.log(`no-state: ${issueId} not tracked by gxpm`);
+    return;
+  }
+
+  const state = readIssueState({ root: stateRoot, issueId });
+  const verdict = evaluatePrePush(
+    state,
+    (id, t) => hasArtifact({ root: stateRoot, issueId: id, type: t }),
+    process.env,
+    stateRoot,
+  );
+  if (!verdict.allowed) {
+    console.error(`[gxpm gate pre-push] ${verdict.code}: ${verdict.reason}`);
+    if (verdict.details && typeof verdict.details.command === "string") {
+      console.error(
+        `Hint: ${verdict.details.command.replace("<issue-id>", issueId)}`,
+      );
+    }
+    process.exit(1);
+  }
+  console.log(`[gxpm gate pre-push] ${verdict.code}: ${verdict.reason}`);
+}
+
+function runPostMergeGate(issueId: string | undefined) {
+  if (!issueId) {
+    throw new Error("Usage: gxpm gate post-merge <issue-id>");
+  }
+  const stateRoot = process.cwd();
+  const paths = getIssuePaths(stateRoot, issueId);
+  if (!existsSync(paths.statePath)) {
+    console.log(`no-state: ${issueId} not tracked by gxpm`);
+    return;
+  }
+
+  const state = readIssueState({ root: stateRoot, issueId });
+  const outcome = evaluatePostMerge(state);
+  if (!outcome.transitionTo) {
+    console.log(`[gxpm gate post-merge] ${outcome.reason}`);
+    return;
+  }
+
+  // Auto-initialize the gate artifact before transitioning so the merge always
+  // produces a complete trail. Idempotent: writeArtifact overwrites existing files.
+  if (outcome.transitionTo === "land" && !hasArtifact({ root: stateRoot, issueId, type: "land-findings" })) {
+    initializeLandFindings({ root: stateRoot, issueId });
+  }
+
+  const updated = transitionIssuePhase({ root: stateRoot, issueId, nextPhase: outcome.transitionTo });
+  console.log(`transitioned ${issueId}: ${state.currentPhase} -> ${updated.currentPhase}`);
+  if (updated.currentPhase === "land") {
+    console.log(`Hint: gxpm cleanup land ${issueId} --execute  # 清理 worktree + local branch`);
+    const sync = runPostLandSkillSync({ env: process.env });
+    if (!sync.ok) {
+      console.error(`[gxpm land sync] ${sync.message}`);
+    }
+  }
+}
+
+function runPostMergeReconcileGate(argv: string[], issueId: string | undefined) {
+  if (!issueId) {
+    throw new Error("Usage: gxpm gate post-merge-reconcile <issue-id> --sha <sha>");
+  }
+  const sha = optionValue(argv, "--sha");
+  if (!sha) {
+    throw new Error("Usage: gxpm gate post-merge-reconcile <issue-id> --sha <sha>");
+  }
+
+  const stateRoot = process.cwd();
+  const paths = getIssuePaths(stateRoot, issueId);
+  if (!existsSync(paths.statePath)) {
+    console.log(`no-state: ${issueId} not tracked by gxpm`);
+    return;
+  }
+
+  const state = readIssueState({ root: stateRoot, issueId });
+  if (state.currentPhase !== "land") {
+    console.log(`[gxpm gate post-merge-reconcile] phase=${state.currentPhase} is not land`);
+    return;
+  }
+  if (!hasArtifact({ root: stateRoot, issueId, type: "land-findings" })) {
+    console.log("[gxpm gate post-merge-reconcile] land-findings artifact missing");
+    return;
+  }
+  if (!gitCommitExists(stateRoot, sha)) {
+    throw new Error(`Git commit not found for post-merge reconcile: ${sha}`);
+  }
+
+  const result = reconcileLandFindings({ root: stateRoot, issueId, sha });
+  if (result.reconciled) {
+    console.log(`[gxpm gate post-merge-reconcile] reconciled land-findings for ${issueId}`);
+    return;
+  }
+  console.log(`[gxpm gate post-merge-reconcile] ${result.reason}`);
+}
+
+function gitCommitExists(cwd: string, sha: string) {
+  const result = Bun.spawnSync({
+    cmd: ["git", "cat-file", "-e", `${sha}^{commit}`],
+    cwd,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  return result.exitCode === 0;
+}

package/scripts/commands/helpers.ts

@@ -0,0 +1,126 @@
+import { readFileSync } from "node:fs";
+
+export function readJsonPayloadFromArgs(argv: string[], usagePrefix: string) {
+  const dashJson = argv.indexOf("--json");
+  const dashFrom = argv.indexOf("--from");
+  const useStdin = argv.includes("--stdin");
+
+  const inputs = [dashJson >= 0, dashFrom >= 0, useStdin].filter(Boolean).length;
+  if (inputs === 0) {
+    throw new Error(`${usagePrefix} requires one of: --json <json> | --from <file> | --stdin`);
+  }
+  if (inputs > 1) {
+    throw new Error(`${usagePrefix}: pick exactly one of --json / --from / --stdin`);
+  }
+
+  let raw: string;
+  if (dashJson >= 0) {
+    raw = argv[dashJson + 1] ?? "";
+  } else if (dashFrom >= 0) {
+    const file = argv[dashFrom + 1];
+    if (!file) throw new Error("--from requires a file path");
+    raw = readFileSync(file, "utf8");
+  } else {
+    raw = readFileSync(0, "utf8");
+  }
+
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    throw new Error(
+      `${usagePrefix}: invalid JSON payload — ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}
+
+export function parsePositiveIntegerOption(argv: string[], option: string) {
+  if (!argv.includes(option)) return undefined;
+  const raw = optionRequiredValue(argv, option);
+  const value = Number.parseInt(raw, 10);
+  if (!Number.isInteger(value) || value < 1 || String(value) !== raw) {
+    throw new Error(`${option} requires a positive integer`);
+  }
+  return value;
+}
+
+export function optionRequiredValue(argv: string[], option: string) {
+  const value = optionValue(argv, option);
+  if (!value) {
+    throw new Error(`${option} requires a value`);
+  }
+  return value;
+}
+
+export function optionValue(argv: string[], option: string) {
+  const index = argv.indexOf(option);
+  if (index < 0) return null;
+  const value = argv[index + 1];
+  return value && !value.startsWith("--") ? value : null;
+}
+
+export function payloadTitle(payload: unknown) {
+  if (!payload || typeof payload !== "object") return null;
+  const title = (payload as Record<string, unknown>).title;
+  return typeof title === "string" && title.trim() ? title : null;
+}
+
+export function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+export function currentGitBranch() {
+  const result = Bun.spawnSync({
+    cmd: ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+    cwd: process.cwd(),
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  if (result.exitCode !== 0) return undefined;
+  const branch = result.stdout.toString().trim();
+  return branch || undefined;
+}
+
+export function currentGitRoot() {
+  const result = Bun.spawnSync({
+    cmd: ["git", "rev-parse", "--show-toplevel"],
+    cwd: process.cwd(),
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  if (result.exitCode !== 0) return undefined;
+  const root = result.stdout.toString().trim();
+  return root || undefined;
+}
+
+export function detectCanonicalMainRoot() {
+  const result = Bun.spawnSync({
+    cmd: ["git", "worktree", "list", "--porcelain"],
+    cwd: process.cwd(),
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  if (result.exitCode !== 0) return undefined;
+  return result.stdout
+    .toString()
+    .split("\n")
+    .find((line) => line.startsWith("worktree "))
+    ?.slice("worktree ".length);
+}
+
+/**
+ * Detect whether the current cwd is inside a linked git worktree (not the canonical main checkout).
+ */
+export function isInsideLinkedWorktree(): boolean {
+  const result = Bun.spawnSync({
+    cmd: ["git", "rev-parse", "--git-path", "HEAD"],
+    cwd: process.cwd(),
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  if (result.exitCode !== 0) return false;
+  const gitPath = result.stdout.toString().trim();
+  // In a linked worktree, git-path resolves to .git/worktrees/<name>/HEAD
+  return gitPath.includes("/worktrees/");
+}

package/scripts/commands/hook.ts

@@ -0,0 +1,66 @@
+/**
+ * `gxpm hook <event> --host <host>`
+ *
+ * Unified hook entry point called by all host-specific hook configurations.
+ * Reads JSON from stdin, dispatches to the hook engine, and prints host-formatted output.
+ */
+
+import { processHook, formatHookOutput, isValidHookHost, type HookInput } from "../../core/hook-engine";
+
+export async function runHookCommand(argv: string[]): Promise<void> {
+  // argv: ["hook", "SessionStart", "--host", "codex", ...]
+  const eventName = argv[1];
+  if (!eventName) {
+    console.error("Usage: gxpm hook <event> --host <claude|codex|cursor|kimi>");
+    process.exit(1);
+  }
+
+  let host: string | undefined;
+  for (let i = 2; i < argv.length; i += 1) {
+    if (argv[i] === "--host" && i + 1 < argv.length) {
+      host = argv[i + 1];
+      break;
+    }
+  }
+
+  if (!host || !isValidHookHost(host)) {
+    console.error("Usage: gxpm hook <event> --host <claude|codex|cursor|kimi>");
+    process.exit(1);
+  }
+
+  let input: HookInput;
+  try {
+    const raw = await readStdin();
+    input = raw ? JSON.parse(raw) : ({} as HookInput);
+  } catch {
+    // fail-open: if stdin is not valid JSON, allow the action to proceed
+    process.exit(0);
+  }
+
+  const result = await processHook(host, eventName, input);
+
+  const output = formatHookOutput(host, eventName, result);
+  if (output) {
+    console.log(output);
+  }
+
+  process.exit(result.exitCode);
+}
+
+function readStdin(): Promise<string> {
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) {
+      resolve("");
+      return;
+    }
+    let data = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on("end", () => {
+      resolve(data);
+    });
+    process.stdin.resume();
+  });
+}