open-index/open-npm huggingface dataset:
npm package: @kata-framework/cli
Description: CLI tool for the Kata narrative framework. Build `.kata` files into KSON JSON, watch for changes, and visualize scene graphs.
Latest version: 0.1.2

# @kata-framework/cli

CLI tool for the Kata narrative framework. Build `.kata` files into KSON JSON, watch for changes, and visualize scene graphs.

## Install

```bash
bun add -g @kata-framework/cli
```

## Commands

### `kata build <glob>`

Parse `.kata` files and write `.kson.json` to an output directory.

```bash
kata build "scenes/**/*.kata" -o dist/kson
# Output: dist/kson/intro.kson.json, dist/kson/shop.kson.json, ...
```

### `kata watch <glob>`

Build + watch for changes, rebuilding on save.

```bash
kata watch "scenes/**/*.kata" -o dist/kson
```

### `kata graph <glob>`

Visualize scene connections and detect structural issues.

```bash
# DOT format (pipe to Graphviz or online renderers)
kata graph "scenes/**/*.kata" --format dot > story.dot

# JSON format (for custom tooling)
kata graph "scenes/**/*.kata" --format json

# Lint for problems
kata graph "scenes/**/*.kata" --lint
# ⚠ Orphaned scene: "secret-ending" (no inbound edges)
# ⚠ Dead end: "bad-ending" (no choices, no outbound edges)
```

## Options

| Flag | Description | Default |
|------|-------------|---------|
| `-o, --output <dir>` | Output directory for build/watch | `dist/kson` |
| `-f, --format <fmt>` | Graph format: `dot` or `json` | `dot` |
| `--lint` | Check for orphaned scenes and dead ends | — |
| `-h, --help` | Show help | — |

## Configuration

Create a `kata.config.json` in your project root to avoid repeating flags:

```json
{
  "input": "scenes/**/*.kata",
  "output": "dist/kson"
}
```

Resolution order: **CLI flags → `kata.config.json` → defaults** (`**/*.kata`, `dist/kson`).

Depends on `@kata-framework/core` for parsing.
npm package: @kata-framework/lsp
Description: Language Server Protocol implementation for `.kata` narrative files. Provides real-time diagnostics, autocomplete, hover info, go-to-definition, and document symbols.
Latest version: 0.2.4

# @kata-framework/lsp

Language Server Protocol implementation for `.kata` narrative files. Provides real-time diagnostics, autocomplete, hover info, go-to-definition, and document symbols.

## Install

```bash
bun add @kata-framework/lsp
```

## Features

### Diagnostics

- **Parse errors** — invalid YAML frontmatter, broken expressions, malformed directives
- **Undefined variables** — empty `${}` interpolations
- **Invalid conditions** — syntax errors in `cond="..."` expressions
- **Unresolved scene targets** — `-> @scene/id` pointing to nonexistent scenes
- **Duplicate scene IDs** — multiple files defining the same `id`
- **Missing wait duration** — `[wait]` without a number
- **Unclosed exec blocks** — `[exec]` without matching `[/exec]`

### Autocomplete

- Scene IDs after `-> @` (from all workspace `.kata` files)
- Variable names inside `${...}` and `cond="..."` (extracted from `<script>` blocks)
- Asset keys inside `[bg src="..."]` (from frontmatter `assets`)

### Hover

- Variable info on `${path}` — shows whether the variable is defined in any script block
- Asset info on `[bg src="..."]` — shows mapped URL from frontmatter
- Scene info on `-> @scene/id` — shows which file defines the target

### Go-to-Definition

- Jump from `-> @scene/id` to the `.kata` file containing that scene

### Document Symbols

- Outline view with scene ID (module), speaker names (function), and choice labels (property)

## Architecture

The LSP is built as pure handler functions that can be tested without VS Code:

| Module | Purpose |
|--------|---------|
| `src/workspace.ts` | `WorkspaceIndex` — cross-file index of scenes, variables, assets |
| `src/diagnostics.ts` | Per-file + cross-file diagnostic generation |
| `src/completions.ts` | Context-aware completion items |
| `src/hover.ts` | Hover info for variables, assets, scene targets |
| `src/definition.ts` | Go-to-definition for scene targets |
| `src/symbols.ts` | Document symbol extraction |
| `src/server.ts` | LSP server entry point (stdio transport) |

## Usage with VS Code

The `kata-vscode` extension bundles this package and launches it automatically for `.kata` files. No manual configuration needed.

## Usage with Other Editors

The server binary is at `dist/server.js`. Configure your editor's LSP client to launch it:

```bash
# Neovim, Helix, etc.
kata-lsp --stdio
```

Depends on `@kata-framework/core` for parsing and `vscode-languageserver` for the LSP protocol.
npm package: @kata-framework/test-utils
Description: Test utilities for the Kata narrative engine. Eliminates boilerplate when testing `.kata` scenes — parse, run, and assert in a few lines.
Latest version: 0.2.5

# @kata-framework/test-utils

Test utilities for the Kata narrative engine. Eliminates boilerplate when testing `.kata` scenes — parse, run, and assert in a few lines.

## Install

```bash
bun add -d @kata-framework/test-utils
```

## API

### `createTestEngine(input, ctx?)`

One-liner engine setup from raw `.kata` strings.

```ts
import { createTestEngine } from "@kata-framework/test-utils";

const { engine, frames } = createTestEngine(`
---
id: test
title: Test Scene
---
:: Narrator :: Hello world
`, { player: { gold: 100 } });

engine.start("test");
// frames is a live array — it updates as the engine emits
```

- Accepts a single `.kata` string or an array of strings
- Registers all scenes automatically
- Applies initial context
- Returns `{ engine, frames }` where `frames` is a live array updated on `"update"` events

### `collectFrames(engine, sceneId, options?)`

Auto-advances a scene to completion and returns all emitted frames.

```ts
import { collectFrames } from "@kata-framework/test-utils";

const allFrames = collectFrames(engine, "test");
// allFrames: KSONFrame[]
```

Options:
- `autoPick?: number` — auto-pick choice by index when encountered (default: stops at first choice)
- `maxFrames?: number` — safety limit to prevent infinite loops

### `assertFrame(frame, expected)`

Partial matching on frame fields with readable error messages.

```ts
import { assertFrame } from "@kata-framework/test-utils";

assertFrame(allFrames[0], {
  type: "text",
  speaker: "Narrator",
  content: "Hello world",
});
```

Only checks the fields you provide — no need to match the full frame shape.

### `mockAudioManager()`

Records audio commands for test assertions.

```ts
import { mockAudioManager } from "@kata-framework/test-utils";

const audio = mockAudioManager();
engine.on("audio", audio.handler);

// After engine runs...
expect(audio.commands).toEqual([{ action: "play", id: "bgm" }]);
audio.lastCommand; // most recent command
audio.reset();     // clear recorded commands
```

## Usage with bun:test

```ts
import { expect, test } from "bun:test";
import { createTestEngine, collectFrames, assertFrame } from "@kata-framework/test-utils";

test("intro scene plays through", () => {
  const { engine } = createTestEngine(introKata);
  const frames = collectFrames(engine, "intro");

  expect(frames).toHaveLength(3);
  assertFrame(frames[0], { type: "text", speaker: "Narrator" });
});
```

Depends on `@kata-framework/core` via `workspace:*`.