@kodax-ai/kodax-cli 0.7.38

package/dist/builtin/skill-creator/scripts/utils.js

@@ -0,0 +1,278 @@
+#!/usr/bin/env node
+
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import YAML from 'yaml';
+
+// FEATURE_150 (v0.7.37, renamed v0.7.39) — KodaX SDK loader for builtin helper scripts.
+//
+// These helper scripts (run-eval.js / grade-evals.js / etc.) need access to
+// the runKodaX / estimateTokens API. The SDK lives in different places
+// depending on install mode:
+//
+//   1. Bundle-installed (npm install -g @kodax-ai/kodax-cli):
+//      this file → <prefix>/lib/node_modules/@kodax-ai/kodax-cli/dist/builtin-skills/skill-creator/scripts/utils.js
+//      SDK       → <prefix>/lib/node_modules/@kodax-ai/kodax-cli/dist/index.js
+//      Resolution: relative path '../../../index.js' (3 levels up from scripts/ to dist/)
+//
+//   2. Dev monorepo (npm run dev / direct invocation against built sub-packages):
+//      this file → <repo>/packages/skills/dist/builtin/skill-creator/scripts/utils.js
+//      SDK       → not at relative path; resolved via npm workspace symlink
+//      Resolution: bare-name `@kodax-ai/coding` (workspace alias works in this scope)
+//
+//   3. Path B SDK consumer (`npm install @kodax-ai/kodax-cli` in user project):
+//      this file would be inside their node_modules; same as case 1 layout.
+//
+// Legacy: v0.7.37/v0.7.38 published the bundle under `@kodax-ai/cli`. That
+// package is deprecated as of v0.7.39 (renamed to `@kodax-ai/kodax-cli`).
+// The Strategy 4 fallback below keeps `import('@kodax-ai/cli')` working for
+// any user still on the legacy installed version; remove the fallback when
+// no `@kodax-ai/cli` installs remain in the wild.
+//
+// See docs/HLD.md §12.4 risk 3 for the dist-layout contract.
+
+let _cachedSdk = null;
+
+export async function loadKodaXSDK() {
+  if (_cachedSdk) return _cachedSdk;
+
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const errors = [];
+
+  // Strategy 1: bundled install — relative path to dist/index.js
+  // Layout: dist/builtin-skills/<skill>/scripts/utils.js → ../../../index.js
+  const relSdkPath = path.resolve(here, '../../../index.js');
+  if (existsSync(relSdkPath)) {
+    _cachedSdk = await import(pathToFileURL(relSdkPath).href);
+    return _cachedSdk;
+  }
+  errors.push(`relative SDK path not found: ${relSdkPath}`);
+
+  // Strategy 2: dev monorepo — workspace symlink resolves bare name
+  try {
+    _cachedSdk = await import('@kodax-ai/coding');
+    return _cachedSdk;
+  } catch (err) {
+    errors.push(`bare-name @kodax-ai/coding failed: ${err?.code ?? err?.message}`);
+  }
+
+  // Strategy 3: bundled install via bare cli name (npm-installed CLI alongside)
+  try {
+    _cachedSdk = await import('@kodax-ai/kodax-cli');
+    return _cachedSdk;
+  } catch (err) {
+    errors.push(`bare-name @kodax-ai/kodax-cli failed: ${err?.code ?? err?.message}`);
+  }
+
+  // Strategy 4: legacy fallback for users still on @kodax-ai/cli installs
+  // (v0.7.37/v0.7.38). Will be removed after a reasonable deprecation window.
+  try {
+    _cachedSdk = await import('@kodax-ai/cli');
+    return _cachedSdk;
+  } catch (err) {
+    errors.push(`bare-name @kodax-ai/cli (legacy) failed: ${err?.code ?? err?.message}`);
+  }
+
+  throw new Error(
+    `Cannot locate KodaX SDK from helper script ${import.meta.url}.\nAttempted:\n  - ${errors.join('\n  - ')}`,
+  );
+}
+
+export function toPosixPath(filePath) {
+  return filePath.replace(/\\/g, '/');
+}
+
+export function extractFrontmatter(rawContent) {
+  const normalized = rawContent
+    .replace(/^\uFEFF/, '')
+    .replace(/\r\n/g, '\n')
+    .replace(/\r/g, '\n')
+    .trimStart();
+
+  if (!normalized.startsWith('---\n')) {
+    throw new Error('SKILL.md missing YAML frontmatter');
+  }
+
+  const closeIndex = normalized.indexOf('\n---\n', 4);
+  if (closeIndex === -1) {
+    throw new Error('SKILL.md has unclosed YAML frontmatter');
+  }
+
+  return {
+    yamlText: normalized.slice(4, closeIndex),
+    body: normalized.slice(closeIndex + 5).trim(),
+  };
+}
+
+export function parseSkillMarkdown(rawContent) {
+  const { yamlText, body } = extractFrontmatter(rawContent);
+  const frontmatter = YAML.parse(yamlText);
+
+  if (!frontmatter || typeof frontmatter !== 'object' || Array.isArray(frontmatter)) {
+    throw new Error('Frontmatter must be a YAML object');
+  }
+
+  return {
+    frontmatter,
+    body,
+  };
+}
+
+export async function loadSkill(skillDir) {
+  const skillMdPath = path.join(skillDir, 'SKILL.md');
+  const info = await stat(skillMdPath).catch(() => null);
+  if (!info?.isFile()) {
+    throw new Error(`SKILL.md not found in ${skillDir}`);
+  }
+
+  const rawContent = await readFile(skillMdPath, 'utf8');
+  const { frontmatter, body } = parseSkillMarkdown(rawContent);
+
+  return {
+    skillDir: path.resolve(skillDir),
+    skillMdPath,
+    rawContent,
+    body,
+    frontmatter,
+  };
+}
+
+export async function writeSkill(skillDir, frontmatter, body) {
+  const skillMdPath = path.join(skillDir, 'SKILL.md');
+  const yamlText = YAML.stringify(frontmatter).trimEnd();
+  const content = `---\n${yamlText}\n---\n\n${body.trim()}\n`;
+  await writeFile(skillMdPath, content, 'utf8');
+}
+
+export async function pathExists(targetPath) {
+  try {
+    await stat(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function calculateStats(values) {
+  if (!values.length) {
+    return { mean: 0, stddev: 0, min: 0, max: 0 };
+  }
+
+  const mean = values.reduce((sum, value) => sum + value, 0) / values.length;
+  const variance = values.length > 1
+    ? values.reduce((sum, value) => sum + ((value - mean) ** 2), 0) / (values.length - 1)
+    : 0;
+
+  return {
+    mean: roundNumber(mean),
+    stddev: roundNumber(Math.sqrt(variance)),
+    min: roundNumber(Math.min(...values)),
+    max: roundNumber(Math.max(...values)),
+  };
+}
+
+export function roundNumber(value, digits = 4) {
+  return Number(value.toFixed(digits));
+}
+
+export function formatDelta(value) {
+  return value >= 0 ? `+${value.toFixed(4)}` : value.toFixed(4);
+}
+
+export function extractTaggedText(text, tagName) {
+  const pattern = new RegExp(`<${tagName}>([\\s\\S]*?)<\\/${tagName}>`, 'i');
+  const match = text.match(pattern);
+  return match?.[1]?.trim() ?? null;
+}
+
+export function safeJsonParse(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+export function extractJsonObject(text) {
+  const direct = safeJsonParse(text.trim());
+  if (direct && typeof direct === 'object') {
+    return direct;
+  }
+
+  const firstBrace = text.indexOf('{');
+  const lastBrace = text.lastIndexOf('}');
+  if (firstBrace === -1 || lastBrace === -1 || lastBrace <= firstBrace) {
+    return null;
+  }
+
+  return safeJsonParse(text.slice(firstBrace, lastBrace + 1));
+}
+
+export async function readJsonFile(filePath, fallback = null) {
+  try {
+    return JSON.parse(await readFile(filePath, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+export async function loadRelativeText(moduleUrl, relativePath) {
+  const moduleDir = path.dirname(fileURLToPath(moduleUrl));
+  return readFile(path.resolve(moduleDir, relativePath), 'utf8');
+}
+
+export function truncateText(text, maxChars = 12000) {
+  const value = typeof text === 'string' ? text : String(text ?? '');
+  if (value.length <= maxChars) {
+    return value;
+  }
+
+  const hiddenChars = value.length - maxChars;
+  return `${value.slice(0, maxChars)}\n\n[truncated ${hiddenChars} chars]`;
+}
+
+export function computePassSummary(expectations) {
+  const total = Array.isArray(expectations) ? expectations.length : 0;
+  const passed = Array.isArray(expectations)
+    ? expectations.filter((item) => item?.passed === true).length
+    : 0;
+  const failed = Math.max(total - passed, 0);
+
+  return {
+    passed,
+    failed,
+    total,
+    pass_rate: total > 0 ? roundNumber(passed / total) : 0,
+  };
+}
+
+export async function collectFiles(rootDir, currentDir = rootDir, files = []) {
+  const entries = await readdir(currentDir, { withFileTypes: true }).catch(() => []);
+  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+    const absolutePath = path.join(currentDir, entry.name);
+    if (entry.isDirectory()) {
+      await collectFiles(rootDir, absolutePath, files);
+      continue;
+    }
+    if (!entry.isFile()) {
+      continue;
+    }
+    files.push({
+      absolutePath,
+      relativePath: path.relative(rootDir, absolutePath).replace(/\\/g, '/'),
+    });
+  }
+  return files;
+}
+
+export function getDefaultSkillsDir() {
+  return path.join(os.homedir(), '.kodax', 'skills');
+}
+
+export async function ensureDirectory(targetPath) {
+  await mkdir(targetPath, { recursive: true });
+  return targetPath;
+}

package/dist/builtin/tdd/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: tdd
+description: 用测试驱动开发方式实现或修复功能：先写失败测试，再做最小实现，最后重构。只在用户明确要求 TDD、先写测试、补回归测试或按 Red-Green-Refactor 工作时使用；不要用于单纯解释测试报错或泛泛讨论测试概念。
+user-invocable: true
+disable-model-invocation: true
+allowed-tools: "Read, Grep, Glob, Write, Edit, Bash(npm:*, node:*, npx:*, vitest:*, jest:*, pytest:*)"
+argument-hint: "[file-or-description]"
+compatibility: "Works best in repositories with an existing test runner and established test conventions."
+---
+
+# TDD (Test-Driven Development) Skill
+
+按小步快跑的 Red -> Green -> Refactor 循环工作，优先建立可复现的行为保护，再修改实现。
+
+## 开始前
+
+- 根据 `$ARGUMENTS` 明确目标行为、bug 场景或待实现功能。
+- 先读现有实现、相邻测试和项目约定，优先沿用仓库已有的测试框架、fixture 和命名方式。
+- 如果用户只要求“补测试”而没有要求改实现，就停在测试层，不主动改生产代码。
+
+## RED
+
+1. 写能暴露目标行为的最小失败测试。
+2. 对 bug 修复，先写复现 bug 的回归测试。
+3. 优先运行最小测试范围，确认它确实失败，并说明失败证明了什么。
+
+## GREEN
+
+1. 只做让新测试通过所需的最小实现改动。
+2. 先重跑刚刚失败的测试；必要时再补跑相邻测试。
+3. 不为了“顺手优化”扩大改动面。
+
+## REFACTOR
+
+1. 在测试保护下整理命名、消除重复、简化实现。
+2. 任何重构后都重新运行相关测试，确保行为不变。
+3. 只有在改动面较大或用户明确要求时，才扩大到更完整的测试集。
+
+## 工作准则
+
+- 优先断言对外可观察行为，而不是内部实现细节。
+- 新增测试尽量贴近现有测试文件；只有在必要时才创建新文件。
+- 如果仓库没有测试基础设施，先说明现状，再决定是补最小配置还是只给出建议。
+- 不要把覆盖率数字当成目标；以行为信心和回归保护为准。
+
+## 汇报方式
+
+- 使用 `## RED`、`## GREEN`、`## REFACTOR` 三段汇报。
+- 说明修改了哪些测试文件、哪些实现文件，以及运行了哪些测试命令。
+- 最后补充剩余风险、未覆盖场景或后续建议。
+
+## 使用示例
+
+- `/tdd src/utils/format.ts` - 为 format.ts 编写测试
+- `/tdd add user validation` - 实现用户验证功能 (TDD 方式)
+- `/tdd` - 为当前 git 变更编写测试