@kafka0102/onespec 0.1.2

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@kafka0102/onespec",
+  "version": "0.1.2",
+  "description": "OpenSpec + Superpowers workflow skill installer for Codex",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kafka0102/onespec.git"
+  },
+  "keywords": [
+    "openspec",
+    "superpowers",
+    "skills",
+    "codex",
+    "workflow"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "onespec": "./bin/onespec.js"
+  },
+  "files": [
+    "assets",
+    "bin",
+    "src",
+    "scripts/postinstall.js"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "test:shell": "node --test test/*.shell.test.js",
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT"
+}

package/scripts/postinstall.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+
+function shouldSkipHint() {
+  if (process.env.CI === 'true' || process.env.CI === '1') {
+    return true;
+  }
+  if (process.env.ONESPEC_NO_HINTS === '1') {
+    return true;
+  }
+  return false;
+}
+
+function main() {
+  if (shouldSkipHint()) {
+    return;
+  }
+
+  console.log('\nOneSpec installed. Next run:');
+  console.log('  onespec init --scope global --yes');
+  console.log('or for the current project:');
+  console.log('  onespec init . --scope project --yes\n');
+}
+
+try {
+  main();
+} catch {
+  // Never break npm install because of an install hint.
+}

package/src/cli.js

@@ -0,0 +1,244 @@
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+
+import { doctorProject } from './doctor.js';
+import { initProject, SUPPORTED_LANGUAGES } from './init.js';
+
+const OPEN_SPEC_CLI_PACKAGE = '@fission-ai/openspec@latest';
+const SUPERPOWERS_PACKAGE = 'obra/superpowers';
+
+function parseArgs(argv) {
+  const args = [...argv];
+  const command = args.shift() ?? 'help';
+  const options = {
+    targetPath: process.cwd(),
+    platform: 'codex',
+    scope: undefined,
+    language: undefined,
+    yes: false,
+    overwrite: false,
+    json: false,
+  };
+
+  while (args.length > 0) {
+    const arg = args.shift();
+    switch (arg) {
+      case '--yes':
+      case '-y':
+        options.yes = true;
+        break;
+      case '--overwrite':
+        options.overwrite = true;
+        break;
+      case '--json':
+        options.json = true;
+        break;
+      case '--scope':
+        options.scope = args.shift();
+        break;
+      case '--language':
+      case '--lang':
+        options.language = args.shift();
+        break;
+      case '--platform':
+        options.platform = args.shift() ?? 'codex';
+        break;
+      default:
+        if (arg?.startsWith('-')) {
+          throw new Error(`Unknown option: ${arg}`);
+        }
+        options.targetPath = arg ?? options.targetPath;
+        break;
+    }
+  }
+
+  return { command, options };
+}
+
+function commandExists(command) {
+  try {
+    const checker = process.platform === 'win32' ? 'where' : 'which';
+    execFileSync(checker, [command], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function askInitOptions(options) {
+  if (options.yes) {
+    return {
+      ...options,
+      scope: options.scope ?? 'project',
+      language: options.language ?? 'zh',
+      installOpenSpecCli: false,
+      initOpenSpecProject: false,
+      installSuperpowers: false,
+    };
+  }
+
+  const preflight = await doctorProject(options.targetPath, {
+    platform: options.platform,
+    scope: options.scope ?? 'project',
+  });
+  const rl = readline.createInterface({ input, output });
+  try {
+    const scopeAnswer =
+      options.scope ??
+      (await rl.question('安装范围？输入 project 或 global（默认 project）：'));
+    const resolvedScope = scopeAnswer.trim() || 'project';
+    const languageAnswer =
+      options.language ??
+      (await rl.question('Skill 语言？输入 zh 或 en（默认 zh）：'));
+    const overwriteAnswer = options.overwrite
+      ? 'yes'
+      : await rl.question('如果 OneSpec skill 已存在，是否覆盖？输入 yes 或 no（默认 no）：');
+    const installOpenSpecCliAnswer =
+      preflight.openspecCli.available
+        ? 'no'
+        : await rl.question(
+            `未检测到 OpenSpec CLI。是否现在执行 npm install -g ${OPEN_SPEC_CLI_PACKAGE} ？输入 yes 或 no（默认 no）：`,
+          );
+    const initOpenSpecProjectAnswer =
+      resolvedScope === 'project' && !preflight.hasOpenSpecProject
+        ? await rl.question(
+            '当前项目未初始化 OpenSpec。是否在安装 OneSpec 后执行 openspec init？输入 yes 或 no（默认 no）：',
+          )
+        : 'no';
+    const installSuperpowersAnswer = preflight.superpowers.available
+      ? 'no'
+      : await rl.question(
+          `未检测到 Superpowers。是否现在执行 npx skills add ${SUPERPOWERS_PACKAGE} -a codex${resolvedScope === 'global' ? ' -g' : ''} -y ？输入 yes 或 no（默认 no）：`,
+        );
+
+    return {
+      ...options,
+      scope: resolvedScope,
+      language: languageAnswer.trim() || 'zh',
+      overwrite: options.overwrite || ['y', 'yes', '是', '覆盖'].includes(overwriteAnswer.trim()),
+      installOpenSpecCli: ['y', 'yes', '是'].includes(installOpenSpecCliAnswer.trim()),
+      initOpenSpecProject: ['y', 'yes', '是'].includes(initOpenSpecProjectAnswer.trim()),
+      installSuperpowers: ['y', 'yes', '是'].includes(installSuperpowersAnswer.trim()),
+    };
+  } finally {
+    rl.close();
+  }
+}
+
+function runCommand(command, args, cwd = process.cwd()) {
+  execFileSync(command, args, {
+    cwd,
+    stdio: 'inherit',
+    shell: process.platform === 'win32',
+  });
+}
+
+function getNpxExecutable() {
+  return process.platform === 'win32' ? 'npx.cmd' : 'npx';
+}
+
+async function ensureRequestedDependencies(targetPath, options, preflight) {
+  if (options.installOpenSpecCli && !preflight.openspecCli.available) {
+    runCommand('npm', ['install', '-g', OPEN_SPEC_CLI_PACKAGE]);
+  }
+
+  if (options.installSuperpowers && !preflight.superpowers.available) {
+    const args = ['skills', 'add', SUPERPOWERS_PACKAGE, '-a', 'codex', '-y'];
+    if (options.scope === 'global') {
+      args.push('-g');
+    }
+    runCommand(getNpxExecutable(), args, targetPath);
+  }
+
+  if (options.initOpenSpecProject && !preflight.hasOpenSpecProject) {
+    runCommand('openspec', ['init', targetPath], targetPath);
+  }
+}
+
+function printHelp() {
+  console.log(`OneSpec Skill Installer
+
+用法：
+  onespec init [path] [--yes] [--overwrite] [--scope project|global] [--language zh|en]
+  onespec doctor [path] [--scope project|global]
+
+说明：
+  当前提供中英文 Skill bundle，暂仅支持 Codex 平台。
+`);
+}
+
+function printSummary(result) {
+  console.log('\nOneSpec 初始化完成\n');
+  console.log(`安装位置：${result.skillPath}`);
+  console.log(`安装范围：${result.scope}`);
+  console.log(`Skill 语言：${result.languageName} (${result.language})`);
+  console.log(`Skill 状态：${result.installedSkill ? '已安装/已覆盖' : '已存在，已跳过'}`);
+  console.log(`已安装 Skills：${result.installedSkills.join(', ') || '无'}`);
+  console.log(`已跳过 Skills：${result.skippedSkills.join(', ') || '无'}`);
+  console.log(`工作目录：${path.join(result.projectPath, 'docs', 'superpowers')}`);
+  console.log('\n环境检查：');
+  console.log(`OpenSpec CLI：${commandExists('openspec') ? '已找到' : '未找到，请先安装或运行 openspec init'}`);
+  console.log('Superpowers：请确认 Codex 可发现 brainstorming / writing-plans / using-git-worktrees 等 skills');
+  console.log('\n开始使用：在 Codex 中输入 “使用 onespec：<你的任务描述>”。\n');
+}
+
+function printDoctor(report) {
+  console.log('\nOneSpec 环境检查\n');
+  console.log(`OneSpec Skill：${report.onespec.installed ? '已安装' : '未安装'}`);
+  console.log(`OneSpec 子 Skills：${report.onespec.installedSkills.join(', ') || '无'}`);
+  console.log(`缺少 OneSpec 子 Skills：${report.onespec.missingSkills.join(', ') || '无'}`);
+  console.log(`Skill 语言：${report.onespec.language}`);
+  console.log(`OpenSpec CLI：${report.openspecCli.available ? '已找到' : '未找到'}`);
+  console.log(`OpenSpec 项目：${report.hasOpenSpecProject ? '已初始化' : '未初始化'}`);
+  console.log(
+    `Superpowers：${report.superpowers.available ? '关键 Skills 已找到' : `缺少 ${report.superpowers.missing.join(', ')}`}`,
+  );
+  console.log('\n下一步：');
+  for (const step of report.nextSteps) {
+    console.log(`- ${step}`);
+  }
+  console.log('');
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const { command, options } = parseArgs(argv);
+
+  if (command === 'help' || command === '--help' || command === '-h') {
+    printHelp();
+    return;
+  }
+  if (command !== 'init' && command !== 'doctor') {
+    throw new Error(`Unknown command: ${command}`);
+  }
+
+  if (command === 'doctor') {
+    const report = await doctorProject(options.targetPath, {
+      platform: options.platform,
+      scope: options.scope ?? 'project',
+    });
+    if (options.json) {
+      console.log(JSON.stringify(report, null, 2));
+    } else {
+      printDoctor(report);
+    }
+    return;
+  }
+
+  const initOptions = await askInitOptions(options);
+  if (!SUPPORTED_LANGUAGES[initOptions.language]) {
+    throw new Error(`Unsupported language: ${initOptions.language}`);
+  }
+  const preflight = await doctorProject(initOptions.targetPath, {
+    platform: initOptions.platform,
+    scope: initOptions.scope ?? 'project',
+  });
+  await ensureRequestedDependencies(initOptions.targetPath, initOptions, preflight);
+  const result = await initProject(initOptions.targetPath, initOptions);
+  if (initOptions.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    printSummary(result);
+  }
+}

package/src/doctor.js

@@ -0,0 +1,172 @@
+import { execFileSync } from 'node:child_process';
+import { access, readFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { BUNDLED_ONESPEC_SKILLS } from './init.js';
+import { getSkillDir, PLATFORMS } from './platforms.js';
+
+const REQUIRED_SUPERPOWERS = [
+  'brainstorming',
+  'writing-plans',
+  'using-git-worktrees',
+  'subagent-driven-development',
+  'executing-plans',
+  'test-driven-development',
+];
+
+async function exists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function hasOpenSpecProject(projectPath) {
+  return exists(path.join(projectPath, 'openspec'));
+}
+
+function defaultCommandChecker(command) {
+  try {
+    const checker = process.platform === 'win32' ? 'where' : 'which';
+    execFileSync(checker, [command], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function defaultSkillRoots(projectPath, scope, platform) {
+  return [
+    getSkillDir(projectPath, scope, platform),
+    path.join(os.homedir(), '.codex', 'skills'),
+    path.join(os.homedir(), '.codex', 'superpowers', 'skills'),
+    path.join(os.homedir(), '.agents', 'skills'),
+  ];
+}
+
+async function skillInstalledInRoots(roots, name) {
+  for (const root of roots) {
+    if (await exists(path.join(root, name, 'SKILL.md'))) {
+      return true;
+    }
+  }
+  return false;
+}
+
+async function isChineseOneSpec(projectPath, scope, platform) {
+  const skillsDir = getSkillDir(projectPath, scope, platform);
+  const installedSkills = [];
+  const missingSkills = [];
+  const skillPaths = {};
+
+  for (const skillName of BUNDLED_ONESPEC_SKILLS) {
+    const skillPath = path.join(skillsDir, skillName, 'SKILL.md');
+    skillPaths[skillName] = skillPath;
+    if (await exists(skillPath)) {
+      installedSkills.push(skillName);
+    } else {
+      missingSkills.push(skillName);
+    }
+  }
+
+  const routerPath = skillPaths.onespec;
+  if (!(await exists(routerPath))) {
+    return {
+      installed: false,
+      skillPath: routerPath,
+      skillPaths,
+      installedSkills,
+      missingSkills,
+      chinese: false,
+    };
+  }
+
+  const content = await readFile(routerPath, 'utf8');
+  const chinese = content.includes('OneSpec 工作流');
+  const english = content.includes('# OneSpec Workflow');
+  return {
+    installed: missingSkills.length === 0 && (chinese || english),
+    skillPath: routerPath,
+    skillPaths,
+    installedSkills,
+    missingSkills,
+    chinese,
+    english,
+    language: chinese ? 'zh' : english ? 'en' : 'unknown',
+  };
+}
+
+export async function doctorProject(projectPath, options = {}) {
+  const resolvedProject = path.resolve(projectPath);
+  const platform = options.platform ?? 'codex';
+  const scope = options.scope ?? 'project';
+  const commandChecker = options.commandChecker ?? defaultCommandChecker;
+
+  if (!PLATFORMS[platform]) {
+    throw new Error(`Unsupported platform "${platform}". Currently only "codex" is supported.`);
+  }
+
+  const onespec = await isChineseOneSpec(resolvedProject, scope, platform);
+  const skillRoots =
+    options.skillRoots ??
+    [
+      ...new Set([
+        ...defaultSkillRoots(resolvedProject, scope, platform),
+        ...(options.extraSkillRoots ?? []),
+      ]),
+    ];
+  const missing = [];
+  for (const skill of REQUIRED_SUPERPOWERS) {
+    if (!(await skillInstalledInRoots(skillRoots, skill))) {
+      missing.push(skill);
+    }
+  }
+
+  const openspecCli = {
+    available: commandChecker('openspec'),
+  };
+  const openSpecProjectInstalled = await hasOpenSpecProject(resolvedProject);
+  const superpowers = {
+    available: missing.length === 0,
+    required: REQUIRED_SUPERPOWERS,
+    missing,
+    searchedRoots: skillRoots,
+  };
+
+  const nextSteps = [];
+  if (onespec.missingSkills.length > 0) {
+    nextSteps.push(
+      `缺少 OneSpec Skills：${onespec.missingSkills.join(', ')}。运行 \`onespec init --overwrite\` 补齐 OneSpec Skill bundle。`,
+    );
+  } else if (!onespec.installed) {
+    nextSteps.push('运行 `onespec init --yes` 安装 OneSpec Skill。');
+  } else if (!onespec.chinese && !onespec.english) {
+    nextSteps.push('当前 OneSpec Skill 无法识别语言版本，运行 `onespec init --overwrite` 覆盖安装。');
+  }
+  if (!openspecCli.available) {
+    nextSteps.push('未找到 OpenSpec CLI，请安装 OpenSpec CLI 并在目标项目运行 `openspec init`。');
+  } else if (scope === 'project' && !openSpecProjectInstalled) {
+    nextSteps.push('当前项目尚未初始化 OpenSpec，请先运行 `openspec init`。');
+  }
+  if (!superpowers.available) {
+    nextSteps.push(`缺少 Superpowers Skills：${missing.join(', ')}。请先安装 Superpowers。`);
+  }
+  if (nextSteps.length === 0) {
+    nextSteps.push('环境检查通过。可以在 Codex 中使用 `onespec` 工作流。');
+  }
+
+  return {
+    projectPath: resolvedProject,
+    platform,
+    platformName: PLATFORMS[platform].name,
+    scope,
+    onespec,
+    openspecCli,
+    hasOpenSpecProject: openSpecProjectInstalled,
+    superpowers,
+    nextSteps,
+  };
+}

package/src/init.js

@@ -0,0 +1,136 @@
+import { access, chmod, cp, mkdir, rm, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { getSkillDir, PLATFORMS } from './platforms.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export const BUNDLED_ONESPEC_SKILLS = [
+  'onespec',
+  'onespec-design',
+  'onespec-execute',
+  'onespec-archive',
+];
+
+export const SUPPORTED_LANGUAGES = {
+  zh: {
+    id: 'zh',
+    name: '中文',
+  },
+  en: {
+    id: 'en',
+    name: 'English',
+  },
+};
+
+function assetsSkillsDir() {
+  return path.resolve(__dirname, '..', 'assets', 'skills');
+}
+
+function localizedSkillsDir(language) {
+  return path.resolve(__dirname, '..', 'assets', `skills-${language}`);
+}
+
+async function exists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function chmodExecutable(filePath) {
+  const current = await stat(filePath);
+  await chmod(filePath, current.mode | 0o111);
+}
+
+async function makeBundledScriptsExecutable(skillPath) {
+  const scriptsDir = path.join(skillPath, 'scripts');
+  if (!(await exists(scriptsDir))) {
+    return;
+  }
+  await chmodExecutable(path.join(scriptsDir, 'onespec-env.sh'));
+  await chmodExecutable(path.join(scriptsDir, 'onespec-state.sh'));
+  await chmodExecutable(path.join(scriptsDir, 'onespec-handoff.sh'));
+  await chmodExecutable(path.join(scriptsDir, 'onespec-commit.sh'));
+  await chmodExecutable(path.join(scriptsDir, 'onespec-closeout.sh'));
+}
+
+async function createWorkingDirs(projectPath) {
+  await mkdir(path.join(projectPath, 'docs', 'superpowers', 'specs'), { recursive: true });
+  await mkdir(path.join(projectPath, 'docs', 'superpowers', 'plans'), { recursive: true });
+}
+
+export async function initProject(projectPath, options = {}) {
+  const resolvedProject = path.resolve(projectPath);
+  const platform = options.platform ?? 'codex';
+  const scope = options.scope ?? 'project';
+  const overwrite = Boolean(options.overwrite);
+  const language = options.language ?? 'zh';
+
+  if (!PLATFORMS[platform]) {
+    throw new Error(`Unsupported platform "${platform}". Currently only "codex" is supported.`);
+  }
+  if (!['project', 'global'].includes(scope)) {
+    throw new Error(`Unsupported scope "${scope}". Use "project" or "global".`);
+  }
+  if (!SUPPORTED_LANGUAGES[language]) {
+    throw new Error(
+      `Unsupported language "${language}". Use one of: ${Object.keys(SUPPORTED_LANGUAGES).join(', ')}.`,
+    );
+  }
+
+  const sourceRoot = assetsSkillsDir();
+  const localizedRoot = localizedSkillsDir(language);
+  const skillsDir = getSkillDir(resolvedProject, scope, platform);
+  const destination = path.join(skillsDir, 'onespec');
+  const installedSkills = [];
+  const skippedSkills = [];
+
+  await mkdir(skillsDir, { recursive: true });
+
+  for (const skillName of BUNDLED_ONESPEC_SKILLS) {
+    const source = path.join(sourceRoot, skillName);
+    const target = path.join(skillsDir, skillName);
+    const hadExisting = await exists(target);
+
+    if (hadExisting && !overwrite) {
+      skippedSkills.push(skillName);
+      continue;
+    }
+
+    if (hadExisting) {
+      await rm(target, { recursive: true, force: true });
+    }
+    await cp(source, target, { recursive: true });
+    if (language !== 'zh') {
+      const localizedSkill = path.join(localizedRoot, skillName, 'SKILL.md');
+      if (await exists(localizedSkill)) {
+        await cp(localizedSkill, path.join(target, 'SKILL.md'));
+      }
+    }
+    await makeBundledScriptsExecutable(target);
+    installedSkills.push(skillName);
+  }
+
+  if (scope === 'project') {
+    await createWorkingDirs(resolvedProject);
+  }
+
+  return {
+    projectPath: resolvedProject,
+    platform,
+    platformName: PLATFORMS[platform].name,
+    scope,
+    language,
+    languageName: SUPPORTED_LANGUAGES[language].name,
+    skillPath: destination,
+    installedSkill: installedSkills.length > 0,
+    skippedExisting: installedSkills.length === 0 && skippedSkills.length > 0,
+    installedSkills,
+    skippedSkills,
+  };
+}

package/src/platforms.js

@@ -0,0 +1,23 @@
+import os from 'node:os';
+import path from 'node:path';
+
+export const PLATFORMS = {
+  codex: {
+    id: 'codex',
+    name: 'Codex',
+    skillsDir: '.codex',
+    openspecToolId: 'codex',
+  },
+};
+
+export function getInstallBase(projectPath, scope) {
+  return scope === 'global' ? os.homedir() : projectPath;
+}
+
+export function getSkillDir(projectPath, scope, platformId = 'codex') {
+  const platform = PLATFORMS[platformId];
+  if (!platform) {
+    throw new Error(`Unsupported platform: ${platformId}`);
+  }
+  return path.join(getInstallBase(projectPath, scope), platform.skillsDir, 'skills');
+}