@kosuke-ai/cli 0.0.56 → 1.0.0

package/README.md

@@ -1,451 +1,34 @@
-# Kosuke CLI
+# @kosuke-ai/cli
 
-Development automation tool for syncing rules and analyzing code quality with Claude AI.
+The Kosuke platform CLI: `kosuke`, the client you install on your own machine to
+drive [app.kosuke.ai](https://app.kosuke.ai). Not the agent that runs inside a
+Kosuke sandbox; that one lives in `sandbox/kosuke-cli` and is never installed
+by hand.
 
-## Installation
-
-Install globally via npm:
-
-```bash
+```sh
 npm install -g @kosuke-ai/cli
-```
-
-Or use with npx (no installation required):
-
-```bash
-npx @kosuke-ai/cli <command>
-```
-
-### Use as Library in TypeScript Projects
-
-Install as a project dependency:
-
-```bash
-npm install @kosuke-ai/cli
-```
-
-Then import and use programmatically:
-
-```typescript
-import {
-  analyseCommand,
-  lintCommand,
-  syncRulesCommand,
-  requirementsCommand,
-  planCoreStream,
-  discoverFiles,
-  createBatches,
-  runLint,
-  runTypecheck,
-} from '@kosuke-ai/cli';
-
-// Run commands programmatically
-await analyseCommand({
-  scope: 'src/components',
-  pr: false,
-});
-
-await lintCommand({ pr: false });
-
-// Use utilities
-const files = await discoverFiles({
-  types: ['ts', 'tsx'],
-  scope: 'lib',
-});
-
-const batches = createBatches(files, {
-  maxSize: 10,
-  groupBy: 'directory',
-});
-
-const lintResult = await runLint();
-if (!lintResult.success) {
-  console.error('Linting failed:', lintResult.error);
-}
-
-// Stream plan command (for real-time updates)
-const stream = planCoreStream({
-  prompt: 'Add dark mode',
-  directory: './my-project',
-});
-
-for await (const event of stream) {
-  if (event.type === 'message') {
-    console.log('Claude:', event.data.text);
-  } else if (event.type === 'done') {
-    console.log('Result:', event.data);
-  }
-}
-```
-
-#### Local Development with npm link
-
-To develop against a local version of kosuke-cli:
-
-```bash
-# In kosuke-cli directory
-npm run dev:link    # Builds, links, and watches for changes
-
-# In your project directory
-npm link @kosuke-ai/cli
-```
-
-Now your project will use the local kosuke-cli, and changes will be reflected automatically.
-
-## Prerequisites
-
-Set up the required environment variables:
-
-```bash
-# Required for Claude API access
-export ANTHROPIC_API_KEY="your-api-key-here"
-
-# Optional: Specify Claude model (default: claude-haiku-4-5-20251001)
-export ANTHROPIC_MODEL="claude-haiku-4-5-20251001"
-
-# Optional: Only required when using --pr flag
-export GITHUB_TOKEN="your-github-token-here"
-```
-
-You can also create a `.env` file in your project root:
-
-```env
-ANTHROPIC_API_KEY=your-api-key-here
-ANTHROPIC_MODEL=claude-haiku-4-5-20251001
-GITHUB_TOKEN=your-github-token-here
-```
-
-**Available Models:**
-
-- `claude-haiku-4-5-20251001` - Fast and cost-effective (default)
-- `claude-sonnet-4-5-20250929` - Balanced performance and quality
-- `claude-opus-4-5-20251101` - Highest quality, slower
-
-Model pricing is configured in `claude.costs.json` (per million tokens).
-
-### CLI Logging (Optional)
-
-Kosuke CLI can automatically log command executions to kosuke-core for analytics, cost monitoring, and debugging. This feature is optional and requires additional configuration.
-
-**Environment Variables:**
-
-```bash
-# Optional: Enable logging to kosuke-core
-export KOSUKE_BASE_URL="https://your-kosuke-core.com"
-export KOSUKE_API_KEY="your-cli-api-key"
-export KOSUKE_PROJECT_ID="your-project-uuid"
-```
-
-Or add to your `.env` file:
-
-```env
-KOSUKE_BASE_URL=https://your-kosuke-core.com
-KOSUKE_API_KEY=your-cli-api-key
-KOSUKE_PROJECT_ID=xxx-xxx-xxx-xxx-xxx
-```
-
-**What gets logged:**
-
-When configured, Kosuke CLI automatically logs:
-
-- Command execution (ship, test, review, getcode, tickets)
-- Token usage (input, output, cache creation, cache read)
-- Cost breakdown (calculated from token usage)
-- Execution time and performance metrics
-- Command-specific metrics (fixes applied, tests run, etc.)
-- Success/error status
-
-**Privacy:**
-
-- Logging is non-blocking and will not interrupt commands if it fails
-- No sensitive data (API keys, tokens, passwords) is logged
-- File paths are logged, but not file contents
-- Logging is automatically enabled when all three environment variables are set
-- Logging can be safely omitted if not using kosuke-core
-
-## Workflow
-
-By default, all commands apply changes **locally** without git operations. This allows you to:
-
-- Review changes before committing
-- Test fixes in your local environment
-- Iterate quickly without creating PRs
-
-Use the `--pr` flag to automatically create a pull request with the changes.
-
-## Commands
-
-### `kosuke serve`
-
-Start an HTTP server that exposes Kosuke CLI commands via REST API with Server-Sent Events (SSE) for real-time streaming.
-
-**Options:**
-
-- `--port=<number>` - Port to listen on (default: 3000)
-
-**Examples:**
-
-```bash
-# Start server on default port 3000
-kosuke serve
-
-# Start server on custom port
-kosuke serve --port=8080
-```
-
-**API Endpoints:**
-
-- `GET /health` - Health check endpoint
-- `POST /api/plan` - Plan command with SSE streaming
-- `POST /api/build` - Build command with SSE streaming
-
-**Example API Usage:**
-
-```bash
-# Health check
-curl http://localhost:3000/health
-
-# Plan command with SSE
-curl -N -X POST http://localhost:3000/api/plan \
-  -H "Content-Type: application/json" \
-  -d '{
-    "query": "Add dark mode toggle",
-    "cwd": "/path/to/project",
-    "noTest": false
-  }'
-
-# Build command with SSE
-curl -N -X POST http://localhost:3000/api/build \
-  -H "Content-Type: application/json" \
-  -d '{
-    "cwd": "/path/to/project",
-    "review": true,
-    "url": "http://localhost:3000"
-  }'
-```
-
-**SSE Event Types:**
-
-The API returns Server-Sent Events (SSE) with the following event types:
-
-- `tool_call` - Tool execution events (file reads, bash commands, etc.)
-- `message` - Assistant text messages (Claude's reasoning and updates)
-- `done` - Final result with statistics, tokens used, and cost
-
-**Request Validation:**
-
-All API requests are validated using Zod schemas:
-
-- `/api/plan` requires: `{ query: string, cwd: string, noTest?: boolean, resume?: string }`
-- `/api/build` requires: `{ cwd: string, ticketsFile?: string, reset?: boolean, review?: boolean }`
-
-Invalid requests return 400 with detailed error messages.
-
-### `kosuke sync-rules`
-
-Sync rules and documentation from kosuke-template repository.
-
-**Options:**
-
-- `--force` - Compare files regardless of recent commit history
-- `--pr` - Create a pull request with the changes
-- `--base-branch=<name>` - Base branch for PR (default: current branch)
-
-**Examples:**
-
-```bash
-# Sync locally
-kosuke sync-rules
-
-# Force comparison and sync locally
-kosuke sync-rules --force
-
-# Create PR with synced changes
-kosuke sync-rules --pr
-
-# Create PR with custom base branch
-kosuke sync-rules --pr --base-branch=develop
-```
-
-### `kosuke analyse`
-
-Analyze and fix code quality issues against CLAUDE.md rules. Applies fixes locally by default.
-
-**Options:**
-
-- `--pr` - Create a pull request with fixes
-- `--base-branch=<name>` - Base branch for PR (default: current branch)
-- `--scope=<dirs>` - Analyze specific directories (comma-separated)
-- `--types=<exts>` - Analyze specific file types (comma-separated)
-
-**Examples:**
-
-```bash
-# Analyze and fix locally
-kosuke analyse
-
-# Analyze specific directories
-kosuke analyse --scope=hooks,lib/trpc
-
-# Analyze specific file types
-kosuke analyse --types=ts,tsx
-
-# Create PR with fixes
-kosuke analyse --pr
-
-# Create PR with custom base branch
-kosuke analyse --pr --base-branch=main
-```
-
-### `kosuke lint`
-
-Use Claude AI to automatically fix linting errors. Applies fixes locally by default.
-
-**Options:**
-
-- `--pr` - Create a pull request with fixes
-- `--base-branch=<name>` - Base branch for PR (default: current branch)
-
-**Examples:**
-
-```bash
-# Fix linting errors locally
-kosuke lint
-
-# Create PR with fixes
-kosuke lint --pr
-
-# Create PR with custom base branch
-kosuke lint --pr --base-branch=main
-```
-
-**Requirements:**
-
-- Your `package.json` must have a `lint` script (e.g., `"lint": "eslint ."`)
-- The lint script should support the `--fix` flag for auto-fixing
-
-### `kosuke requirements`
-
-Interactive requirements gathering tool powered by Claude AI. Creates a comprehensive `docs.md` file through a conversational workflow.
-
-**How it works:**
-
-1. You describe your web application
-2. Claude analyzes and extracts core functionalities
-3. Claude asks clarification questions
-4. You answer iteratively until requirements are clear
-5. Claude generates a detailed `docs.md` with:
-   - Product Overview
-   - Core Functionalities
-   - Technical Architecture
-   - User Flows
-   - Database Schema
-   - API Endpoints
-   - Implementation Notes
-
-**Example:**
-
-```bash
-kosuke requirements
-```
-
-**Features:**
-
-- ✨ Fully interactive conversation workflow
-- 💰 Real-time cost tracking (shows token usage)
-- 🔄 Iterative refinement until requirements are comprehensive
-- 📝 Structured markdown output in `docs.md`
-- 🌐 Optimized for web application projects
-
-## Configuration
-
-### `.kosukeignore`
-
-Create a `.kosukeignore` file in your project root to exclude files and directories from analysis. Uses the same syntax as `.gitignore`.
-
-Example:
-
-```gitignore
-# Ignore build outputs
-dist/
-build/
-
-# Ignore specific files
-*.test.ts
-**/*.spec.ts
-
-# Ignore directories
-node_modules/
-.git/
-```
-
-## Development
-
-### Local Development
-
-If you want to contribute or run from source:
-
-```bash
-# Clone the repository
-git clone https://github.com/Kosuke-Org/kosuke-cli.git
-cd kosuke-cli
-
-# Install dependencies
-npm install
-
-# Build the project
-npm run build
-
-# Run in development mode
-npm run dev <command>
-
-# Link for local testing
-npm link
-kosuke <command>
-```
-
-### Docker Development
-
-Run kosuke-cli inside Docker for an isolated development environment:
-
-**Prerequisites:**
-
-- Docker installed and running
-- `kosuke_network` Docker network created (if you want to connect to other services)
-
-**Quick Start:**
-
-```bash
-# Create .env file with your credentials
-cat > .env << EOF
-ANTHROPIC_API_KEY=your-api-key
-GITHUB_TOKEN=your-github-token
-EOF
-
-# Run the development container
-./docker-dev.sh
-```
-
-The script will:
-
-- Build the Docker image
-- Mount your current directory into the container
-- Connect to `kosuke_network` for inter-service communication
-- Load environment variables from `.env`
-- Drop you into an interactive bash shell
-
-**Inside the container:**
-
-```bash
-# Run any kosuke command
-kosuke sync-rules
-kosuke analyse
-kosuke lint
-
-# The workspace is mounted, so changes are reflected immediately
-npm run build
-kosuke <command>
-
-# Exit the container
-exit
-```
+kosuke auth login          # paste an auth token from Settings
+kosuke projects list | jq '.data[] | {id, name}'
+kosuke sessions create <projectId> --title "Fix the login form" \
+  --content "See the screenshot" --status backlog --attach shot.png
+```
+
+Every command prints the platform's JSON response as is, so it pipes into `jq`.
+Path params are positional, request fields are flags (`--exclude-archived`,
+`--start-line-number 12`), and any body can be passed whole with `--body '{…}'`,
+`--body-file path` or `--body-file -` for stdin. `kosuke <group> --help` lists
+the operations; each one's help is the API's own description.
+
+The token comes from `--api-key`, then `KOSUKE_API_KEY`, then the file
+`kosuke auth login` writes (mode 0600, under `~/.config/kosuke`, or
+`KOSUKE_CONFIG_DIR`). `--api-url` / `KOSUKE_API_URL` point it at another
+deployment.
+
+## Generated from the API
+
+`openapi.json` is the platform's own `GET /api/openapi.json`, snapshotted by
+`bun run openapi:snapshot` at the repository root. `npm run generate` turns it
+into `src/generated/`: request types (openapi-typescript) and one descriptor per
+operation, which the hand-written runtime turns into commands. `npm run check`
+regenerates and fails on any difference, so the tree is only ever what the
+document says.

package/dist/commands/auth.js

@@ -0,0 +1,117 @@
+import { createApiClient } from '../runtime/client.js';
+import { credentialsPath, DEFAULT_API_URL, deleteCredentials, writeCredentials, } from '../runtime/config.js';
+export function attachAuthCommands(root, runtime, deps = {}) {
+    const { env = process.env, fetch, prompt = promptHidden, stdout = (line) => process.stdout.write(line + '\n'), stderr = (line) => process.stderr.write(line + '\n'), exit = (code) => {
+        process.exitCode = code;
+    }, } = deps;
+    const auth = root.command('auth').description('Manage the auth token this machine uses.');
+    auth
+        .command('login')
+        .description('Store an auth token, after checking it works. Takes the global --api-key when ' +
+        'given, and prompts otherwise. Create one in Settings.')
+        .action(async () => {
+        // The global --api-key is the one flag: commander reads a program option
+        // wherever it appears, so a second `--api-key` on this subcommand would
+        // never receive the value. Only that flag counts as the token to store:
+        // logging in is an explicit act, and a stale KOSUKE_API_KEY left in the
+        // shell is exactly what someone running this may be trying to replace.
+        const resolved = runtime.credentials();
+        const apiUrl = resolved.apiUrl;
+        const apiKey = resolved.apiKeySource === 'flag' ? resolved.apiKey : (await prompt('Auth token: ')).trim();
+        if (!apiKey) {
+            stderr('No token given.');
+            exit(1);
+            return;
+        }
+        const who = await verify(apiUrl, apiKey, fetch);
+        if (!who.ok) {
+            stderr(`The token was refused by ${apiUrl} (HTTP ${who.status}). Nothing saved.`);
+            exit(1);
+            return;
+        }
+        const path = writeCredentials({ apiKey, ...(apiUrl !== DEFAULT_API_URL ? { apiUrl } : {}) }, env);
+        stdout(`Logged in to ${apiUrl}; member of ${who.workspaces} workspace${who.workspaces === 1 ? '' : 's'}. Token saved to ${path}.`);
+    });
+    auth
+        .command('status')
+        .description('Show where the token comes from and whether the platform accepts it.')
+        .action(async () => {
+        const { apiKey, apiKeySource, apiUrl, apiUrlSource } = runtime.credentials();
+        const result = {
+            apiUrl,
+            apiUrlSource,
+            apiKeySource,
+            credentialsFile: credentialsPath(env),
+        };
+        if (apiKey) {
+            const who = await verify(apiUrl, apiKey, fetch);
+            result.tokenPrefix = apiKey.slice(0, 12);
+            result.accepted = who.ok;
+            if (who.ok)
+                result.workspaces = who.workspaces;
+            else
+                result.status = who.status;
+        }
+        else {
+            result.accepted = false;
+        }
+        stdout(JSON.stringify(result, null, 2));
+        if (!result.accepted)
+            exit(1);
+    });
+    auth
+        .command('logout')
+        .description('Delete the stored token. Tokens from the environment or flags are untouched.')
+        .action(() => {
+        const path = credentialsPath(env);
+        stdout(deleteCredentials(env) ? `Removed ${path}.` : `Nothing stored at ${path}.`);
+    });
+}
+/** The cheapest call a token must be able to make: the workspaces it belongs to. */
+async function verify(apiUrl, apiKey, fetch) {
+    const client = createApiClient({ apiUrl, apiKey, fetch });
+    const { data, response } = await client.GET('/api/organizations');
+    if (!response.ok)
+        return { ok: false, status: response.status };
+    const list = data?.data;
+    return { ok: true, workspaces: Array.isArray(list) ? list.length : 0 };
+}
+/** Read a line without echoing it, when stdin is a terminal. */
+async function promptHidden(question) {
+    const { stdin, stdout } = process;
+    stdout.write(question);
+    if (!stdin.isTTY) {
+        const { createInterface } = await import('node:readline/promises');
+        const rl = createInterface({ input: stdin, terminal: false });
+        const answer = await rl.question('');
+        rl.close();
+        return answer;
+    }
+    return new Promise((resolve) => {
+        let answer = '';
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.setEncoding('utf8');
+        const onData = (chunk) => {
+            for (const char of chunk) {
+                if (char === '\n' || char === '\r' || char === '\u0004') {
+                    stdin.setRawMode(false);
+                    stdin.pause();
+                    stdin.off('data', onData);
+                    stdout.write('\n');
+                    resolve(answer);
+                    return;
+                }
+                if (char === '\u0003') {
+                    stdin.setRawMode(false);
+                    process.exit(130);
+                }
+                if (char === '\u007f' || char === '\b')
+                    answer = answer.slice(0, -1);
+                else
+                    answer += char;
+            }
+        };
+        stdin.on('data', onData);
+    });
+}

package/dist/generated/commands/deploy/cancel.js

@@ -0,0 +1,17 @@
+export const operation = {
+    "method": "post",
+    "path": "/api/projects/{projectId}/settings/agentic-deploy/cancel",
+    "command": [
+        "deploy",
+        "cancel"
+    ],
+    "summary": "Stop the running deploy. Steers queued behind it are discarded and listed.",
+    "pathParams": [
+        "projectId"
+    ],
+    "query": [],
+    "body": null,
+    "multipart": null,
+    "attachments": false,
+    "anonymous": false
+};

package/dist/generated/commands/deploy/messages.js

@@ -0,0 +1,17 @@
+export const operation = {
+    "method": "get",
+    "path": "/api/projects/{projectId}/deploy-messages",
+    "command": [
+        "deploy",
+        "messages"
+    ],
+    "summary": "Read the deploy conversation and the current deploy status.",
+    "pathParams": [
+        "projectId"
+    ],
+    "query": [],
+    "body": null,
+    "multipart": null,
+    "attachments": false,
+    "anonymous": false
+};

package/dist/generated/commands/deploy/run.js

@@ -0,0 +1,60 @@
+export const operation = {
+    "method": "post",
+    "path": "/api/projects/{projectId}/settings/agentic-deploy",
+    "command": [
+        "deploy",
+        "run"
+    ],
+    "summary": "Start a deploy (empty JSON body), continue the current one with userResponse, or steer a running one with steerTargetDeployJobId. Attachments ride along as multipart, where the message is called content.",
+    "pathParams": [
+        "projectId"
+    ],
+    "query": [],
+    "body": {
+        "fields": [
+            {
+                "name": "userResponse",
+                "flag": "user-response",
+                "kind": "string",
+                "required": false
+            },
+            {
+                "name": "steerTargetDeployJobId",
+                "flag": "steer-target-deploy-job-id",
+                "kind": "string",
+                "required": false
+            },
+            {
+                "name": "freshDeploy",
+                "flag": "fresh-deploy",
+                "kind": "boolean",
+                "required": false
+            }
+        ],
+        "required": false
+    },
+    "multipart": [
+        {
+            "name": "content",
+            "flag": "content",
+            "kind": "string",
+            "required": true,
+            "description": "The message for the deploy agent."
+        },
+        {
+            "name": "freshDeploy",
+            "flag": "fresh-deploy",
+            "kind": "boolean",
+            "required": false,
+            "description": "Sent as the string 'true'."
+        },
+        {
+            "name": "steerTargetDeployJobId",
+            "flag": "steer-target-deploy-job-id",
+            "kind": "string",
+            "required": false
+        }
+    ],
+    "attachments": true,
+    "anonymous": false
+};