@redaksjon/protokoll-cli 0.1.1-dev.0

package/.nvmrc

@@ -0,0 +1 @@
+24

package/README.md

@@ -0,0 +1,252 @@
+# Protokoll CLI
+
+Command-line interface for [Protokoll](https://github.com/redaksjon/protokoll) - A thin MCP client for transcription and context management.
+
+## Overview
+
+`protokoll-cli` is a lightweight command-line client that communicates with the Protokoll MCP server. It provides a familiar CLI experience while leveraging the full power of Protokoll's intelligent transcription pipeline through the Model Context Protocol.
+
+## Architecture
+
+```
+protokoll-cli (this package)     protokoll (core)
+┌─────────────────────┐         ┌──────────────────────┐
+│   CLI Commands      │         │   MCP Server         │
+│   ├─ status         │  stdio  │   ├─ Tools           │
+│   ├─ task           │ ◄─────► │   ├─ Resources       │
+│   ├─ transcript     │         │   ├─ Prompts         │
+│   ├─ context        │         │   └─ Pipeline        │
+│   ├─ project/etc    │         │                      │
+│   ├─ action         │         │   Core Library       │
+│   ├─ feedback       │         │   ├─ Context         │
+│   └─ process/batch  │         │   ├─ Routing         │
+└─────────────────────┘         │   └─ Transcription   │
+                                 └──────────────────────┘
+```
+
+## Installation
+
+```bash
+npm install -g @redaksjon/protokoll-cli
+```
+
+**Prerequisites**: Requires `@redaksjon/protokoll` to be installed (provides the MCP server).
+
+```bash
+npm install -g @redaksjon/protokoll
+```
+
+## Quick Start
+
+```bash
+# Show version information
+protokoll version
+
+# Process an audio file
+protokoll process recording.m4a
+
+# List transcripts
+protokoll transcript list
+
+# Read a transcript
+protokoll transcript read meeting-notes.md
+
+# Manage status
+protokoll status set meeting.md reviewed
+
+# Add a task
+protokoll task add meeting.md "Follow up with client"
+```
+
+## Commands
+
+### Audio Processing
+
+Process audio files through Protokoll's intelligent transcription pipeline:
+
+```bash
+# Process single audio file
+protokoll process <audioFile> [options]
+  -p, --project <projectId>      Specific project ID for routing
+  -o, --output <directory>       Override output directory
+  -m, --model <model>            LLM model for enhancement
+  --transcription-model <model>  Transcription model (default: whisper-1)
+
+# Batch process multiple files
+protokoll batch <inputDirectory> [options]
+  -o, --output <directory>       Override output directory
+  -e, --extensions <list>        Audio extensions (comma-separated)
+```
+
+### Transcript Management
+
+Read and manage transcripts:
+
+```bash
+# Read a transcript
+protokoll transcript read <transcriptPath>
+
+# List transcripts
+protokoll transcript list [options]
+  -l, --limit <number>  Maximum results (default: 50)
+  -s, --search <text>   Search within transcripts
+  --sort <field>        Sort by: date, filename, title (default: date)
+```
+
+### Status Management
+
+Manage transcript lifecycle status:
+
+```bash
+# Set status
+protokoll status set <transcriptPath> <newStatus>
+
+# Show current status
+protokoll status show <transcriptPath>
+```
+
+Valid statuses: `initial`, `enhanced`, `reviewed`, `in_progress`, `closed`, `archived`
+
+### Task Management
+
+Manage transcript tasks:
+
+```bash
+# Add a task
+protokoll task add <transcriptPath> <description>
+
+# Complete a task
+protokoll task complete <transcriptPath> <taskId>
+
+# Delete a task
+protokoll task delete <transcriptPath> <taskId>
+```
+
+### Context Management
+
+Manage context entities (projects, people, terms, companies):
+
+```bash
+# Show context system status
+protokoll context status
+
+# Search across all entities
+protokoll context search <query>
+
+# Entity commands (project, person, term, company)
+protokoll <entity> list [--verbose]
+protokoll <entity> show <id>
+protokoll <entity> add [options]
+protokoll <entity> delete <id>
+
+# Term-specific
+protokoll term merge <sourceId> <targetId>
+```
+
+### Transcript Actions
+
+Perform actions on transcripts:
+
+```bash
+# Combine multiple transcripts
+protokoll action combine <files...> [options]
+  -t, --title <title>    Title for combined transcript
+  -p, --project <id>     Project ID to assign
+
+# Edit transcript metadata
+protokoll action edit <transcriptPath> [options]
+  -t, --title <title>    New title (renames file)
+  -p, --project <id>     New project ID
+  --add-tag <tag>        Add a tag (repeatable)
+  --remove-tag <tag>     Remove a tag (repeatable)
+  -s, --status <status>  New status
+
+# Change transcript date
+protokoll action change-date <transcriptPath> <newDate>
+
+# Create a new note
+protokoll action create-note [options]
+  -t, --title <title>    Note title (required)
+  -c, --content <text>   Note content
+  -p, --project <id>     Project ID
+  --tag <tag>            Add tag (repeatable)
+  -d, --date <date>      Date (ISO format)
+```
+
+### Feedback
+
+Provide natural language feedback to correct transcripts:
+
+```bash
+protokoll feedback <transcriptPath> <feedback> [options]
+  -m, --model <model>  LLM model for processing
+
+# Examples:
+protokoll feedback meeting.md "YB should be Wibey"
+protokoll feedback notes.md "This should be assigned to quarterly-review project"
+```
+
+## Configuration
+
+Protokoll-cli uses the Protokoll core's configuration system. Configuration is stored in `.protokoll/config.yaml` in your workspace.
+
+The CLI automatically discovers configuration by searching up the directory tree from your current working directory.
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://github.com/redaksjon/protokoll-cli.git
+cd protokoll-cli
+
+# Install dependencies
+npm install
+
+# Link local protokoll for development
+cd ../protokoll && npm link
+cd ../protokoll-cli && npm link @redaksjon/protokoll
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Run locally
+node dist/main.js --help
+```
+
+## How It Works
+
+### MCP Communication
+
+Protokoll-cli spawns the Protokoll MCP server (`protokoll-mcp`) as a child process and communicates via stdio transport:
+
+1. CLI command is invoked
+2. `createMCPClient()` spawns `protokoll-mcp` server
+3. Client sends MCP tool call (JSON-RPC over stdio)
+4. Server processes request and returns result
+5. CLI formats and displays output
+6. Connection is closed
+
+### Progress Notifications
+
+Long-running operations (audio processing, batch operations) can send progress notifications from the server. The CLI renders these as progress bars in TTY environments or milestone logs in non-TTY environments.
+
+## Relationship to Protokoll Core
+
+`protokoll-cli` is a **thin client** - it contains no business logic. All transcription, context management, routing, and entity operations are handled by the Protokoll core via MCP tool calls.
+
+This architecture provides several benefits:
+- **Consistency**: Same backend for CLI, VS Code extension, macOS app, and Cursor
+- **Maintainability**: Business logic in one place
+- **Extensibility**: Easy to add new clients without duplicating logic
+- **Testing**: Core logic tested independently of CLI presentation
+
+## License
+
+Apache-2.0
+
+## Author
+
+Tim O'Brien <tobrien@discursive.com>