openkitt 0.1.2

package/README.md

@@ -0,0 +1,236 @@
+# KITT
+
+**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.1.0 — 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, or Gemini) 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
+- **Secret scan** — 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
+- API key for one of: Anthropic, OpenAI, or Gemini
+
+---
+
+## Quick Start
+
+```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). You only do this once — credentials are stored locally.
+
+### 2. Initialize a workspace
+
+Create a new directory and initialize it as a KITT monorepo:
+
+```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
+```
+
+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.
+
+### 5. Deploy to Railway
+
+```
+kitt [my-project] > /deploy
+```
+
+Selects the app, generates `railway.toml` if needed, scans for exposed secrets, and triggers a Railway deployment via the MCP server.
+
+---
+
+## Commands
+
+### Setup
+
+| Command | Description |
+|---|---|
+| `/login` | Full auth setup — Railway + LLM in one flow |
+| `/login railway` | Authenticate with Railway only |
+| `/login llm` | Configure LLM provider, model, and API key |
+| `/login model` | Switch model without re-entering your key |
+| `/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 |
+
+### Deploy & Infrastructure
+
+| Command | Description |
+|---|---|
+| `/deploy [appName]` | Deploy an app to Railway |
+| `/deploy:template <name>` | Provision infrastructure — `PostgreSQL`, `MySQL`, `Redis`, `MinIO` |
+| `/env:create <name>` | Create a new Railway environment |
+| `/env:vars [service]` | List environment variables for a service |
+| `/domain [appName]` | Generate or show the Railway domain for an app |
+| `/logs [appName]` | Tail deployment logs |
+| `/status` | Show workspace status and Railway deployment health |
+
+### 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 |
+
+---
+
+## Frameworks & Integrations
+
+**Frameworks**
+
+| Type | Options |
+|---|---|
+| Full-stack | `tanstack-start`, `nextjs` |
+| Backend | `hono`, `expressjs` |
+
+**Integrations**
+
+| Category | Options |
+|---|---|
+| Databases | `postgresql`, `mysql`, `sqlite` |
+| ORM | `drizzle`, `prisma` |
+| Auth | `better-auth` |
+| Payments | `stripe`, `polar` |
+| Email | `resend` |
+| Queues | `bullmq`, `trigger-dev` |
+| Cache | `redis` |
+| UI | `tailwindcss`, `shadcn` |
+| 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
+-y, --yes              Auto-confirm all prompts
+--config <json>        Pass command selections as inline 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
+-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
+```
+
+State-changing commands (`init`, `create`, `delete`, `deploy`, `env:create`, `env:vars`, `domain`) require `--yes` in non-interactive mode.
+
+---
+
+## How it works
+
+KITT uses an LLM (via your API key) 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.
+
+---
+
+## License
+
+MIT

package/dist/ast/engine.d.ts

@@ -0,0 +1,26 @@
+import { Project, SourceFile } from 'ts-morph';
+export interface AstOperation {
+    op: string;
+    [key: string]: unknown;
+}
+export interface AstTransform {
+    path: string;
+    operations: AstOperation[];
+}
+export interface AstEngineResult {
+    success: boolean;
+    modifiedFiles: string[];
+    errors: AstError[];
+}
+export interface AstError {
+    filePath: string;
+    operation: AstOperation;
+    message: string;
+}
+export interface AstEngine {
+    loadSourceFile(relativePath: string): SourceFile;
+    writeToStaging(relativePath: string, sourceFile: SourceFile): void;
+    applyTransforms(transforms: AstTransform[], operationHandler: (sourceFile: SourceFile, operation: AstOperation) => void): AstEngineResult;
+    getProject(): Project;
+}
+export declare function createAstEngine(workspaceDir: string): AstEngine;

package/dist/ast/engine.js

@@ -0,0 +1,130 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, normalize, relative, resolve } from 'node:path';
+import { Project } from 'ts-morph';
+import { createAuditLogger } from '../audit/logger.js';
+const KITT_DIR = '.kitt';
+const STAGING_DIR = 'staging';
+function hashContent(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+function isRelativePathInside(baseDir, targetPath) {
+    const pathFromBase = relative(baseDir, targetPath);
+    if (pathFromBase === '') {
+        return true;
+    }
+    return !pathFromBase.startsWith('..') && !isAbsolute(pathFromBase);
+}
+function validateRelativePath(relativePath) {
+    if (isAbsolute(relativePath)) {
+        throw new Error(`Absolute paths are not allowed: ${relativePath}`);
+    }
+    const rawSegments = relativePath.split(/[\\/]+/);
+    if (rawSegments.includes('..')) {
+        throw new Error(`Path traversal is not allowed: ${relativePath}`);
+    }
+    const normalizedRelativePath = normalize(relativePath);
+    const pathSegments = normalizedRelativePath.split(/[\\/]+/);
+    if (pathSegments.includes('node_modules')) {
+        throw new Error(`Refusing to load files from node_modules: ${relativePath}`);
+    }
+    if (pathSegments.includes(KITT_DIR)) {
+        throw new Error(`Refusing to load files from ${KITT_DIR}: ${relativePath}`);
+    }
+}
+export function createAstEngine(workspaceDir) {
+    const project = new Project({
+        compilerOptions: {
+            skipLibCheck: true,
+        },
+        skipAddingFilesFromTsConfig: true,
+    });
+    const auditLogger = createAuditLogger(workspaceDir);
+    function loadSourceFile(relativePath) {
+        validateRelativePath(relativePath);
+        const fullPath = resolve(workspaceDir, relativePath);
+        if (!isRelativePathInside(workspaceDir, fullPath)) {
+            throw new Error(`Path is outside workspace: ${relativePath}`);
+        }
+        if (!existsSync(fullPath)) {
+            throw new Error(`File does not exist: ${relativePath}`);
+        }
+        const existing = project.getSourceFile(fullPath);
+        if (existing) {
+            return existing;
+        }
+        return project.addSourceFileAtPath(fullPath);
+    }
+    function writeToStaging(relativePath, sourceFile) {
+        validateRelativePath(relativePath);
+        const stagingPath = join(workspaceDir, KITT_DIR, STAGING_DIR, relativePath);
+        if (!isRelativePathInside(resolve(workspaceDir, KITT_DIR, STAGING_DIR), stagingPath)) {
+            throw new Error(`Refusing to write outside staging directory: ${relativePath}`);
+        }
+        mkdirSync(dirname(stagingPath), { recursive: true });
+        const fullText = sourceFile.getFullText();
+        writeFileSync(stagingPath, fullText, 'utf-8');
+        auditLogger.staged(relativePath, 'AST modified');
+        auditLogger.fileWrite(join(KITT_DIR, STAGING_DIR, relativePath), hashContent(fullText));
+    }
+    function applyTransforms(transforms, operationHandler) {
+        const modifiedFiles = [];
+        const errors = [];
+        for (const transform of transforms) {
+            let sourceFile;
+            try {
+                sourceFile = loadSourceFile(transform.path);
+            }
+            catch (error) {
+                errors.push({
+                    filePath: transform.path,
+                    operation: { op: 'loadSourceFile' },
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                continue;
+            }
+            const priorErrorCount = errors.length;
+            for (const operation of transform.operations) {
+                try {
+                    operationHandler(sourceFile, operation);
+                }
+                catch (error) {
+                    errors.push({
+                        filePath: transform.path,
+                        operation,
+                        message: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
+            if (errors.length > priorErrorCount) {
+                continue;
+            }
+            try {
+                writeToStaging(transform.path, sourceFile);
+                modifiedFiles.push(transform.path);
+            }
+            catch (error) {
+                errors.push({
+                    filePath: transform.path,
+                    operation: { op: 'writeToStaging' },
+                    message: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        return {
+            success: errors.length === 0,
+            modifiedFiles,
+            errors,
+        };
+    }
+    function getProject() {
+        return project;
+    }
+    return {
+        loadSourceFile,
+        writeToStaging,
+        applyTransforms,
+        getProject,
+    };
+}
+//# sourceMappingURL=engine.js.map

package/dist/ast/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../src/ast/engine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC/D,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpF,OAAO,EAAE,OAAO,EAAc,MAAM,UAAU,CAAC;AAE/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAEvD,MAAM,QAAQ,GAAG,OAAO,CAAC;AACzB,MAAM,WAAW,GAAG,SAAS,CAAC;AAkC9B,SAAS,WAAW,CAAC,OAAe;IAClC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC5D,CAAC;AAED,SAAS,oBAAoB,CAAC,OAAe,EAAE,UAAkB;IAC/D,MAAM,YAAY,GAAG,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IACnD,IAAI,YAAY,KAAK,EAAE,EAAE,CAAC;QACxB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,CAAC,YAAY,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;AACrE,CAAC;AAED,SAAS,oBAAoB,CAAC,YAAoB;IAChD,IAAI,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,mCAAmC,YAAY,EAAE,CAAC,CAAC;IACrE,CAAC;IAED,MAAM,WAAW,GAAG,YAAY,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IACjD,IAAI,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,kCAAkC,YAAY,EAAE,CAAC,CAAC;IACpE,CAAC;IAED,MAAM,sBAAsB,GAAG,SAAS,CAAC,YAAY,CAAC,CAAC;IACvD,MAAM,YAAY,GAAG,sBAAsB,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAE5D,IAAI,YAAY,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CAAC,6CAA6C,YAAY,EAAE,CAAC,CAAC;IAC/E,CAAC;IAED,IAAI,YAAY,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,+BAA+B,QAAQ,KAAK,YAAY,EAAE,CAAC,CAAC;IAC9E,CAAC;AACH,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,YAAoB;IAClD,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC;QAC1B,eAAe,EAAE;YACf,YAAY,EAAE,IAAI;SACnB;QACD,2BAA2B,EAAE,IAAI;KAClC,CAAC,CAAC;IACH,MAAM,WAAW,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAAC;IAEpD,SAAS,cAAc,CAAC,YAAoB;QAC1C,oBAAoB,CAAC,YAAY,CAAC,CAAC;QAEnC,MAAM,QAAQ,GAAG,OAAO,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;QACrD,IAAI,CAAC,oBAAoB,CAAC,YAAY,EAAE,QAAQ,CAAC,EAAE,CAAC;YAClD,MAAM,IAAI,KAAK,CAAC,8BAA8B,YAAY,EAAE,CAAC,CAAC;QAChE,CAAC;QAED,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,wBAAwB,YAAY,EAAE,CAAC,CAAC;QAC1D,CAAC;QAED,MAAM,QAAQ,GAAG,OAAO,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;QACjD,IAAI,QAAQ,EAAE,CAAC;YACb,OAAO,QAAQ,CAAC;QAClB,CAAC;QAED,OAAO,OAAO,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IAC/C,CAAC;IAED,SAAS,cAAc,CAAC,YAAoB,EAAE,UAAsB;QAClE,oBAAoB,CAAC,YAAY,CAAC,CAAC;QAEnC,MAAM,WAAW,GAAG,IAAI,CAAC,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,CAAC,CAAC;QAC5E,IAAI,CAAC,oBAAoB,CAAC,OAAO,CAAC,YAAY,EAAE,QAAQ,EAAE,WAAW,CAAC,EAAE,WAAW,CAAC,EAAE,CAAC;YACrF,MAAM,IAAI,KAAK,CAAC,gDAAgD,YAAY,EAAE,CAAC,CAAC;QAClF,CAAC;QAED,SAAS,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAErD,MAAM,QAAQ,GAAG,UAAU,CAAC,WAAW,EAAE,CAAC;QAC1C,aAAa,CAAC,WAAW,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;QAE9C,WAAW,CAAC,MAAM,CAAC,YAAY,EAAE,cAAc,CAAC,CAAC;QACjD,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,EAAE,WAAW,EAAE,YAAY,CAAC,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC1F,CAAC;IAED,SAAS,eAAe,CACtB,UAA0B,EAC1B,gBAA2E;QAE3E,MAAM,aAAa,GAAa,EAAE,CAAC;QACnC,MAAM,MAAM,GAAe,EAAE,CAAC;QAE9B,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACnC,IAAI,UAAsB,CAAC;YAE3B,IAAI,CAAC;gBACH,UAAU,GAAG,cAAc,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YAC9C,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,CAAC,IAAI,CAAC;oBACV,QAAQ,EAAE,SAAS,CAAC,IAAI;oBACxB,SAAS,EAAE,EAAE,EAAE,EAAE,gBAAgB,EAAE;oBACnC,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;iBAChE,CAAC,CAAC;gBACH,SAAS;YACX,CAAC;YAED,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,CAAC;YACtC,KAAK,MAAM,SAAS,IAAI,SAAS,CAAC,UAAU,EAAE,CAAC;gBAC7C,IAAI,CAAC;oBACH,gBAAgB,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;gBAC1C,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,MAAM,CAAC,IAAI,CAAC;wBACV,QAAQ,EAAE,SAAS,CAAC,IAAI;wBACxB,SAAS;wBACT,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;qBAChE,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;YAED,IAAI,MAAM,CAAC,MAAM,GAAG,eAAe,EAAE,CAAC;gBACpC,SAAS;YACX,CAAC;YAED,IAAI,CAAC;gBACH,cAAc,CAAC,SAAS,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;gBAC3C,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YACrC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,CAAC,IAAI,CAAC;oBACV,QAAQ,EAAE,SAAS,CAAC,IAAI;oBACxB,SAAS,EAAE,EAAE,EAAE,EAAE,gBAAgB,EAAE;oBACnC,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;iBAChE,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,OAAO;YACL,OAAO,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC;YAC5B,aAAa;YACb,MAAM;SACP,CAAC;IACJ,CAAC;IAED,SAAS,UAAU;QACjB,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,OAAO;QACL,cAAc;QACd,cAAc;QACd,eAAe;QACf,UAAU;KACX,CAAC;AACJ,CAAC"}

package/dist/ast/operations.d.ts

@@ -0,0 +1,13 @@
+import { SourceFile } from 'ts-morph';
+import type { AstOperation } from './engine.js';
+/**
+ * The set of supported AST operation names.
+ */
+export declare const SUPPORTED_OPERATIONS: ReadonlySet<string>;
+/**
+ * Apply a single AST operation to a source file.
+ * This is the operation handler that gets passed to engine.applyTransforms().
+ *
+ * Throws if the operation type is unknown or if the operation fails.
+ */
+export declare function applyOperation(sourceFile: SourceFile, operation: AstOperation): void;