# TypeScript SDK

The SDK provides a programmatic interface to all SkillLane functionality. It works in two modes: **local** (direct filesystem access) and **remote** (HTTP API client).

---

## Installation

```bash
npm install @talocode/skilllane
```

---

## Quick Start

```typescript
import { SkillLaneClient } from '@talocode/skilllane';

const client = new SkillLaneClient();

// Initialize storage
await client.init();

// Create, validate, install, run skills
const skill = await client.createSkill({
  name: 'my-skill',
  description: 'A custom skill',
  category: 'engineering',
  outDir: './skills',
});

const validation = await client.validateSkill('./my-skill');
console.log(`Score: ${validation.score}/100`);

await client.installSkill('./my-skill');

const result = await client.runSkill({
  skillName: 'my-skill',
  task: 'Do something useful',
  target: 'opencode',
});

console.log(result.prompt);
```

---

## Client Options

```typescript
// Local mode (default)
const client = new SkillLaneClient();

// Remote mode (connect to API server)
const client = new SkillLaneClient({
  baseUrl: 'http://localhost:3080',
  authToken: 'your-token',
});
```

| Option | Type | Description |
|--------|------|-------------|
| `baseUrl` | string | API server URL (omit for local mode) |
| `authToken` | string | Bearer token for authenticated requests |

---

## Methods

### init()

Initialize SkillLane storage directory.

```typescript
await client.init();
```

### createSkill(input)

Create a new skill from a template.

```typescript
const skill = await client.createSkill({
  name: 'my-skill',
  description: 'Does something',
  title: 'My Skill',           // optional
  category: 'engineering',      // optional, default: general
  tags: ['debugging'],          // optional
  targets: ['codex', 'opencode'], // optional
  template: 'debugging',        // optional: basic, debugging, writing, product-launch
  outDir: './skills',           // optional, default: cwd
});
```

Returns: `SkillDefinition`

### validateSkill(path, options?)

Validate a skill directory.

```typescript
const result = await client.validateSkill('./my-skill', { strict: false });
// result.valid: boolean
// result.score: number (0-100)
// result.errors: string[]
// result.warnings: string[]
```

### installSkill(source, options?)

Install a skill from a local path.

```typescript
const entry = await client.installSkill('./my-skill', {
  builtin: false,  // install from built-in directory
  name: 'custom',  // override skill name
  force: false,     // overwrite existing
});
```

Returns: `RegistryEntry`

### listSkills(filters?)

List installed skills.

```typescript
const skills = await client.listSkills({
  tag: 'debugging',       // optional filter
  category: 'engineering', // optional filter
});
```

Returns: `RegistryEntry[]`

### searchSkills(query)

Search installed skills by name, title, description, or tags.

```typescript
const results = await client.searchSkills('debug');
```

Returns: `RegistryEntry[]`

### getSkill(name)

Get details of an installed skill.

```typescript
const skill = await client.getSkill('systematic-debugging');
```

Returns: `RegistryEntry`

### runSkill(input)

Run a skill to generate a prompt.

```typescript
const result = await client.runSkill({
  skillName: 'systematic-debugging', // or skillPath: './my-skill'
  task: 'Debug a TypeError',
  context: 'Cannot read property of undefined',
  target: 'opencode',   // optional
  mode: 'markdown',     // optional: prompt, markdown, json
});
```

Returns: `SkillRunResult`

### removeSkill(name)

Remove an installed skill.

```typescript
await client.removeSkill('my-skill');
```

### exportSkill(name, outPath?)

Export a skill to a tarball.

```typescript
const path = await client.exportSkill('my-skill', './backup.tar.gz');
```

### doctor()

Run system health checks.

```typescript
const result = await client.doctor();
// result.healthy: boolean
// result.checks: { name, status, message }[]
```

### demo()

Run the demo.

```typescript
const result = await client.demo();
// result.success: boolean
// result.output: string
```

---

## Types

All types are exported from the package:

```typescript
import type {
  SkillTarget,
  SkillCategory,
  SkillMode,
  SkillMetadata,
  ToolDefinition,
  SkillDefinition,
  SkillValidationResult,
  SkillRunInput,
  SkillRunResult,
  RegistryEntry,
  ValidateOptions,
  CreateSkillInput,
  InstallOptions,
} from '@talocode/skilllane';
```

---

## Standalone Functions

For direct usage without the client:

```typescript
import {
  loadSkill,
  validateSkill,
  createSkill,
  installSkill,
  runSkill,
  listInstalledSkills,
  searchSkills,
  getInstalledSkill,
  removeSkill,
  getRegistryStats,
  rebuildRegistry,
  exportSkill,
  ensureStorage,
  loadConfig,
  saveConfig,
} from '@talocode/skilllane';
```

---

## Error Handling

```typescript
import {
  SkillLaneError,
  SkillNotFoundError,
  SkillValidationError,
  SkillInstallError,
  SkillRunError,
  RegistryError,
  ConfigError,
  AuthError,
} from '@talocode/skilllane';

try {
  await client.runSkill({ skillName: 'nonexistent', task: 'test' });
} catch (err) {
  if (err instanceof SkillNotFoundError) {
    console.error('Skill not found:', err.message);
  } else if (err instanceof SkillRunError) {
    console.error('Run failed:', err.message);
  }
}
```

---

## Configuration

```typescript
import { loadConfig, saveConfig } from '@talocode/skilllane';

const config = await loadConfig();
console.log(config.defaultTarget); // 'opencode'

await saveConfig({
  ...config,
  defaultTarget: 'codex',
  outputMode: 'markdown',
});
```