openkitt 0.3.18 → 0.4.0

package/README.md

@@ -2,188 +2,111 @@
 
 **AI-powered monorepo CLI for Railway deployments.**
 
-KITT is an interactive terminal interface that scaffolds full-stack monorepos, adds apps with integrations pre-wired, and manages deployment to [Railway](https://railway.app) — all from a persistent REPL shell.
-
 ```
   ______ _______________________
   ___  //_/___  /__  __/__  __/
   __  ,<   __  / __  /  __  /
   _  /| | __/ /  _  /   _  /
   /_/ |_| /___/  /_/    /_/
-
-  KITT v0.3.17 — AI-Powered App Scaffolding CLI
 ```
 
----
-
-## Why KITT?
-
-Modern app development means stitching together a monorepo, a cloud platform, an ORM, auth, payments, a job queue, and more — before writing a single line of product code. The setup tax is real and repetitive.
-
-KITT eliminates that tax. It scaffolds a production-ready monorepo in one command, adds new apps with integrations already wired, and handles Railway deployments through a conversational REPL — no context-switching, no config hunting.
-
----
-
-## Who it's for
-
-- **Indie developers and small teams** shipping full-stack TypeScript apps to Railway
-- **Developers who want opinions** — KITT makes a stack choice (TanStack Start, Next.js, Hono, Express) and sets it up correctly
-- **Teams who iterate fast** — add apps, provision databases, rotate envs, tail logs, all without leaving the terminal
-
----
-
-## Features
-
-- **Interactive REPL** with tab-completion and ghost text suggestions
-- **AI scaffolding** — uses your LLM key (Anthropic, OpenAI, Gemini, or GitHub Copilot) to generate app code, wire integrations, and provision Railway infrastructure
-- **Monorepo workspace** with `apps/` and `packages/` following convention
-- **Framework support**: TanStack Start, Next.js, Hono, Express
-- **Integration catalog**: databases, auth, payments, email, queues, caching, UI, analytics, testing
-- **Version management** — pin integration versions, check for updates, apply selectively
-- **Sandbox & secret scan** — stages LLM-generated files for review before writing to disk; blocks deploys if `.env` files containing secrets would be committed
-- **Non-interactive mode** — scriptable via `--run` flag for CI pipelines
-- **Auto update check** — notifies on new releases at startup
-
----
-
-## Requirements
-
-- Node.js ≥ 20
-- [Railway CLI](https://docs.railway.app/develop/cli) installed and authenticated
-- One of the following LLM providers configured:
-  - **Anthropic** — API key (claude-sonnet-4-5, claude-opus-4-5, claude-3-5-haiku)
-  - **OpenAI** — API key (gpt-4o, gpt-4o-mini, o1, o1-mini)
-  - **Gemini** — API key (gemini-2.0-flash, gemini-2.0-flash-lite, gemini-1.5-pro)
-  - **GitHub Copilot** — device OAuth flow (claude-haiku-4.5, gpt-4.1, claude-sonnet-4.6, claude-opus-4.6)
-
----
+KITT scaffolds full-stack monorepos, adds apps with integrations pre-wired, and manages deployment to [Railway](https://railway.app) — all from a persistent REPL shell.
 
-## Quick Start
+## Install
 
 ```bash
-# Install globally
 npm install -g openkitt
-
-# Or run without installing
-npx openkitt
 ```
 
-### 1. Authenticate
-
-```
-kitt > /login
-```
-
-This walks you through Railway authentication (browser OAuth) and LLM provider setup (provider, model, API key or GitHub Copilot device flow). You only do this once — credentials are stored locally.
-
-### 2. Initialize a workspace
-
-Create a new directory and initialize it as a KITT monorepo:
+Or run without installing:
 
 ```bash
-mkdir my-project && cd my-project
 npx openkitt
 ```
 
-```
-kitt > /init
-```
-
-KITT will:
-- Prompt for a workspace name
-- Create the `apps/` and `packages/` directory structure
-- Write a workspace manifest (`.kitt/manifest.json`)
-- Create a Railway project and link it to the workspace
-- Generate `versions.md` with pinned integration versions
-
-### 3. Add an app
-
-```
-kitt [my-project] > /create
-```
-
-KITT prompts you to select:
-- **Framework** — TanStack Start, Next.js, Hono, or Express
-- **Integrations** — pick from databases, auth, payments, email, queues, UI libraries, testing, and more
-
-Then it scaffolds the app, installs packages, wires integrations, and stages everything for review before writing to disk.
-
-### 4. Run locally
-
-```
-kitt [my-project] > /run
-```
+## Requirements
 
-Starts the dev server for a selected app. Auto-detects the dev script (`dev`, `start`, `serve`, `preview`) and opens the browser when the URL is detected.
+- Node.js ≥ 20
+- [Railway CLI](https://docs.railway.com/guides/cli) installed and authenticated
+- An LLM provider: **Anthropic**, **OpenAI**, **Gemini**, or **GitHub Copilot**
 
-### 5. Deploy to Railway
+## Quick Start
 
 ```
-kitt [my-project] > /deploy
+kitt > /auth:login          # Authenticate Railway + LLM
+kitt > /kitt:init            # Create a new workspace
+kitt [my-project] > /app:create    # Add an app (framework + integrations)
+kitt [my-project] > /deploy:app    # Deploy to Railway
 ```
 
-Selects the app, generates `railway.toml` if needed, scans for exposed secrets, and triggers a Railway deployment via the MCP server.
-
----
-
 ## Commands
 
-### Setup
+### Auth
 
 | Command | Description |
 |---|---|
-| `/login` | Full auth setup — Railway + LLM in one flow |
-| `/login railway` | Authenticate with Railway only |
-| `/login llm` | Configure LLM provider, model, and auth method |
-| `/login model` | Switch active model without re-entering your key |
-| `/login status` | Show current auth status for Railway and LLM |
-| `/logout` | Remove all stored credentials |
+| `/auth:login` | Full auth setup — Railway + LLM |
+| `/auth:railway` | Authenticate with Railway |
+| `/auth:llm` | Configure LLM provider and API key |
+| `/auth:model` | Switch active model |
+| `/auth:status` | Show current auth status |
+| `/auth:logout` | Remove all stored credentials |
 
 ### Workspace
 
 | Command | Description |
 |---|---|
-| `/init` | Scaffold a new KITT monorepo workspace |
-| `/create` | Add a new app to the current workspace |
-| `/delete [appName]` | Remove an app and its files |
-| `/list` | List all apps, packages, and Railway services |
-| `/run [appName]` | Start an app's dev server |
-| `/settings` | View or update workspace settings |
+| `/kitt:init` | Scaffold a new KITT workspace |
+| `/kitt:delete [name]` | Delete a workspace and all its files |
+| `/kitt:switch [name]` | Switch active workspace |
+| `/kitt:list` | List all reachable workspaces |
+| `/kitt:status` | Workspace overview and Railway links |
+| `/kitt:link [projectId]` | Link a Railway project to this workspace |
+
+### Apps
+
+| Command | Description |
+|---|---|
+| `/app:create` | Add a new app (framework + integrations) |
+| `/app:delete [appName]` | Remove an app and its files |
+| `/app:list` | List all apps, packages, and services |
+| `/app:run [appName]` | Start an app's dev server |
+| `/app:settings` | View or update workspace settings |
 
 ### Deploy & Infrastructure
 
 | Command | Description |
 |---|---|
-| `/deploy [appName]` | Deploy an app to Railway |
-| `/deploy:template <name>` | Provision infrastructure — `PostgreSQL`, `MySQL`, `Redis`, `MinIO` |
+| `/deploy:app [appName]` | Deploy an app to Railway |
+| `/deploy:template <query>` | Search and provision a Railway template |
+| `/deploy:delete [service]` | Delete a Railway service |
+| `/deploy:destroy` | Delete entire Railway project (irreversible) |
+| `/deploy:domain [appName]` | Generate or show Railway domain |
+| `/deploy:logs [appName]` | Tail deployment logs |
+| `/deploy:status` | App status and Railway deployment health |
+| `/deploy:health [appName]` | HTTP health check on deployed services |
 | `/env:create <name>` | Create a new Railway environment |
-| `/env:vars [service]` | List environment variables for a service |
-| `/env:vars set [service] <key> <value>` | Set an environment variable |
-| `/domain [appName]` | Generate or show the Railway domain for an app |
-| `/logs [appName]` | Tail deployment logs |
-| `/status` | Show workspace status and Railway deployment health |
+| `/env:delete <name>` | Delete a Railway environment |
+| `/env:vars [service]` | List environment variables |
+| `/env:vars set [svc] <k> <v>` | Set an environment variable |
 
 ### Version Management
 
 | Command | Description |
 |---|---|
-| `/versions` | View all pinned integration versions |
-| `/versions check` | Check npm registry for newer versions |
-| `/versions update` | Interactive update wizard — pick which to bump |
-| `/versions set <integration> <version>` | Pin a specific version manually |
-
----
+| `/versions:list` | View all pinned integration versions |
+| `/versions:check` | Check for newer available versions |
+| `/versions:update` | Interactive version update wizard |
+| `/versions:set <name> <ver>` | Pin a specific version |
 
-## Frameworks & Integrations
-
-**Frameworks**
+## Frameworks
 
 | Type | Options |
 |---|---|
 | Full-stack | `tanstack-start`, `nextjs` |
 | Backend | `hono`, `expressjs` |
 
-**Integrations**
+## Integrations
 
 | Category | Options |
 |---|---|
@@ -198,47 +121,28 @@ Selects the app, generates `railway.toml` if needed, scans for exposed secrets,
 | Analytics | `posthog`, `sentry` |
 | Testing | `vitest`, `playwright`, `storybook` |
 
----
-
 ## CLI Flags
 
 ```
 --verbose              Enable verbose logging
 -q, --quiet            Suppress non-essential output
---run <command>        Execute a single command and exit (non-interactive)
---dry-run              Preview changes without applying them
+--run <command>        Execute a single command and exit
+--dry-run              Preview changes without applying
 -y, --yes              Auto-confirm all prompts
---config <json>        Pass command selections as inline JSON
+--config <json>        Pass command selections as JSON
 --env <name>           Target a specific Railway environment
---no-update-check      Skip the version check on startup
---debug                Show LLM timing and token usage after scaffolding
+--no-update-check      Skip version check on startup
+--debug                Show LLM timing and token usage
 -v, --version          Print CLI version
 -h, --help             Print help
 ```
 
 ### Non-interactive mode
 
-KITT supports scriptable execution via `--run`:
-
 ```bash
-# Deploy from CI without prompts
-npx openkitt --run "deploy my-app" --yes --env production
+npx openkitt --run "deploy:app my-app" --yes --env production
 ```
 
-State-changing commands (`init`, `create`, `delete`, `deploy`, `deploy:template`, `env:create`, `env:vars`, `domain`) require `--yes` in non-interactive mode.
-
----
-
-## How it works
-
-KITT uses an LLM (via your API key or GitHub Copilot) together with Railway's [MCP server](https://github.com/railwayapp/mcp-server) to perform Railway operations — creating projects, provisioning services, setting environment variables, and deploying. The LLM orchestrates MCP tool calls; KITT acts as the secure intermediary, enforcing a project-scoped guard so operations are confined to your linked Railway project.
-
-For `hono` and `expressjs` apps, scaffolding is fully static — the LLM generates code at creation time only. For `tanstack-start` and `nextjs`, full server and client capabilities are available.
-
-Generated code is staged to `.kitt/staging/` for review before being written to disk. A security scanner validates files for suspicious patterns, path traversal, and restricted file types before applying changes.
-
----
-
 ## License
 
 MIT