create-interview-cockpit 0.1.0

package/README.md

@@ -0,0 +1,62 @@
+# create-interview-cockpit
+
+Scaffold your own AI-powered interview prep cockpit in seconds.
+
+```bash
+npx create-interview-cockpit
+```
+
+## What you get
+
+A self-hosted, full-stack interview prep tool with:
+
+- **Topics** — organise prep by theme (C#, System Design, Azure, etc.)
+- **Questions** — nested questions under each topic with persistent chat history
+- **AI chat** — powered by any of OpenAI / Google Gemini / Anthropic Claude via the Vercel AI SDK
+- **Context files** — attach PDFs, DOCX, or plain text (job specs, CVs, notes) as context per topic or question
+- **Code context panel** — point the AI at your local codebase files
+- **Text annotations** — highlight any AI response and ask follow-up questions inline
+- **Response tuning** — control length (concise / moderate / full) and style (prose / bullets / structured)
+- **Mermaid diagrams** — the AI renders architecture diagrams inline
+
+## Usage
+
+```bash
+npx create-interview-cockpit my-cockpit
+cd my-cockpit
+npm install
+npm run dev
+```
+
+The CLI will prompt you to choose an AI provider (OpenAI, Google, or Anthropic) and optionally paste your API key. Everything is written to a local `.env` file — nothing leaves your machine.
+
+Open **http://localhost:5173**.
+
+## Tech stack
+
+| Layer    | Tech                                 |
+|----------|--------------------------------------|
+| Frontend | React 19, TypeScript, Vite, Tailwind |
+| Backend  | Express, TypeScript, tsx             |
+| AI       | Vercel AI SDK (multi-provider)       |
+| Storage  | Local JSON files                     |
+
+## Supported AI providers
+
+| Provider  | Env var              | Default model              |
+|-----------|----------------------|----------------------------|
+| OpenAI    | `OPENAI_API_KEY`     | `gpt-4o`                   |
+| Google    | `GOOGLE_API_KEY`     | `gemini-2.5-flash`         |
+| Anthropic | `ANTHROPIC_API_KEY`  | `claude-sonnet-4-20250514` |
+
+Switch provider at any time by editing `.env`:
+
+```ini
+AI_PROVIDER=google
+AI_MODEL=gemini-2.5-flash
+GOOGLE_API_KEY=your-key-here
+```
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+
+import fs from "fs";
+import path from "path";
+import readline from "readline";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const templateDir = path.join(__dirname, "template");
+
+// This CLI's own version — used for upgrade version stamping
+const CLI_VERSION = JSON.parse(
+  fs.readFileSync(path.join(__dirname, "package.json"), "utf-8")
+).version;
+
+// ── Readline helpers ───────────────────────────────────────
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+});
+
+const ask = (question, fallback) =>
+  new Promise((resolve) => {
+    const suffix = fallback ? ` (${fallback}): ` : ": ";
+    rl.question(question + suffix, (answer) => {
+      resolve(answer.trim() || fallback || "");
+    });
+  });
+
+const askChoice = (question, choices, fallback) =>
+  new Promise((resolve) => {
+    rl.question(`${question} [${choices.join("/")}] (${fallback}): `, (answer) => {
+      const v = answer.trim().toLowerCase();
+      resolve(choices.includes(v) ? v : fallback);
+    });
+  });
+
+const confirm = (message) =>
+  new Promise((resolve) => {
+    rl.question(`${message} [y/N]: `, (answer) => {
+      resolve(answer.trim().toLowerCase() === "y");
+    });
+  });
+
+// ── Helpers ────────────────────────────────────────────────
+// Files/dirs never overwritten during upgrade
+const UPGRADE_KEEP = new Set([".env", "data", "node_modules", "dist"]);
+// Files/dirs excluded when copying from the template
+const COPY_EXCLUDE = new Set(["node_modules", "dist", ".env"]);
+
+function copyDirSync(src, dest, exclude = COPY_EXCLUDE) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (exclude.has(entry.name)) continue;
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirSync(srcPath, destPath, exclude);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+/** Merge incoming deps into existing — never downgrade a pinned version. */
+function mergeDeps(existing = {}, incoming = {}) {
+  const merged = { ...existing };
+  for (const [pkg, ver] of Object.entries(incoming)) {
+    if (!(pkg in merged)) merged[pkg] = ver;
+  }
+  return merged;
+}
+
+// ── Create command ────────────────────────────────────────
+async function runCreate() {
+  const projectArg = process.argv[2];
+
+  console.log("");
+  console.log("╔══════════════════════════════════════════════════╗");
+  console.log("║    create-interview-cockpit                      ║");
+  console.log("║    Your personal AI-powered interview prep tool  ║");
+  console.log("╚══════════════════════════════════════════════════╝");
+  console.log("");
+
+  // ── Project directory ──────────────────────────────────
+  const projectName =
+    projectArg || (await ask("  Project directory name", "my-cockpit"));
+  const targetDir = path.resolve(process.cwd(), projectName);
+
+  if (fs.existsSync(targetDir) && fs.readdirSync(targetDir).length > 0) {
+    console.error(`\n  ✖ Directory "${projectName}" already exists and is not empty.\n`);
+    rl.close();
+    process.exit(1);
+  }
+
+  // ── AI Provider ────────────────────────────────────────
+  console.log("");
+  console.log("  Interview Cockpit supports OpenAI, Google Gemini, and Anthropic Claude.");
+  console.log("");
+  const provider = await askChoice(
+    "  AI provider",
+    ["openai", "google", "anthropic"],
+    "openai"
+  );
+
+  const keyEnvNames = {
+    openai: "OPENAI_API_KEY",
+    google: "GOOGLE_API_KEY",
+    anthropic: "ANTHROPIC_API_KEY",
+  };
+  const defaultModels = {
+    openai: "gpt-4o",
+    google: "gemini-2.5-flash",
+    anthropic: "claude-sonnet-4-20250514",
+  };
+  const keyName = keyEnvNames[provider];
+  const defaultModel = defaultModels[provider];
+
+  const apiKey = await ask(
+    `  ${keyName} (paste your key, or leave blank to add to .env later)`,
+    ""
+  );
+  const model = await ask("  Model name", defaultModel);
+
+  console.log("");
+  console.log("  ─── Summary ─────────────────────────────────────");
+  console.log("  Directory : " + projectName);
+  console.log("  Provider  : " + provider);
+  console.log("  Model     : " + model);
+  console.log("  ─────────────────────────────────────────────────");
+  console.log("");
+
+  // ── 1. Copy template ──────────────────────────────────
+  console.log("  Scaffolding project…");
+  copyDirSync(templateDir, targetDir);
+  // cockpit.json is already in the template with the correct version
+  console.log("  ✔ Copied template");
+
+  // ── 2. Write .env ─────────────────────────────────────
+  const envLines = [
+    `# AI provider: openai | google | anthropic`,
+    `AI_PROVIDER=${provider}`,
+    `AI_MODEL=${model}`,
+    ``,
+    `# Paste your API key for the provider you selected`,
+    `OPENAI_API_KEY=${provider === "openai" ? apiKey : ""}`,
+    `GOOGLE_API_KEY=${provider === "google" ? apiKey : ""}`,
+    `ANTHROPIC_API_KEY=${provider === "anthropic" ? apiKey : ""}`,
+    ``,
+    `# Port the backend runs on`,
+    `PORT=3001`,
+    ``,
+    `# Optional: absolute path to a local code directory you want the AI to reference`,
+    `# CODE_CONTEXT_DIR=`,
+  ];
+  fs.writeFileSync(path.join(targetDir, ".env"), envLines.join("\n") + "\n");
+  console.log("  ✔ Created .env");
+
+  rl.close();
+
+  console.log("");
+  console.log("  ✔ Done! Get started:");
+  console.log("");
+  console.log(`     cd ${projectName}`);
+  console.log("     npm install");
+  console.log("     npm run dev");
+  console.log("");
+  console.log("  The app opens at http://localhost:5173");
+  console.log("  Add topics, create questions, and start prepping.");
+  console.log("");
+}
+
+// ── Upgrade command ────────────────────────────────────────
+async function runUpgrade() {
+  const cwd = process.cwd();
+
+  console.log("");
+  console.log("╔══════════════════════════════════════════════════╗");
+  console.log("║    create-interview-cockpit  —  upgrade          ║");
+  console.log("╚══════════════════════════════════════════════════╝");
+  console.log("");
+
+  // ── Detect cockpit project ─────────────────────────────
+  const hasClient = fs.existsSync(path.join(cwd, "client"));
+  const hasServer = fs.existsSync(path.join(cwd, "server"));
+
+  if (!hasClient || !hasServer) {
+    console.error(
+      "  ✖ This doesn't look like an Interview Cockpit project.\n" +
+        "    Run this command from inside a cockpit project directory.\n"
+    );
+    rl.close();
+    process.exit(1);
+  }
+
+  // ── Version comparison ─────────────────────────────────
+  const cockpitJsonPath = path.join(cwd, "cockpit.json");
+  let currentVersion = "unknown";
+  if (fs.existsSync(cockpitJsonPath)) {
+    try {
+      currentVersion = JSON.parse(
+        fs.readFileSync(cockpitJsonPath, "utf-8")
+      ).version;
+    } catch {
+      // malformed cockpit.json
+    }
+  }
+
+  const currentLabel =
+    currentVersion === "unknown" ? "(pre-versioning / unknown)" : `v${currentVersion}`;
+
+  console.log(`  Installed version : ${currentLabel}`);
+  console.log(`  Available version : v${CLI_VERSION}`);
+  console.log("");
+
+  if (currentVersion === CLI_VERSION) {
+    console.log("  Already up to date. Nothing to do.");
+    console.log("");
+    rl.close();
+    return;
+  }
+
+  // ── What will change ───────────────────────────────────
+  console.log("  The following will be updated:");
+  console.log("    ✦ client/   (all source files)");
+  console.log("    ✦ server/   (all source files)");
+  console.log("    ✦ package.json  (new deps merged in, your pinned versions preserved)");
+  console.log("");
+  console.log("  These will NOT be touched:");
+  console.log("    ✧ .env");
+  console.log("    ✧ data/  (your topics, questions, and context files)");
+  console.log("    ✧ node_modules/");
+  console.log("");
+
+  const ok = await confirm(
+    `  Upgrade ${currentLabel} → v${CLI_VERSION}?`
+  );
+  if (!ok) {
+    console.log("\n  Upgrade cancelled.\n");
+    rl.close();
+    return;
+  }
+
+  console.log("");
+
+  // ── Apply upgrade ──────────────────────────────────────
+  copyDirSync(path.join(templateDir, "client"), path.join(cwd, "client"));
+  console.log("  ✔ client/");
+
+  copyDirSync(path.join(templateDir, "server"), path.join(cwd, "server"));
+  console.log("  ✔ server/");
+
+  // package.json — merge scripts + deps, never replace outright
+  const templatePkgPath = path.join(templateDir, "package.json");
+  const targetPkgPath = path.join(cwd, "package.json");
+  if (fs.existsSync(templatePkgPath) && fs.existsSync(targetPkgPath)) {
+    const tmpl = JSON.parse(fs.readFileSync(templatePkgPath, "utf-8"));
+    const target = JSON.parse(fs.readFileSync(targetPkgPath, "utf-8"));
+    // Template scripts win (may contain new like sync:template)
+    target.scripts = { ...target.scripts, ...tmpl.scripts };
+    // Deps — only add new packages
+    target.dependencies = mergeDeps(target.dependencies, tmpl.dependencies);
+    target.devDependencies = mergeDeps(
+      target.devDependencies,
+      tmpl.devDependencies
+    );
+    fs.writeFileSync(targetPkgPath, JSON.stringify(target, null, 2) + "\n");
+    console.log("  ✔ package.json  (deps merged)");
+  }
+
+  // Stamp the new version
+  fs.writeFileSync(
+    cockpitJsonPath,
+    JSON.stringify({ version: CLI_VERSION }, null, 2) + "\n"
+  );
+  console.log(`  ✔ cockpit.json  → v${CLI_VERSION}`);
+
+  rl.close();
+
+  console.log("");
+  console.log(`  ✔ Upgraded to v${CLI_VERSION}!`);
+  console.log("");
+  console.log("  Run  npm install  to pick up any dependency changes,");
+  console.log("  then  npm run dev  to start.");
+  console.log("");
+}
+
+// ── Entry point ────────────────────────────────────────────
+const subcommand = process.argv[2];
+
+if (subcommand === "upgrade") {
+  runUpgrade().catch((e) => {
+    console.error(e);
+    process.exit(1);
+  });
+} else {
+  runCreate().catch((e) => {
+    console.error(e);
+    process.exit(1);
+  });
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "create-interview-cockpit",
+  "version": "0.1.0",
+  "description": "Scaffold a personal AI-powered interview prep cockpit",
+  "type": "module",
+  "bin": {
+    "create-interview-cockpit": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "template"
+  ],
+  "scripts": {
+    "changeset": "changeset"
+  },
+  "keywords": [
+    "interview",
+    "ai",
+    "cockpit",
+    "scaffold",
+    "create",
+    "prep"
+  ],
+  "author": {
+    "name": "Chipili Kafwilo",
+    "email": "ckafwilo@gmail.com",
+    "url": "https://chipilidev.com"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@changesets/changelog-github": "^0.5.2",
+    "@changesets/cli": "^2.29.6"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ChipiKaf/create-interview-cockpit.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/template/.env.example

@@ -0,0 +1,14 @@
+# AI provider: openai | google | anthropic
+AI_PROVIDER=openai
+AI_MODEL=gpt-4o
+
+# Paste the key for whichever provider you use
+OPENAI_API_KEY=
+GOOGLE_API_KEY=
+ANTHROPIC_API_KEY=
+
+# Port the backend listens on
+PORT=3001
+
+# Optional: absolute path to a local code directory you want the AI to reference
+# CODE_CONTEXT_DIR=

package/template/client/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en" class="dark">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Interview Cockpit</title>
+  </head>
+  <body class="bg-slate-950 text-slate-100">
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>