@geminix/gxpm 0.1.0

package/scripts/gen-skill-docs.ts

@@ -0,0 +1,201 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { mkdirSync } from "node:fs";
+import { discoverTemplates } from "./discover-skills";
+import { getHostConfig } from "../hosts";
+import type { HostConfig } from "../core/contracts/host";
+import { PHASE_GATE_RULES } from "../core/phase-gates";
+import { renderTemplate } from "../core/converters/template-renderer";
+import { SkillParser, HostConverter, SkillWriter } from "../core/converters";
+import { PresetResolver } from "../core/preset-system/preset-resolver";
+
+export interface GenerateSkillDocsOptions {
+  root?: string;
+  host?: string;
+  dryRun?: boolean;
+}
+
+const GENERATED_MARK = "<!-- AUTO-GENERATED from SKILL.md.tmpl - do not edit directly -->";
+
+export function renderSkillContentForHost(
+  root: string,
+  host: HostConfig,
+  templateRelative: string,
+  references?: string[],
+): string {
+  const templatePath = join(root, templateRelative);
+  const source = readFileSync(templatePath, "utf8");
+
+  // Static files (non-.tmpl) are returned as-is for backward compatibility
+  if (!templateRelative.endsWith(".tmpl")) {
+    return source;
+  }
+
+  // Template files keep string-replacement behavior for backward compatibility
+  const rendered = renderTemplate(source, {
+    PREAMBLE: buildPreamble(root, host),
+    CANON: buildCanonInline(root),
+    ARTIFACT_READ_COMMANDS: buildArtifactReadCommands(),
+    PHASE_GATE_COMMANDS: buildPhaseGateCommands(),
+    PHASE_TRANSITION_SUMMARY: buildPhaseTransitionSummary(),
+    references: buildReferences(root, references),
+  });
+  return insertGeneratedMark(rendered);
+}
+
+export function generateSkillDocs(options: GenerateSkillDocsOptions = {}): string[] {
+  const root = options.root ?? process.cwd();
+  const host = getHostConfig(options.host ?? "codex");
+  const outputs: string[] = [];
+  const stale: string[] = [];
+
+  // Load preset resolver for composition layer support
+  const resolver = new PresetResolver(root);
+  resolver.load();
+
+  for (const template of discoverTemplates(root)) {
+    const outputPath = join(root, template.output);
+    const generated = renderSkillContentForHost(root, host, template.tmpl, template.references);
+
+    // Apply Override > Preset > Core resolution
+    const resolved = resolver.resolve(template.output, generated);
+    const finalContent = resolved?.content ?? generated;
+
+    if (options.dryRun) {
+      const current = existsSync(outputPath) ? readFileSync(outputPath, "utf8") : "";
+      if (current !== finalContent) {
+        stale.push(template.output);
+      }
+      continue;
+    }
+
+    mkdirSync(dirname(outputPath), { recursive: true });
+    writeFileSync(outputPath, finalContent);
+    outputs.push(template.output);
+  }
+
+  if (stale.length > 0) {
+    throw new Error(`Stale generated skill docs:\n${stale.map((path) => `- ${path}`).join("\n")}`);
+  }
+
+  return outputs;
+}
+
+function buildReferences(root: string, references?: string[]): Record<string, string> {
+  const result: Record<string, string> = {};
+  if (!references) return result;
+  for (const refPath of references) {
+    const name = refPath.replace(/^.*\//, "").replace(/\.md$/, "");
+    const content = readFileSync(join(root, refPath), "utf8");
+    result[name] = content;
+  }
+  return result;
+}
+
+function insertGeneratedMark(content: string) {
+  const frontmatter = content.match(/^---\n[\s\S]*?\n---\n?/);
+  if (!frontmatter) {
+    return `${GENERATED_MARK}\n\n${content}`;
+  }
+
+  const head = frontmatter[0].trimEnd();
+  const body = content.slice(frontmatter[0].length).replace(/^\n+/, "");
+  return `${head}\n${GENERATED_MARK}\n\n${body}`;
+}
+
+function buildCanonInline(root: string): string {
+  const canonPath = join(root, "CANON.md");
+  if (!existsSync(canonPath)) {
+    return "";
+  }
+  const content = readFileSync(canonPath, "utf8");
+  return [
+    "## CANON（行为宪法）",
+    "",
+    "以下纪律内联自 gxpm 源码仓库 `CANON.md`，所有 gxpm 操作前必须遵守：",
+    "",
+    content.replace(/^# .*(\n|$)/, "").trim(),
+  ].join("\n");
+}
+
+function buildPreamble(_root: string, host: ReturnType<typeof getHostConfig>) {
+  const envLines = host.usesEnvVars
+    ? [
+        'GXPM_ROOT="${GXPM_ROOT:-$PWD}"',
+        `GXPM_STATE_DIR="\${GXPM_STATE_DIR:-$GXPM_ROOT/.gxpm}"`,
+        "export GXPM_ROOT GXPM_STATE_DIR",
+      ]
+    : ['GXPM_ROOT="${GXPM_ROOT:-$PWD}"', "export GXPM_ROOT"];
+
+  return [
+    "## Host Preamble",
+    "",
+    `Target host: ${host.displayName}.`,
+    "",
+    "```bash",
+    ...envLines,
+    "```",
+  ].join("\n");
+}
+
+function buildArtifactReadCommands() {
+  return PHASE_GATE_RULES.map((rule) => `gxpm artifact read <issue-id> ${rule.requiredArtifact}`).join(
+    "\n",
+  );
+}
+
+function buildPhaseGateCommands() {
+  return PHASE_GATE_RULES.map((rule) =>
+    [
+      `Before leaving \`${rule.fromPhase}\`, initialize \`${rule.requiredArtifact}\`:`,
+      "",
+      "```bash",
+      rule.command,
+      "```",
+    ].join("\n"),
+  ).join("\n\n");
+}
+
+function buildPhaseTransitionSummary() {
+  const gateSummary = PHASE_GATE_RULES.map(
+    (rule) =>
+      `\`${rule.fromPhase} -> ${rule.nextPhase}\` is blocked until \`${rule.requiredArtifact}\` exists.`,
+  ).join(" ");
+
+  return [
+    "V0 phase transitions are strict.",
+    "Use `gxpm issue transition <issue-id> <next-phase>` only for the next phase in the phase map.",
+    gateSummary,
+  ].join(" ");
+}
+
+function parseArgs(argv: string[]) {
+  const options: GenerateSkillDocsOptions = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--host") {
+      options.host = argv[++index];
+    } else if (arg === "--dry-run") {
+      options.dryRun = true;
+    } else if (arg === "--root") {
+      options.root = argv[++index];
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  return options;
+}
+
+if (import.meta.main) {
+  try {
+    const outputs = generateSkillDocs(parseArgs(Bun.argv.slice(2)));
+    if (outputs.length > 0) {
+      console.log(outputs.map((path) => `generated ${path}`).join("\n"));
+    } else {
+      console.log("skill docs are current");
+    }
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}

package/scripts/global-discover.ts

@@ -0,0 +1,217 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** Extract a cwd string from a parsed JSON object, checking top-level and payload.cwd. */
+function extractCwd(parsed: unknown): string | null {
+  if (!parsed || typeof parsed !== "object") return null;
+  const obj = parsed as Record<string, unknown>;
+  if (typeof obj.cwd === "string") return obj.cwd;
+  if (obj.payload && typeof obj.payload === "object") {
+    const payload = obj.payload as Record<string, unknown>;
+    if (typeof payload.cwd === "string") return payload.cwd;
+  }
+  return null;
+}
+
+export interface DiscoverEntry {
+  key: string;
+  repos: string[];
+}
+
+interface RunGlobalDiscoverInput {
+  home?: string;
+}
+
+/** Cache for remote resolution to avoid repeated git subprocess calls per cwd. */
+const remoteCache = new Map<string, string | null>();
+
+/**
+ * Resolve the primary git remote origin URL for a directory.
+ * Results are cached by cwd so each directory is queried at most once.
+ * Returns null if the directory is not a git repo or has no remote.
+ */
+function resolveRemote(cwd: string): string | null {
+  if (remoteCache.has(cwd)) {
+    return remoteCache.get(cwd)!;
+  }
+  let result: string | null = null;
+  try {
+    const url = execFileSync("git", ["remote", "get-url", "origin"], {
+      cwd,
+      stdio: ["ignore", "pipe", "ignore"],
+    })
+      .toString()
+      .trim();
+    result = url || null;
+  } catch {
+    result = null;
+  }
+  remoteCache.set(cwd, result);
+  return result;
+}
+
+/**
+ * Read cwd values from a single file.
+ * Supports whole-file JSON and line-delimited JSON content.
+ */
+function readCwdsFromFile(filePath: string): string[] {
+  let raw: string;
+  try {
+    raw = readFileSync(filePath, "utf8");
+  } catch {
+    return [];
+  }
+
+  const cwds: string[] = [];
+
+  // Try whole-file JSON first; if it succeeds, skip line-by-line to avoid duplicates.
+  let isWholeFileJson = false;
+  try {
+    const parsed = JSON.parse(raw);
+    isWholeFileJson = true;
+    const cwd = extractCwd(parsed);
+    if (cwd) cwds.push(cwd);
+  } catch {
+    // not valid whole-file JSON; fall through to line-by-line parsing
+  }
+
+  if (!isWholeFileJson) {
+    for (const line of raw.split(/\r?\n/)) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try {
+        const parsed = JSON.parse(trimmed);
+        const cwd = extractCwd(parsed);
+        if (cwd) cwds.push(cwd);
+      } catch {
+        // ignore malformed lines
+      }
+    }
+  }
+
+  return cwds;
+}
+
+function listFiles(root: string, recursive: boolean): string[] {
+  if (!existsSync(root)) {
+    return [];
+  }
+
+  let names: string[];
+  try {
+    names = readdirSync(root).sort((a, b) => a.localeCompare(b));
+  } catch {
+    return [];
+  }
+
+  const files: string[] = [];
+
+  for (const name of names) {
+    const fullPath = join(root, name);
+    let stats;
+    try {
+      stats = statSync(fullPath);
+    } catch {
+      continue;
+    }
+
+    if (stats.isFile()) {
+      files.push(fullPath);
+      continue;
+    }
+
+    if (recursive && stats.isDirectory()) {
+      files.push(...listFiles(fullPath, true));
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Read cwd entries from ~/.claude/projects.
+ * Supports both flat test fixtures and real one-level slug directories.
+ */
+function readClaudeCwdEntries(root: string): string[] {
+  if (!existsSync(root)) {
+    return [];
+  }
+
+  const files: string[] = [];
+  let names: string[];
+  try {
+    names = readdirSync(root).sort((a, b) => a.localeCompare(b));
+  } catch {
+    return [];
+  }
+
+  for (const name of names) {
+    const fullPath = join(root, name);
+    let stats;
+    try {
+      stats = statSync(fullPath);
+    } catch {
+      continue;
+    }
+
+    if (stats.isFile()) {
+      files.push(fullPath);
+      continue;
+    }
+
+    if (stats.isDirectory()) {
+      files.push(...listFiles(fullPath, false));
+    }
+  }
+
+  return files.flatMap(readCwdsFromFile);
+}
+
+/**
+ * Read cwd entries from ~/.codex/sessions.
+ * Supports both flat test fixtures and real nested date directories.
+ */
+function readCodexCwdEntries(root: string): string[] {
+  return listFiles(root, true).flatMap(readCwdsFromFile);
+}
+
+/**
+ * Scan ~/.claude/projects and ~/.codex/sessions for session JSON files,
+ * extract cwd values, resolve git remotes, and deduplicate entries.
+ */
+export function runGlobalDiscover(input: RunGlobalDiscoverInput = {}): DiscoverEntry[] {
+  const home = input.home ?? homedir();
+
+  const claudeRoot = join(home, ".claude", "projects");
+  const codexRoot = join(home, ".codex", "sessions");
+
+  const allCwds = [
+    ...readClaudeCwdEntries(claudeRoot),
+    ...readCodexCwdEntries(codexRoot),
+  ];
+
+  // Map from key -> set of cwd paths
+  const keyToRepos = new Map<string, Set<string>>();
+
+  for (const cwd of allCwds) {
+    const remote = resolveRemote(cwd);
+    const key = remote ? `remote:${remote}` : `cwd:${cwd}`;
+
+    if (!keyToRepos.has(key)) {
+      keyToRepos.set(key, new Set());
+    }
+    keyToRepos.get(key)!.add(cwd);
+  }
+
+  const result: DiscoverEntry[] = [];
+  for (const [key, repoSet] of keyToRepos) {
+    result.push({
+      key,
+      repos: Array.from(repoSet).sort((a, b) => a.localeCompare(b)),
+    });
+  }
+
+  return result.sort((a, b) => a.key.localeCompare(b.key));
+}

package/scripts/governance-check.ts

@@ -0,0 +1,75 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export interface GovernanceCheckOptions {
+  root?: string;
+}
+
+const REQUIRED_DOCS = [
+  "CANON.md",
+  "AGENTS.md",
+  "CLAUDE.md",
+  "docs/governance/development-contract.md",
+  "docs/governance/template-authoring.md",
+  "docs/governance/host-adapter.md",
+];
+
+export function validateGovernanceDocs(options: GovernanceCheckOptions = {}): string[] {
+  const root = options.root ?? process.cwd();
+  const errors: string[] = [];
+
+  for (const doc of REQUIRED_DOCS) {
+    if (!existsSync(join(root, doc))) {
+      errors.push(`missing governance doc: ${doc}`);
+    }
+  }
+
+  if (errors.length > 0) {
+    return errors;
+  }
+
+  const agents = readText(root, "AGENTS.md");
+  const claude = readText(root, "CLAUDE.md");
+
+  if (lineCount(agents) > 150) {
+    errors.push("AGENTS.md should stay under 150 lines");
+  }
+
+  if (lineCount(claude) > 80) {
+    errors.push("CLAUDE.md should stay a thin bootstrap under 80 lines");
+  }
+
+  if (!agents.includes("CANON.md")) {
+    errors.push("AGENTS.md must reference CANON.md");
+  }
+
+  const canon = readText(root, "CANON.md");
+  for (const heading of ["## 1. 真值优先", "## 9. 安全门控", "## 10. 失败归因"]) {
+    if (!canon.includes(heading)) {
+      errors.push(`CANON.md missing boundary heading: ${heading}`);
+    }
+  }
+
+  if (!claude.includes("AGENTS.md")) {
+    errors.push("CLAUDE.md must point back to AGENTS.md");
+  }
+
+  return errors;
+}
+
+function readText(root: string, path: string) {
+  return readFileSync(join(root, path), "utf8");
+}
+
+function lineCount(content: string) {
+  return content.trimEnd().split("\n").length;
+}
+
+if (import.meta.main) {
+  const errors = validateGovernanceDocs();
+  if (errors.length > 0) {
+    console.error(errors.map((error) => `governance: ${error}`).join("\n"));
+    process.exit(1);
+  }
+  console.log("governance docs check passed");
+}

package/scripts/gxpm-check.ts

@@ -0,0 +1,12 @@
+import { runScaffoldCheck } from "./scaffold-check";
+
+function main() {
+  console.log(runScaffoldCheck());
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}