@prajwolkc/stk 0.1.1 → 0.2.1

package/README.md

@@ -4,10 +4,13 @@ One CLI to deploy, monitor, and debug your entire stack.
 
 Stop opening 5 dashboards. `stk` checks your services, watches your deploys, syncs your env vars, tails your logs, and manages your issues — all from one command.
 
+<!-- TODO: Add demo GIF here -->
+<!-- ![stk demo](./docs/demo.gif) -->
+
 ## Install
 
 ```bash
-npm install -g stk-cli
+npm install -g @prajwolkc/stk
 ```
 
 ## Quick Start
@@ -16,6 +19,7 @@ npm install -g stk-cli
 cd my-project
 stk init                      # auto-detect your services
 stk init --template saas      # or use a starter template
+stk doctor                    # diagnose any misconfig
 stk health                    # check everything
 stk status                    # one-line summary of your whole stack
 ```
@@ -27,10 +31,12 @@ stk status                    # one-line summary of your whole stack
 | `stk init` | Initialize config (auto-detect or `--template saas\|api\|fullstack\|static\|fly\|aws`) |
 | `stk status` | One-line summary: git, services, deploys, issues |
 | `stk health` | Health check all configured services |
-| `stk deploy` | Git push + watch Railway/Vercel/Fly deploys |
+| `stk doctor` | Diagnose misconfig, missing env vars, and suggest fixes |
+| `stk deploy` | Git push + watch deploy providers |
 | `stk env pull` | Pull env vars from Vercel + Railway into `.env.pulled` |
 | `stk env diff` | Show what's in your local `.env` |
-| `stk logs` | Tail Railway deployment logs |
+| `stk logs` | Tail logs from Railway, Vercel, Fly, or Render |
+| `stk logs -p vercel` | Logs from a specific provider |
 | `stk todo ls` | List open GitHub issues |
 | `stk todo add "title"` | Create a GitHub issue |
 | `stk todo close 42` | Close an issue |
@@ -40,6 +46,7 @@ stk status                    # one-line summary of your whole stack
 **Deploy providers:** Railway, Vercel, Fly.io, Render, AWS
 **Databases:** PostgreSQL, MongoDB, Redis, Supabase
 **Storage & billing:** Cloudflare R2, Stripe
+**Custom:** Add your own via plugins
 
 ## Configuration
 
@@ -82,15 +89,57 @@ stk init --list-templates
 | `fly` | Fly.io + PostgreSQL + Redis |
 | `aws` | AWS + PostgreSQL + Redis |
 
-## Environment Variables
+## Doctor
+
+`stk doctor` scans your config and environment to catch issues before they bite:
+
+```
+$ stk doctor
+
+  my-saas — Doctor
+  ─────────────────────────────────────────
+  ✓  railway      Configured correctly
+  ✗  vercel       Missing required: VERCEL_TOKEN
+                   See https://vercel.com/account/tokens
+  !  database     Missing optional: RAILWAY_PROJECT_ID
+                   Some features need these for full functionality
+  ✓  stripe       Configured correctly
+```
+
+## Plugins
+
+Add custom services without forking. Create `.stk/plugins/my-service.mjs`:
+
+```js
+export default {
+  name: "my-plugin",
+  services: {
+    myservice: {
+      name: "My Service",
+      envVars: ["MY_SERVICE_TOKEN"],
+      healthCheck: async () => {
+        const token = process.env.MY_SERVICE_TOKEN;
+        if (!token) {
+          return { name: "My Service", status: "skipped", detail: "MY_SERVICE_TOKEN not set" };
+        }
+        // Your check logic here
+        return { name: "My Service", status: "healthy", detail: "connected" };
+      }
+    }
+  }
+};
+```
 
-Set the tokens for your services:
+Plugins are automatically loaded by `stk health` and `stk health --all`.
+
+## Environment Variables
 
 ```bash
 # Deploy providers
 RAILWAY_API_TOKEN=
 VERCEL_TOKEN=
 FLY_API_TOKEN=
+FLY_APP_NAME=              # needed for stk logs -p fly
 RENDER_API_KEY=
 AWS_ACCESS_KEY_ID= / AWS_SECRET_ACCESS_KEY=
 
@@ -109,6 +158,64 @@ GITHUB_TOKEN=
 GITHUB_REPO=owner/repo   # or auto-detected from git remote
 ```
 
+## Claude Code / MCP Integration
+
+`stk` ships with a built-in MCP server so Claude Code can use your infrastructure as native tools.
+
+### Setup
+
+1. Install stk globally:
+
+```bash
+npm install -g @prajwolkc/stk
+```
+
+2. Add to your project's `.mcp.json` (create it in your project root):
+
+```json
+{
+  "mcpServers": {
+    "stk": {
+      "command": "stk-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+3. Restart Claude Code. Approve the stk MCP server when prompted.
+
+### What Claude can do
+
+| Tool | Description |
+|------|-------------|
+| `stk_health` | Check if all services are up before writing code |
+| `stk_status` | Full overview: git, services, deploys, issues |
+| `stk_doctor` | Diagnose misconfig and missing env vars |
+| `stk_logs` | Read production logs to understand bugs |
+| `stk_todo_list` | See what needs to be worked on |
+| `stk_todo_add` | Create GitHub issues |
+| `stk_deploy` | Push code and trigger deploys |
+| `stk_config` | Read the project's stack config |
+
+### Example prompts
+
+- *"Check if all my services are healthy"*
+- *"What errors are in my production logs?"*
+- *"What should I work on next?"*
+- *"Deploy this and verify it worked"*
+
+## Development
+
+```bash
+git clone https://github.com/Harden43/stk.git
+cd stk
+npm install
+npm run dev -- health --all     # run in dev mode
+npm test                        # run tests
+npm run build                   # compile TypeScript
+```
+
 ## License
 
 MIT

package/dist/commands/doctor.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const doctorCommand: Command;

package/dist/commands/doctor.js

@@ -0,0 +1,220 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { existsSync } from "fs";
+import { loadConfig, enabledServices, CONFIG_FILE } from "../lib/config.js";
+const ENV_REQUIREMENTS = {
+    railway: {
+        required: ["RAILWAY_API_TOKEN"],
+        optional: ["RAILWAY_PROJECT_ID", "RAILWAY_ENVIRONMENT_ID", "RAILWAY_SERVICE_ID"],
+        docs: "https://docs.railway.com/guides/public-api",
+    },
+    vercel: {
+        required: ["VERCEL_TOKEN"],
+        optional: ["VERCEL_PROJECT_ID"],
+        docs: "https://vercel.com/account/tokens",
+    },
+    fly: {
+        required: ["FLY_API_TOKEN"],
+        optional: ["FLY_APP_NAME"],
+        docs: "https://fly.io/docs/flyctl/tokens/",
+    },
+    render: {
+        required: ["RENDER_API_KEY"],
+        optional: [],
+        docs: "https://render.com/docs/api",
+    },
+    aws: {
+        required: ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY"],
+        optional: ["AWS_REGION"],
+    },
+    database: {
+        required: ["DATABASE_URL"],
+        optional: [],
+    },
+    mongodb: {
+        required: ["MONGODB_URL"],
+        optional: [],
+    },
+    redis: {
+        required: ["REDIS_URL"],
+        optional: [],
+    },
+    supabase: {
+        required: ["SUPABASE_URL"],
+        optional: ["SUPABASE_SERVICE_KEY", "SUPABASE_ANON_KEY"],
+        docs: "https://supabase.com/docs/guides/api",
+    },
+    r2: {
+        required: ["CLOUDFLARE_ACCOUNT_ID", "CLOUDFLARE_API_TOKEN"],
+        optional: [],
+        docs: "https://developers.cloudflare.com/r2/api/",
+    },
+    stripe: {
+        required: ["STRIPE_SECRET_KEY"],
+        optional: [],
+        docs: "https://dashboard.stripe.com/apikeys",
+    },
+};
+export const doctorCommand = new Command("doctor")
+    .description("Diagnose configuration issues and suggest fixes")
+    .action(async () => {
+    const issues = [];
+    // 1. Check config file
+    const hasConfig = existsSync(CONFIG_FILE);
+    if (!hasConfig) {
+        issues.push({
+            level: "warn",
+            service: "config",
+            message: `No ${CONFIG_FILE} found — using auto-detection`,
+            fix: `Run ${chalk.white("stk init")} to create one`,
+        });
+    }
+    const config = loadConfig();
+    const enabled = enabledServices(config);
+    // 2. Check each enabled service for env vars
+    for (const svc of enabled) {
+        const reqs = ENV_REQUIREMENTS[svc];
+        if (!reqs)
+            continue;
+        const missingRequired = reqs.required.filter((v) => !process.env[v]);
+        const missingOptional = reqs.optional.filter((v) => !process.env[v]);
+        if (missingRequired.length > 0) {
+            issues.push({
+                level: "error",
+                service: svc,
+                message: `Missing required: ${missingRequired.join(", ")}`,
+                fix: reqs.docs ? `See ${reqs.docs}` : `Set ${missingRequired[0]} in your .env`,
+            });
+        }
+        if (missingOptional.length > 0) {
+            issues.push({
+                level: "warn",
+                service: svc,
+                message: `Missing optional: ${missingOptional.join(", ")}`,
+                fix: `Some features (logs, env sync, deploy) need these for full functionality`,
+            });
+        }
+        if (missingRequired.length === 0) {
+            issues.push({
+                level: "info",
+                service: svc,
+                message: "Configured correctly",
+            });
+        }
+    }
+    // 3. Check for partial config (env vars set but service not enabled)
+    for (const [svc, reqs] of Object.entries(ENV_REQUIREMENTS)) {
+        if (enabled.includes(svc))
+            continue;
+        const hasAny = reqs.required.some((v) => process.env[v]);
+        if (hasAny) {
+            issues.push({
+                level: "warn",
+                service: svc,
+                message: `Env vars found but service not enabled in config`,
+                fix: `Add "${svc}": true to services in ${CONFIG_FILE}`,
+            });
+        }
+    }
+    // 4. Check for common misconfigurations
+    if (process.env.DATABASE_URL) {
+        try {
+            new URL(process.env.DATABASE_URL);
+        }
+        catch {
+            issues.push({
+                level: "error",
+                service: "database",
+                message: "DATABASE_URL is not a valid URL",
+                fix: "Format: postgresql://user:pass@host:5432/dbname",
+            });
+        }
+    }
+    if (process.env.REDIS_URL) {
+        try {
+            new URL(process.env.REDIS_URL);
+        }
+        catch {
+            issues.push({
+                level: "error",
+                service: "redis",
+                message: "REDIS_URL is not a valid URL",
+                fix: "Format: redis://default:pass@host:6379",
+            });
+        }
+    }
+    if (process.env.STRIPE_SECRET_KEY && !process.env.STRIPE_SECRET_KEY.startsWith("sk_")) {
+        issues.push({
+            level: "error",
+            service: "stripe",
+            message: "STRIPE_SECRET_KEY should start with sk_test_ or sk_live_",
+        });
+    }
+    // 5. Check deploy config
+    if (hasConfig && config.deploy?.providers) {
+        for (const p of config.deploy.providers) {
+            if (!enabled.includes(p)) {
+                issues.push({
+                    level: "error",
+                    service: "deploy",
+                    message: `Deploy provider "${p}" is not enabled in services`,
+                    fix: `Add "${p}": true to services, or remove from deploy.providers`,
+                });
+            }
+        }
+    }
+    // 6. Check GitHub config for todo
+    if (!process.env.GITHUB_TOKEN && !config.github?.repo) {
+        issues.push({
+            level: "info",
+            service: "github",
+            message: "GITHUB_TOKEN not set — stk todo will have limited access",
+            fix: "Set GITHUB_TOKEN for creating/closing issues",
+        });
+    }
+    // Print results
+    const ICONS = {
+        error: chalk.red("✗"),
+        warn: chalk.yellow("!"),
+        info: chalk.green("✓"),
+    };
+    const COLORS = {
+        error: chalk.red,
+        warn: chalk.yellow,
+        info: chalk.green,
+    };
+    console.log();
+    console.log(chalk.bold(`  ${config.name} — Doctor`));
+    console.log(chalk.dim("  ─────────────────────────────────────────"));
+    const grouped = new Map();
+    for (const issue of issues) {
+        const list = grouped.get(issue.service) ?? [];
+        list.push(issue);
+        grouped.set(issue.service, list);
+    }
+    for (const [service, serviceIssues] of grouped) {
+        for (const issue of serviceIssues) {
+            const icon = ICONS[issue.level];
+            const svc = COLORS[issue.level](service.padEnd(12));
+            console.log(`  ${icon}  ${svc} ${issue.message}`);
+            if (issue.fix) {
+                console.log(`     ${" ".repeat(12)} ${chalk.dim(issue.fix)}`);
+            }
+        }
+    }
+    const errors = issues.filter((i) => i.level === "error");
+    const warns = issues.filter((i) => i.level === "warn");
+    const ok = issues.filter((i) => i.level === "info");
+    console.log();
+    if (errors.length > 0) {
+        console.log(chalk.red(`  ${errors.length} error${errors.length > 1 ? "s" : ""} found`));
+        process.exitCode = 1;
+    }
+    else if (warns.length > 0) {
+        console.log(chalk.yellow(`  ${warns.length} warning${warns.length > 1 ? "s" : ""}, ${ok.length} ok`));
+    }
+    else {
+        console.log(chalk.green(`  All ${ok.length} checks passed`));
+    }
+    console.log();
+});

package/dist/commands/health.js

@@ -2,7 +2,8 @@ import { Command } from "commander";
 import chalk from "chalk";
 import ora from "ora";
 import { loadConfig, enabledServices } from "../lib/config.js";
-import { getChecker, allCheckerNames } from "../services/registry.js";
+import { getChecker, allCheckerNames, loadPluginCheckers } from "../services/registry.js";
+import { jsonOutput } from "../lib/output.js";
 const STATUS_ICON = {
     healthy: chalk.green("✓"),
     degraded: chalk.yellow("~"),
@@ -19,20 +20,25 @@ export const healthCommand = new Command("health")
     .description("Check the health of all connected services")
     .option("-v, --verbose", "Show latency and extra detail")
     .option("-a, --all", "Check all known services, not just configured ones")
+    .option("-j, --json", "Output as JSON")
     .action(async (opts) => {
     const config = loadConfig();
-    const spinner = ora("Checking services...").start();
+    await loadPluginCheckers();
     const serviceList = opts.all
         ? allCheckerNames()
         : enabledServices(config);
     if (serviceList.length === 0) {
-        spinner.stop();
+        if (opts.json) {
+            jsonOutput({ services: [], summary: "no services configured" });
+            return;
+        }
         console.log();
         console.log(chalk.yellow("  No services configured."));
         console.log(chalk.dim(`  Run ${chalk.white("stk init")} to set up your project, or ${chalk.white("stk health --all")} to check everything.`));
         console.log();
         return;
     }
+    const spinner = opts.json ? null : ora("Checking services...").start();
     const checks = serviceList.map((name) => {
         const checker = getChecker(name);
         if (!checker) {
@@ -45,7 +51,26 @@ export const healthCommand = new Command("health")
         return checker();
     });
     const results = await Promise.all(checks);
-    spinner.stop();
+    spinner?.stop();
+    // JSON output
+    if (opts.json) {
+        const down = results.filter((r) => r.status === "down");
+        jsonOutput({
+            project: config.name,
+            services: results,
+            summary: {
+                healthy: results.filter((r) => r.status === "healthy").length,
+                down: down.length,
+                skipped: results.filter((r) => r.status === "skipped").length,
+                total: results.length,
+            },
+            ok: down.length === 0,
+        });
+        if (down.length > 0)
+            process.exitCode = 1;
+        return;
+    }
+    // Human output
     console.log();
     console.log(chalk.bold(`  ${config.name} — Service Health`));
     console.log(chalk.dim("  ─────────────────────────────────────────"));