@skillit/client 0.2.0 → 0.3.1

package/src/__tests__/init.test.ts

@@ -1,218 +0,0 @@
-import { buildInitCommand, type GenerateSkillOpts, type InitDeps } from '../commands/init.js';
-import type { RefineCommandOpts } from '../commands/refine.js';
-import { mkdtemp, rm, writeFile } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-
-let tmpDir: string;
-let prevCwd: string;
-
-beforeEach(() => {
-  prevCwd = process.cwd();
-});
-
-afterEach(async () => {
-  process.chdir(prevCwd);
-  if (tmpDir) await rm(tmpDir, { recursive: true, force: true });
-});
-
-/**
- * A cli-nature project with a pnpm lockfile. Returns the realized cwd
- * (`process.cwd()` after chdir), since macOS resolves `/tmp` → `/private/tmp`.
- */
-async function writeCliFixture(): Promise<string> {
-  tmpDir = await mkdtemp(join(tmpdir(), 'init-'));
-  await writeFile(
-    join(tmpDir, 'package.json'),
-    JSON.stringify({ name: '@scope/my-tool', dependencies: { commander: '^14.0.0' } })
-  );
-  await writeFile(join(tmpDir, 'pnpm-lock.yaml'), '');
-  process.chdir(tmpDir);
-  return process.cwd();
-}
-
-/** An mcp-nature project (no commander/yargs, no loadable bin). */
-async function writeMcpFixture(): Promise<string> {
-  tmpDir = await mkdtemp(join(tmpdir(), 'init-'));
-  await writeFile(
-    join(tmpDir, 'package.json'),
-    JSON.stringify({
-      name: 'my-server',
-      dependencies: { '@modelcontextprotocol/sdk': '^1.0.0' }
-    })
-  );
-  await writeFile(join(tmpDir, 'pnpm-lock.yaml'), '');
-  process.chdir(tmpDir);
-  return process.cwd();
-}
-
-interface InstallCall {
-  pkg: string;
-  pm: string;
-  cwd: string;
-}
-
-function makeStubs(overrides?: Partial<InitDeps>): {
-  deps: InitDeps;
-  installCalls: InstallCall[];
-  generateCalls: GenerateSkillOpts[];
-  refineCalls: unknown[];
-} {
-  const installCalls: InstallCall[] = [];
-  const generateCalls: GenerateSkillOpts[] = [];
-  const refineCalls: unknown[] = [];
-  const deps: InitDeps = {
-    runInstall: async (pkg, pm, cwd) => {
-      installCalls.push({ pkg, pm, cwd });
-    },
-    generateSkill: async (opts) => {
-      generateCalls.push(opts);
-    },
-    runRefine: async (opts) => {
-      refineCalls.push(opts);
-    },
-    ...overrides
-  };
-  return { deps, installCalls, generateCalls, refineCalls };
-}
-
-async function run(deps: InitDeps, argv: string[] = []): Promise<void> {
-  const cmd = buildInitCommand(deps);
-  await cmd.parseAsync(argv, { from: 'user' });
-}
-
-describe('buildInitCommand', () => {
-  it('chooses @skillit/cli with the detected pnpm add command for a cli project', async () => {
-    const dir = await writeCliFixture();
-    const { deps, installCalls } = makeStubs();
-    await run(deps);
-    expect(installCalls).toHaveLength(1);
-    expect(installCalls[0]!.pkg).toBe('@skillit/cli');
-    expect(installCalls[0]!.pm).toBe('pnpm');
-    expect(installCalls[0]!.cwd).toBe(dir);
-  });
-
-  it('generates the skill into <cwd>/skills before and after refine', async () => {
-    const dir = await writeCliFixture();
-    const { deps, generateCalls } = makeStubs();
-    await run(deps);
-    // Generated once before refine (initial) and once after (reflecting the
-    // freshly-written JSDoc), both into the same out dir.
-    expect(generateCalls).toHaveLength(2);
-    expect(generateCalls[0]!.outDir).toBe(join(dir, 'skills'));
-    expect(generateCalls[1]!.outDir).toBe(join(dir, 'skills'));
-  });
-
-  it('runs refine between the initial generate and the post-refine regenerate', async () => {
-    await writeCliFixture();
-    const order: string[] = [];
-    const { deps } = makeStubs({
-      generateSkill: async () => {
-        order.push('generate');
-      },
-      runRefine: async () => {
-        order.push('refine');
-      }
-    });
-    await run(deps);
-    expect(order).toEqual(['generate', 'refine', 'generate']);
-  });
-
-  it('dispatches refine with the cli source', async () => {
-    await writeCliFixture();
-    const { deps, refineCalls } = makeStubs();
-    await run(deps);
-    expect(refineCalls).toHaveLength(1);
-    expect((refineCalls[0] as { source?: string }).source).toBe('cli');
-  });
-
-  it('respects an explicit --out directory', async () => {
-    const dir = await writeCliFixture();
-    const { deps, generateCalls } = makeStubs();
-    await run(deps, ['--out', 'docs/skills']);
-    expect(generateCalls[0]!.outDir).toBe(join(dir, 'docs/skills'));
-  });
-
-  it('throws with the exact command on install failure and skips generate + refine', async () => {
-    await writeCliFixture();
-    const generate = vi.fn();
-    const refine = vi.fn();
-    const { deps } = makeStubs({
-      runInstall: async (pkg, pm) => {
-        throw new Error(`install of ${pkg} via ${pm} failed`);
-      },
-      generateSkill: generate,
-      runRefine: refine
-    });
-    await expect(run(deps)).rejects.toThrow(/pnpm add -D @skillit\/cli/);
-    expect(generate).not.toHaveBeenCalled();
-    expect(refine).not.toHaveBeenCalled();
-  });
-
-  it('rejects an invalid --source value', async () => {
-    await writeCliFixture();
-    const { deps } = makeStubs();
-    await expect(run(deps, ['--source', 'bogus'])).rejects.toThrow(/cli\|mcp\|typedoc/);
-  });
-
-  it("degrades gracefully (no throw, no refine, prints guidance) when the cli program won't load", async () => {
-    await writeCliFixture();
-    const refine = vi.fn();
-    const { deps } = makeStubs({
-      generateSkill: async () => {
-        throw new Error('not a commander program');
-      },
-      runRefine: refine
-    });
-    // Capture via plain reassignment: vitest's console interceptor bypasses
-    // vi.spyOn(console, 'log') under this config.
-    const logged: string[] = [];
-    const originalLog = console.log;
-    console.log = (...args: unknown[]): void => {
-      logged.push(String(args[0]));
-    };
-    try {
-      await expect(run(deps)).resolves.toBeUndefined();
-    } finally {
-      console.log = originalLog;
-    }
-    expect(refine).not.toHaveBeenCalled();
-    const out = logged.join('\n');
-    expect(out).toMatch(/Installed @skillit\/cli/);
-    expect(out).toMatch(/not a commander program/);
-    expect(out).toMatch(/skillit refine --source cli --program/);
-  });
-
-  it('installs @skillit/mcp but skips generate + refine for an mcp project', async () => {
-    await writeMcpFixture();
-    const { deps, installCalls, generateCalls, refineCalls } = makeStubs();
-    // Override console.log directly: vitest's console interceptor bypasses
-    // vi.spyOn(console, 'log') here, so capture via a plain reassignment.
-    const logged: string[] = [];
-    const originalLog = console.log;
-    console.log = (...args: unknown[]): void => {
-      logged.push(String(args[0]));
-    };
-    try {
-      await run(deps);
-    } finally {
-      console.log = originalLog;
-    }
-    expect(installCalls).toHaveLength(1);
-    expect(installCalls[0]!.pkg).toBe('@skillit/mcp');
-    // CLI-first: no auto generate or refine for the mcp source this pass.
-    expect(generateCalls).toHaveLength(0);
-    expect(refineCalls).toHaveLength(0);
-    expect(logged.join('\n')).toMatch(/skillit refine --source mcp/);
-  });
-
-  it('threads --model-client and --model-cli-timeout into the refine dispatch', async () => {
-    await writeCliFixture();
-    const { deps, refineCalls } = makeStubs();
-    await run(deps, ['--source', 'cli', '--model-client', 'claude', '--model-cli-timeout', '7000']);
-    const opts = refineCalls[0] as RefineCommandOpts;
-    expect(opts.modelClient).toBe('claude');
-    expect(opts.modelCliTimeout).toBe('7000');
-  });
-});

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

@@ -1,28 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { createModelClient } from '../model/model-client-factory.js';
-import { AnthropicModelClient } from '../model/anthropic.js';
-import { CliModelClient } from '../model/cli/cli-client.js';
-
-describe('createModelClient', () => {
-  it("returns an AnthropicModelClient for 'api'", () => {
-    expect(createModelClient('api')).toBeInstanceOf(AnthropicModelClient);
-  });
-
-  it('returns a CliModelClient for a cli kind whose binary is present', () => {
-    // inject a pre-flight that reports the binary exists
-    const client = createModelClient('claude', { hasBinary: () => true });
-    expect(client).toBeInstanceOf(CliModelClient);
-  });
-
-  it('throws an actionable error when the cli binary is missing', () => {
-    expect(() => createModelClient('codex', { hasBinary: () => false })).toThrow(
-      /codex CLI not found on PATH.*--model-client api/s
-    );
-  });
-
-  it('throws on an invalid kind', () => {
-    expect(() => createModelClient('bogus')).toThrow(
-      /invalid --model-client.*api\|claude\|codex\|copilot/s
-    );
-  });
-});

package/src/__tests__/refine-resolve.test.ts

@@ -1,72 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { resolveModelClientKind, resolveRefineSource } from '../commands/refine.js';
-
-describe('resolveModelClientKind', () => {
-  it("defaults to 'api' when --model-client is omitted", () => {
-    expect(resolveModelClientKind(undefined)).toBe('api');
-  });
-  it('passes through a provided kind', () => {
-    expect(resolveModelClientKind('claude')).toBe('claude');
-  });
-});
-
-describe('resolveRefineSource', () => {
-  it('explicit --source cli wins over detection', () => {
-    const res = resolveRefineSource({ source: 'cli' }, 'mcp');
-    expect(res).toEqual({ kind: 'cli' });
-  });
-
-  it('explicit --source mcp requires --mcp', () => {
-    const res = resolveRefineSource({ source: 'mcp' }, 'none');
-    expect('error' in res && res.error).toMatch(/--mcp/);
-  });
-
-  it('explicit --source mcp with --mcp resolves to mcp', () => {
-    const res = resolveRefineSource({ source: 'mcp', mcp: 'mcp.json' }, 'none');
-    expect(res).toEqual({ kind: 'mcp' });
-  });
-
-  it('rejects an invalid --source value', () => {
-    const res = resolveRefineSource({ source: 'bogus' }, 'cli');
-    expect('error' in res && res.error).toMatch(/cli|mcp|typedoc/);
-  });
-
-  it('falls back to detection when --source is omitted', () => {
-    const res = resolveRefineSource({}, 'cli');
-    expect(res).toEqual({ kind: 'cli' });
-  });
-
-  it('detected mcp still requires --mcp', () => {
-    const res = resolveRefineSource({}, 'mcp');
-    expect('error' in res && res.error).toMatch(/--mcp/);
-  });
-
-  it('detected mcp with --mcp resolves to mcp', () => {
-    const res = resolveRefineSource({ mcp: 'mcp.json' }, 'mcp');
-    expect(res).toEqual({ kind: 'mcp' });
-  });
-
-  it('errors on ambiguous detection listing candidates and --source form', () => {
-    const res = resolveRefineSource({}, 'ambiguous', ['cli', 'mcp']);
-    const error = 'error' in res ? res.error : '';
-    expect(error).toMatch(/--source <cli\|mcp\|typedoc>/);
-    expect(error).toMatch(/cli/);
-    expect(error).toMatch(/mcp/);
-    expect(error).toMatch(/found: cli, mcp/);
-  });
-
-  it('errors on no detected source with the --source form', () => {
-    const res = resolveRefineSource({}, 'none');
-    expect('error' in res && res.error).toMatch(/--source <cli\|mcp\|typedoc>/);
-  });
-
-  it('errors that typedoc is not yet supported', () => {
-    const res = resolveRefineSource({ source: 'typedoc' }, 'none');
-    expect('error' in res && res.error).toMatch(/not yet supported/);
-  });
-
-  it('errors that detected typedoc is not yet supported', () => {
-    const res = resolveRefineSource({}, 'typedoc');
-    expect('error' in res && res.error).toMatch(/not yet supported/);
-  });
-});

package/src/bin.ts

@@ -1,18 +0,0 @@
-#!/usr/bin/env node
-// packages/client/src/bin.ts
-import { Command } from 'commander';
-import { buildMcpCommand, reportMcpErrorAndExit } from '@skillit/mcp';
-import { buildInitCommand } from './commands/init.js';
-import { buildRefineCommand } from './commands/refine.js';
-
-const program = new Command('skillit').description('skillit CLI').version('0.1.0');
-
-program.addCommand(buildRefineCommand());
-program.addCommand(buildInitCommand());
-program.addCommand(buildMcpCommand());
-
-program.parseAsync(process.argv).catch((err: unknown) => {
-  // Preserve the mcp exit-code contract for the `skillit mcp …` path; other
-  // errors keep the prior generic behavior (stderr message + exit 1).
-  reportMcpErrorAndExit(err);
-});

package/src/commands/init.ts

@@ -1,207 +0,0 @@
-// packages/client/src/commands/init.ts
-import { spawn } from 'node:child_process';
-import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { Command } from 'commander';
-import { extractCliSkill, loadProgram, writeCliSkill } from '@skillit/cli';
-import {
-  detectPackageManager,
-  detectProjectNature,
-  type RefineSourceKind
-} from '../detect-source.js';
-import { runRefineCommand, type RefineCommandOpts } from './refine.js';
-
-type PackageManager = 'pnpm' | 'yarn' | 'npm';
-
-/** Options passed to the (CLI-path) skill generator. */
-export interface GenerateSkillOpts {
-  /** Project root being initialized. */
-  cwd: string;
-  /** Resolved project nature. */
-  nature: RefineSourceKind;
-  /** Skill name (consumer package name, scope stripped). */
-  name: string;
-  /** Absolute output directory (`<cwd>/<out>`). */
-  outDir: string;
-  /** `--program <file#export>` entry, if provided. */
-  program?: string;
-}
-
-/**
- * Injectable side-effecting steps for {@link buildInitCommand}. All optional;
- * real defaults run install / generate / refine. Tests inject stubs so no real
- * install, network, or model call runs.
- */
-export interface InitDeps {
-  /** Install `pkg` as a dev dependency in `cwd` using package manager `pm`. */
-  runInstall?(pkg: string, pm: PackageManager, cwd: string): Promise<void>;
-  /** Generate the initial skill (CLI path only). */
-  generateSkill?(opts: GenerateSkillOpts): Promise<void>;
-  /** Dispatch the refine loop for the resolved source. */
-  runRefine?(opts: RefineCommandOpts): Promise<void>;
-}
-
-interface InitOpts {
-  source?: string;
-  program?: string;
-  out: string;
-  modelClient?: string;
-  modelCliTimeout?: string;
-}
-
-const VALID_SOURCES: readonly RefineSourceKind[] = ['cli', 'mcp', 'typedoc'];
-
-/** Map a project nature to the `@skillit/*` package that handles it. */
-function natureToPackage(nature: RefineSourceKind): string {
-  if (nature === 'cli') return '@skillit/cli';
-  if (nature === 'mcp') return '@skillit/mcp';
-  return 'typedoc-plugin-skillit';
-}
-
-/** Build the package manager's add-dev command line (for messaging + spawn). */
-function addDevCommand(pm: PackageManager, pkg: string): string {
-  if (pm === 'pnpm') return `pnpm add -D ${pkg}`;
-  if (pm === 'yarn') return `yarn add -D ${pkg}`;
-  return `npm install -D ${pkg}`;
-}
-
-/** Strip a leading `@scope/` from a package name for use as a skill dir name. */
-function skillNameFrom(packageName: string): string {
-  const slash = packageName.indexOf('/');
-  if (packageName.startsWith('@') && slash !== -1) {
-    return packageName.slice(slash + 1);
-  }
-  return packageName;
-}
-
-async function readPackageName(cwd: string): Promise<string> {
-  try {
-    const raw = await readFile(join(cwd, 'package.json'), 'utf8');
-    const pkg = JSON.parse(raw) as { name?: string };
-    return pkg.name ?? 'skill';
-  } catch {
-    return 'skill';
-  }
-}
-
-/** Default install: spawn the package manager's add-dev command, cwd-scoped. */
-function defaultRunInstall(pkg: string, pm: PackageManager, cwd: string): Promise<void> {
-  const command = addDevCommand(pm, pkg);
-  const [bin, ...args] = command.split(' ');
-  return new Promise((resolve, reject) => {
-    const child = spawn(bin!, args, { cwd, stdio: 'inherit' });
-    child.on('error', reject);
-    child.on('close', (code) => {
-      if (code === 0) resolve();
-      else reject(new Error(`exited with code ${code}`));
-    });
-  });
-}
-
-/** Default CLI-path skill generation: loadProgram → extractCliSkill → writeCliSkill. */
-async function defaultGenerateSkill(opts: GenerateSkillOpts): Promise<void> {
-  const program = await loadProgram({ program: opts.program, cwd: opts.cwd });
-  const skill = await extractCliSkill({ program, metadata: { name: opts.name } });
-  writeCliSkill(skill, { outDir: opts.outDir });
-}
-
-/** Default refine dispatch: reuse the shared refine command body. */
-function defaultRunRefine(opts: RefineCommandOpts): Promise<void> {
-  return runRefineCommand(opts);
-}
-
-export function buildInitCommand(deps: InitDeps = {}): Command {
-  const runInstall = deps.runInstall ?? defaultRunInstall;
-  const generateSkill = deps.generateSkill ?? defaultGenerateSkill;
-  const runRefine = deps.runRefine ?? defaultRunRefine;
-
-  return new Command('init')
-    .description(
-      'Detect the project, install the right @skillit package, generate + refine a skill'
-    )
-    .option('--source <kind>', 'cli | mcp | typedoc (auto-detected if omitted)')
-    .option('--program <file#export>', 'commander program entry (cli source)')
-    .option('--out <dir>', 'output directory for the generated skill', 'skills')
-    .option(
-      '--model-client <kind>',
-      'model backend for refine: api | claude | codex | copilot',
-      'api'
-    )
-    .option('--model-cli-timeout <ms>', 'per-call timeout for cli model backends (ms)')
-    .action(async (opts: InitOpts) => {
-      const cwd = process.cwd();
-
-      // 1. Resolve nature: explicit --source wins, else detect.
-      let nature: RefineSourceKind;
-      if (opts.source !== undefined) {
-        if (!VALID_SOURCES.includes(opts.source as RefineSourceKind)) {
-          throw new Error(
-            `Invalid --source value: ${opts.source}. Use --source <cli|mcp|typedoc>.`
-          );
-        }
-        nature = opts.source as RefineSourceKind;
-      } else {
-        nature = await detectProjectNature(cwd);
-      }
-
-      // 2 + 3. Map nature → package, install via the detected package manager.
-      const pkg = natureToPackage(nature);
-      const pm = detectPackageManager(cwd);
-      const command = addDevCommand(pm, pkg);
-      try {
-        await runInstall(pkg, pm, cwd);
-      } catch (error) {
-        const reason = error instanceof Error ? error.message : String(error);
-        // Surface the exact command and STOP — do not generate or refine.
-        throw new Error(`Install failed (${reason}). Run it manually:\n  ${command}`);
-      }
-
-      // 4 + 5. Generate + refine — CLI-first: only the cli source is fully
-      // automated this pass. For mcp/typedoc, skip both and print actionable
-      // next-step guidance rather than silently no-opping (refine needs
-      // source-specific flags like --mcp that init can't supply yet).
-      if (nature === 'cli') {
-        const outDir = join(cwd, opts.out);
-        const name = skillNameFrom(await readPackageName(cwd));
-        const generateOpts: GenerateSkillOpts = {
-          cwd,
-          nature,
-          name,
-          outDir,
-          ...(opts.program !== undefined ? { program: opts.program } : {})
-        };
-        try {
-          await generateSkill(generateOpts);
-        } catch (error) {
-          // The cli source only auto-loads a commander program. A yargs/other
-          // CLI (still classified as 'cli') can't be generated yet — degrade
-          // gracefully: surface the reason and how to proceed, do NOT crash,
-          // and do NOT run refine/regenerate on a failed generate.
-          const reason = error instanceof Error ? error.message : String(error);
-          console.log(
-            `Installed ${pkg}, but couldn't auto-load a commander program (${reason}). ` +
-              `If this is a commander CLI, run: skillit refine --source cli --program <file#export>. ` +
-              `(yargs/other CLIs aren't auto-generated yet.)`
-          );
-          return;
-        }
-        await runRefine({
-          source: nature,
-          ...(opts.program !== undefined ? { program: opts.program } : {}),
-          ...(opts.modelClient !== undefined ? { modelClient: opts.modelClient } : {}),
-          ...(opts.modelCliTimeout !== undefined ? { modelCliTimeout: opts.modelCliTimeout } : {}),
-          maxIterations: '5',
-          items: '5'
-        });
-        // refine only writes JSDoc back into source files; regenerate so the
-        // on-disk skill reflects the freshly-written annotations. Runs only
-        // after a successful refine (a refine throw propagates above).
-        await generateSkill(generateOpts);
-      } else {
-        const extra = nature === 'mcp' ? ' [--mcp <path>]' : '';
-        console.log(
-          `Installed ${pkg}. Skill generation + refine for the ${nature} source isn't automated yet — run: skillit refine --source ${nature}${extra}`
-        );
-      }
-    });
-}