@geminix/gxpm 0.1.0

package/docs/specs/cursor.md

@@ -0,0 +1,44 @@
+# Cursor Host 规范镜像
+
+## 平台标识
+
+- **名称**: Cursor IDE
+- **上下文长度**: ~200K tokens（Claude 3.5 Sonnet / GPT-4o）
+- **工具支持**: MCP、Composer、Tab
+
+## 上下文格式
+
+- 优先使用 `.cursorrules` 或项目根目录的规则文件
+- 支持 `AGENTS.md` 和 `CLAUDE.md` 作为补充契约
+- Composer 模式支持多文件编辑和全局上下文
+
+## 工具调用约定
+
+- **MCP**: 通过 Cursor Settings 中的 MCP 配置添加
+- **Composer**: 支持 `@` 引用文件、符号、文档
+- **Tab**: 自动补全基于当前文件和打开的标签页上下文
+
+## 已知限制
+
+- 无原生 hooks 系统，需通过 gxpm 的 IDE 插件或外部脚本模拟
+- `.cursorrules` 长度受限，复杂规则需拆分到 `docs/governance/`
+- 不区分 Skills 和 Plugins 概念
+
+## gxpm 集成点
+
+- `hosts/cursor.ts` — Cursor 宿主适配器
+- `docs/governance/cursor-rules.md` — Cursor 专属规则（如存在）
+- 通过 gxpm CLI 在终端中查询 issue 状态，再复制关键信息到 Composer
+
+## 工作流差异
+
+| 阶段 | Cursor 行为 |
+|------|-------------|
+| 启动 | 加载 .cursorrules + 打开的文件上下文 |
+| 用户提示 | Composer 支持多文件 @ 引用 |
+| 文件编辑 | 内联 diff 或 Composer 批量编辑 |
+| 终端集成 | 内置终端可直接运行 gxpm CLI |
+
+## 同步策略
+
+当 `hosts/cursor.ts` 或 Cursor 专属规则文件发生变更时，同步更新本文档。

package/hosts/adapters/claude.ts

@@ -0,0 +1,29 @@
+import type { HostAdapter, CommandDef } from "../schema";
+
+export const claudeAdapter: HostAdapter = {
+  key: "claude",
+  name: "Claude Code",
+  cliCommand: "claude",
+
+  detect(): boolean {
+    try {
+      return Bun.which("claude") !== null;
+    } catch {
+      return false;
+    }
+  },
+
+  install(_command: CommandDef, _projectRoot: string): void {
+    // TODO: integrate with scripts/install-skill.ts for host-specific install
+    throw new Error("Claude Code install not yet implemented via registry");
+  },
+
+  uninstall(_commandName: string, _projectRoot: string): void {
+    // TODO: integrate with host-specific uninstall
+    throw new Error("Claude Code uninstall not yet implemented via registry");
+  },
+
+  preferredFormat(): "markdown" {
+    return "markdown";
+  },
+};

package/hosts/adapters/codex.ts

@@ -0,0 +1,27 @@
+import type { HostAdapter, CommandDef } from "../schema";
+
+export const codexAdapter: HostAdapter = {
+  key: "codex",
+  name: "OpenAI Codex CLI",
+  cliCommand: "codex",
+
+  detect(): boolean {
+    try {
+      return Bun.which("codex") !== null;
+    } catch {
+      return false;
+    }
+  },
+
+  install(_command: CommandDef, _projectRoot: string): void {
+    throw new Error("Codex CLI install not yet implemented via registry");
+  },
+
+  uninstall(_commandName: string, _projectRoot: string): void {
+    throw new Error("Codex CLI uninstall not yet implemented via registry");
+  },
+
+  preferredFormat(): "skills" {
+    return "skills";
+  },
+};

package/hosts/adapters/cursor.ts

@@ -0,0 +1,27 @@
+import type { HostAdapter, CommandDef } from "../schema";
+
+export const cursorAdapter: HostAdapter = {
+  key: "cursor",
+  name: "Cursor",
+  cliCommand: "cursor",
+
+  detect(): boolean {
+    try {
+      return Bun.which("cursor") !== null;
+    } catch {
+      return false;
+    }
+  },
+
+  install(_command: CommandDef, _projectRoot: string): void {
+    throw new Error("Cursor install not yet implemented via registry");
+  },
+
+  uninstall(_commandName: string, _projectRoot: string): void {
+    throw new Error("Cursor uninstall not yet implemented via registry");
+  },
+
+  preferredFormat(): "markdown" {
+    return "markdown";
+  },
+};

package/hosts/adapters/kimi.ts

@@ -0,0 +1,27 @@
+import type { HostAdapter, CommandDef } from "../schema";
+
+export const kimiAdapter: HostAdapter = {
+  key: "kimi",
+  name: "Kimi Code CLI",
+  cliCommand: "kimi",
+
+  detect(): boolean {
+    try {
+      return Bun.which("kimi") !== null;
+    } catch {
+      return false;
+    }
+  },
+
+  install(_command: CommandDef, _projectRoot: string): void {
+    throw new Error("Kimi CLI install not yet implemented via registry");
+  },
+
+  uninstall(_commandName: string, _projectRoot: string): void {
+    throw new Error("Kimi CLI uninstall not yet implemented via registry");
+  },
+
+  preferredFormat(): "skills" {
+    return "skills";
+  },
+};

package/hosts/claude.ts

@@ -0,0 +1,23 @@
+import type { HostConfig } from "../core/contracts/host";
+
+export const claudeHostConfig: HostConfig = {
+  name: "claude",
+  displayName: "Claude Code",
+  cliCommand: "claude",
+  hostSubdir: ".claude",
+  globalRoot: ".claude/skills/gxpm",
+  localSkillRoot: ".claude/skills/gxpm",
+  usesEnvVars: false,
+  frontmatter: {
+    mode: "preserve",
+  },
+  install: {
+    strategy: "copy",
+  },
+  hooks: {
+    configFileName: "settings.json",
+    configFormat: "json",
+    configPathSegments: [".claude", "settings.json"],
+    featureFlagRequired: false,
+  },
+};

package/hosts/codex.ts

@@ -0,0 +1,26 @@
+import type { HostConfig } from "../core/contracts/host";
+
+export const codexHostConfig: HostConfig = {
+  name: "codex",
+  displayName: "OpenAI Codex CLI",
+  cliCommand: "codex",
+  hostSubdir: ".agents",
+  globalRoot: ".codex/skills/gxpm",
+  localSkillRoot: ".agents/skills/gxpm",
+  usesEnvVars: true,
+  frontmatter: {
+    mode: "allowlist",
+    keys: ["name", "description"],
+  },
+  install: {
+    strategy: "copy",
+  },
+  hooks: {
+    configFileName: "hooks.json",
+    configFormat: "json",
+    configPathSegments: [".codex", "hooks.json"],
+    featureFlagRequired: true,
+    featureFlagKey: "codex_hooks",
+    featureFlagSection: "[features]",
+  },
+};

package/hosts/cursor.ts

@@ -0,0 +1,19 @@
+import type { HostConfig } from "../core/contracts/host";
+
+export const cursorHostConfig: HostConfig = {
+  name: "cursor",
+  displayName: "Cursor",
+  cliCommand: "cursor",
+  hostSubdir: ".cursor",
+  globalRoot: ".cursor/skills/gxpm",
+  localSkillRoot: ".cursor/skills/gxpm",
+  usesEnvVars: false,
+  frontmatter: {
+    mode: "preserve",
+  },
+  install: {
+    strategy: "copy",
+  },
+  // Cursor does not currently expose a native hooks system.
+  // Rules (.cursor/rules/*.md) and skills are the primary extension points.
+};

package/hosts/index.ts

@@ -0,0 +1,33 @@
+import { HOST_REGISTRY, registerHost } from "./registry";
+import { claudeAdapter } from "./adapters/claude";
+import { codexAdapter } from "./adapters/codex";
+import { cursorAdapter } from "./adapters/cursor";
+import { kimiAdapter } from "./adapters/kimi";
+
+// Register built-in host adapters (idempotent for test isolation)
+if (!HOST_REGISTRY.has(claudeAdapter.key)) registerHost(claudeAdapter);
+if (!HOST_REGISTRY.has(codexAdapter.key)) registerHost(codexAdapter);
+if (!HOST_REGISTRY.has(cursorAdapter.key)) registerHost(cursorAdapter);
+if (!HOST_REGISTRY.has(kimiAdapter.key)) registerHost(kimiAdapter);
+
+// Backward-compatible HostConfig exports
+import { claudeHostConfig } from "./claude";
+import { codexHostConfig } from "./codex";
+import { cursorHostConfig } from "./cursor";
+
+export const ALL_HOST_CONFIGS = [claudeHostConfig, codexHostConfig, cursorHostConfig] as const;
+export const ALL_HOST_NAMES = ALL_HOST_CONFIGS.map((host) => host.name);
+
+export type HostName = (typeof ALL_HOST_NAMES)[number];
+
+export function getHostConfig(name: string) {
+  const config = ALL_HOST_CONFIGS.find((host) => host.name === name);
+  if (!config) {
+    throw new Error(`Unknown gxpm host: ${name}`);
+  }
+  return config;
+}
+
+// Re-export new registry system
+export { HOST_REGISTRY, registerHost };
+export type { HostAdapter, HostConfig, CommandDef } from "./schema";

package/hosts/registry.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect } from "bun:test";
+import { HostRegistry, registerHost, HOST_REGISTRY } from "./registry";
+import { claudeAdapter } from "./adapters/claude";
+import { codexAdapter } from "./adapters/codex";
+
+describe("HostRegistry", () => {
+  it("registers and retrieves adapters", () => {
+    const registry = new HostRegistry();
+    registry.register(claudeAdapter);
+    expect(registry.get("claude")).toBe(claudeAdapter);
+  });
+
+  it("throws on duplicate registration", () => {
+    const registry = new HostRegistry();
+    registry.register(claudeAdapter);
+    expect(() => registry.register(claudeAdapter)).toThrow("already registered");
+  });
+
+  it("unregisters adapters", () => {
+    const registry = new HostRegistry();
+    registry.register(claudeAdapter);
+    expect(registry.unregister("claude")).toBe(true);
+    expect(registry.has("claude")).toBe(false);
+  });
+
+  it("lists registered keys", () => {
+    const registry = new HostRegistry();
+    registry.register(claudeAdapter);
+    registry.register(codexAdapter);
+    expect(registry.list()).toEqual(["claude", "codex"]);
+  });
+
+  it("detects active hosts", () => {
+    const registry = new HostRegistry();
+    registry.register(claudeAdapter);
+    // Detection depends on whether 'claude' is in PATH; test shape only
+    const active = registry.detectAll();
+    expect(Array.isArray(active)).toBe(true);
+  });
+});
+
+describe("registerHost", () => {
+  it("adds to global registry", () => {
+    // If index.ts side-effect already ran, codex is present; test idempotent path
+    if (HOST_REGISTRY.has("codex")) {
+      expect(HOST_REGISTRY.get("codex")).toBe(codexAdapter);
+    } else {
+      registerHost(codexAdapter);
+      expect(HOST_REGISTRY.has("codex")).toBe(true);
+    }
+  });
+});

package/hosts/registry.ts

@@ -0,0 +1,57 @@
+/**
+ * Host Registry — registry-driven host adapter system.
+ *
+ * Eliminates hard-coded host arrays in favor of dynamic registration.
+ * New hosts require only a single adapter file + registerHost() call.
+ */
+
+import type { HostAdapter } from "./schema";
+
+export class HostRegistry {
+  private adapters = new Map<string, HostAdapter>();
+
+  register(adapter: HostAdapter): void {
+    if (this.adapters.has(adapter.key)) {
+      throw new Error(`Host adapter '${adapter.key}' is already registered`);
+    }
+    this.adapters.set(adapter.key, adapter);
+  }
+
+  unregister(key: string): boolean {
+    return this.adapters.delete(key);
+  }
+
+  get(key: string): HostAdapter | undefined {
+    return this.adapters.get(key);
+  }
+
+  has(key: string): boolean {
+    return this.adapters.has(key);
+  }
+
+  /** List all registered host keys */
+  list(): string[] {
+    return Array.from(this.adapters.keys());
+  }
+
+  /** Find the first host whose detect() returns true */
+  detectActive(): HostAdapter | undefined {
+    for (const adapter of this.adapters.values()) {
+      if (adapter.detect()) return adapter;
+    }
+    return undefined;
+  }
+
+  /** Get all adapters whose detect() returns true */
+  detectAll(): HostAdapter[] {
+    return Array.from(this.adapters.values()).filter((a) => a.detect());
+  }
+}
+
+/** Global singleton registry */
+export const HOST_REGISTRY = new HostRegistry();
+
+/** Convenience shorthand for HOST_REGISTRY.register */
+export function registerHost(adapter: HostAdapter): void {
+  HOST_REGISTRY.register(adapter);
+}

package/hosts/schema.ts

@@ -0,0 +1,58 @@
+/**
+ * Host Schema — declarative host adapter protocol.
+ *
+ * Defines the contract that every host CLI must satisfy to integrate with gxpm.
+ */
+
+export type CommandFormat = "markdown" | "toml" | "yaml" | "skills";
+
+export interface CommandDef {
+  name: string;
+  description: string;
+  format: CommandFormat;
+  /** Whether this command requires an interactive session */
+  interactive?: boolean;
+}
+
+export interface HostAdapter {
+  /** Unique host identifier (e.g. 'claude', 'codex', 'cursor') */
+  key: string;
+  /** Human-readable display name */
+  name: string;
+  /** CLI executable name used for detection */
+  cliCommand: string;
+  /** Detect whether this host is installed/available */
+  detect(): boolean;
+  /** Install a gxpm command into the host's command system */
+  install(command: CommandDef, projectRoot: string): void;
+  /** Uninstall a command from the host */
+  uninstall(commandName: string, projectRoot: string): void;
+  /** Return the host's preferred command format */
+  preferredFormat(): CommandFormat;
+}
+
+/** Raw host config used for static declarations (before adapter instantiation) */
+export interface HostConfig {
+  name: string;
+  displayName: string;
+  cliCommand: string;
+  hostSubdir: string;
+  globalRoot: string;
+  localSkillRoot: string;
+  usesEnvVars: boolean;
+  frontmatter: {
+    mode: "preserve" | "allowlist";
+    keys?: string[];
+  };
+  install: {
+    strategy: "copy" | "symlink";
+  };
+  hooks?: {
+    configFileName: string;
+    configFormat: "json" | "toml";
+    configPathSegments: string[];
+    featureFlagRequired?: boolean;
+    featureFlagKey?: string;
+    featureFlagSection?: string;
+  };
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@geminix/gxpm",
+  "version": "0.1.0",
+  "description": "Second-generation project management runtime designed to replace PMC and gstack.",
+  "type": "module",
+  "bin": {
+    "gxpm": "./bin/gxpm",
+    "gxpm-config": "./bin/gxpm-config",
+    "gxpm-investigate": "./bin/gxpm-investigate",
+    "gxpm-init": "./bin/gxpm-init",
+    "gxpm-uninstall": "./bin/gxpm-uninstall",
+    "gxpm-update-check": "./bin/gxpm-update-check"
+  },
+  "files": [
+    "bin/",
+    "core/",
+    "scripts/",
+    "hosts/",
+    "skills/",
+    "templates/",
+    "agents/",
+    "docs/",
+    "commands/",
+    "CANON.md",
+    "AGENTS.md",
+    "CONTEXT.md",
+    "CLAUDE.md",
+    "DEBUG.md",
+    "README.md",
+    "ISSUE_CONTEXT.md",
+    "VERSION"
+  ],
+  "scripts": {
+    "check": "bun run scripts/gxpm-check.ts",
+    "dev:skill": "bun run scripts/dev-skill.ts",
+    "gen:skill-docs": "bun run scripts/gen-skill-docs.ts",
+    "sync:markdown": "bun run scripts/sync-markdown-artifacts.ts",
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^6.0.3"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "dependencies": {
+    "playwright": "^1.59.1",
+    "yaml": "^2.8.4",
+    "zod": "^4.4.3"
+  }
+}

package/scripts/browser.ts

@@ -0,0 +1,185 @@
+#!/usr/bin/env bun
+/**
+ * gxpm-browser — minimal headless browser CLI for QA evidence capture.
+ *
+ * Uses Playwright to drive Chromium/Chrome in headless mode.
+ * Screenshots and evidence are written to the gxpm evidence store when
+ * an issue-id is provided.
+ */
+
+import { chromium } from "playwright";
+import { writeFileSync, mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { homedir } from "node:os";
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function usage() {
+  console.log(`gxpm-browser — headless browser for QA evidence
+
+Usage:
+  gxpm-browser navigate <url> [--json]
+  gxpm-browser screenshot <url> [--out <path>] [--full-page] [--json]
+  gxpm-browser assert <url> --selector <css> --text <expected> [--json]
+  gxpm-browser click <url> --selector <css> [--json]
+  gxpm-browser type <url> --selector <css> --text <value> [--json]
+
+Options:
+  --out <path>       Screenshot output path (default: /tmp/gxpm-browser-<ts>.png)
+  --full-page        Capture full page instead of viewport
+  --selector <css>   CSS selector for element interaction
+  --text <value>     Text to assert or type
+  --json             Output JSON
+  --headless         Run headless (default: true)
+  --no-headless      Run headed for debugging
+`);
+}
+
+function parseFlags(argv: string[]) {
+  const flags: Record<string, string | boolean> = {};
+  const positional: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--json") {
+      flags.json = true;
+    } else if (arg === "--full-page") {
+      flags.fullPage = true;
+    } else if (arg === "--headless") {
+      flags.headless = true;
+    } else if (arg === "--no-headless") {
+      flags.headless = false;
+    } else if (arg.startsWith("--")) {
+      const key = arg.replace(/^--/, "").replace(/-/g, "");
+      const next = argv[i + 1];
+      if (next && !next.startsWith("--")) {
+        flags[key] = next;
+        i++;
+      } else {
+        flags[key] = true;
+      }
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { flags, positional };
+}
+
+function output(data: unknown, asJson: boolean) {
+  if (asJson) {
+    console.log(JSON.stringify(data, null, 2));
+  } else {
+    console.log(data);
+  }
+}
+
+function resolveEvidencePath(issueId: string | undefined, label: string): string | undefined {
+  if (!issueId) return undefined;
+  const repoRoot = process.cwd();
+  const evidenceDir = join(repoRoot, ".gxpm", "issues", issueId, "evidence", "browser");
+  mkdirSync(evidenceDir, { recursive: true });
+  const ts = Date.now();
+  const filename = `${label}-${ts}.png`;
+  return join(evidenceDir, filename);
+}
+
+async function run() {
+  if (!command || command === "--help" || command === "-h") {
+    usage();
+    process.exit(0);
+  }
+
+  const { flags, positional } = parseFlags(args.slice(1));
+  const asJson = !!flags.json;
+  const headless = flags.headless !== false;
+  const url = positional[0];
+
+  if (!url) {
+    output({ error: "Missing URL" }, asJson);
+    process.exit(1);
+  }
+
+  const browser = await chromium.launch({
+    headless,
+    executablePath: process.env.GXPM_BROWSER_EXECUTABLE || undefined,
+  });
+
+  const context = await browser.newContext({
+    viewport: { width: 1280, height: 720 },
+  });
+  const page = await context.newPage();
+
+  try {
+    await page.goto(url, { waitUntil: "networkidle" });
+
+    switch (command) {
+      case "navigate": {
+        const title = await page.title();
+        output({ url: page.url(), title }, asJson);
+        break;
+      }
+
+      case "screenshot": {
+        const outPath =
+          (flags.out as string) ||
+          resolveEvidencePath(flags.issueid as string | undefined, "screenshot") ||
+          `/tmp/gxpm-browser-${Date.now()}.png`;
+        const fullPage = !!flags.fullPage;
+        await page.screenshot({ path: outPath, fullPage });
+        output({ screenshot: resolve(outPath), url: page.url(), fullPage }, asJson);
+        break;
+      }
+
+      case "assert": {
+        const selector = flags.selector as string;
+        const expected = flags.text as string;
+        if (!selector || expected === undefined) {
+          output({ error: "Missing --selector or --text" }, asJson);
+          process.exit(1);
+        }
+        const el = await page.locator(selector).first();
+        const text = await el.textContent();
+        const pass = text?.includes(expected) ?? false;
+        output({ pass, expected, actual: text, selector }, asJson);
+        if (!pass) process.exit(1);
+        break;
+      }
+
+      case "click": {
+        const selector = flags.selector as string;
+        if (!selector) {
+          output({ error: "Missing --selector" }, asJson);
+          process.exit(1);
+        }
+        await page.locator(selector).first().click();
+        output({ clicked: selector, url: page.url() }, asJson);
+        break;
+      }
+
+      case "type": {
+        const selector = flags.selector as string;
+        const value = flags.text as string;
+        if (!selector || value === undefined) {
+          output({ error: "Missing --selector or --text" }, asJson);
+          process.exit(1);
+        }
+        await page.locator(selector).first().fill(value);
+        output({ filled: selector, value, url: page.url() }, asJson);
+        break;
+      }
+
+      default: {
+        output({ error: `Unknown command: ${command}` }, asJson);
+        process.exit(1);
+      }
+    }
+  } finally {
+    await context.close();
+    await browser.close();
+  }
+}
+
+run().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});