oh-my-codex-cli 0.1.0

package/scripts/check-skill-llm-governance.js

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+const fs = require('fs');
+const fsp = require('fs/promises');
+const path = require('path');
+
+function parseArgs(argv) {
+  const result = {
+    mode: 'auto',
+    skillsDir: '',
+    outDir: '',
+    maxFiles: 20,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--mode' && argv[i + 1]) {
+      result.mode = argv[i + 1];
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith('--mode=')) {
+      result.mode = arg.slice('--mode='.length);
+      continue;
+    }
+    if (arg === '--skills-dir' && argv[i + 1]) {
+      result.skillsDir = argv[i + 1];
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith('--skills-dir=')) {
+      result.skillsDir = arg.slice('--skills-dir='.length);
+      continue;
+    }
+    if (arg === '--out-dir' && argv[i + 1]) {
+      result.outDir = argv[i + 1];
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith('--out-dir=')) {
+      result.outDir = arg.slice('--out-dir='.length);
+      continue;
+    }
+    if (arg === '--max-files' && argv[i + 1]) {
+      result.maxFiles = Number(argv[i + 1]) || result.maxFiles;
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith('--max-files=')) {
+      result.maxFiles = Number(arg.slice('--max-files='.length)) || result.maxFiles;
+    }
+  }
+
+  return result;
+}
+
+function detectSkillsDir(root, explicit) {
+  if (explicit) return path.resolve(explicit);
+  const candidates = [
+    path.join(root, '.agent', 'skills'),
+    path.join(root, '.codex', 'skills'),
+  ];
+  return candidates.find((dir) => fs.existsSync(dir)) || candidates[0];
+}
+
+function detectOutDir(root, explicit) {
+  return explicit ? path.resolve(explicit) : path.join(root, '.omcodex', 'reports');
+}
+
+function readAllowlist(root) {
+  const file = path.join(root, '.governance', 'skill-llm.allowlist');
+  if (!fs.existsSync(file)) return new Set();
+  const lines = fs.readFileSync(file, 'utf8')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line && !line.startsWith('#'));
+  return new Set(lines);
+}
+
+async function listSkillFiles(skillsDir) {
+  if (!fs.existsSync(skillsDir)) return [];
+  const entries = await fsp.readdir(skillsDir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const file = path.join(skillsDir, entry.name, 'SKILL.md');
+    if (fs.existsSync(file)) files.push({ name: entry.name, file });
+  }
+  files.sort((a, b) => a.name.localeCompare(b.name));
+  return files;
+}
+
+function heuristicAudit(skillName, content) {
+  const issues = [];
+
+  if (!/^---\n[\s\S]*?\n---\n?/.test(content)) {
+    issues.push({ severity: 'high', rule: 'missing_frontmatter', message: 'SKILL.md missing frontmatter block.' });
+  }
+  if (!/name:\s*[^\n]+/.test(content)) {
+    issues.push({ severity: 'high', rule: 'missing_frontmatter_name', message: 'frontmatter.name is missing.' });
+  }
+  if (!/description:\s*[^\n]+/.test(content)) {
+    issues.push({ severity: 'high', rule: 'missing_frontmatter_description', message: 'frontmatter.description is missing.' });
+  }
+  if (/\bTask\s*\(/.test(content)) {
+    issues.push({ severity: 'high', rule: 'legacy_task_api', message: 'Legacy Task(...) syntax is not codex-native.' });
+  }
+  if (/cc\s+--plugin-dir|\/plugin|HUD/.test(content)) {
+    issues.push({ severity: 'high', rule: 'non_codex_runtime', message: 'Contains runtime guidance not supported by Codex.' });
+  }
+  if (!/\$[\w-]+|[a-z-]+:\s+[^\n]+/i.test(content)) {
+    issues.push({ severity: 'medium', rule: 'missing_invocation_example', message: 'No explicit Codex invocation example found.' });
+  }
+  if (/\betc\.\b|\bmaybe\b|\bif possible\b/i.test(content)) {
+    issues.push({ severity: 'low', rule: 'ambiguous_wording', message: 'Contains ambiguous wording that can reduce determinism.' });
+  }
+  if (!/step|workflow|instructions|usage|how to use|when to use|步骤|用法/i.test(content)) {
+    issues.push({ severity: 'medium', rule: 'missing_structure', message: 'Missing clear workflow/instruction sections.' });
+  }
+
+  return {
+    skill: skillName,
+    mode: 'heuristic',
+    issues,
+  };
+}
+
+function extractJson(content) {
+  const trimmed = String(content || '').trim();
+  try {
+    return JSON.parse(trimmed);
+  } catch {}
+
+  const fenced = trimmed.match(/```(?:json)?\n([\s\S]*?)\n```/i);
+  if (fenced) {
+    try {
+      return JSON.parse(fenced[1]);
+    } catch {}
+  }
+  return null;
+}
+
+async function llmAudit(skillName, content, options) {
+  const prompt = [
+    'Audit the Codex skill document and return JSON.',
+    'Rules:',
+    '- Identify execution blockers and ambiguous instructions.',
+    '- Focus on Codex compatibility and deterministic execution.',
+    '- Keep findings concise.',
+    'Output JSON schema:',
+    '{"issues":[{"severity":"high|medium|low","rule":"string","message":"string"}]}',
+    '',
+    `Skill name: ${skillName}`,
+    'Document:',
+    content.slice(0, 7000),
+  ].join('\n');
+
+  const response = await fetch('https://api.openai.com/v1/chat/completions', {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${options.apiKey}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      model: options.model,
+      temperature: 0,
+      response_format: { type: 'json_object' },
+      messages: [
+        { role: 'system', content: 'You are a strict governance auditor for Codex skill docs.' },
+        { role: 'user', content: prompt },
+      ],
+    }),
+  });
+
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(`llm_http_${response.status}: ${body.slice(0, 240)}`);
+  }
+
+  const data = await response.json();
+  const contentText = data && data.choices && data.choices[0] && data.choices[0].message
+    ? data.choices[0].message.content
+    : '';
+  const parsed = extractJson(contentText);
+  if (!parsed || !Array.isArray(parsed.issues)) {
+    throw new Error('llm_invalid_json_output');
+  }
+  return {
+    skill: skillName,
+    mode: 'llm',
+    issues: parsed.issues
+      .filter((issue) => issue && typeof issue === 'object')
+      .map((issue) => ({
+        severity: ['high', 'medium', 'low'].includes(issue.severity) ? issue.severity : 'medium',
+        rule: String(issue.rule || 'llm_rule'),
+        message: String(issue.message || '').slice(0, 400),
+      })),
+  };
+}
+
+function mergeAudits(heuristic, llm) {
+  if (!llm) return heuristic;
+  return {
+    skill: heuristic.skill,
+    mode: 'hybrid',
+    issues: [...heuristic.issues, ...llm.issues],
+  };
+}
+
+function summarize(results) {
+  const severity = { high: 0, medium: 0, low: 0 };
+  for (const result of results) {
+    for (const issue of result.issues) {
+      if (severity[issue.severity] !== undefined) severity[issue.severity] += 1;
+    }
+  }
+  const blockers = results.filter((result) => result.issues.some((issue) => issue.severity === 'high'));
+  return {
+    totalSkills: results.length,
+    severity,
+    blockerSkills: blockers.map((item) => item.skill),
+    blockerCount: blockers.length,
+  };
+}
+
+async function main() {
+  const root = path.resolve(__dirname, '..');
+  const args = parseArgs(process.argv.slice(2));
+  const skillsDir = detectSkillsDir(root, args.skillsDir);
+  const outDir = detectOutDir(root, args.outDir);
+  const allowlist = readAllowlist(root);
+
+  const files = await listSkillFiles(skillsDir);
+  const mode = ['auto', 'heuristic', 'llm'].includes(args.mode) ? args.mode : 'auto';
+  const apiKey = process.env.OPENAI_API_KEY;
+  const llmEnabled = mode === 'llm' || (mode === 'auto' && !!apiKey);
+  const model = process.env.OMX_GOVERNANCE_MODEL || 'gpt-4o-mini';
+
+  const results = [];
+  for (let i = 0; i < files.length; i += 1) {
+    const item = files[i];
+    const content = await fsp.readFile(item.file, 'utf8');
+    const heuristic = heuristicAudit(item.name, content);
+    let llm = null;
+
+    if (llmEnabled && i < Math.max(1, Number(args.maxFiles) || 20)) {
+      try {
+        llm = await llmAudit(item.name, content, { apiKey, model });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        heuristic.issues.push({
+          severity: 'medium',
+          rule: 'llm_fallback',
+          message: `LLM audit unavailable, fallback to heuristic: ${message}`,
+        });
+      }
+    }
+
+    const merged = mergeAudits(heuristic, llm);
+    merged.issues = merged.issues.map((issue) => {
+      const key = `${issue.rule}:${merged.skill}`;
+      if (allowlist.has(key)) {
+        return {
+          ...issue,
+          severity: issue.severity === 'high' ? 'medium' : issue.severity,
+          message: `${issue.message} [allowlisted:${key}]`,
+        };
+      }
+      return issue;
+    });
+    results.push(merged);
+  }
+
+  const summary = summarize(results);
+  const report = {
+    generatedAt: new Date().toISOString(),
+    mode: llmEnabled ? (mode === 'llm' ? 'llm' : 'auto-llm') : 'heuristic',
+    model: llmEnabled ? model : null,
+    skillsDir,
+    allowlist: Array.from(allowlist).sort(),
+    summary,
+    results,
+  };
+
+  await fsp.mkdir(outDir, { recursive: true });
+  const reportPath = path.join(outDir, 'skill-llm-governance-latest.json');
+  await fsp.writeFile(reportPath, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+
+  console.log(`Skill governance (LLM gate) completed: ${summary.totalSkills} skills`);
+  console.log(`High=${summary.severity.high} Medium=${summary.severity.medium} Low=${summary.severity.low}`);
+  console.log(`Report: ${reportPath}`);
+
+  if (summary.blockerCount > 0) {
+    console.error(`Blockers detected in skills: ${summary.blockerSkills.join(', ')}`);
+    process.exitCode = 1;
+  }
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/scripts/eval-skills.js

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+const fs = require('fs');
+const fsp = require('fs/promises');
+const path = require('path');
+
+function parseArgs(argv) {
+  const result = {
+    skillsDir: '',
+    outDir: '',
+    minScore: 70,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--skills-dir' && argv[i + 1]) {
+      result.skillsDir = argv[i + 1];
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith('--skills-dir=')) {
+      result.skillsDir = arg.slice('--skills-dir='.length);
+      continue;
+    }
+    if (arg === '--out-dir' && argv[i + 1]) {
+      result.outDir = argv[i + 1];
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith('--out-dir=')) {
+      result.outDir = arg.slice('--out-dir='.length);
+      continue;
+    }
+    if (arg === '--min-score' && argv[i + 1]) {
+      result.minScore = Number(argv[i + 1]) || result.minScore;
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith('--min-score=')) {
+      result.minScore = Number(arg.slice('--min-score='.length)) || result.minScore;
+    }
+  }
+
+  return result;
+}
+
+function detectSkillsDir(root, explicit) {
+  if (explicit) return path.resolve(explicit);
+  const candidates = [
+    path.join(root, '.agent', 'skills'),
+    path.join(root, '.codex', 'skills'),
+  ];
+  return candidates.find((dir) => fs.existsSync(dir)) || candidates[0];
+}
+
+function detectOutDir(root, explicit) {
+  return explicit ? path.resolve(explicit) : path.join(root, '.omcodex', 'reports');
+}
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n?/);
+  if (!match) return null;
+  const lines = match[1].split('\n');
+  const map = {};
+  for (const line of lines) {
+    const idx = line.indexOf(':');
+    if (idx <= 0) continue;
+    const key = line.slice(0, idx).trim();
+    const value = line.slice(idx + 1).trim().replace(/^["']|["']$/g, '');
+    map[key] = value;
+  }
+  return map;
+}
+
+function hasCodeFence(content) {
+  return content.includes('```');
+}
+
+function evaluateSkill(name, content) {
+  const findings = [];
+  let score = 100;
+  const frontmatter = parseFrontmatter(content);
+
+  if (!frontmatter) {
+    score -= 40;
+    findings.push('missing frontmatter');
+  } else {
+    if (!frontmatter.name) {
+      score -= 20;
+      findings.push('frontmatter.name missing');
+    }
+    if (!frontmatter.description) {
+      score -= 20;
+      findings.push('frontmatter.description missing');
+    }
+  }
+
+  if (!/\$[\w-]+|[a-z-]+:\s+/i.test(content)) {
+    score -= 15;
+    findings.push('missing codex invocation example');
+  }
+
+  if (!/usage|when to use|instructions|workflow|步骤|用法/i.test(content)) {
+    score -= 10;
+    findings.push('missing workflow guidance sections');
+  }
+
+  if (!hasCodeFence(content)) {
+    score -= 8;
+    findings.push('missing runnable examples');
+  }
+
+  if (/\bTask\s*\(/.test(content)) {
+    score -= 12;
+    findings.push('contains legacy Task(...) syntax');
+  }
+
+  if (/cc\s+--plugin-dir|\/plugin|HUD/i.test(content)) {
+    score -= 12;
+    findings.push('contains non-codex runtime reference');
+  }
+
+  if (/\betc\.\b|\bmaybe\b|\bif possible\b/i.test(content)) {
+    score -= 4;
+    findings.push('contains ambiguous instruction wording');
+  }
+
+  score = Math.max(0, Math.min(100, score));
+  return {
+    skill: name,
+    score,
+    findings,
+    pass: score >= 70,
+  };
+}
+
+async function listSkillFiles(skillsDir) {
+  if (!fs.existsSync(skillsDir)) return [];
+  const entries = await fsp.readdir(skillsDir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const file = path.join(skillsDir, entry.name, 'SKILL.md');
+    if (fs.existsSync(file)) files.push({ name: entry.name, file });
+  }
+  files.sort((a, b) => a.name.localeCompare(b.name));
+  return files;
+}
+
+function renderMarkdownReport(summary) {
+  const lines = [];
+  lines.push('# Skill Eval Report');
+  lines.push('');
+  lines.push(`Generated At: ${summary.generatedAt}`);
+  lines.push(`Skills Evaluated: ${summary.total}`);
+  lines.push(`Average Score: ${summary.averageScore}`);
+  lines.push(`Pass: ${summary.passCount}`);
+  lines.push(`Fail: ${summary.failCount}`);
+  lines.push('');
+  lines.push('| Skill | Score | Pass | Findings |');
+  lines.push('|---|---:|:---:|---|');
+
+  for (const row of summary.results) {
+    lines.push(`| ${row.skill} | ${row.score} | ${row.pass ? 'Y' : 'N'} | ${row.findings.join('; ') || '-'} |`);
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+async function main() {
+  const root = path.resolve(__dirname, '..');
+  const args = parseArgs(process.argv.slice(2));
+  const skillsDir = detectSkillsDir(root, args.skillsDir);
+  const outDir = detectOutDir(root, args.outDir);
+  const minScore = Math.max(1, Number(args.minScore) || 70);
+
+  const files = await listSkillFiles(skillsDir);
+  const results = [];
+  for (const item of files) {
+    const content = await fsp.readFile(item.file, 'utf8');
+    const score = evaluateSkill(item.name, content);
+    results.push(score);
+  }
+
+  const average = results.length === 0
+    ? 0
+    : Number((results.reduce((sum, item) => sum + item.score, 0) / results.length).toFixed(2));
+  const passCount = results.filter((item) => item.score >= minScore).length;
+  const failCount = results.length - passCount;
+  const summary = {
+    generatedAt: new Date().toISOString(),
+    skillsDir,
+    minScore,
+    total: results.length,
+    averageScore: average,
+    passCount,
+    failCount,
+    results,
+  };
+
+  await fsp.mkdir(outDir, { recursive: true });
+  const jsonPath = path.join(outDir, 'skill-eval-latest.json');
+  const mdPath = path.join(outDir, 'skill-eval-latest.md');
+  await fsp.writeFile(jsonPath, `${JSON.stringify(summary, null, 2)}\n`, 'utf8');
+  await fsp.writeFile(mdPath, renderMarkdownReport(summary), 'utf8');
+
+  console.log(`Skill eval completed: ${summary.total} skills, avg=${summary.averageScore}, fail=${summary.failCount}`);
+  console.log(`Reports: ${jsonPath}`);
+  console.log(`Reports: ${mdPath}`);
+
+  if (summary.failCount > 0) process.exitCode = 1;
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/scripts/generate-catalog-docs.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+const fs = require('fs');
+const path = require('path');
+const { validateCatalogManifest, summarizeCatalogCounts } = require('../src/catalog/schema');
+
+const root = path.resolve(__dirname, '..');
+const skillsRoot = fs.existsSync(path.join(root, '.agent', 'skills'))
+  ? path.join(root, '.agent', 'skills')
+  : path.join(root, '.codex', 'skills');
+const promptsRoot = path.join(root, 'prompts');
+
+const CATEGORY_MAP = new Map([
+  ['autopilot', 'execution'],
+  ['ralph', 'execution'],
+  ['team', 'execution'],
+  ['ultrawork', 'execution'],
+  ['ultraqa', 'execution'],
+  ['swarm', 'execution'],
+  ['ralplan', 'planning'],
+  ['plan', 'planning'],
+  ['code-review', 'shortcut'],
+  ['security-review', 'shortcut'],
+  ['tdd', 'shortcut'],
+  ['build-fix', 'shortcut'],
+]);
+
+const CORE = new Set(['autopilot', 'ralph', 'ultrawork', 'swarm', 'plan']);
+
+function detectSkills() {
+  if (!fs.existsSync(skillsRoot)) return [];
+  return fs.readdirSync(skillsRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort();
+}
+
+function detectPrompts() {
+  if (!fs.existsSync(promptsRoot)) return [];
+  return fs.readdirSync(promptsRoot, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
+    .map((entry) => entry.name.replace(/\.md$/i, ''))
+    .sort();
+}
+
+function buildManifest() {
+  const skillNames = detectSkills();
+  const promptNames = detectPrompts();
+
+  const skills = skillNames.map((name) => ({
+    name,
+    category: CATEGORY_MAP.get(name) || 'utility',
+    status: 'active',
+    core: CORE.has(name),
+  }));
+
+  const agents = promptNames.map((name) => ({
+    name,
+    category: 'role',
+    status: 'active',
+    core: ['architect', 'planner', 'executor'].includes(name),
+  }));
+
+  return {
+    schemaVersion: 1,
+    catalogVersion: new Date().toISOString().slice(0, 10),
+    skills,
+    agents,
+  };
+}
+
+function main() {
+  const manifest = validateCatalogManifest(buildManifest());
+  const counts = summarizeCatalogCounts(manifest);
+
+  const templatePath = path.join(root, 'templates', 'catalog-manifest.json');
+  const sourcePath = path.join(root, 'src', 'catalog', 'manifest.json');
+  const generatedPath = path.join(root, 'src', 'catalog', 'generated', 'public-catalog.json');
+
+  fs.mkdirSync(path.dirname(templatePath), { recursive: true });
+  fs.mkdirSync(path.dirname(sourcePath), { recursive: true });
+  fs.mkdirSync(path.dirname(generatedPath), { recursive: true });
+
+  fs.writeFileSync(templatePath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+  fs.writeFileSync(sourcePath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+  fs.writeFileSync(
+    generatedPath,
+    `${JSON.stringify({ generatedAt: new Date().toISOString(), counts, skills: manifest.skills, agents: manifest.agents }, null, 2)}\n`,
+    'utf8',
+  );
+
+  console.log(`Catalog generated: ${counts.skillCount} skills, ${counts.promptCount} prompts`);
+}
+
+main();

package/scripts/generate-codex-mcp-config.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+MODE="user"
+ENABLE_CONTEXT7="false"
+
+for arg in "$@"; do
+  case "$arg" in
+    --project) MODE="project-local" ;;
+    --enable-context7) ENABLE_CONTEXT7="true" ;;
+    --enable-collab) : ;; # compatibility no-op; collaboration_modes is managed in setup
+  esac
+done
+
+args=(setup --scope "$MODE" --no-skills --no-prompts --no-rules)
+if [[ "$ENABLE_CONTEXT7" == "true" ]]; then
+  args+=(--enable-context7)
+fi
+
+cd "$ROOT_DIR"
+node ./bin/omcodex.js "${args[@]}"

package/scripts/install-codex-force.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+FORCE_OVERWRITE=1 "$ROOT_DIR/scripts/install-codex.sh" "$@"

package/scripts/install-codex-incremental.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SKIP_OVERWRITE=1 "$ROOT_DIR/scripts/install-codex.sh" "$@"