@skillit/client 0.2.0 → 0.4.0

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);
-  }
-}

package/src/model/cli/adapters.ts

@@ -1,178 +0,0 @@
-// packages/client/src/model/cli/adapters.ts
-import { DRAFTER, REVIEWER } from '../models.js';
-
-export type CliModelClientKind = 'claude' | 'codex' | 'copilot';
-export type ModelRole = 'draft' | 'review';
-
-export interface CliInvocation {
-  /** Executable name. */
-  cmd: string;
-  /** Arguments (no shell). */
-  args: string[];
-  /** Prompt to pipe to stdin, if this CLI takes the prompt that way. */
-  input?: string;
-}
-
-export interface CliAdapter {
-  readonly name: CliModelClientKind;
-  /** How to invoke the CLI for a given role with a given prompt. */
-  invocation(role: ModelRole, prompt: string): CliInvocation;
-  /**
-   * Extract the model's answer text from the CLI's stdout. An empty-string
-   * answer is valid and returned as-is; throws only when no answer message is
-   * present or the CLI reported an in-band error.
-   */
-  extractResult(stdout: string): string;
-}
-
-/** Minimal shape a JSONL line is narrowed to before an adapter inspects it. */
-interface JsonlEvent {
-  type?: string;
-  item?: { type?: string; text?: string };
-  data?: { content?: string };
-  exitCode?: number;
-}
-
-/**
- * Walk a JSONL stream (one JSON object per line), skip non-`{` log/noise lines
- * and unparseable lines, and return the LAST value `extract` accepts. Returning
- * `''` from `extract` is a valid match (the empty answer wins last) — only
- * `undefined` means "not a match", so the adapter never editorializes empty
- * model output.
- */
-function lastJsonlMatch<T>(
-  stdout: string,
-  extract: (evt: JsonlEvent) => T | undefined
-): T | undefined {
-  let last: T | undefined;
-  for (const line of stdout.split('\n')) {
-    const trimmed = line.trim();
-    if (!trimmed.startsWith('{')) continue;
-    let evt: JsonlEvent;
-    try {
-      evt = JSON.parse(trimmed) as JsonlEvent;
-    } catch {
-      continue;
-    }
-    const got = extract(evt);
-    if (got !== undefined) last = got;
-  }
-  return last;
-}
-
-/** Best-effort scan for a JSONL failure signal, used to enrich no-match errors. */
-function jsonlFailureSignal(
-  stdout: string,
-  detect: (evt: JsonlEvent) => string | undefined
-): string | undefined {
-  let signal: string | undefined;
-  for (const line of stdout.split('\n')) {
-    const trimmed = line.trim();
-    if (!trimmed.startsWith('{')) continue;
-    let evt: JsonlEvent;
-    try {
-      evt = JSON.parse(trimmed) as JsonlEvent;
-    } catch {
-      continue;
-    }
-    const got = detect(evt);
-    if (got !== undefined) signal = got;
-  }
-  return signal;
-}
-
-export const claudeAdapter: CliAdapter = {
-  name: 'claude',
-  invocation(role, prompt) {
-    const model = role === 'review' ? REVIEWER : DRAFTER;
-    return {
-      cmd: 'claude',
-      args: ['-p', '--output-format', 'json', '--model', model],
-      input: prompt
-    };
-  },
-  extractResult(stdout) {
-    let parsed: { is_error?: boolean; result?: string };
-    try {
-      parsed = JSON.parse(stdout) as typeof parsed;
-    } catch {
-      throw new Error(`claude: could not parse JSON output: ${stdout.slice(0, 200)}`);
-    }
-    if (parsed.is_error) {
-      throw new Error(`claude reported an error: ${parsed.result ?? '(no result)'}`);
-    }
-    if (typeof parsed.result !== 'string') {
-      throw new Error(`claude: no result field in output: ${stdout.slice(0, 200)}`);
-    }
-    return parsed.result;
-  }
-};
-
-export const codexAdapter: CliAdapter = {
-  name: 'codex',
-  invocation(_role, prompt) {
-    // codex uses its default model (no per-role mapping); prompt on stdin.
-    return { cmd: 'codex', args: ['exec', '--json'], input: prompt };
-  },
-  extractResult(stdout) {
-    const last = lastJsonlMatch(stdout, (evt) =>
-      evt.type === 'item.completed' &&
-      evt.item?.type === 'agent_message' &&
-      typeof evt.item.text === 'string'
-        ? evt.item.text
-        : undefined
-    );
-    if (last === undefined) {
-      const failure = jsonlFailureSignal(stdout, (evt) =>
-        evt.type === 'turn.failed' || (evt.type === 'item.completed' && evt.item?.type === 'error')
-          ? evt.type === 'turn.failed'
-            ? 'turn.failed'
-            : 'item.error'
-          : undefined
-      );
-      const detail = failure !== undefined ? ` (failure signal: ${failure})` : '';
-      throw new Error(`codex: no agent_message in output${detail}: ${stdout.slice(0, 200)}`);
-    }
-    return last;
-  }
-};
-
-export const copilotAdapter: CliAdapter = {
-  name: 'copilot',
-  invocation(_role, prompt) {
-    // copilot uses its default model; prompt piped via stdin (not `-p <text>`)
-    // so untrusted prompt content never reaches argv — keeps the Windows
-    // shell-launch path injection-safe (only static flags are args).
-    return { cmd: 'copilot', args: ['--output-format', 'json', '--no-color'], input: prompt };
-  },
-  extractResult(stdout) {
-    // copilot emits JSONL; the answer is the last `assistant.message` event's
-    // data.content (skip `assistant.message_delta` streaming events + the final
-    // `result` event). Verified live 2026-06-03.
-    const last = lastJsonlMatch(stdout, (evt) =>
-      evt.type === 'assistant.message' && typeof evt.data?.content === 'string'
-        ? evt.data.content
-        : undefined
-    );
-    if (last === undefined) {
-      const failure = jsonlFailureSignal(stdout, (evt) =>
-        evt.type === 'result' && typeof evt.exitCode === 'number' && evt.exitCode !== 0
-          ? `exitCode ${evt.exitCode}`
-          : undefined
-      );
-      const detail = failure !== undefined ? ` (failure signal: ${failure})` : '';
-      throw new Error(`copilot: no assistant.message in output${detail}: ${stdout.slice(0, 200)}`);
-    }
-    return last;
-  }
-};
-
-const ADAPTERS: Record<CliModelClientKind, CliAdapter> = {
-  claude: claudeAdapter,
-  codex: codexAdapter,
-  copilot: copilotAdapter
-};
-
-export function adapterFor(kind: CliModelClientKind): CliAdapter {
-  return ADAPTERS[kind];
-}

package/src/model/cli/cli-client.ts

@@ -1,52 +0,0 @@
-// packages/client/src/model/cli/cli-client.ts
-import type { DraftRequest, ReviewRequest, ReviewResult, ModelClient } from '@skillit/core';
-import { buildDraftPrompt, buildReviewPrompt, parseReviewVerdict } from '../anthropic.js';
-import { runCli, type RunCliOptions } from './run.js';
-import type { CliAdapter } from './adapters.js';
-
-/** Injectable process runner (defaults to the real `runCli`). */
-export type CliRunner = (opts: RunCliOptions) => Promise<string>;
-
-export interface CliModelClientOptions {
-  runner?: CliRunner;
-  timeoutMs?: number;
-}
-
-/**
- * A {@link ModelClient} that drives an agent CLI (claude/codex/copilot) instead
- * of the Anthropic API. Reuses the shared prompt builders and verdict parser;
- * only the transport differs.
- */
-export class CliModelClient implements ModelClient {
-  private readonly runner: CliRunner;
-  private readonly timeoutMs?: number;
-
-  constructor(
-    private readonly adapter: CliAdapter,
-    options: CliModelClientOptions = {}
-  ) {
-    this.runner = options.runner ?? runCli;
-    this.timeoutMs = options.timeoutMs;
-  }
-
-  private async run(role: 'draft' | 'review', prompt: string): Promise<string> {
-    const inv = this.adapter.invocation(role, prompt);
-    const stdout = await this.runner({
-      cmd: inv.cmd,
-      args: inv.args,
-      ...(inv.input !== undefined ? { input: inv.input } : {}),
-      ...(this.timeoutMs !== undefined ? { timeoutMs: this.timeoutMs } : {})
-    });
-    return this.adapter.extractResult(stdout);
-  }
-
-  async draft(req: DraftRequest): Promise<string> {
-    const result = await this.run('draft', buildDraftPrompt(req));
-    return result.trim();
-  }
-
-  async review(req: ReviewRequest): Promise<ReviewResult> {
-    const result = await this.run('review', buildReviewPrompt(req));
-    return parseReviewVerdict(result);
-  }
-}

package/src/model/cli/run.ts

@@ -1,83 +0,0 @@
-// packages/client/src/model/cli/run.ts
-import { spawn } from 'node:child_process';
-
-export interface RunCliOptions {
-  /** Executable name (resolved on PATH) — never a shell string. */
-  cmd: string;
-  /** Arguments as an array — no shell, so no injection/escaping concerns. */
-  args: string[];
-  /** Optional text written to the child's stdin, then closed. */
-  input?: string;
-  /** Per-call timeout in milliseconds (default 120000). */
-  timeoutMs?: number;
-}
-
-const DEFAULT_TIMEOUT_MS = 120_000;
-
-/**
- * Spawn `cmd` with `args` (no shell), optionally pipe `input` to stdin, and
- * resolve the captured stdout. Throws on non-zero exit (message includes the
- * command, exit code, and a stderr tail) or on timeout.
- */
-export function runCli(opts: RunCliOptions): Promise<string> {
-  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-  return new Promise<string>((resolve, reject) => {
-    // On Windows, npm-installed CLIs are `.cmd`/`.bat` shims that Node cannot
-    // exec directly — they must go through the shell. This is injection-safe
-    // because every adapter delivers the (untrusted) prompt via stdin, so
-    // `args` only ever holds static flags and hardcoded model ids — no
-    // untrusted content reaches argv on any platform. On POSIX we keep the
-    // no-shell path regardless.
-    const child = spawn(opts.cmd, opts.args, {
-      stdio: ['pipe', 'pipe', 'pipe'],
-      shell: process.platform === 'win32'
-    });
-    let stdout = '';
-    let stderr = '';
-    let settled = false;
-
-    const timer = setTimeout(() => {
-      if (settled) return;
-      settled = true;
-      child.kill('SIGKILL');
-      reject(new Error(`${opts.cmd} timed out after ${timeoutMs}ms`));
-    }, timeoutMs);
-
-    child.stdout.on('data', (d: Buffer) => {
-      stdout += d.toString();
-    });
-    child.stderr.on('data', (d: Buffer) => {
-      stderr += d.toString();
-    });
-    child.on('error', (err) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      reject(new Error(`${opts.cmd} failed to start: ${err.message}`));
-    });
-    child.on('close', (code) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      if (code === 0) {
-        resolve(stdout);
-      } else {
-        const tail = stderr.trim().slice(-500);
-        // Intentionally omit args from the message: an adapter may pass the
-        // prompt as an argument (copilot), and the prompt can be large/sensitive.
-        reject(new Error(`${opts.cmd} exited with code ${code}: ${tail}`));
-      }
-    });
-
-    // The child may exit before consuming stdin (e.g. an auth/usage failure),
-    // in which case writing a large prompt emits EPIPE. Swallow stdin errors so
-    // they don't crash the process as an unhandled stream error — the `close`
-    // handler still rejects with the real exit code + stderr. Also omit args
-    // from that message: the prompt is delivered here, not via argv.
-    child.stdin.on('error', () => {});
-    if (opts.input !== undefined) {
-      child.stdin.write(opts.input);
-    }
-    child.stdin.end();
-  });
-}

package/src/model/model-client-factory.ts

@@ -1,62 +0,0 @@
-// packages/client/src/model/model-client-factory.ts
-import { execFileSync } from 'node:child_process';
-import type { ModelClient } from '@skillit/core';
-import { AnthropicModelClient } from './anthropic.js';
-import { CliModelClient } from './cli/cli-client.js';
-import { adapterFor, type CliModelClientKind } from './cli/adapters.js';
-
-export type ModelClientKind = 'api' | CliModelClientKind;
-
-const CLI_KINDS: readonly CliModelClientKind[] = ['claude', 'codex', 'copilot'];
-const ALL_KINDS = ['api', ...CLI_KINDS] as const;
-
-export interface CreateModelClientOptions {
-  /** Per-call timeout for CLI invocations. */
-  timeoutMs?: number;
-  /** Injectable PATH check (defaults to a real `command -v` probe). */
-  hasBinary?: (cmd: string) => boolean;
-}
-
-function defaultHasBinary(cmd: string): boolean {
-  try {
-    if (process.platform === 'win32') {
-      // `where` has no `-v` flag; `where <cmd>` exits non-zero when not found.
-      execFileSync('where', [cmd], { stdio: 'ignore' });
-    } else {
-      // POSIX: `command -v <cmd>` is a shell builtin, so run it through a shell.
-      execFileSync('command', ['-v', cmd], { stdio: 'ignore', shell: true });
-    }
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function isCliKind(kind: string): kind is CliModelClientKind {
-  return (CLI_KINDS as readonly string[]).includes(kind);
-}
-
-/**
- * Build the {@link ModelClient} for the requested backend. `'api'` → the
- * Anthropic API client; a CLI kind → a {@link CliModelClient} after a PATH
- * pre-flight. Throws an actionable error for an unknown kind or a missing CLI.
- */
-export function createModelClient(
-  kind: string,
-  options: CreateModelClientOptions = {}
-): ModelClient {
-  if (kind === 'api') return new AnthropicModelClient();
-  if (!isCliKind(kind)) {
-    throw new Error(`invalid --model-client '${kind}'. Use one of: ${ALL_KINDS.join('|')}.`);
-  }
-  const hasBinary = options.hasBinary ?? defaultHasBinary;
-  if (!hasBinary(kind)) {
-    throw new Error(
-      `${kind} CLI not found on PATH — install it, or use --model-client api (requires ANTHROPIC_API_KEY).`
-    );
-  }
-  return new CliModelClient(
-    adapterFor(kind),
-    options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}
-  );
-}

package/src/model/models.ts

@@ -1,7 +0,0 @@
-// packages/client/src/model/models.ts
-// Shared model identifiers for the refine drafter/reviewer roles. Imported by
-// both the Anthropic API client and the claude CLI adapter so the role→model
-// mapping has one source of truth.
-export const DRAFTER = 'claude-sonnet-4-6';
-export const REVIEWER = 'claude-opus-4-7';
-export const MAX_TOKENS = 1024;

package/tsconfig.build.json

@@ -1,9 +0,0 @@
-{
-  "extends": "./tsconfig.json",
-  "exclude": ["src/**/__tests__"],
-  "compilerOptions": {
-    "rootDir": "src",
-    "outDir": "dist",
-    "declarationDir": "dist"
-  }
-}

package/tsconfig.json

@@ -1,4 +0,0 @@
-{
-  "extends": "../../tsconfig.json",
-  "include": ["src"]
-}