@geminix/gxpm 0.1.0

package/scripts/skill-naming-check.ts

@@ -0,0 +1,78 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const DEFAULT_GXPM_ROOT = resolve(import.meta.dir, "..");
+
+export interface SkillNamingCheckOptions {
+  root?: string;
+}
+
+export function validateSkillNaming(options: SkillNamingCheckOptions = {}): string[] {
+  const root = options.root ?? DEFAULT_GXPM_ROOT;
+  const skillsDir = join(root, "skills");
+  const errors: string[] = [];
+
+  if (!existsSync(skillsDir) || !statSync(skillsDir).isDirectory()) {
+    return [`skills directory not found: ${skillsDir}`];
+  }
+
+  const entries = readdirSync(skillsDir);
+  for (const entry of entries) {
+    const entryPath = join(skillsDir, entry);
+    if (!statSync(entryPath).isDirectory()) continue;
+    if (entry.startsWith(".")) continue;
+
+    const isGxpmSkill = entry === "gxpm" || entry.startsWith("gxpm-");
+
+    if (!isGxpmSkill) {
+      console.warn(`[skill-naming] warning: skill "${entry}" does not use gxpm- prefix (recommended for gxpm official skills)`);
+      continue;
+    }
+
+    const skillMdPath = join(entryPath, "SKILL.md");
+    const skillTmplPath = join(entryPath, "SKILL.md.tmpl");
+
+    let sourcePath: string | null = null;
+    if (existsSync(skillTmplPath)) {
+      sourcePath = skillTmplPath;
+    } else if (existsSync(skillMdPath)) {
+      sourcePath = skillMdPath;
+    }
+
+    if (!sourcePath) {
+      errors.push(`skill "${entry}" missing SKILL.md or SKILL.md.tmpl`);
+      continue;
+    }
+
+    const content = readFileSync(sourcePath, "utf8");
+    if (!content.startsWith("---")) {
+      errors.push(`skill "${entry}" frontmatter missing`);
+      continue;
+    }
+
+    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!frontmatterMatch) {
+      errors.push(`skill "${entry}" frontmatter malformed`);
+      continue;
+    }
+
+    const frontmatter = frontmatterMatch[1];
+    if (!frontmatter.includes("name:")) {
+      errors.push(`skill "${entry}" frontmatter missing name`);
+    }
+    if (!frontmatter.includes("description:")) {
+      errors.push(`skill "${entry}" frontmatter missing description`);
+    }
+  }
+
+  return errors;
+}
+
+if (import.meta.main) {
+  const errors = validateSkillNaming();
+  if (errors.length > 0) {
+    console.error(errors.map((error) => `skill-naming: ${error}`).join("\n"));
+    process.exit(1);
+  }
+  console.log("skill naming check passed");
+}

package/scripts/skill-structure-check.ts

@@ -0,0 +1,157 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+
+export interface SkillStructureViolation {
+  skillPath: string;
+  missing: string[];
+  warnings: string[];
+}
+
+const REQUIRED_SECTIONS = [
+  {
+    id: "entry",
+    names: ["入口条件", "入口", "触发条件", "Entry Conditions", "When to Use", "Recognition criteria"],
+    label: "入口条件 (Entry Conditions)",
+  },
+  {
+    id: "process",
+    names: ["可操作流程", "流程", "操作步骤", "Process", "Steps", "Workflow"],
+    label: "可操作流程 (Process)",
+  },
+  {
+    id: "redflags",
+    names: ["红旗清单", "红旗", "反模式", "常见陷阱", "Red Flags", "Anti-Patterns", "Pitfalls"],
+    label: "红旗/反模式 (Red Flags)",
+  },
+  {
+    id: "verification",
+    names: ["验证清单", "出口条件", "验证", "Checklist", "Verification", "Exit Conditions"],
+    label: "验证清单/出口条件 (Verification)",
+  },
+];
+
+const OPTIONAL_SECTIONS = [
+  {
+    id: "phrases",
+    names: ["常见说辞表", "说辞", "Phrases", "Common Phrases"],
+    label: "常见说辞表 (Common Phrases)",
+  },
+];
+
+function hasSection(content: string, names: string[]): boolean {
+  const pattern = new RegExp(
+    `^#{2,3}\\s*(?:\\[[ x]\\]\\s*)?(${names.map((n) => n.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})`,
+    "im",
+  );
+  return pattern.test(content);
+}
+
+function walkDir(dir: string, callback: (path: string) => void) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory() && !entry.name.startsWith(".")) {
+      walkDir(fullPath, callback);
+    } else if (entry.isFile()) {
+      callback(fullPath);
+    }
+  }
+}
+
+export function validateSkillStructure(root: string): SkillStructureViolation[] {
+  const violations: SkillStructureViolation[] = [];
+  const skillsDir = join(root, "skills");
+
+  if (!existsSync(skillsDir)) {
+    return [{ skillPath: "skills/", missing: ["skills directory not found"], warnings: [] }];
+  }
+
+  walkDir(skillsDir, (fullPath: string) => {
+    if (!fullPath.endsWith("SKILL.md")) return;
+    const content = readFileSync(fullPath, "utf-8");
+    const relPath = relative(root, fullPath);
+    const missing: string[] = [];
+    const warnings: string[] = [];
+
+    for (const section of REQUIRED_SECTIONS) {
+      if (!hasSection(content, section.names)) {
+        missing.push(section.label);
+      }
+    }
+
+    for (const section of OPTIONAL_SECTIONS) {
+      if (!hasSection(content, section.names)) {
+        warnings.push(`可选: ${section.label}`);
+      }
+    }
+
+    // Gatekeeping skills (workflow/verify/ship) should have phrases
+    if (/\b(triage|plan|verify|review|ship|debug|diagnose|hygiene)\b/.test(relPath)) {
+      if (!hasSection(content, OPTIONAL_SECTIONS[0].names)) {
+        warnings.push(`建议补充: ${OPTIONAL_SECTIONS[0].label} (此 skill 涉及 gatekeeping 或交互)`);
+      }
+    }
+
+    if (missing.length > 0 || warnings.length > 0) {
+      violations.push({ skillPath: relPath, missing, warnings });
+    }
+  });
+
+  return violations;
+}
+
+export function formatSkillStructureErrors(violations: SkillStructureViolation[]): { errors: string[]; warnings: string[] } {
+  if (violations.length === 0) return { errors: [], warnings: [] };
+
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  const missingOnly = violations.filter((v) => v.missing.length > 0);
+  const warningOnly = violations.filter((v) => v.missing.length === 0 && v.warnings.length > 0);
+
+  if (missingOnly.length > 0) {
+    errors.push(`SKILL.md structure violations found: ${missingOnly.length} skill(s) missing required sections`);
+    for (const v of missingOnly) {
+      errors.push(`\n  ${v.skillPath}:`);
+      for (const m of v.missing) {
+        errors.push(`    ❌ MISSING: ${m}`);
+      }
+      for (const w of v.warnings) {
+        errors.push(`    ⚠️  ${w}`);
+      }
+    }
+  }
+
+  if (warningOnly.length > 0) {
+    warnings.push(`SKILL.md structure warnings: ${warningOnly.length} skill(s) with optional section gaps`);
+    for (const v of warningOnly) {
+      warnings.push(`\n  ${v.skillPath}:`);
+      for (const w of v.warnings) {
+        warnings.push(`    ⚠️  ${w}`);
+      }
+    }
+  }
+
+  const guide = [
+    "\nEach SKILL.md must contain these sections (## or ### heading):",
+    "  1. 入口条件 / Entry Conditions / Recognition criteria / When to Use",
+    "  2. 可操作流程 / Process / Steps / Workflow",
+    "  3. 红旗清单 / 反模式 / Red Flags / Anti-Patterns / Pitfalls",
+    "  4. 验证清单 / 出口条件 / Verification / Checklist",
+    "Optional but recommended for gatekeeping skills:",
+    "  5. 常见说辞表 / Common Phrases",
+  ];
+
+  return {
+    errors: errors.length > 0 ? [...errors, ...guide] : [],
+    warnings: warnings.length > 0 ? [...warnings, ...guide] : [],
+  };
+}
+
+if (import.meta.main) {
+  const root = process.argv[2] ?? resolve(import.meta.dir, "..");
+  const violations = validateSkillStructure(root);
+  if (violations.length > 0) {
+    console.error(formatSkillStructureErrors(violations).join("\n"));
+    process.exit(1);
+  }
+  console.log("All SKILL.md files conform to the five-section structure.");
+}

package/scripts/skills-lock-check.ts

@@ -0,0 +1,60 @@
+import { createHash } from "node:crypto";
+import { readFileSync, existsSync, readdirSync } from "node:fs";
+import { resolve } from "node:path";
+
+interface SkillsLock {
+  version: number;
+  skills: Record<string, string>;
+}
+
+export function validateSkillsLock(options: { root?: string } = {}): string[] {
+  const root = options.root ?? resolve(import.meta.dir, "..");
+  const lockPath = resolve(root, "skills-lock.json");
+  const skillsDir = resolve(root, "skills");
+
+  if (!existsSync(lockPath)) {
+    return ["skills-lock.json not found"];
+  }
+
+  let lock: SkillsLock;
+  try {
+    lock = JSON.parse(readFileSync(lockPath, "utf8")) as SkillsLock;
+  } catch {
+    return ["skills-lock.json is not valid JSON"];
+  }
+
+  if (lock.version !== 1) {
+    return [`skills-lock.json version ${lock.version} is not supported`];
+  }
+
+  const errors: string[] = [];
+  const expectedSkills = new Set(Object.keys(lock.skills));
+
+  for (const [skillName, expectedHash] of Object.entries(lock.skills)) {
+    const skillPath = resolve(skillsDir, skillName, "SKILL.md");
+    if (!existsSync(skillPath)) {
+      errors.push(`skill ${skillName}: SKILL.md missing`);
+      continue;
+    }
+    const content = readFileSync(skillPath);
+    const actualHash = createHash("sha256").update(content).digest("hex");
+    if (actualHash !== expectedHash) {
+      errors.push(`skill ${skillName}: hash mismatch (expected ${expectedHash}, got ${actualHash})`);
+    }
+  }
+
+  // Check for unlisted skills
+  if (existsSync(skillsDir)) {
+    const entries = readdirSync(skillsDir, { withFileTypes: true }) as unknown as { name: string; isDirectory: () => boolean }[];
+    for (const entry of entries) {
+      if (entry.isDirectory() && !expectedSkills.has(entry.name)) {
+        const skillPath = resolve(skillsDir, entry.name, "SKILL.md");
+        if (existsSync(skillPath)) {
+          errors.push(`skill ${entry.name}: not listed in skills-lock.json`);
+        }
+      }
+    }
+  }
+
+  return errors;
+}

package/scripts/sync-markdown-artifacts.ts

@@ -0,0 +1,172 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+interface StoredArtifact {
+  schemaVersion: 1;
+  issueId: string;
+  type: string;
+  writtenAt: string;
+  payload: unknown;
+}
+
+const ARTIFACT_TO_MARKDOWN: Record<string, string> = {
+  "acceptance-contract": "01-spec.md",
+  "implementation-plan": "03-plan.md",
+  "self-review": "04-review.md",
+  "ship-readiness": "05-ship.md",
+  "pr-check": "05-ship.md",
+  "verify-findings": "05-ship.md",
+  "qa-findings": "05-ship.md",
+  "land-findings": "05-ship.md",
+};
+
+function artifactToMarkdown(artifact: StoredArtifact): string {
+  const { type, writtenAt, payload } = artifact;
+  const p = payload as Record<string, unknown>;
+
+  const lines: string[] = [];
+  lines.push(`# ${type}`);
+  lines.push("");
+  lines.push(`> Artifact type: \`${type}\``);
+  lines.push(`> Written at: ${writtenAt}`);
+  lines.push("");
+
+  if (type === "acceptance-contract") {
+    lines.push(`## Goal`);
+    lines.push(String(p.goal ?? "N/A"));
+    lines.push("");
+    lines.push(`## Scope`);
+    lines.push(String(p.scope ?? "N/A"));
+    lines.push("");
+    lines.push(`## Non-Goals`);
+    lines.push(String(p.nonGoals ?? "N/A"));
+    lines.push("");
+    lines.push(`## Success Criteria`);
+    lines.push(String(p.successCriteria ?? "N/A"));
+    lines.push("");
+    lines.push(`## Risks`);
+    lines.push(String(p.risks ?? "N/A"));
+  } else if (type === "implementation-plan") {
+    lines.push(`## Objective`);
+    lines.push(String(p.objective ?? "N/A"));
+    lines.push("");
+    lines.push(`## Scope`);
+    lines.push(String(p.scope ?? "N/A"));
+    lines.push("");
+    lines.push(`## Constitution Check`);
+    const cc = p.constitutionCheck as Record<string, unknown> | undefined;
+    if (cc) {
+      for (const [k, v] of Object.entries(cc)) {
+        lines.push(`- ${k}: ${v}`);
+      }
+    }
+    lines.push("");
+    lines.push(`## Steps`);
+    const steps = p.steps as Array<Record<string, unknown>> | undefined;
+    if (steps) {
+      for (const step of steps) {
+        lines.push(`### ${step.id ?? "?"}: ${step.title ?? "?"}`);
+        lines.push(String(step.description ?? ""));
+        lines.push("");
+        lines.push(`**Acceptance Criteria:** ${step.acceptanceCriteria ?? "N/A"}`);
+        lines.push("");
+      }
+    }
+  } else if (type === "self-review") {
+    lines.push(`## Blocking`);
+    const blocking = p.blocking as string[] | undefined;
+    lines.push(blocking && blocking.length > 0 ? blocking.map((b) => `- ${b}`).join("\n") : "None");
+    lines.push("");
+    lines.push(`## Important`);
+    const important = p.important as string[] | undefined;
+    lines.push(important && important.length > 0 ? important.map((b) => `- ${b}`).join("\n") : "None");
+    lines.push("");
+    lines.push(`## Suggestions`);
+    const suggestions = p.suggestions as string[] | undefined;
+    lines.push(suggestions && suggestions.length > 0 ? suggestions.map((b) => `- ${b}`).join("\n") : "None");
+    lines.push("");
+    lines.push(`## Conclusion`);
+    lines.push(String(p.conclusion ?? "N/A"));
+  } else if (type === "ship-readiness") {
+    lines.push(`## Ready`);
+    lines.push(String(p.ready ?? "N/A"));
+    lines.push("");
+    lines.push(`## Ship Type`);
+    lines.push(String(p.shipType ?? "N/A"));
+    lines.push("");
+    lines.push(`## Changes`);
+    lines.push(String(p.changes ?? "N/A"));
+    lines.push("");
+    lines.push(`## Risk`);
+    lines.push(String(p.risk ?? "N/A"));
+    lines.push("");
+    lines.push(`## Rollback`);
+    lines.push(String(p.rollback ?? "N/A"));
+  } else {
+    lines.push("## Payload");
+    lines.push("```json");
+    lines.push(JSON.stringify(payload, null, 2));
+    lines.push("```");
+  }
+
+  return lines.join("\n") + "\n";
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const issueId = args[0];
+  if (!issueId) {
+    console.error("Usage: bun run scripts/sync-markdown-artifacts.ts <issue-id>");
+    process.exit(1);
+  }
+
+  const root = process.cwd();
+  const artifactsDir = join(root, ".gxpm", "issues", issueId, "artifacts");
+  const docsDir = join(root, ".gxpm", "issues", issueId, "docs");
+
+  if (!existsSync(artifactsDir)) {
+    console.error(`Artifacts directory not found: ${artifactsDir}`);
+    process.exit(1);
+  }
+
+  mkdirSync(docsDir, { recursive: true });
+
+  const artifacts = readdirSync(artifactsDir)
+    .filter((f) => f.endsWith(".json"))
+    .map((f) => {
+      const content = readFileSync(join(artifactsDir, f), "utf8");
+      return JSON.parse(content) as StoredArtifact;
+    });
+
+  const written: string[] = [];
+  for (const artifact of artifacts) {
+    const mdFile = ARTIFACT_TO_MARKDOWN[artifact.type];
+    if (!mdFile) continue;
+
+    const mdPath = join(docsDir, mdFile);
+    const mdContent = artifactToMarkdown(artifact);
+
+    // Append with separator if file already exists for multi-artifact types like 05-ship.md
+    if (existsSync(mdPath)) {
+      const existing = readFileSync(mdPath, "utf8");
+      writeFileSync(mdPath, existing + "\n---\n\n" + mdContent);
+    } else {
+      writeFileSync(mdPath, mdContent);
+    }
+    written.push(`${artifact.type} → docs/${mdFile}`);
+  }
+
+  if (written.length === 0) {
+    console.log("No markdown-mappable artifacts found.");
+    return;
+  }
+
+  console.log(`Synced ${written.length} artifacts to markdown for ${issueId}:`);
+  for (const line of written) {
+    console.log(`  ${line}`);
+  }
+}
+
+
+
+main();

package/scripts/uninstall.ts

@@ -0,0 +1,162 @@
+import { existsSync, lstatSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+interface UninstallOptions {
+  target?: string;
+  home?: string;
+  dryRun?: boolean;
+  purge?: boolean;
+}
+
+interface PlannedAction {
+  kind: "remove" | "update";
+  path: string;
+}
+
+const GIT_HOOKS = [
+  "pre-commit",
+  "commit-msg",
+  "pre-push",
+  "post-merge",
+  "gxpm-pre-commit",
+  "gxpm-commit-msg",
+  "gxpm-pre-push",
+  "gxpm-post-merge",
+];
+
+const CODEX_HOOK_SCRIPTS = [
+  "gxpm-session-start.sh",
+  "gxpm-user-prompt-submit.sh",
+  "gxpm-pre-tool-use.sh",
+  "gxpm-stop.sh",
+];
+
+export function planUninstall(options: UninstallOptions = {}): PlannedAction[] {
+  const home = options.home ?? homedir();
+  const target = resolve(options.target ?? process.cwd());
+  const actions: PlannedAction[] = [
+    { kind: "remove", path: join(home, ".codex", "skills", "gxpm") },
+    { kind: "remove", path: join(home, ".claude", "skills", "gxpm") },
+    ...GIT_HOOKS.map((hook) => ({ kind: "remove" as const, path: join(target, ".githooks", hook) })),
+    ...CODEX_HOOK_SCRIPTS.map((script) => ({
+      kind: "remove" as const,
+      path: join(target, ".codex", "hooks", script),
+    })),
+  ];
+
+  const hooksJson = join(target, ".codex", "hooks.json");
+  if (existsSync(hooksJson)) {
+    actions.push({ kind: "update", path: hooksJson });
+  }
+
+  if (options.purge) {
+    actions.push({ kind: "remove", path: join(home, ".gxpm") });
+  }
+
+  return actions;
+}
+
+export function runUninstall(options: UninstallOptions = {}): PlannedAction[] {
+  const actions = planUninstall(options);
+  if (options.dryRun) {
+    return actions;
+  }
+
+  for (const action of actions) {
+    if (action.kind === "remove") {
+      removePath(action.path);
+    } else {
+      removeCodexHookEntries(action.path);
+    }
+  }
+
+  return actions;
+}
+
+function removePath(path: string) {
+  if (!existsSync(path)) return;
+  rmSync(path, { recursive: true, force: true });
+}
+
+function removeCodexHookEntries(path: string) {
+  if (!existsSync(path)) return;
+  let parsed: any;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return;
+  }
+
+  if (!parsed || typeof parsed !== "object" || !parsed.hooks || typeof parsed.hooks !== "object") {
+    return;
+  }
+
+  for (const eventName of Object.keys(parsed.hooks)) {
+    const entries = Array.isArray(parsed.hooks[eventName]) ? parsed.hooks[eventName] : [];
+    const nextEntries = entries
+      .map((entry: any) => {
+        const hooks = Array.isArray(entry?.hooks) ? entry.hooks : [];
+        const kept = hooks.filter((hook: any) => {
+          const command = typeof hook?.command === "string" ? hook.command : "";
+          return !isGxpmOwnedCodexHookCommand(command);
+        });
+        return { ...entry, hooks: kept };
+      })
+      .filter((entry: any) => Array.isArray(entry.hooks) && entry.hooks.length > 0);
+
+    if (nextEntries.length > 0) {
+      parsed.hooks[eventName] = nextEntries;
+    } else {
+      delete parsed.hooks[eventName];
+    }
+  }
+
+  writeFileSync(path, JSON.stringify(parsed, null, 2) + "\n");
+}
+
+function isGxpmOwnedCodexHookCommand(command: string) {
+  if (CODEX_HOOK_SCRIPTS.some((script) => command.includes(script))) return true;
+  return /^gxpm hook \S+ --host codex(?:\s|$)/.test(command.trim());
+}
+
+function describeAction(action: PlannedAction, dryRun: boolean) {
+  const prefix = dryRun ? "would" : "did";
+  if (action.kind === "remove") {
+    const type = existsSync(action.path) && lstatSync(action.path).isDirectory() ? "directory" : "path";
+    return `${prefix} remove ${type}: ${action.path}`;
+  }
+  return `${prefix} update file: ${action.path}`;
+}
+
+function parseArgs(argv: string[]): UninstallOptions {
+  const options: UninstallOptions = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--dry-run") {
+      options.dryRun = true;
+    } else if (arg === "--purge") {
+      options.purge = true;
+    } else if (arg === "--target") {
+      options.target = argv[++index];
+    } else if (arg === "--home") {
+      options.home = argv[++index];
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  return options;
+}
+
+if (import.meta.main) {
+  try {
+    const options = parseArgs(Bun.argv.slice(2));
+    const actions = runUninstall(options);
+    for (const action of actions) {
+      console.log(describeAction(action, options.dryRun ?? false));
+    }
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}

package/scripts/version.ts

@@ -0,0 +1,47 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const DEFAULT_GXPM_ROOT = resolve(import.meta.dir, "..");
+const VERSION_PATTERN = /^\d+\.\d+\.\d+\.\d+$/;
+
+export function readGxpmVersion(input: { root?: string } = {}): string {
+  const root = input.root ?? DEFAULT_GXPM_ROOT;
+  const versionPath = join(root, "VERSION");
+  if (!existsSync(versionPath)) {
+    throw new Error(`VERSION file not found: ${versionPath}`);
+  }
+  const version = readFileSync(versionPath, "utf8").trim();
+  if (!version) {
+    throw new Error("VERSION file is empty");
+  }
+  return version;
+}
+
+export function validateVersionTruth(input: { root?: string } = {}): string[] {
+  const root = input.root ?? DEFAULT_GXPM_ROOT;
+  const errors: string[] = [];
+  let version = "";
+
+  try {
+    version = readGxpmVersion({ root });
+  } catch (error) {
+    errors.push(error instanceof Error ? error.message : String(error));
+  }
+
+  if (version && !VERSION_PATTERN.test(version)) {
+    errors.push(`VERSION must use four-segment numeric format, got: ${version}`);
+  }
+
+  try {
+    const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8")) as {
+      version?: string;
+    };
+    if (version && pkg.version !== version) {
+      errors.push(`package.json version (${pkg.version ?? "<missing>"}) must match VERSION (${version})`);
+    }
+  } catch (error) {
+    errors.push(`package.json version check failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  return errors;
+}