chels-code 0.0.0-stage → 0.5.1

package/README.md

@@ -1,3 +1,124 @@
-# Temporary Holding Version
+# Chels Code
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Chels Code is a Windows-friendly terminal coding assistant powered by MystBloom V1.0, where OpenRouter, NVIDIA, and Groq models collaborate on one coding task.
+
+**I like cats**
+
+The interface is built with TypeScript, React, and [Ink](https://github.com/vadimdemedes/ink). It includes a real multi-line text area, a scrolling session transcript, an animated `Thinking` / `◆ Done` status, plan approval, and inline confirmation for every file write and PowerShell command.
+
+## Requirements
+
+- Node.js 22 or newer
+- API keys for OpenRouter, NVIDIA, and Groq
+- Windows PowerShell for the `run_command` tool
+
+Free model availability and rate limits vary by provider and can change. Chels Code automatically discovers the models available to each key, prefers models explicitly marked free, and selects a stable chat model without asking you to choose. It prefers tool-capable models when the provider reports that capability. If a provider doesn't identify free models, the selected model may be metered; check current provider pricing and limits.
+
+## Configure
+
+In the project directory where you will run Chels Code, create a `.env` file:
+
+```dotenv
+OPENROUTER_API_KEY=your-openrouter-key
+NVIDIA_API_KEY=your-nvidia-key
+GROQ_API_KEY=your-groq-key
+```
+
+Chels Code reads the file without printing or saving the keys. `.env` is ignored by Git. Alternatively, set the three variables in PowerShell before starting.
+
+## Install and run
+
+Install dependencies and build the CLI once from the Chels Code folder:
+
+```powershell
+npm install
+npm run build
+npm link
+```
+
+Then open a terminal in any project folder and type:
+
+```powershell
+chelscode
+```
+
+For local development, run the TypeScript entry directly without building:
+
+```powershell
+npm run dev
+```
+
+`npm start` builds and then runs the compiled CLI.
+
+### Install with Winget
+
+To install the CLI as a global Windows command, use the Winget package:
+
+```powershell
+winget install -g ChelsCode
+```
+
+The package manifest lives in [`winget/ChelsCode.yaml`](winget/ChelsCode.yaml). Before it can be installed from the default Winget source, the manifest has to be submitted to the official community repository ([microsoft/winget-pkgs](https://github.com/microsoft/winget-pkgs)). After that, the installed CLI reads your API keys from the environment or from a `.env` file in the project folder (`OPENROUTER_API_KEY`, `NVIDIA_API_KEY`, `GROQ_API_KEY`) and starts answering questions, planning work, and editing code like the local build.
+
+While ChelsCode is running, the PowerShell window and tab title show `ChelsCode`. The previous title is restored when the session ends.
+
+## Use
+
+The start screen shows the big ChelsCode wordmark, the tagline, and the current workspace. The text area at the bottom is multi-line:
+
+- `Enter` sends the request.
+- `Shift+Enter` inserts a newline. In terminals that do not report modified Enter keys, `Ctrl+J` still works as a fallback.
+- `Tab` or `Shift+Tab` switches between `Build` and `Plan` mode; the status line below the input updates to match. Some terminals send Shift+Tab as a plain Tab, so both keys work. `Ctrl+T` also toggles the mode.
+- `Ctrl+P` opens the command menu: `Mode`, `Effort`, `Help`, or `Exit`. `Mode` switches between Build and Plan, and `Effort` lets you pick `low`, `medium`, `high`, `max`, or `ultra`; the default is `max`.
+- Arrow keys move the cursor, including up and down across wrapped lines and newlines.
+- `Home`/`End` or `Ctrl+A`/`Ctrl+E` jump to the start or end of a line.
+- `Ctrl+U`/`Ctrl+K` delete to the start or end of a line, and `Ctrl+W` deletes the previous word.
+- `/exit` or `/quit` ends the session.
+
+A status line under the input shows `Build · MystBloom V1.0  Free ChelsCode · max`. The mode is blue, the model and plan name are white, and the effort value is color-coded: `low` green, `medium` cyan, `high` yellow, `max` orange, and `ultra` pink. Use `Ctrl+P` → `Effort` to change the level. The footer below it starts at `0 (0%)` and updates as the session uses the API keys. The number is cumulative session tokens; the percentage is the share of your OpenRouter credits used this session, until the credits run out. If OpenRouter does not expose a credit limit, the percentage falls back to the share of model context used. OpenRouter's free models do not consume credits, so the percentage can stay at 0% while the token count grows. The footer also shows `shift+tab mode` and `ctrl+p commands`, for example `109.6K (55%)  shift+tab mode  ctrl+p commands`.
+
+## Sessions
+
+Every session is saved automatically under `%LOCALAPPDATA%\ChelsCode\sessions` on Windows, or `$XDG_STATE_HOME/chelscode/sessions` (usually `~/.local/state/chelscode/sessions`) elsewhere. When the session ends, ChelsCode prints:
+
+```text
+Resume this session with:
+  chelscode --id 3f8a1c2e
+```
+
+Run that command from the same folder to restore the transcript, mode, effort, and usage counter. `chelscode --id` without an ID resumes the most recent session in the current folder. Session files contain your prompts and the AI responses, so treat the sessions folder as private.
+
+For each request, ChelsCode picks the lightest workflow:
+
+- Questions and read-only requests get a direct answer from MystBloom V1.0. It can list and read workspace files and use built-in lookups for the current date and time, weather, web search, and news headlines, but it cannot write files or run commands.
+- Requests that change files or run commands go to the three-AI team. The AIs independently propose a work breakdown, OpenRouter combines the proposals into subtasks, and you approve the plan before execution.
+- After a task, MystBloom V1.0 writes the final answer summarizing what was actually completed.
+
+### Answering questions about the world
+
+Ask anything that needs current information and the single-AI question workflow answers it:
+
+- `what's the date today?` or `what time is it now?` → the built-in current date and time lookup.
+- `what's the weather in Chicago?` or `how cold is it in Tokyo?` → the live weather lookup for the requested place.
+- `what's the news today?` or `any updates on ...` → the latest news headlines.
+- `search the web for ...` or `what do you know about ...` → a web search for current information.
+
+These questions stay on the light path: one AI answers, no plan, no file writes, and no commands. If a lookup fails, the AI tells you what it could not confirm.
+
+While an AI is searching, planning, editing, or running a command, the status shows an animated spinner with `Thinking`. When the request finishes, `◆ Done` shows the response and a `Made` list of the files written and commands that actually ran. Intermediate tool activity and provider/model headers stay hidden. ChelsCode asks for confirmation before every file write and PowerShell command. A declined write or command is reported back to the AI instead of being executed or counted as made.
+
+Workspace file tools are restricted to the current project directory, exclude secret-like files such as `.env`, and do not follow links outside the project.
+
+## Tests
+
+```powershell
+npm test
+```
+
+The test suite covers model discovery, credit balance lookup, workspace confinement, the multi-line text area, confirmations, effort selection and Build/Plan switching in the command UI, and an end-to-end mocked session with plan approval and a file write.
+
+To type-check and build the CLI:
+
+```powershell
+npm run build
+```

package/dist/src/cli-options.js

@@ -0,0 +1,30 @@
+export function parseOptions(argv) {
+    const options = {};
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--help" || arg === "-h") {
+            options.help = true;
+        }
+        else if (arg === "--version" || arg === "-v") {
+            options.version = true;
+        }
+        else if (arg === "--id") {
+            const next = argv[index + 1];
+            if (next && !next.startsWith("-")) {
+                options.id = next;
+                index += 1;
+            }
+            else {
+                options.id = true;
+            }
+        }
+        else if (arg.startsWith("--id=")) {
+            const value = arg.slice("--id=".length).trim();
+            options.id = value || true;
+        }
+        else {
+            throw new Error(`Unknown option: ${arg}`);
+        }
+    }
+    return options;
+}

package/dist/src/cli.js

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+import { jsx as _jsx } from "react/jsx-runtime";
+import path from "node:path";
+import { realpathSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { createInterface } from "node:readline";
+import { stdin, stdout } from "node:process";
+import { fileURLToPath } from "node:url";
+import { render } from "ink";
+import { parseOptions } from "./cli-options.js";
+import { PROVIDERS, PROVIDER_IDS } from "./providers.js";
+import { createSessionId, findLatestSession, loadSession, resumeHint, sameWorkspace, saveSession, } from "./session.js";
+import { installTerminalTitle } from "./terminal-title.js";
+import { DEFAULT_EFFORT, DEFAULT_MODE } from "./types.js";
+import { App } from "./ui/App.js";
+import { VERSION } from "./version.js";
+const useColor = Boolean(stdout.isTTY && !process.env.NO_COLOR);
+const paint = (code, text) => (useColor ? `\u001b[${code}m${text}\u001b[0m` : text);
+const purple = (text) => paint("38;5;141", text);
+const bold = (text) => paint("1", text);
+const dim = (text) => paint("38;5;244", text);
+function printHelp() {
+    console.log(`${purple("◆")} ${bold("ChelsCode")} ${dim(VERSION)}
+  ${dim("MystBloom V1.0")}
+
+  ${bold("Usage")}  chelscode [--id [session]] [--help] [--version]
+
+  ${bold("Environment")}
+    ${dim("OPENROUTER_API_KEY")}   OpenRouter key
+    ${dim("NVIDIA_API_KEY")}       NVIDIA key
+    ${dim("GROQ_API_KEY")}         Groq key
+
+  Keys can also live in a ${dim(".env")} file in the project directory.
+
+  ${bold("Input")}
+    ${dim("enter")} send
+    ${dim("shift+enter")} newline
+    ${dim("tab")} or ${dim("shift+tab")} build / plan mode
+    ${dim("ctrl+p")} commands, mode, and effort
+    ${dim("/exit")} or ${dim("/quit")} quit
+
+  ${bold("Sessions")}
+    ${dim("--id")} [session] resume a session, or the latest one in this folder
+    Every session is saved automatically, including its transcript and usage.
+
+  Effort choices are low, medium, high, max, and ultra; max is the default.
+  The PowerShell window and tab title show ChelsCode while the session runs.
+
+  MystBloom V1.0 answers questions with one AI. It can answer about the current date, weather, news, and web facts with built-in lookups and web search.
+  Requests that change files or run commands bring in all three AIs for a plan and
+  execution. It shows an animated Thinking spinner while working and ◆ Done with a
+  Made list when finished. File writes and PowerShell commands always ask first.`);
+}
+async function loadProjectEnvironment() {
+    try {
+        process.loadEnvFile(path.join(process.cwd(), ".env"));
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+function getApiKeys() {
+    const keys = {};
+    const missing = [];
+    for (const provider of PROVIDER_IDS) {
+        const variable = PROVIDERS[provider].keyVariable;
+        const value = process.env[variable]?.trim();
+        if (value)
+            keys[provider] = value;
+        else
+            missing.push(variable);
+    }
+    if (missing.length) {
+        throw new Error(`Set all three API keys before starting: ${missing.join(", ")}.`);
+    }
+    return keys;
+}
+const REQUIRED_API_KEY_VARS = [
+    { variable: "OPENROUTER_API_KEY", label: "OpenRouter" },
+    { variable: "NVIDIA_API_KEY", label: "NVIDIA" },
+    { variable: "GROQ_API_KEY", label: "Groq" },
+];
+async function ensureApiKeys() {
+    const missing = REQUIRED_API_KEY_VARS.filter((item) => !process.env[item.variable]?.trim());
+    if (missing.length === 0)
+        return;
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const provided = {};
+        for (const item of missing) {
+            const answer = await new Promise((resolve) => {
+                rl.question(`\n${item.label} API key: `, (response) => resolve(response.trim()));
+            });
+            if (answer) {
+                process.env[item.variable] = answer;
+                provided[item.variable] = answer;
+            }
+        }
+        if (Object.keys(provided).length > 0) {
+            const content = Object.entries(provided)
+                .map(([key, value]) => `${key}=${value}`)
+                .join("\n") + "\n";
+            await writeFile(path.join(process.cwd(), ".env"), content, { encoding: "utf8" });
+        }
+    }
+    finally {
+        rl.close();
+    }
+}
+async function main() {
+    const options = parseOptions(process.argv.slice(2));
+    if (options.help) {
+        printHelp();
+        return;
+    }
+    if (options.version) {
+        stdout.write(`${VERSION}\n`);
+        return;
+    }
+    await loadProjectEnvironment();
+    if (!stdin.isTTY || !stdout.isTTY) {
+        throw new Error("ChelsCode needs an interactive terminal.");
+    }
+    const keysMissing = REQUIRED_API_KEY_VARS.some((item) => !process.env[item.variable]?.trim());
+    await ensureApiKeys();
+    const apiKeys = getApiKeys();
+    const workspace = process.cwd();
+    let resumed = null;
+    if (options.id === true) {
+        resumed = findLatestSession(workspace);
+        if (!resumed) {
+            throw new Error(`No saved sessions in ${workspace} yet. Start chelscode without --id.`);
+        }
+    }
+    else if (typeof options.id === "string") {
+        resumed = loadSession(options.id);
+    }
+    if (resumed && !sameWorkspace(resumed.workspace, workspace)) {
+        throw new Error(`Session ${resumed.id} belongs to ${resumed.workspace}. Run chelscode from that folder to resume it.`);
+    }
+    const now = new Date().toISOString();
+    const session = resumed ?? {
+        schema: 1,
+        id: createSessionId(),
+        workspace,
+        createdAt: now,
+        updatedAt: now,
+        mode: DEFAULT_MODE,
+        effort: DEFAULT_EFFORT,
+        tokensUsed: 0,
+        creditsUsed: 0,
+        creditsAvailable: null,
+        entries: [],
+    };
+    if (!resumed)
+        saveSession(session);
+    const restoreTitle = installTerminalTitle("ChelsCode");
+    try {
+        const instance = render(_jsx(App, { apiKeys: apiKeys, workspace: workspace, version: VERSION, sessionId: session.id, resume: resumed, missingKeys: keysMissing }), {
+            exitOnCtrlC: true,
+            kittyKeyboard: { mode: "auto" },
+        });
+        await instance.waitUntilExit();
+    }
+    finally {
+        restoreTitle();
+        stdout.write(`\n${resumeHint(session.id)}\n`);
+    }
+}
+if (process.argv[1]
+    && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+    main().catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`ChelsCode: ${message}`);
+        process.exitCode = 1;
+    });
+}