universal-dev-standards 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Universal Development Standards Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,248 @@
+# Universal Development Standards CLI
+# 通用開發規範 CLI 工具
+
+CLI tool for adopting Universal Development Standards in your projects.
+
+採用通用開發規範的 CLI 工具，協助您在專案中快速導入標準。
+
+## Installation | 安裝
+
+### Option 1: npm (Recommended) | 選項一：npm（推薦）
+
+```bash
+# Install globally
+npm install -g universal-dev-standards
+
+# Or use npx directly
+npx universal-dev-standards init
+```
+
+### Option 2: Clone and Run Locally | 選項二：本地克隆執行
+
+```bash
+# Clone the repository
+git clone https://github.com/AsiaOstrich/universal-dev-standards.git
+
+# Navigate to CLI directory
+cd universal-dev-standards/cli
+
+# Install dependencies
+npm install
+
+# Run directly
+node bin/uds.js list
+node bin/uds.js init
+
+# Or link globally
+npm link
+uds list
+```
+
+## Commands | 命令
+
+### `uds list`
+
+List all available standards. | 列出所有可用的規範。
+
+```bash
+# List all standards
+uds list
+
+# Filter by level
+uds list --level 2
+
+# Filter by category
+uds list --category skill
+```
+
+**Options | 選項:**
+- `-l, --level <1|2|3>` - Filter by adoption level | 按採用等級篩選
+- `-c, --category <name>` - Filter by category | 按類別篩選 (skill, reference, extension, integration, template)
+
+### `uds init`
+
+Initialize standards in your project. | 在您的專案中初始化規範。
+
+```bash
+# Interactive mode (recommended)
+uds init
+
+# Non-interactive with defaults
+uds init --yes
+
+# Specify options
+uds init --level 2 --lang php --locale zh-tw
+```
+
+**Options | 選項:**
+- `-l, --level <1|2|3>` - Adoption level | 採用等級 (1=基本, 2=推薦, 3=企業)
+- `--lang <language>` - Language extension | 語言延伸 (csharp, php)
+- `--framework <name>` - Framework extension | 框架延伸 (fat-free)
+- `--locale <locale>` - Locale extension | 地區延伸 (zh-tw)
+- `--no-skills` - Skip Claude Code Skills installation prompt | 跳過 Skills 安裝提示
+- `-y, --yes` - Use defaults, skip interactive prompts | 使用預設值，跳過互動提示
+
+**What it does | 功能說明:**
+1. Detects your project's language and framework
+2. Asks which standards to adopt
+3. Copies reference documents to `.standards/`
+4. Copies AI tool integrations (Cursor, Copilot, etc.)
+5. Creates `.standards/manifest.json` for tracking
+
+### `uds check`
+
+Check adoption status of current project. | 檢查當前專案的採用狀態。
+
+```bash
+uds check
+```
+
+**Output includes | 輸出內容:**
+- Installed version and level | 已安裝版本和等級
+- File integrity check | 檔案完整性檢查
+- Skills installation status | Skills 安裝狀態
+- Coverage summary | 涵蓋範圍摘要
+- Update availability | 更新可用性
+
+### `uds update`
+
+Update standards to the latest version. | 更新規範到最新版本。
+
+```bash
+# Interactive update
+uds update
+
+# Skip confirmation
+uds update --yes
+```
+
+**Options | 選項:**
+- `-y, --yes` - Skip confirmation prompts | 跳過確認提示
+
+## Adoption Levels | 採用等級
+
+| Level | Name | Description | 說明 |
+|-------|------|-------------|------|
+| 1 | Essential | Minimum viable standards | 最低可行標準 |
+| 2 | Recommended | Professional quality for teams | 團隊專業品質 |
+| 3 | Enterprise | Comprehensive standards | 全面企業標準 |
+
+## Categories | 類別
+
+| Category | Description | 說明 |
+|----------|-------------|------|
+| `skill` | Standards with Claude Code Skills | 包含 Skills 的規範 |
+| `reference` | Reference documents (no Skills) | 參考文件（無 Skills）|
+| `extension` | Language/framework-specific | 語言/框架特定 |
+| `integration` | AI tool configurations | AI 工具配置 |
+| `template` | Document templates | 文件模板 |
+
+## Example Workflow | 範例工作流程
+
+```bash
+# 1. Install CLI (one-time)
+npm install -g universal-dev-standards
+
+# 2. Navigate to your project
+cd my-project
+
+# 3. Initialize standards (interactive)
+uds init
+# ? Select adoption level: Level 2: Recommended
+# ? Detected PHP project. Select style guides: PHP Style Guide
+# ? Select AI tool integrations: Cursor, GitHub Copilot
+# ? Install Claude Code Skills? Yes
+
+# 4. Review what was created
+ls .standards/
+# checkin-standards.md
+# spec-driven-development.md
+# manifest.json
+
+# 5. Check status anytime
+uds check
+
+# 6. Update when new version is available
+uds update
+```
+
+## File Structure | 檔案結構
+
+After initialization, your project will have: | 初始化後，您的專案將包含：
+
+```
+your-project/
+├── .standards/
+│   ├── manifest.json        # Tracks what was installed
+│   ├── checkin-standards.md # Reference documents
+│   ├── spec-driven-development.md
+│   └── (other standards...)
+├── .cursorrules             # AI tool integrations
+├── .github/
+│   └── copilot-instructions.md
+└── ...
+```
+
+## Manifest File | 清單檔案
+
+The `.standards/manifest.json` tracks your adoption: | `.standards/manifest.json` 追蹤您的採用狀態：
+
+```json
+{
+  "version": "1.0.0",
+  "upstream": {
+    "repo": "AsiaOstrich/universal-dev-standards",
+    "version": "2.0.0",
+    "installed": "2025-12-23"
+  },
+  "level": 2,
+  "standards": ["core/checkin-standards.md", ...],
+  "extensions": ["extensions/languages/php-style.md"],
+  "integrations": [".cursorrules"],
+  "skills": {
+    "installed": true,
+    "version": "1.1.0"
+  }
+}
+```
+
+## Integration with Claude Code Skills | 與 Claude Code Skills 整合
+
+This CLI works alongside [universal-dev-skills](https://github.com/AsiaOstrich/universal-dev-skills):
+此 CLI 與 [universal-dev-skills](https://github.com/AsiaOstrich/universal-dev-skills) 配合使用：
+
+- **Skills** provide interactive AI assistance (commit messages, code review, etc.)
+- **Skills** 提供互動式 AI 協助（commit 訊息、程式碼審查等）
+- **Reference documents** provide guidelines for manual reference
+- **參考文件**提供手動參考的指南
+
+**Important | 重要**: For standards with Skills available, use the Skill OR copy the source document — never both.
+對於有可用 Skills 的規範，請使用 Skill 或複製來源文件 — 切勿兩者同時使用。
+
+## Related | 相關資源
+
+- [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards) - Source repository | 原始碼庫
+- [universal-dev-skills](https://github.com/AsiaOstrich/universal-dev-skills) - Claude Code Skills
+- [Adoption Guide](https://github.com/AsiaOstrich/universal-dev-standards/blob/main/adoption/ADOPTION-GUIDE.md) - Complete guidance | 完整指南
+
+---
+
+## Version History | 版本歷史
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 3.0.0 | 2025-12-30 | Published to npm, enhanced init with AI tools selection |
+| 1.0.1 | 2025-12-24 | Added: Bilingual support (English + Chinese) |
+| 1.0.0 | 2025-12-23 | Initial CLI documentation |
+
+---
+
+## License | 授權
+
+This project uses a **dual-license** model:
+本專案使用**雙授權**模式：
+
+| Content Type | License | 說明 |
+|-------------|---------|------|
+| Documentation (`*.md`) | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) | 文件 |
+| Code (`*.js`, etc.) | [MIT](https://opensource.org/licenses/MIT) | 程式碼 |

package/bin/uds.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+import { program } from 'commander';
+import { listCommand } from '../src/commands/list.js';
+import { initCommand } from '../src/commands/init.js';
+import { checkCommand } from '../src/commands/check.js';
+import { updateCommand } from '../src/commands/update.js';
+import { configureCommand } from '../src/commands/configure.js';
+
+program
+  .name('uds')
+  .description('CLI tool for adopting Universal Development Standards')
+  .version('3.0.0');
+
+program
+  .command('list')
+  .description('List available standards')
+  .option('-l, --level <level>', 'Filter by adoption level (1, 2, or 3)')
+  .option('-c, --category <category>', 'Filter by category (skill, reference, extension, integration, template)')
+  .action(listCommand);
+
+program
+  .command('init')
+  .description('Initialize standards in current project')
+  .option('-m, --mode <mode>', 'Installation mode (skills, full)')
+  .option('-l, --level <level>', 'Adoption level (1=Essential, 2=Recommended, 3=Enterprise)')
+  .option('-f, --format <format>', 'Standards format (ai, human, both)')
+  .option('--workflow <workflow>', 'Git workflow (github-flow, gitflow, trunk-based)')
+  .option('--merge-strategy <strategy>', 'Merge strategy (squash, merge-commit, rebase-ff)')
+  .option('--commit-lang <lang>', 'Commit message language (english, traditional-chinese, bilingual)')
+  .option('--test-levels <levels>', 'Test levels, comma-separated (unit-testing,integration-testing,...)')
+  .option('--lang <language>', 'Language extension (csharp, php)')
+  .option('--framework <framework>', 'Framework extension (fat-free)')
+  .option('--locale <locale>', 'Locale extension (zh-tw)')
+  .option('-y, --yes', 'Use defaults, skip interactive prompts')
+  .action(initCommand);
+
+program
+  .command('configure')
+  .alias('config')
+  .description('Modify options for initialized project')
+  .option('-t, --type <type>', 'Option type to configure (format, workflow, merge_strategy, commit_language, test_levels, all)')
+  .action(configureCommand);
+
+program
+  .command('check')
+  .description('Check adoption status of current project')
+  .action(checkCommand);
+
+program
+  .command('update')
+  .description('Update standards to latest version')
+  .option('-y, --yes', 'Skip confirmation prompts')
+  .action(updateCommand);
+
+program.parse();

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "universal-dev-standards",
+  "version": "3.0.0",
+  "description": "CLI tool for adopting Universal Development Standards",
+  "keywords": [
+    "documentation",
+    "standards",
+    "cli",
+    "developer-tools",
+    "best-practices"
+  ],
+  "author": "AsiaOstrich",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AsiaOstrich/universal-dev-standards.git",
+    "directory": "cli"
+  },
+  "homepage": "https://github.com/AsiaOstrich/universal-dev-standards#readme",
+  "bugs": {
+    "url": "https://github.com/AsiaOstrich/universal-dev-standards/issues"
+  },
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "uds": "bin/uds.js",
+    "universal-dev-standards": "bin/uds.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "standards-registry.json",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src/",
+    "prepare": "cd .. && husky cli/.husky"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "inquirer": "^9.2.12",
+    "ora": "^8.0.1"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.0.16",
+    "eslint": "^8.56.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^15.2.10",
+    "vitest": "^4.0.16"
+  },
+  "lint-staged": {
+    "src/**/*.js": [
+      "eslint --fix"
+    ]
+  }
+}

package/src/commands/check.js

@@ -0,0 +1,149 @@
+import chalk from 'chalk';
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { readManifest, isInitialized } from '../utils/copier.js';
+import {
+  getStandardsByLevel,
+  getLevelInfo,
+  getRepositoryInfo
+} from '../utils/registry.js';
+
+/**
+ * Check command - verify adoption status
+ */
+export function checkCommand() {
+  const projectPath = process.cwd();
+
+  console.log();
+  console.log(chalk.bold('Universal Documentation Standards - Check'));
+  console.log(chalk.gray('─'.repeat(50)));
+
+  // Check if initialized
+  if (!isInitialized(projectPath)) {
+    console.log(chalk.red('✗ Standards not initialized in this project.'));
+    console.log(chalk.gray('  Run `uds init` to initialize.'));
+    console.log();
+    return;
+  }
+
+  // Read manifest
+  const manifest = readManifest(projectPath);
+  if (!manifest) {
+    console.log(chalk.red('✗ Could not read manifest file.'));
+    console.log(chalk.gray('  The .standards/manifest.json may be corrupted.'));
+    console.log();
+    return;
+  }
+
+  // Display adoption info
+  const levelInfo = getLevelInfo(manifest.level);
+  const repoInfo = getRepositoryInfo();
+
+  console.log(chalk.green('✓ Standards initialized'));
+  console.log();
+  console.log(chalk.cyan('Adoption Status:'));
+  console.log(chalk.gray(`  Level: ${manifest.level} - ${levelInfo.name} (${levelInfo.nameZh})`));
+  console.log(chalk.gray(`  Installed: ${manifest.upstream.installed}`));
+  console.log(chalk.gray(`  Version: ${manifest.upstream.version}`));
+  console.log();
+
+  // Check for updates
+  if (manifest.upstream.version !== repoInfo.standards.version) {
+    console.log(chalk.yellow(`⚠ Update available: ${manifest.upstream.version} → ${repoInfo.standards.version}`));
+    console.log(chalk.gray('  Run `uds update` to update.'));
+    console.log();
+  }
+
+  // Check file integrity
+  console.log(chalk.cyan('File Integrity:'));
+
+  let missingCount = 0;
+  let presentCount = 0;
+
+  // Check standards
+  for (const std of manifest.standards) {
+    const filePath = join(projectPath, '.standards', std.split('/').pop());
+    if (existsSync(filePath)) {
+      presentCount++;
+    } else {
+      missingCount++;
+      console.log(chalk.red(`  ✗ Missing: .standards/${std.split('/').pop()}`));
+    }
+  }
+
+  // Check extensions
+  for (const ext of manifest.extensions) {
+    const filePath = join(projectPath, '.standards', ext.split('/').pop());
+    if (existsSync(filePath)) {
+      presentCount++;
+    } else {
+      missingCount++;
+      console.log(chalk.red(`  ✗ Missing: .standards/${ext.split('/').pop()}`));
+    }
+  }
+
+  // Check integrations
+  for (const int of manifest.integrations) {
+    const filePath = join(projectPath, int);
+    if (existsSync(filePath)) {
+      presentCount++;
+    } else {
+      missingCount++;
+      console.log(chalk.red(`  ✗ Missing: ${int}`));
+    }
+  }
+
+  if (missingCount === 0) {
+    console.log(chalk.green(`  ✓ All ${presentCount} files present`));
+  } else {
+    console.log(chalk.yellow(`  ${presentCount} present, ${missingCount} missing`));
+  }
+  console.log();
+
+  // Skills status
+  console.log(chalk.cyan('Skills Status:'));
+  if (manifest.skills.installed) {
+    const skillsDir = join(process.env.HOME || '', '.claude', 'skills');
+    const hasGlobalSkills = existsSync(skillsDir);
+    const hasProjectSkills = existsSync(join(projectPath, '.claude', 'skills'));
+
+    if (hasGlobalSkills || hasProjectSkills) {
+      console.log(chalk.green('  ✓ Claude Code Skills installed'));
+      if (hasGlobalSkills) console.log(chalk.gray('    Global: ~/.claude/skills/'));
+      if (hasProjectSkills) console.log(chalk.gray('    Project: .claude/skills/'));
+    } else {
+      console.log(chalk.yellow('  ⚠ Skills marked as installed but not found'));
+      console.log(chalk.gray('    Run: git clone https://github.com/AsiaOstrich/universal-dev-skills.git'));
+      console.log(chalk.gray('          cd universal-dev-skills && ./install.sh'));
+    }
+  } else {
+    console.log(chalk.gray('  Skills not installed (using reference documents only)'));
+  }
+  console.log();
+
+  // Coverage report
+  console.log(chalk.cyan('Coverage Summary:'));
+  const expectedStandards = getStandardsByLevel(manifest.level);
+  const skillStandards = expectedStandards.filter(s => s.skillName);
+  const refStandards = expectedStandards.filter(s => !s.skillName);
+
+  console.log(chalk.gray(`  Level ${manifest.level} requires ${expectedStandards.length} standards:`));
+  console.log(chalk.gray(`    ${skillStandards.length} with Skills (interactive AI assistance)`));
+  console.log(chalk.gray(`    ${refStandards.length} reference documents`));
+
+  const coveredBySkills = manifest.skills.installed ? skillStandards.length : 0;
+  const coveredByDocs = manifest.standards.length;
+
+  console.log(chalk.gray('  Your coverage:'));
+  console.log(chalk.gray(`    ${coveredBySkills} via Skills`));
+  console.log(chalk.gray(`    ${coveredByDocs} via copied documents`));
+  console.log();
+
+  // Final status
+  if (missingCount === 0 && (manifest.skills.installed || !manifest.skills.installed)) {
+    console.log(chalk.green('✓ Project is compliant with standards'));
+  } else {
+    console.log(chalk.yellow('⚠ Some issues detected. Review above for details.'));
+  }
+  console.log();
+}