@skillit/client 0.2.0 → 0.3.1

package/src/commands/refine.ts

@@ -1,261 +0,0 @@
-// packages/client/src/commands/refine.ts
-import { Command } from 'commander';
-import {
-  McpRefineSource,
-  TypeScriptMcpRefineSource,
-  extractMcpSkill,
-  readMcpConfigFile
-} from '@skillit/mcp';
-import { CliRefineSource, loadProgram } from '@skillit/cli';
-import { refineSkill, type ModelClient, type RefineSource } from '@skillit/core';
-import { createModelClient } from '../model/model-client-factory.js';
-import { detectRefineMode } from '../detect-mode.js';
-import {
-  classifyRefineSources,
-  detectInstalledSources,
-  type DetectedRefineSource,
-  type RefineSourceKind
-} from '../detect-source.js';
-import { join } from 'node:path';
-
-function parsePositiveInt(raw: string, flag: string): number {
-  const n = parseInt(raw, 10);
-  if (!Number.isFinite(n) || n < 1) {
-    throw new Error(`${flag} must be a positive integer, got: ${raw}`);
-  }
-  return n;
-}
-
-/** Options consulted by {@link resolveRefineSource}. */
-export interface RefineSourceResolveOpts {
-  source?: string;
-  mcp?: string;
-}
-
-/** Result of resolving the refine source: a concrete kind or an actionable error. */
-export type RefineSourceResolution = { kind: 'cli' | 'mcp' } | { error: string };
-
-const VALID_SOURCES = ['cli', 'mcp', 'typedoc'] as const;
-const SOURCE_FORM = '--source <cli|mcp|typedoc>';
-
-/**
- * Resolve the refine source from explicit `--source` (wins) or detection,
- * then validate per-source flag requirements. Pure and unit-testable: it does
- * not read the filesystem or invoke the model.
- *
- * @param opts - parsed `--source` / `--mcp` flags
- * @param detected - result of {@link detectRefineSource} for the cwd
- * @param candidates - the raw installed source kinds (from
- *   {@link detectInstalledSources}); named in the ambiguous error
- */
-export function resolveRefineSource(
-  opts: RefineSourceResolveOpts,
-  detected: DetectedRefineSource,
-  candidates: readonly RefineSourceKind[] = []
-): RefineSourceResolution {
-  let kind: RefineSourceKind;
-  if (opts.source !== undefined) {
-    if (!VALID_SOURCES.includes(opts.source as RefineSourceKind)) {
-      return { error: `Invalid --source value: ${opts.source}. Use ${SOURCE_FORM}.` };
-    }
-    kind = opts.source as RefineSourceKind;
-  } else if (detected === 'ambiguous') {
-    return {
-      error: `Cannot determine refine source: multiple @skillit sources installed (found: ${candidates.join(', ')}).
-Pass ${SOURCE_FORM} to choose one.`
-    };
-  } else if (detected === 'none') {
-    return {
-      error: `Cannot determine refine source: no @skillit source package detected.
-Pass ${SOURCE_FORM} to choose one.`
-    };
-  } else {
-    kind = detected;
-  }
-
-  if (kind === 'typedoc') {
-    return { error: 'typedoc refine not yet supported; use --source cli|mcp.' };
-  }
-  if (kind === 'mcp' && opts.mcp === undefined) {
-    return { error: 'The mcp source requires --mcp <path> (path to mcp.json or MCP config file).' };
-  }
-  return { kind };
-}
-
-/** Parsed options for the `refine` action / {@link runRefineCommand}. */
-export interface RefineCommandOpts {
-  source?: string;
-  program?: string;
-  mcp?: string;
-  server?: string;
-  overlay?: string;
-  mode?: string;
-  sourceGlob?: string;
-  maxIterations: string;
-  items: string;
-  modelClient?: string;
-  modelCliTimeout?: string;
-}
-
-/** The model backend to use; defaults to the API client. */
-export function resolveModelClientKind(raw: string | undefined): string {
-  return raw ?? 'api';
-}
-
-/**
- * The body of the `refine` command action, extracted so it can be reused
- * programmatically (e.g. by `skillit init`) without argv gymnastics. Sets
- * `process.exitCode` and writes progress/errors to the console exactly as the
- * CLI does.
- */
-export async function runRefineCommand(opts: RefineCommandOpts): Promise<void> {
-  const cwd = process.cwd();
-  const maxIterations = parsePositiveInt(opts.maxIterations, '--max-iterations');
-  const itemsPerIteration = parsePositiveInt(opts.items, '--items');
-
-  const timeoutMs =
-    opts.modelCliTimeout !== undefined
-      ? parsePositiveInt(opts.modelCliTimeout, '--model-cli-timeout')
-      : undefined;
-  let model: ModelClient;
-  try {
-    model = createModelClient(
-      resolveModelClientKind(opts.modelClient),
-      timeoutMs !== undefined ? { timeoutMs } : {}
-    );
-  } catch (error) {
-    console.error(error instanceof Error ? error.message : String(error));
-    process.exitCode = 1;
-    return;
-  }
-
-  const candidates = await detectInstalledSources(cwd);
-  const detected = classifyRefineSources(candidates);
-  const resolution = resolveRefineSource(opts, detected, candidates);
-  if ('error' in resolution) {
-    console.error(resolution.error);
-    process.exitCode = 1;
-    return;
-  }
-
-  let source: RefineSource;
-  let reportInPlace = false;
-
-  if (resolution.kind === 'cli') {
-    const program = await loadProgram({ program: opts.program, cwd });
-    const sourceGlob = opts.sourceGlob ?? join(cwd, '**', '*.ts');
-    source = new CliRefineSource({ program, sourceGlob, cwd });
-    reportInPlace = true;
-  } else {
-    // mcp source: --mcp guaranteed present by resolveRefineSource.
-    const mcpPath = opts.mcp!;
-    const overlayPath = opts.overlay ?? join(cwd, '.skillit-overlay.json');
-
-    let mode: 'build' | 'runtime';
-    if (opts.mode === 'build' || opts.mode === 'runtime') {
-      mode = opts.mode;
-    } else if (opts.mode !== undefined) {
-      console.error(`Invalid --mode value: ${opts.mode}. Use 'build' or 'runtime'.`);
-      process.exitCode = 1;
-      return;
-    } else {
-      const detectedMode = await detectRefineMode(cwd, mcpPath);
-      if (detectedMode === 'ambiguous') {
-        console.error(`Cannot determine refine mode.
-Use --mode build  (TypeScript MCP server you own)
-     --mode runtime  (consuming project, any MCP server)`);
-        process.exitCode = 1;
-        return;
-      }
-      mode = detectedMode;
-    }
-
-    if (mode === 'build') {
-      console.log('Refining in build mode (TypeScript MCP)');
-    } else {
-      console.log('Refining in runtime mode (overlay)');
-    }
-
-    const entries = await readMcpConfigFile(mcpPath);
-    const entry = opts.server
-      ? entries.find((e) => e.name === opts.server)
-      : entries.find((e) => !e.disabled);
-    if (!entry) {
-      const name = opts.server ? `"${opts.server}"` : 'any enabled server';
-      throw new Error(`Could not find ${name} in ${mcpPath}`);
-    }
-
-    if (mode === 'build') {
-      const sourceGlob = opts.sourceGlob ?? join(cwd, '**', '*.ts');
-      source = new TypeScriptMcpRefineSource({
-        transport: entry.transport,
-        sourceGlob
-      });
-      reportInPlace = true;
-    } else {
-      source = new McpRefineSource({
-        overlayPath,
-        extract: () => extractMcpSkill({ transport: entry.transport })
-      });
-    }
-
-    const result = await runRefine(source, model, maxIterations, itemsPerIteration);
-    reportResult(result, { reportInPlace, overlayPath });
-    process.exitCode = result.passed ? 0 : 1;
-    return;
-  }
-
-  const result = await runRefine(source, model, maxIterations, itemsPerIteration);
-  reportResult(result, { reportInPlace });
-  process.exitCode = result.passed ? 0 : 1;
-}
-
-export function buildRefineCommand(): Command {
-  return new Command('refine')
-    .description('Autonomously improve a skill via the audit→draft→review loop')
-    .option('--source <kind>', 'cli | mcp | typedoc (auto-detected if omitted)')
-    .option('--program <file#export>', 'commander program entry (cli source)')
-    .option('--mcp <path>', 'path to mcp.json or MCP config file')
-    .option('--server <name>', 'server name within the config (defaults to first enabled)')
-    .option('--overlay <path>', 'path to overlay JSON file (runtime mode only)')
-    .option('--mode <mode>', 'refine mode: build or runtime (auto-detected if omitted)')
-    .option('--source-glob <glob>', 'glob pattern for TypeScript source files')
-    .option('--max-iterations <n>', 'iteration cap (default 5)', '5')
-    .option('--items <n>', 'work items per iteration (default 5)', '5')
-    .option('--model-client <kind>', 'model backend: api | claude | codex | copilot', 'api')
-    .option('--model-cli-timeout <ms>', 'per-call timeout for cli model backends (ms)')
-    .action((opts: RefineCommandOpts) => runRefineCommand(opts));
-}
-
-function runRefine(
-  source: RefineSource,
-  model: ModelClient,
-  maxIterations: number,
-  itemsPerIteration: number
-): ReturnType<typeof refineSkill> {
-  return refineSkill({
-    source,
-    model,
-    maxIterations,
-    itemsPerIteration,
-    onIteration: (iter) => {
-      const { grade, total } = iter.estimate;
-      console.log(
-        `  Iteration ${iter.iteration}: grade ${grade} (${total}/120), ${iter.fixes.length} fix(es) applied`
-      );
-    }
-  });
-}
-
-function reportResult(
-  result: Awaited<ReturnType<typeof refineSkill>>,
-  opts: { reportInPlace: boolean; overlayPath?: string }
-): void {
-  console.log(`\nDone. Reason: ${result.stoppedReason}`);
-  console.log(`Final grade: ${result.finalEstimate.grade} (${result.finalEstimate.total}/120)`);
-  if (opts.reportInPlace) {
-    console.log(`Source files updated in place.`);
-  } else if (opts.overlayPath && result.iterations.length > 0) {
-    console.log(`Overlay: ${opts.overlayPath}`);
-  }
-}

package/src/detect-mode.ts

@@ -1,94 +0,0 @@
-import { access, readFile } from 'node:fs/promises';
-import { homedir } from 'node:os';
-import { basename, dirname, join } from 'node:path';
-
-function isMcpServerDep(dep: string): boolean {
-  // Match server-implementation packages only. Excludes purely consumer-side
-  // packages such as @modelcontextprotocol/inspector or @modelcontextprotocol/client-*
-  // which do not imply the project has editable server source files.
-  return (
-    dep === '@modelcontextprotocol/sdk' ||
-    dep.startsWith('@modelcontextprotocol/server-') ||
-    dep === 'fastmcp'
-  );
-}
-
-async function hasMcpSdkDep(cwd: string): Promise<boolean> {
-  const home = homedir();
-  let dir = cwd;
-  while (dir !== home && dir !== dirname(dir)) {
-    try {
-      const raw = await readFile(join(dir, 'package.json'), 'utf8');
-      const pkg = JSON.parse(raw) as Record<string, unknown>;
-      const deps = {
-        ...(pkg['dependencies'] as Record<string, string> | undefined),
-        ...(pkg['devDependencies'] as Record<string, string> | undefined)
-      };
-      if (Object.keys(deps).some(isMcpServerDep)) return true;
-    } catch {
-      // no package.json or parse error in this dir; keep walking
-    }
-    dir = dirname(dir);
-  }
-  return false;
-}
-
-async function fileExists(path: string): Promise<boolean> {
-  try {
-    await access(path);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-async function hasMcpConfig(cwd: string): Promise<boolean> {
-  const home = homedir();
-  let dir = cwd;
-  while (dir !== home && dir !== dirname(dir)) {
-    if (
-      (await fileExists(join(dir, 'mcp.json'))) ||
-      (await fileExists(join(dir, 'claude_desktop_config.json')))
-    ) {
-      return true;
-    }
-    dir = dirname(dir);
-  }
-  return false;
-}
-
-const KNOWN_RUNTIME_BASENAMES = new Set(['mcp.json', 'claude_desktop_config.json']);
-
-async function isMcpRuntimeConfigFile(path: string): Promise<boolean> {
-  if (KNOWN_RUNTIME_BASENAMES.has(basename(path))) return true;
-  try {
-    const raw = await readFile(path, 'utf8');
-    const parsed = JSON.parse(raw) as Record<string, unknown>;
-    return 'mcpServers' in parsed;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Detect refine mode from project context.
- *
- * @param cwd - directory to inspect for build/runtime signals
- * @param mcpConfigPath - optional path to the --mcp config file; if its
- *   basename is a known runtime config filename, or its contents contain a
- *   top-level `mcpServers` key, it is treated as an additional runtime signal.
- */
-export async function detectRefineMode(
-  cwd: string,
-  mcpConfigPath?: string
-): Promise<'build' | 'runtime' | 'ambiguous'> {
-  const [hasBuild, hasRuntimeFromCwd, mcpFileIsRuntime] = await Promise.all([
-    hasMcpSdkDep(cwd),
-    hasMcpConfig(cwd),
-    mcpConfigPath !== undefined ? isMcpRuntimeConfigFile(mcpConfigPath) : Promise.resolve(false)
-  ]);
-  const hasRuntime = hasRuntimeFromCwd || mcpFileIsRuntime;
-  if (hasBuild && !hasRuntime) return 'build';
-  if (hasRuntime && !hasBuild) return 'runtime';
-  return 'ambiguous';
-}

package/src/detect-source.ts

@@ -1,123 +0,0 @@
-import { existsSync } from 'node:fs';
-import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { loadProgram } from '@skillit/cli';
-
-export type RefineSourceKind = 'cli' | 'mcp' | 'typedoc';
-export type DetectedRefineSource = RefineSourceKind | 'ambiguous' | 'none';
-
-/**
- * Read the union of `dependencies` + `devDependencies` from `<cwd>/package.json`.
- * Missing or unreadable `package.json` → `{}` (never throws). Single source of
- * truth for dependency reads across detection helpers.
- */
-async function readDeps(cwd: string): Promise<Record<string, string>> {
-  try {
-    const raw = await readFile(join(cwd, 'package.json'), 'utf8');
-    const pkg = JSON.parse(raw) as Record<string, unknown>;
-    return {
-      ...(pkg['dependencies'] as Record<string, string> | undefined),
-      ...(pkg['devDependencies'] as Record<string, string> | undefined)
-    };
-  } catch {
-    return {};
-  }
-}
-
-/** Map an installed package name to its refine source kind, if any. */
-function packageToSource(dep: string): RefineSourceKind | undefined {
-  if (dep === '@skillit/cli') return 'cli';
-  if (dep === '@skillit/mcp') return 'mcp';
-  if (dep === 'typedoc-plugin-skillit' || dep === '@skillit/typedoc') return 'typedoc';
-  return undefined;
-}
-
-/** Stable, canonical ordering for reported candidate lists. */
-const SOURCE_ORDER: readonly RefineSourceKind[] = ['cli', 'mcp', 'typedoc'];
-
-/**
- * Detect the raw, deduped list of refine source kinds installed in `cwd`'s
- * `package.json` (union of `dependencies` + `devDependencies`), in stable
- * order (`cli`, `mcp`, `typedoc`).
- *
- * Missing or unreadable `package.json` → `[]` (never throws). This is the
- * single place the package→source mapping lives; {@link detectRefineSource}
- * is derived from it.
- */
-export async function detectInstalledSources(cwd: string): Promise<RefineSourceKind[]> {
-  const deps = await readDeps(cwd);
-
-  const sources = new Set<RefineSourceKind>();
-  for (const dep of Object.keys(deps)) {
-    const source = packageToSource(dep);
-    if (source) sources.add(source);
-  }
-  return SOURCE_ORDER.filter((s) => sources.has(s));
-}
-
-/**
- * Collapse an installed-source list into the {@link DetectedRefineSource}
- * verdict: empty → `'none'`, single → that source, many → `'ambiguous'`.
- */
-export function classifyRefineSources(sources: readonly RefineSourceKind[]): DetectedRefineSource {
-  if (sources.length === 0) return 'none';
-  if (sources.length === 1) return sources[0]!;
-  return 'ambiguous';
-}
-
-/**
- * Detect the refine source from `@skillit/*` packages installed in `cwd`'s
- * `package.json` (union of `dependencies` + `devDependencies`).
- *
- * - 0 matching packages → `'none'`
- * - exactly 1 distinct source → that source
- * - more than 1 distinct source → `'ambiguous'`
- * - missing or unreadable `package.json` → `'none'` (never throws)
- */
-export async function detectRefineSource(cwd: string): Promise<DetectedRefineSource> {
-  return classifyRefineSources(await detectInstalledSources(cwd));
-}
-
-/**
- * Detect the nature of the project at `cwd` from its `package.json`:
- * - has `commander` or `yargs` dep, OR a `bin` that loads to a commander
- *   {@link Command} → `'cli'`
- * - else has `@modelcontextprotocol/sdk` → `'mcp'`
- * - else → `'typedoc'` (safe default for a plain TS library)
- *
- * Missing or unreadable `package.json` → `'typedoc'` (never throws). The `cli`
- * check is evaluated first (deps as a fast path, no import; the loadable-bin
- * probe runs only when those deps are absent), then `mcp`, then the `typedoc`
- * default.
- */
-export async function detectProjectNature(cwd: string): Promise<RefineSourceKind> {
-  const deps = await readDeps(cwd);
-  if ('commander' in deps || 'yargs' in deps) return 'cli';
-  if (await hasLoadableProgram(cwd)) return 'cli';
-  if ('@modelcontextprotocol/sdk' in deps) return 'mcp';
-  return 'typedoc';
-}
-
-/**
- * Attempt to load the consumer's `package.json` `bin` as a commander program
- * (via {@link loadProgram}). Returns `true` only if it resolves to a `Command`;
- * any failure (no bin, import error, non-Command export) → `false`.
- */
-async function hasLoadableProgram(cwd: string): Promise<boolean> {
-  try {
-    await loadProgram({ cwd });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Detect the package manager for `cwd` by lockfile presence:
- * `pnpm-lock.yaml` → `'pnpm'`, `yarn.lock` → `'yarn'`, else `'npm'`.
- */
-export function detectPackageManager(cwd: string): 'pnpm' | 'yarn' | 'npm' {
-  if (existsSync(join(cwd, 'pnpm-lock.yaml'))) return 'pnpm';
-  if (existsSync(join(cwd, 'yarn.lock'))) return 'yarn';
-  return 'npm';
-}

package/src/index.ts

@@ -1,3 +0,0 @@
-// packages/client/src/index.ts
-export { AnthropicModelClient } from './model/anthropic.js';
-export { parseReviewVerdict } from './model/anthropic.js';

package/src/model/anthropic.ts

@@ -1,116 +0,0 @@
-// packages/client/src/model/anthropic.ts
-import Anthropic from '@anthropic-ai/sdk';
-import type { DraftRequest, ReviewRequest, ReviewResult, ModelClient } from '@skillit/core';
-import { DRAFTER, REVIEWER, MAX_TOKENS } from './models.js';
-
-export function parseReviewVerdict(text: string): ReviewResult {
-  // Prefer {"verdict" anchor to skip stray {braces} in prose.
-  // Fall back to the first { if the model omits the verdict key.
-  // Depth-scan for the matching }, skipping { and } inside JSON string values.
-  const verdictAnchor = text.indexOf('{"verdict"');
-  const start = verdictAnchor !== -1 ? verdictAnchor : text.indexOf('{');
-  if (start === -1) return { verdict: 'accepted', feedback: '' };
-  let depth = 0;
-  let end = -1;
-  let inString = false;
-  let escaped = false;
-  for (let i = start; i < text.length; i++) {
-    const ch = text[i]!;
-    if (escaped) {
-      escaped = false;
-      continue;
-    }
-    if (ch === '\\' && inString) {
-      escaped = true;
-      continue;
-    }
-    if (ch === '"') {
-      inString = !inString;
-      continue;
-    }
-    if (inString) continue;
-    if (ch === '{') depth++;
-    else if (ch === '}') {
-      if (--depth === 0) {
-        end = i;
-        break;
-      }
-    }
-  }
-  if (end === -1) return { verdict: 'accepted', feedback: '' };
-  try {
-    const parsed = JSON.parse(text.slice(start, end + 1)) as Partial<ReviewResult>;
-    return {
-      verdict: parsed.verdict === 'revise' ? 'revise' : 'accepted',
-      feedback: parsed.feedback ?? ''
-    };
-  } catch {
-    return { verdict: 'accepted', feedback: '' };
-  }
-}
-
-export function buildDraftPrompt(req: DraftRequest): string {
-  const parts = [
-    `You are improving skill annotations for "${req.skill.name}".`,
-    `Tool: ${req.toolName}`,
-    `Tag to fill: @${req.tag}`,
-    `Guidance: ${req.suggestion}`,
-    req.currentValue ? `Current value:\n${req.currentValue}` : 'No current value.',
-    'Write only the annotation content — no code fences, no extra commentary.'
-  ];
-  if (req.guidance) {
-    parts.push(`Conventions (follow these):\n${req.guidance}`);
-  }
-  return parts.join('\n\n');
-}
-
-export function buildReviewPrompt(req: ReviewRequest): string {
-  const parts = [
-    `You are reviewing a skill annotation draft for "${req.skill.name}".`,
-    `Tool: ${req.toolName}, Tag: @${req.tag}`,
-    `Guidance the drafter was given: ${req.suggestion}`,
-    `Draft:\n${req.draft}`
-  ];
-  if (req.guidance) {
-    parts.push(`Conventions (follow these):\n${req.guidance}`);
-  }
-  parts.push(
-    'Respond with JSON only: {"verdict":"accepted"|"revise","feedback":"..."}.',
-    'Accept if the draft meaningfully addresses the guidance. Revise if it is vague or incorrect.'
-  );
-  return parts.join('\n\n');
-}
-
-export class AnthropicModelClient implements ModelClient {
-  private client = new Anthropic();
-
-  async draft(req: DraftRequest): Promise<string> {
-    const prompt = buildDraftPrompt(req);
-
-    const msg = await this.client.messages.create({
-      model: DRAFTER,
-      max_tokens: MAX_TOKENS,
-      messages: [{ role: 'user', content: prompt }]
-    });
-    const block = msg.content[0];
-    if (!block || block.type !== 'text') {
-      throw new Error(`Unexpected response from ${DRAFTER}: no text block`);
-    }
-    return block.text.trim();
-  }
-
-  async review(req: ReviewRequest): Promise<ReviewResult> {
-    const prompt = buildReviewPrompt(req);
-
-    const msg = await this.client.messages.create({
-      model: REVIEWER,
-      max_tokens: MAX_TOKENS,
-      messages: [{ role: 'user', content: prompt }]
-    });
-    const block = msg.content[0];
-    if (!block || block.type !== 'text') {
-      throw new Error(`Unexpected response from ${REVIEWER}: no text block`);
-    }
-    return parseReviewVerdict(block.text);
-  }
-}