universal-dev-standards 5.1.0-beta.6 → 5.1.0-beta.7

package/src/commands/init.js

@@ -177,18 +177,22 @@ export async function initCommand(options) {
 }
 
 /**
- * Configure Husky pre-commit hook
+ * Configure pre-commit hook (language-aware)
+ * - Node.js projects: use husky
+ * - Non-Node.js projects: write native .git/hooks/pre-commit
  */
 async function setupHuskyHook(projectPath) {
   const hasGit = existsSync(join(projectPath, '.git'));
   if (!hasGit) return;
 
-  console.log(chalk.cyan('Configuring Pre-commit Hook (Husky)...'));
+  const isNodeProject = existsSync(join(projectPath, 'package.json'));
 
-  // 1. Install husky if needed
-  try {
-    const pkgPath = join(projectPath, 'package.json');
-    if (existsSync(pkgPath)) {
+  if (isNodeProject) {
+    console.log(chalk.cyan('Configuring Pre-commit Hook (Husky)...'));
+
+    // 1. Install husky if needed
+    try {
+      const pkgPath = join(projectPath, 'package.json');
       const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
       const hasHusky = pkg.devDependencies?.husky || pkg.dependencies?.husky;
 
@@ -196,59 +200,100 @@ async function setupHuskyHook(projectPath) {
         console.log(chalk.gray('  Installing husky...'));
         execSync('npm install --save-dev husky', { stdio: 'ignore', cwd: projectPath });
       }
+    } catch (e) {
+      console.log(chalk.yellow(`  ⚠ Failed to check/install husky: ${e.message}`));
+      return;
     }
-  } catch (e) {
-    console.log(chalk.yellow(`  ⚠ Failed to check/install husky: ${e.message}`));
-    return;
-  }
 
-  // 2. Initialize husky
-  const huskyDir = join(projectPath, '.husky');
-  try {
+    // 2. Initialize husky
+    const huskyDir = join(projectPath, '.husky');
+    try {
+      if (!existsSync(huskyDir)) {
+        console.log(chalk.gray('  Initializing husky...'));
+        execSync('npx husky init', { stdio: 'ignore', cwd: projectPath });
+      }
+    } catch (e) {
+      // Ignore, might already be init
+    }
+
+    // 3. Ensure .husky directory exists (fallback if husky init failed)
     if (!existsSync(huskyDir)) {
-       console.log(chalk.gray('  Initializing husky...'));
-       execSync('npx husky init', { stdio: 'ignore', cwd: projectPath });
+      try {
+        mkdirSync(huskyDir, { recursive: true });
+      } catch (e) {
+        console.log(chalk.red(`  ✗ Failed to create .husky directory: ${e.message}`));
+        return;
+      }
     }
-  } catch (e) {
-     // Ignore, might already be init
-  }
 
-  // 3. Ensure .husky directory exists (fallback if husky init failed)
-  if (!existsSync(huskyDir)) {
+    // 4. Add pre-commit hook
+    const preCommitPath = join(huskyDir, 'pre-commit');
+    const udsCmd = 'npx uds check';
+
     try {
-      mkdirSync(huskyDir, { recursive: true });
+      let content = '';
+      if (existsSync(preCommitPath)) {
+        content = readFileSync(preCommitPath, 'utf-8');
+      } else {
+        // Create if not exists (husky init usually creates it, but just in case)
+        content = '#!/usr/bin/env sh\n. "$(dirname -- "$0")/_/husky.sh"\n';
+      }
+
+      if (!content.includes('uds check')) {
+        writeFileSync(preCommitPath, content + `\n# UDS Standard Check\n${udsCmd}\n`, 'utf-8');
+        try {
+          execSync(`chmod +x ${preCommitPath}`);
+        } catch (e) {
+          // Ignore chmod failures on systems that don't support it
+        }
+        console.log(chalk.green('  ✓ Adding uds check to pre-commit hook'));
+      } else {
+        console.log(chalk.gray('  ✓ Pre-commit hook already configured'));
+      }
     } catch (e) {
-      console.log(chalk.red(`  ✗ Failed to create .husky directory: ${e.message}`));
-      return;
+      console.log(chalk.red(`  ✗ Failed to configure pre-commit hook: ${e.message}`));
     }
-  }
+  } else {
+    // Non-Node.js: write native .git/hooks/pre-commit
+    console.log(chalk.cyan('Configuring Pre-commit Hook (native git hook)...'));
 
-  // 4. Add pre-commit hook
-  const preCommitPath = join(huskyDir, 'pre-commit');
-  const udsCmd = 'npx uds check';
+    const hookDir = join(projectPath, '.git', 'hooks');
+    const hookPath = join(hookDir, 'pre-commit');
 
-  try {
-    let content = '';
-    if (existsSync(preCommitPath)) {
-      content = readFileSync(preCommitPath, 'utf-8');
-    } else {
-      // Create if not exists (husky init usually creates it, but just in case)
-      content = '#!/usr/bin/env sh\n. "$(dirname -- "$0")/_/husky.sh"\n';
-    }
+    try {
+      if (!existsSync(hookDir)) {
+        mkdirSync(hookDir, { recursive: true });
+      }
 
-    if (!content.includes('uds check')) {
-      writeFileSync(preCommitPath, content + `\n# UDS Standard Check\n${udsCmd}\n`, 'utf-8');
-      try {
-        execSync(`chmod +x ${preCommitPath}`);
-      } catch (e) {
-        // Ignore chmod failures on systems that don't support it
+      if (existsSync(hookPath) && readFileSync(hookPath, 'utf-8').includes('uds check')) {
+        console.log(chalk.gray('  ✓ Pre-commit hook already configured'));
+      } else {
+        const hookContent = `#!/bin/sh
+# UDS pre-commit hook
+# Auto-generated by uds init
+
+echo "Running UDS pre-commit checks..."
+
+# Run lint if available
+if [ -f pyproject.toml ] || [ -f requirements.txt ]; then
+  python -m ruff check . 2>/dev/null || true
+elif [ -f go.mod ]; then
+  go vet ./... 2>/dev/null || true
+elif [ -f Cargo.toml ]; then
+  cargo clippy 2>/dev/null || true
+fi
+
+# UDS Standard Check
+uds check 2>/dev/null || true
+
+echo "Pre-commit checks passed"
+`;
+        writeFileSync(hookPath, hookContent, { mode: 0o755 });
+        console.log(chalk.green('  ✓ Installed .git/hooks/pre-commit (native git hook)'));
       }
-      console.log(chalk.green('  ✓ Adding uds check to pre-commit hook'));
-    } else {
-      console.log(chalk.gray('  ✓ Pre-commit hook already configured'));
+    } catch (e) {
+      console.log(chalk.red(`  ✗ Failed to configure pre-commit hook: ${e.message}`));
     }
-  } catch (e) {
-    console.log(chalk.red(`  ✗ Failed to configure pre-commit hook: ${e.message}`));
   }
   console.log();
 }

package/src/commands/mcp.js

@@ -0,0 +1,26 @@
+/**
+ * uds mcp - MCP server subcommands for AI tool integration
+ */
+
+import { McpServer } from '../mcp/server.js';
+
+/**
+ * Register the `mcp` command group on the given Commander program
+ * @param {import('commander').Command} program
+ */
+export function mcpCommand(program) {
+  const mcp = program
+    .command('mcp')
+    .description('MCP server commands for AI tool integration');
+
+  mcp
+    .command('serve')
+    .description('Start MCP Design Standards Server (stdio transport)')
+    .option('--root <path>', 'UDS standards root path', process.cwd())
+    .action((options) => {
+      const server = new McpServer({ udsRoot: options.root });
+      server.start();
+      // Log to stderr only — stdout is reserved for MCP JSON-RPC messages
+      process.stderr.write('UDS MCP Design Standards Server started (stdio)\n');
+    });
+}

package/src/commands/run-intent.js

@@ -0,0 +1,66 @@
+/**
+ * run-intent command — uds run <intent>
+ * Unified proxy: resolves intent to actual command via command-router
+ * XSPEC-029
+ */
+import chalk from 'chalk';
+import { execSync } from 'child_process';
+import { resolveCommand } from '../core/command-router.js';
+
+const KNOWN_INTENTS = ['test', 'lint', 'build', 'security'];
+
+export async function runIntentCommand(intent, options = {}) {
+  const projectPath = process.cwd();
+
+  if (!intent) {
+    console.log(chalk.yellow('使用方式: uds run <intent>'));
+    console.log(chalk.gray(`可用 intent: ${KNOWN_INTENTS.join(', ')}`));
+    console.log(chalk.gray('自訂 intent 可在 uds.project.yaml 的 custom: 區塊定義'));
+    return;
+  }
+
+  let resolved;
+  try {
+    resolved = resolveCommand(intent, projectPath);
+  } catch (err) {
+    console.error(chalk.red(`✗ 讀取 uds.project.yaml 失敗：${err.message}`));
+    process.exit(1);
+  }
+
+  if (!resolved) {
+    console.log();
+    console.log(chalk.yellow(`⚠️  無法解析 intent "${intent}" 的執行命令`));
+    console.log();
+    console.log(chalk.gray('解決方式：'));
+    console.log(chalk.gray('  1. 執行 uds configure 建立 uds.project.yaml'));
+    console.log(chalk.gray('  2. 或在專案根目錄建立含 test:/lint: target 的 Makefile'));
+    console.log(chalk.gray('  3. 或手動建立 uds.project.yaml：'));
+    console.log(chalk.gray(''));
+    console.log(chalk.gray('     version: "1"'));
+    console.log(chalk.gray('     commands:'));
+    console.log(chalk.gray(`       ${intent}: <your command here>`));
+    console.log();
+    process.exit(1);
+  }
+
+  const sourceLabel = {
+    'uds.project.yaml': chalk.green('uds.project.yaml'),
+    'convention-runner': chalk.cyan('Makefile/justfile'),
+  }[resolved.source] ?? chalk.gray(`fallback:${resolved.source.split(':')[1] ?? resolved.source}`);
+
+  console.log();
+  console.log(`${chalk.bold('uds run')} ${chalk.cyan(intent)}  ${chalk.gray('←')} ${sourceLabel}`);
+  console.log(chalk.gray(`$ ${resolved.command}`));
+  console.log();
+
+  if (options.dryRun) {
+    console.log(chalk.yellow('(dry-run mode — 未實際執行)'));
+    return;
+  }
+
+  try {
+    execSync(resolved.command, { stdio: 'inherit', cwd: projectPath });
+  } catch (err) {
+    process.exit(err.status ?? 1);
+  }
+}

package/src/commands/update.js

@@ -128,6 +128,34 @@ function compareVersions(v1, v2) {
   return 0;
 }
 
+/**
+ * Detect the global package manager used to install UDS.
+ * Checks npm_execpath env var first, then falls back to lock-file detection.
+ */
+function detectGlobalPackageManager() {
+  // npm_execpath is set by npm/yarn/pnpm when running scripts
+  const execPath = process.env.npm_execpath || '';
+  if (execPath.includes('yarn')) return 'yarn';
+  if (execPath.includes('pnpm')) return 'pnpm';
+
+  // Check if running under bun
+  if (process.versions?.bun) return 'bun';
+
+  return 'npm'; // default
+}
+
+/**
+ * Build the global install command for universal-dev-standards.
+ */
+function buildInstallCommand(pm, tag) {
+  switch (pm) {
+    case 'yarn': return `yarn global add universal-dev-standards${tag}`;
+    case 'pnpm': return `pnpm add -g universal-dev-standards${tag}`;
+    case 'bun':  return `bun install -g universal-dev-standards${tag}`;
+    default:     return `npm install -g universal-dev-standards${tag}`;
+  }
+}
+
 /**
  * Update CLI to latest version and prompt user to re-run
  * @param {boolean} useBeta - Whether to install beta version
@@ -139,9 +167,9 @@ async function updateCliAndExit(useBeta = false) {
   try {
     // Command is hardcoded - no user input, safe from injection
     const tag = useBeta ? '@beta' : '@latest';
-    execSync(`npm install -g universal-dev-standards${tag}`, {
-      stdio: 'pipe'
-    });
+    const pm = detectGlobalPackageManager();
+    const installCmd = buildInstallCommand(pm, tag);
+    execSync(installCmd, { stdio: 'pipe' });
 
     spinner.succeed(msg.cliUpdated);
     console.log();
@@ -152,7 +180,10 @@ async function updateCliAndExit(useBeta = false) {
     spinner.fail(msg.cliUpdateFailed);
     console.log(chalk.yellow(`  ${msg.permissionIssue}`));
     console.log(chalk.gray(`  ${msg.tryManually}`));
-    console.log(chalk.white(`    sudo npm install -g universal-dev-standards${useBeta ? '@beta' : ''}`));
+    const pm = detectGlobalPackageManager();
+    const manualTag = useBeta ? '@beta' : '';
+    console.log(chalk.white(`    ${buildInstallCommand(pm, manualTag)}`));
+    console.log(chalk.gray(`    (or: npm install -g universal-dev-standards${manualTag})`));
     console.log();
     process.exit(1);
   }

package/src/core/command-router.js

@@ -0,0 +1,85 @@
+/**
+ * Command Router — resolves an intent to an executable command
+ * Priority: uds.project.yaml → Makefile/justfile/taskfile → ecosystem detection → guide
+ * XSPEC-029
+ */
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { loadProjectConfig, getCommand } from './project-config.js';
+
+// Ecosystem defaults (from XSPEC-028)
+const ECOSYSTEM_DEFAULTS = {
+  node:        { test: 'npm test', lint: 'npm run lint', build: 'npm run build', security: 'npm audit' },
+  python:      { test: 'python -m pytest', lint: 'python -m ruff check .', build: 'python -m build', security: 'pip-audit' },
+  go:          { test: 'go test ./...', lint: 'go vet ./...', build: 'go build ./...', security: 'govulncheck ./...' },
+  java_maven:  { test: 'mvn test', lint: 'mvn checkstyle:check', build: 'mvn package', security: 'mvn dependency-check:check' },
+  java_gradle: { test: './gradlew test', lint: './gradlew checkstyleMain', build: './gradlew build', security: './gradlew dependencyCheckAnalyze' },
+  rust:        { test: 'cargo test', lint: 'cargo clippy', build: 'cargo build', security: 'cargo audit' },
+  ruby:        { test: 'bundle exec rspec', lint: 'bundle exec rubocop', build: 'gem build *.gemspec', security: 'bundle audit' },
+};
+
+/**
+ * Detect the project ecosystem from manifest files.
+ * Returns an ecosystem key or 'unknown'.
+ */
+function detectEcosystem(projectPath) {
+  const has = (f) => existsSync(join(projectPath, f));
+  if (has('package.json'))                          return 'node';
+  if (has('requirements.txt') || has('pyproject.toml') || has('setup.py')) return 'python';
+  if (has('go.mod'))                                return 'go';
+  if (has('pom.xml'))                               return 'java_maven';
+  if (has('build.gradle') || has('build.gradle.kts')) return 'java_gradle';
+  if (has('Cargo.toml'))                            return 'rust';
+  if (has('Gemfile'))                               return 'ruby';
+  return 'unknown';
+}
+
+/**
+ * Check if a Makefile (or justfile/taskfile) has a target for the given intent.
+ */
+function findConventionRunner(projectPath, intent) {
+  const has = (f) => existsSync(join(projectPath, f));
+
+  if (has('Makefile')) {
+    const content = readFileSync(join(projectPath, 'Makefile'), 'utf8');
+    const pattern = new RegExp(`^${intent}\\s*:`, 'm');
+    if (pattern.test(content)) return `make ${intent}`;
+  }
+  if (has('justfile') || has('.justfile')) {
+    const file = has('justfile') ? 'justfile' : '.justfile';
+    const content = readFileSync(join(projectPath, file), 'utf8');
+    const pattern = new RegExp(`^${intent}\\s*:`, 'm');
+    if (pattern.test(content)) return `just ${intent}`;
+  }
+  if (has('Taskfile.yml') || has('taskfile.yml')) {
+    return `task ${intent}`;
+  }
+  return null;
+}
+
+/**
+ * Resolve a command intent to an executable command string.
+ * Returns { command, source } where source describes which layer resolved it.
+ * Returns null if unresolvable (caller should trigger configure guidance).
+ */
+export function resolveCommand(intent, projectPath = '.') {
+  // Layer 1: uds.project.yaml
+  // loadProjectConfig throws on invalid config — let it propagate to caller
+  const config = loadProjectConfig(projectPath);
+  const cmd = getCommand(config, intent);
+  if (cmd) return { command: cmd, source: 'uds.project.yaml' };
+
+  // Layer 2: Convention task runners (Makefile / justfile / taskfile)
+  const conventionCmd = findConventionRunner(projectPath, intent);
+  if (conventionCmd) return { command: conventionCmd, source: 'convention-runner' };
+
+  // Layer 3: Ecosystem detection fallback
+  const ecosystem = detectEcosystem(projectPath);
+  if (ecosystem !== 'unknown') {
+    const cmd = ECOSYSTEM_DEFAULTS[ecosystem]?.[intent];
+    if (cmd) return { command: cmd, source: `ecosystem-fallback:${ecosystem}` };
+  }
+
+  // Layer 4: Unresolvable
+  return null;
+}

package/src/core/project-config.js

@@ -0,0 +1,91 @@
+/**
+ * Project Command Contract — reads and validates uds.project.yaml
+ * XSPEC-029
+ */
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+const CONFIG_FILENAME = 'uds.project.yaml';
+
+/**
+ * Parse uds.project.yaml from the given project path.
+ * Returns null if the file does not exist.
+ * Throws if the file exists but is invalid.
+ */
+export function loadProjectConfig(projectPath = '.') {
+  const configPath = join(projectPath, CONFIG_FILENAME);
+  if (!existsSync(configPath)) return null;
+
+  const raw = readFileSync(configPath, 'utf8');
+
+  // Minimal YAML parser for the simple key: value structure we need.
+  // We deliberately avoid a heavy dependency — uds.project.yaml is intentionally simple.
+  const config = parseMinimalYaml(raw, configPath);
+  validateConfig(config, configPath);
+  return config;
+}
+
+/**
+ * Parse a minimal YAML subset sufficient for uds.project.yaml.
+ * Supports: top-level scalars, one-level nested mappings (commands:, custom:).
+ */
+function parseMinimalYaml(raw, _filePath) {
+  const lines = raw.split('\n');
+  const result = {};
+  let currentSection = null;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trimEnd();
+
+    // Skip blank lines and comments
+    if (!trimmed || trimmed.trimStart().startsWith('#')) continue;
+
+    const indent = line.length - line.trimStart().length;
+
+    if (indent === 0) {
+      // Top-level key
+      const match = trimmed.match(/^([a-zA-Z_][a-zA-Z0-9_-]*):\s*(.*)$/);
+      if (!match) continue;
+      const [, key, value] = match;
+      if (value.trim()) {
+        result[key] = value.trim().replace(/^["']|["']$/g, '');
+        currentSection = null;
+      } else {
+        result[key] = {};
+        currentSection = key;
+      }
+    } else if (currentSection && indent > 0) {
+      // Nested key under current section
+      const match = trimmed.trim().match(/^([a-zA-Z_][a-zA-Z0-9_-]*):\s*(.*)$/);
+      if (!match) continue;
+      const [, key, value] = match;
+      result[currentSection][key] = value.trim().replace(/^["']|["']$/g, '');
+    }
+  }
+
+  return result;
+}
+
+function validateConfig(config, filePath) {
+  if (!config.version) {
+    throw new Error(
+      `${filePath}: missing required field "version". ` +
+      'Add "version: \\"1\\"" at the top of the file.'
+    );
+  }
+  if (config.commands && typeof config.commands !== 'object') {
+    throw new Error(`${filePath}: "commands" must be a mapping of intent: command pairs.`);
+  }
+}
+
+/**
+ * Get a specific command intent from config.
+ * Returns undefined if not configured.
+ */
+export function getCommand(config, intent) {
+  if (!config) return undefined;
+  return config.commands?.[intent] ?? config.custom?.[intent];
+}
+
+export { CONFIG_FILENAME };

package/src/flows/init-flow.js

@@ -13,7 +13,8 @@ import {
   promptCommandsInstallation,
   handleAgentsMdSharing,
   promptAgentsMd,
-  promptReleaseMode
+  promptReleaseMode,
+  promptProjectContractStep
 } from '../prompts/init.js';
 import {
   promptIntegrationConfig
@@ -237,6 +238,10 @@ export async function runInitFlow(options, detected, projectPath) {
   skillsConfig.methodology = methodology;
   skillsConfig.locale = displayLanguageToLocale(displayLanguage);
 
+  // === STEP 13: Project Command Contract (uds.project.yaml) — XSPEC-029 Phase 3 ===
+  // Optional step — skippable by answering "n" or pressing Ctrl+C.
+  await promptProjectContractStep(projectPath);
+
   return {
     languages,
     frameworks,

package/src/i18n/messages.js

@@ -18,7 +18,7 @@ export const messages = {
     // Update Notice
     updateNotice: {
       header: 'Update available',
-      command: 'npm update -g universal-dev-standards',
+      command: 'npm update -g universal-dev-standards (or: yarn global upgrade / pnpm update -g)',
       disableHint: 'Set UDS_NO_UPDATE_CHECK=1 to disable'
     },
 
@@ -887,7 +887,7 @@ export const messages = {
         currentCli: 'Current CLI',
         latestOnNpm: 'Latest on npm',
         latestStable: 'Latest stable',
-        runNpmUpdate: 'Run: npm update -g universal-dev-standards',
+        runNpmUpdate: 'Run: npm update -g universal-dev-standards  (or: yarn global upgrade / pnpm update -g)',
         // Final status
         projectCompliant: '✓ Project is compliant with standards',
         issuesDetected: '⚠ Some issues detected. Review above for details.',
@@ -1278,7 +1278,7 @@ export const messages = {
     // 更新通知
     updateNotice: {
       header: '有新版本可用',
-      command: 'npm update -g universal-dev-standards',
+      command: 'npm update -g universal-dev-standards（或 yarn global upgrade / pnpm update -g）',
       disableHint: '設定 UDS_NO_UPDATE_CHECK=1 可關閉'
     },
 
@@ -2147,7 +2147,7 @@ export const messages = {
         currentCli: '目前 CLI',
         latestOnNpm: 'npm 最新版本',
         latestStable: '最新穩定版',
-        runNpmUpdate: '執行：npm update -g universal-dev-standards',
+        runNpmUpdate: '執行：npm update -g universal-dev-standards（或 yarn global upgrade / pnpm update -g）',
         // Final status
         projectCompliant: '✓ 專案符合標準',
         issuesDetected: '⚠ 偵測到一些問題。請檢視上方詳情。',
@@ -2538,7 +2538,7 @@ export const messages = {
     // 更新通知
     updateNotice: {
       header: '有新版本可用',
-      command: 'npm update -g universal-dev-standards',
+      command: 'npm update -g universal-dev-standards（或 yarn global upgrade / pnpm update -g）',
       disableHint: '设置 UDS_NO_UPDATE_CHECK=1 可关闭'
     },
 
@@ -3420,7 +3420,7 @@ export const messages = {
         currentCli: '当前 CLI',
         latestOnNpm: 'npm 最新版本',
         latestStable: '最新稳定版',
-        runNpmUpdate: '执行：npm update -g universal-dev-standards',
+        runNpmUpdate: '执行：npm update -g universal-dev-standards（或 yarn global upgrade / pnpm update -g）',
         // Final status
         projectCompliant: '✓ 项目符合标准',
         issuesDetected: '⚠ 检测到一些问题。详情请查看上文。',