@geminix/gxpm 0.1.0

package/core/worktree-init.ts

@@ -0,0 +1,330 @@
+/**
+ * WorktreeInitPipeline — pluggable initialization for gxpm-managed worktrees.
+ *
+ * Problem: gxpm creates worktrees via IsolationResolver but only does minimal
+ * post-creation setup (.gxpm symlink, node_modules symlink, owner marker).
+ * Real projects (Gxgen, etc.) need much richer initialization:
+ *   - node_modules overlay mode
+ *   - .env symlinks + .env.local generation
+ *   - multi-service port allocation with occupancy checks
+ *   - warp.md / launch.json generation
+ *   - git hooks, tool indexes, baseline freshness checks
+ *
+ * Solution: a configurable pipeline of InitSteps. Projects opt-in via
+ * `.gxpm/config.json` `worktree.initSteps`. Each step is self-contained,
+ * reads its own configuration from the gxpm config registry, and reports
+ * warnings/errors without blocking the pipeline unless configured to do so.
+ */
+
+import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { getResolvedConfigValue } from "./config";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface PortAllocation {
+  slot: number;
+  webPort: number;
+  serverPort: number;
+  studioPort: number;
+  queuePrefix: string;
+}
+
+export interface WorktreeInitContext {
+  /** Absolute path to the canonical (main) repo checkout. */
+  canonicalRepoPath: string;
+  /** Absolute path to the worktree being initialized. */
+  worktreePath: string;
+  /** Git branch name for the worktree. */
+  branchName: string;
+  /** gxpm issue id. */
+  issueId: string;
+  /** Base branch used to create the worktree (if known). */
+  baseBranch?: string;
+  /** Base commit SHA used to create the worktree (if known). */
+  baseSha?: string;
+  /** Populated by the port-allocation step for downstream consumers. */
+  ports?: PortAllocation;
+}
+
+export interface WorktreeInitStepResult {
+  ok: boolean;
+  warnings?: string[];
+  error?: string;
+}
+
+export interface WorktreeInitStep {
+  name: string;
+  run(ctx: WorktreeInitContext): Promise<WorktreeInitStepResult> | WorktreeInitStepResult;
+}
+
+export interface WorktreeInitPipelineResult {
+  ok: boolean;
+  warnings: string[];
+  errors: string[];
+  stepsRun: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Pipeline
+// ---------------------------------------------------------------------------
+
+export class WorktreeInitPipeline {
+  private steps: WorktreeInitStep[] = [];
+
+  add(step: WorktreeInitStep): this {
+    this.steps.push(step);
+    return this;
+  }
+
+  async run(ctx: WorktreeInitContext): Promise<WorktreeInitPipelineResult> {
+    const warnings: string[] = [];
+    const errors: string[] = [];
+    const stepsRun: string[] = [];
+
+    for (const step of this.steps) {
+      try {
+        const result = await step.run(ctx);
+        stepsRun.push(step.name);
+        if (result.warnings) warnings.push(...result.warnings);
+        if (!result.ok) {
+          if (result.error) errors.push(`[${step.name}] ${result.error}`);
+          else errors.push(`[${step.name}] failed`);
+        }
+      } catch (err) {
+        stepsRun.push(step.name);
+        const message = err instanceof Error ? err.message : String(err);
+        errors.push(`[${step.name}] ${message}`);
+      }
+    }
+
+    return { ok: errors.length === 0, warnings, errors, stepsRun };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Built-in step registry
+// ---------------------------------------------------------------------------
+
+const BUILTIN_STEPS: Record<string, (() => WorktreeInitStep) | WorktreeInitStep> = {};
+
+export function registerBuiltinStep(name: string, step: (() => WorktreeInitStep) | WorktreeInitStep): void {
+  BUILTIN_STEPS[name] = step;
+}
+
+export function getBuiltinStepNames(): string[] {
+  return Object.keys(BUILTIN_STEPS);
+}
+
+export function resolveStep(name: string): WorktreeInitStep | undefined {
+  const entry = BUILTIN_STEPS[name];
+  if (!entry) return undefined;
+  return typeof entry === "function" ? entry() : entry;
+}
+
+// ---------------------------------------------------------------------------
+// Pipeline factory
+// ---------------------------------------------------------------------------
+
+export interface CreatePipelineInput {
+  /** Explicit step names; if omitted reads from config. */
+  steps?: string[];
+  root?: string;
+}
+
+export function createPipeline(input: CreatePipelineInput = {}): WorktreeInitPipeline {
+  const root = input.root ?? process.cwd();
+  const stepNames =
+    input.steps ??
+    (() => {
+      const cfg = getResolvedConfigValue({ root, key: "worktree.initSteps" });
+      return Array.isArray(cfg.value) ? (cfg.value as string[]) : ["owner-marker", "issue-context"];
+    })();
+
+  const pipeline = new WorktreeInitPipeline();
+  for (const name of stepNames) {
+    const step = resolveStep(name);
+    if (step) {
+      pipeline.add(step);
+    } else {
+      // Unknown step: inject a no-op that warns
+      pipeline.add({
+        name: `unknown:${name}`,
+        run: () => ({
+          ok: false,
+          warnings: [`Unknown worktree init step "${name}". Available: ${getBuiltinStepNames().join(", ")}`],
+        }),
+      });
+    }
+  }
+  return pipeline;
+}
+
+// ---------------------------------------------------------------------------
+// High-level runner
+// ---------------------------------------------------------------------------
+
+export async function runWorktreeInit(
+  ctx: WorktreeInitContext,
+  input?: CreatePipelineInput,
+): Promise<WorktreeInitPipelineResult> {
+  const pipeline = createPipeline(input);
+  return pipeline.run(ctx);
+}
+
+// ---------------------------------------------------------------------------
+// Shared helpers used by multiple steps
+// ---------------------------------------------------------------------------
+
+export function ensureSymlink(src: string, dst: string): { ok: boolean; warning?: string } {
+  if (resolve(src) === resolve(dst)) return { ok: true };
+
+  if (existsSync(dst)) {
+    const stat = lstatSync(dst);
+    if (stat.isSymbolicLink()) {
+      try {
+        const current = readlinkSync(dst);
+        if (resolve(dst, current) === resolve(src) || realpathSync(resolve(dst, current)) === realpathSync(src)) {
+          return { ok: true };
+        }
+        rmSync(dst, { force: true });
+      } catch {
+        rmSync(dst, { force: true });
+      }
+    } else {
+      return { ok: false, warning: `overlay conflict: ${dst} exists as real file/directory; skipped` };
+    }
+  }
+
+  mkdirSync(dirname(dst), { recursive: true });
+  symlinkSync(src, dst, "dir");
+  return { ok: true };
+}
+
+export function setEnvVar(filePath: string, key: string, value: string): void {
+  mkdirSync(dirname(filePath), { recursive: true });
+  let content = "";
+  try {
+    content = readFileSync(filePath, "utf8");
+  } catch {
+    // file does not exist yet
+  }
+
+  const lines = content.split("\n");
+  let found = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.startsWith(`${key}=`)) {
+      lines[i] = `${key}=${value}`;
+      found = true;
+      break;
+    }
+  }
+  if (!found) {
+    lines.push(`${key}=${value}`);
+  }
+  writeFileSync(filePath, lines.join("\n").replace(/\n+$/, "") + "\n");
+}
+
+export function readEnvFile(path: string): Record<string, string> {
+  const result: Record<string, string> = {};
+  if (!existsSync(path)) return result;
+  const content = readFileSync(path, "utf8");
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq === -1) continue;
+    result[trimmed.slice(0, eq)] = trimmed.slice(eq + 1);
+  }
+  return result;
+}
+
+export function safeWorktreeSlug(raw: string): string {
+  let slug = raw
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .replace(/_+/g, "_")
+    .slice(0, 48);
+  if (!slug) {
+    slug = String(createHash("sha256").update(raw).digest("hex").slice(0, 8));
+  }
+  return slug;
+}
+
+export function hashSlot(input: string, maxSlot: number): number {
+  const hash = createHash("sha256").update(input).digest();
+  return (hash.readUInt32BE(0) % maxSlot) + 1; // 1-based
+}
+
+export function checkPortAvailable(port: number, worktreePath: string): boolean {
+  try {
+    const result = Bun.spawnSync({
+      cmd: ["lsof", "-nP", "-iTCP:" + String(port), "-sTCP:LISTEN"],
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    if (result.exitCode !== 0) return true; // lsof found nothing
+
+    const output = result.stdout.toString().trim();
+    if (!output) return true;
+
+    // Parse PIDs and check if they belong to this worktree
+    const lines = output.split("\n").slice(1); // skip header
+    for (const line of lines) {
+      const pid = line.trim().split(/\s+/)[1];
+      if (!pid) continue;
+      try {
+        const cwdResult = Bun.spawnSync({
+          cmd: ["lsof", "-a", "-p", pid, "-d", "cwd", "-Fn"],
+          stdout: "pipe",
+          stderr: "pipe",
+        });
+        if (cwdResult.exitCode === 0) {
+          const cwdLine = cwdResult.stdout.toString().split("\n").find((l) => l.startsWith("n"));
+          const cwd = cwdLine ? cwdLine.slice(1) : "";
+          if (cwd === worktreePath || cwd.startsWith(worktreePath + "/")) {
+            continue; // belongs to this worktree, that's fine
+          }
+        }
+      } catch {
+        // ignore lsof failure
+      }
+      return false; // someone else owns this port
+    }
+    return true;
+  } catch {
+    // lsof not available → assume available (best-effort)
+    return true;
+  }
+}
+
+export function appendGitExcludeEntry(repoRoot: string, entry: string): void {
+  try {
+    const result = Bun.spawnSync({
+      cmd: ["git", "rev-parse", "--git-path", "info/exclude"],
+      cwd: repoRoot,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    if (result.exitCode !== 0) return;
+    const excludeFile = result.stdout.toString().trim();
+    if (!excludeFile) return;
+    mkdirSync(dirname(excludeFile), { recursive: true });
+    let content = "";
+    try {
+      content = readFileSync(excludeFile, "utf8");
+    } catch {
+      // file may not exist
+    }
+    if (!content.split("\n").includes(entry)) {
+      writeFileSync(excludeFile, (content ? content.replace(/\n+$/, "") + "\n" : "") + entry + "\n");
+    }
+  } catch {
+    // best-effort
+  }
+}

package/core/worktree-owner.ts

@@ -0,0 +1,143 @@
+/**
+ * Worktree owner marker and passive context recovery.
+ *
+ * Problem: After multi-turn context compaction, an AI agent may forget the
+ * current issue and worktree. These files let the agent recover passively
+ * from the filesystem without needing to remember the issue id.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export interface WorktreeOwner {
+  ownerIssueId: string;
+  linkedIssues: string[];
+  createdAt: string;
+  /** Current issue phase (v2) */
+  currentPhase?: string;
+  /** Issue title or checkpoint title (v2) */
+  title?: string;
+  /** Last update timestamp (v2) */
+  updatedAt?: string;
+  /** Git branch name (v2) */
+  branchName?: string;
+  /** Absolute workspace path (v2) */
+  workspacePath?: string;
+}
+
+export function readWorktreeOwner(cwd: string): WorktreeOwner | null {
+  try {
+    const path = join(cwd, ".gxpm-worktree-owner.json");
+    if (!existsSync(path)) return null;
+    const raw = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
+    const ownerIssueId = typeof raw.ownerIssueId === "string" ? raw.ownerIssueId : "";
+    const linkedIssues = Array.isArray(raw.linkedIssues)
+      ? raw.linkedIssues.filter((item): item is string => typeof item === "string")
+      : [];
+    const createdAt = typeof raw.createdAt === "string" ? raw.createdAt : "";
+    if (!ownerIssueId || !createdAt) return null;
+    return {
+      ownerIssueId,
+      linkedIssues,
+      createdAt,
+      currentPhase: typeof raw.currentPhase === "string" ? raw.currentPhase : undefined,
+      title: typeof raw.title === "string" ? raw.title : undefined,
+      updatedAt: typeof raw.updatedAt === "string" ? raw.updatedAt : undefined,
+      branchName: typeof raw.branchName === "string" ? raw.branchName : undefined,
+      workspacePath: typeof raw.workspacePath === "string" ? raw.workspacePath : undefined,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function writeWorktreeOwnerMarker(
+  workspacePath: string,
+  marker: Omit<WorktreeOwner, "createdAt"> & Partial<Pick<WorktreeOwner, "createdAt">>,
+): void {
+  const fullMarker: WorktreeOwner = {
+    linkedIssues: marker.linkedIssues,
+    createdAt: marker.createdAt ?? new Date().toISOString(),
+    ownerIssueId: marker.ownerIssueId,
+    currentPhase: marker.currentPhase,
+    title: marker.title,
+    updatedAt: marker.updatedAt ?? new Date().toISOString(),
+    branchName: marker.branchName,
+    workspacePath: marker.workspacePath,
+  };
+  writeFileSync(
+    join(workspacePath, ".gxpm-worktree-owner.json"),
+    `${JSON.stringify(fullMarker, null, 2)}\n`,
+  );
+}
+
+export interface IssueContextMdData {
+  issueId: string;
+  title?: string;
+  currentPhase: string;
+  nextPhase?: string;
+  branchName?: string;
+  workspacePath: string;
+  updatedAt: string;
+  resumeHint?: string;
+}
+
+export function writeIssueContextMd(workspacePath: string, data: IssueContextMdData): void {
+  const lines: string[] = [
+    `# ISSUE_CONTEXT — ${data.issueId}`,
+    ``,
+    `> 这是 gxpm 自动生成的上下文恢复文件。`,
+    `> 如果 AI 代理忘记了当前正在处理的 issue，请阅读此文件。`,
+    ``,
+    `- **Issue ID**: \`${data.issueId}\``,
+    `- **当前阶段**: \`${data.currentPhase}\``,
+  ];
+  if (data.title) {
+    lines.push(`- **标题**: ${data.title}`);
+  }
+  if (data.branchName) {
+    lines.push(`- **分支**: \`${data.branchName}\``);
+  }
+  lines.push(`- **工作目录**: \`${data.workspacePath}\``);
+  lines.push(`- **更新时间**: ${data.updatedAt}`);
+  lines.push(``);
+  lines.push(`## 快速恢复`);
+  lines.push(``);
+  lines.push(`如果你忘记了当前 issue，运行以下命令恢复上下文：`);
+  lines.push(``);
+  lines.push(`\`\`\`bash`);
+  lines.push(`gxpm issue context --auto`);
+  lines.push(`\`\`\``);
+  lines.push(``);
+  if (data.nextPhase) {
+    lines.push(`## 下一步`);
+    lines.push(``);
+    lines.push(`下一阶段: \`${data.nextPhase}\``);
+    lines.push(``);
+  }
+  if (data.resumeHint) {
+    lines.push(`## 续做提示`);
+    lines.push(``);
+    lines.push(data.resumeHint);
+    lines.push(``);
+  }
+  lines.push(`---`);
+  lines.push(`*此文件由 gxpm 自动生成，请勿手动编辑。*`);
+
+  writeFileSync(join(workspacePath, "ISSUE_CONTEXT.md"), lines.join("\n") + "\n");
+}
+
+export function removeIssueContextMd(workspacePath: string): void {
+  try {
+    const path = join(workspacePath, "ISSUE_CONTEXT.md");
+    if (existsSync(path)) {
+      // Leave the file but mark it as stale so the agent doesn't trust it
+      const content = readFileSync(path, "utf8");
+      if (!content.includes("[STALE]")) {
+        writeFileSync(path, `# [STALE] ${content.replace(/^# /, "")}`, "utf8");
+      }
+    }
+  } catch {
+    // best-effort
+  }
+}

package/docs/GXPM_VERIFY.md

@@ -0,0 +1,98 @@
+# GXPM Verification Checklist
+
+Run these checks after installing or upgrading gxpm to confirm everything works.
+
+## Check #1: Runtime
+
+```bash
+gxpm doctor --json
+```
+
+Expected: `status` is `healthy` or `warnings`. `health_score` >= 80.
+
+If `status` is `error`, run `gxpm doctor --fix` and retry.
+
+## Check #2: CLI Commands
+
+```bash
+gxpm --version
+gxpm config list
+gxpm session-id
+```
+
+All should return valid output without error.
+
+## Check #3: Git Hooks
+
+Make any commit in a repo where gxpm hooks are installed:
+
+```bash
+git commit --allow-empty -m "test: verify gxpm hooks"
+```
+
+The commit should succeed. If pre-commit fails, check `.githooks/gxpm-pre-commit` output.
+
+## Check #4: Issue Lifecycle
+
+```bash
+gxpm issue create --auto-id
+```
+
+Note the created issue ID (e.g., `GXPM-123`). Then:
+
+```bash
+gxpm issue transition GXPM-123 plan
+gxpm issue transition GXPM-123 dispatch
+gxpm issue transition GXPM-123 implement
+```
+
+Each transition should succeed. Inspect `.gxpm/issues/GXPM-123/state.json` to confirm phase progression.
+
+## Check #5: Worktree (if worktree.enforcement != forbidden)
+
+```bash
+git worktree add ../test-worktree main
+```
+
+Should succeed. Clean up:
+
+```bash
+git worktree remove ../test-worktree
+```
+
+## Check #6: Linear Sync (if configured)
+
+If `sync.provider` is `linear`:
+
+```bash
+gxpm doctor --json | jq '.checks[] | select(.name=="linear_connectivity")'
+```
+
+Expected: `status: "ok"`. If `warn`, check `LINEAR_API_KEY` env var.
+
+Create an issue and confirm it appears in Linear (may take a few seconds):
+
+```bash
+gxpm issue create --auto-id
+gxpm issue sync <id>
+```
+
+## Check #7: Skill Host Discovery
+
+```bash
+gxpm doctor --json | jq '.checks[] | select(.name=="skill_installation")'
+```
+
+Expected: `status: "ok"`. If `warn`, run:
+
+```bash
+gxpm init --install-skill --host all
+```
+
+## One-Command Smoke Test
+
+```bash
+gxpm verify
+```
+
+This runs all checks above (except Check #6 which requires manual confirmation in Linear UI). Result should be `passed`.

package/docs/INSTALL_FOR_AGENTS.md

@@ -0,0 +1,113 @@
+# gxpm Installation Guide for AI Agents
+
+Read this entire file, then follow the steps. Target: ~10 minutes to a fully working project management runtime.
+
+## Step 0: If you are not Claude Code
+
+Read `AGENTS.md` at the repo root first. It's the non-Claude-agent operating protocol (install, read order, trust boundary, common tasks). Claude Code reads `CLAUDE.md` automatically and can skip ahead.
+
+If you fetched this file by URL without cloning yet, the companion files live at:
+- `https://raw.githubusercontent.com/laozhong86/gxpm/main/AGENTS.md` — start here
+- `https://raw.githubusercontent.com/laozhong86/gxpm/main/CONTEXT.md` — shared language / glossary
+
+## Step 1: Install gxpm
+
+```bash
+git clone https://github.com/laozhong86/gxpm.git ~/gxpm && cd ~/gxpm
+curl -fsSL https://bun.sh/install | bash
+export PATH="$HOME/.bun/bin:$PATH"
+bun install && bun link
+```
+
+Verify: `gxpm --version` should print a version number. If `gxpm` is not found, restart the shell or add the PATH export to the shell profile.
+
+## Step 2: Initialize a Project
+
+Navigate to the project you want to manage with gxpm (or stay in `~/gxpm` to manage gxpm itself):
+
+```bash
+cd /path/to/your/project
+gxpm init
+```
+
+This will:
+1. Create `.gxpm/` directory structure
+2. Install git hooks (pre-commit, commit-msg, pre-push, post-merge, post-checkout)
+3. Install Codex hooks (if `.codex/` detected)
+4. Install gxpm skills to all detected host adapters (Claude, Codex, Cursor)
+5. Initialize `.gxpm/config.json` with sensible defaults
+
+For non-interactive / CI mode:
+```bash
+gxpm init --non-interactive --target /path/to/project
+```
+
+## Step 3: Configure
+
+Review and adjust configuration:
+
+```bash
+gxpm config list
+```
+
+Key settings to consider:
+- `sync.provider`: `linear`, `github`, or `none`
+- `sync.linearTeamId` / `sync.linearTeamKey`: if using Linear
+- `worktree.enforcement`: `optional` (default), `required`, or `forbidden`
+
+Set via:
+```bash
+gxpm config set sync.provider linear
+gxpm config set sync.linearTeamId your-team-uuid --global
+```
+
+## Step 4: Verify
+
+Run the verification suite:
+
+```bash
+gxpm doctor --json
+gxpm verify
+```
+
+All checks should pass. If any fail, follow the remediation hints printed.
+
+## Step 5: Create Your First Issue
+
+```bash
+gxpm issue create --auto-id
+```
+
+Follow the triage flow. The issue state will be persisted under `.gxpm/issues/<id>/`.
+
+## Step 6: Load Skills
+
+Read `skills/gxpm/SKILL.md`. This is the skill dispatcher. It tells you which skill to read for any task. Save this to your memory permanently.
+
+The three most important skills to adopt immediately:
+
+1. **gxpm-triage** — intake and classify incoming work
+2. **gxpm-planning** — scope confirmation and implementation planning
+3. **gxpm** — master dispatch for issue lifecycle, phase gates, and artifact management
+
+## Step 7: Recurring Jobs
+
+Set up using your platform's scheduler:
+
+- **Auto-update check** (daily): `gxpm-update-check` (tell user, never auto-install)
+- **Weekly health check**: `gxpm doctor --json && gxpm verify`
+
+## Upgrade
+
+```bash
+cd ~/gxpm && git pull origin main && bun install
+gxpm upgrade
+```
+
+Then read `docs/migrations/v*.md` for any versions you skipped and run any backfill steps listed.
+
+## Troubleshooting
+
+- `gxpm doctor --fix` auto-repairs common issues (missing hooks, stale skill docs)
+- `gxpm doctor --json` gives machine-readable output for agent consumption
+- Read `docs/GXPM_VERIFY.md` for the full verification checklist