@0xprathamesh/why-cli 1.1.1

package/README.md

@@ -0,0 +1,436 @@
+# why
+
+`why` helps you understand what a terminal command will do, what went wrong, and what to try next.
+
+It can:
+
+- run a command and explain failures
+- simulate risky commands before they change anything
+- stream live logs for long-running commands
+- use OpenAI or Ollama for AI explanations
+- read local code context when an error points into your project
+
+## Install
+
+Global install:
+
+```bash
+npm install -g @0xprathamesh/why-cli
+```
+
+Local development:
+
+```bash
+npm install
+npm run build
+npm link
+```
+
+After that, the `why` command is available from any folder.
+
+Package name on npm:
+
+```text
+@0xprathamesh/why-cli
+```
+
+Repository name on GitHub:
+
+```text
+why
+```
+
+The install package is scoped, but the CLI command is still just:
+
+```bash
+why
+```
+
+## Docker
+
+Build the image:
+
+```bash
+docker build -t why-cli .
+```
+
+Show help from the container:
+
+```bash
+docker run --rm why-cli --help
+```
+
+Run a command through `why` inside the container:
+
+```bash
+docker run --rm why-cli --simulate -- git push origin main
+```
+
+If you want to use your current project inside the container:
+
+```bash
+docker run --rm -it -v "$PWD:/workspace" -w /workspace why-cli -- npm run build
+```
+
+If you want AI config inside Docker, pass env values or an env file:
+
+```bash
+docker run --rm --env-file .env why-cli --doctor
+```
+
+## Quick Start
+
+Run a normal command:
+
+```bash
+why -- npm run build
+```
+
+Simulate a risky command:
+
+```bash
+why --simulate -- git push origin main
+```
+
+Run a command for real even if `auto` mode would simulate it:
+
+```bash
+why --run -- git init
+```
+
+Check AI setup:
+
+```bash
+why --doctor
+```
+
+Interactive setup:
+
+```bash
+why --setup
+```
+
+## How It Works
+
+For every command, `why-cli` goes through this pipeline:
+
+`command -> classify -> risk -> simulate/run -> analyze -> explain`
+
+That means:
+
+- safe read-only commands usually run in `auto` mode
+- risky state-changing commands are usually simulated in `auto` mode
+- failures are summarized in plain language
+- if AI is configured, `why-cli` adds an AI explanation on top
+
+## Modes
+
+`why-cli` has 3 execution modes.
+
+### `auto`
+
+Default mode.
+
+- runs read-only commands
+- simulates risky commands
+
+Example:
+
+```bash
+why npm run build
+why git init
+why rm test.txt
+```
+
+### `run`
+
+Runs the command for real.
+
+```bash
+why --run -- git init
+why --run -- rm test.txt
+```
+
+### `simulate`
+
+Never runs the real command. It only does a safe preview when supported.
+
+```bash
+why --simulate -- git add .
+why --simulate -- npm install express
+why --simulate -- mkdir demo-folder
+```
+
+## Important Behavior
+
+If you run:
+
+```bash
+why git init
+```
+
+you may see simulation output instead of actual execution. That is expected in `auto` mode.
+
+If you want the real command to run, use:
+
+```bash
+why --run -- git init
+```
+
+## AI Setup
+
+You can configure AI once and stop passing keys or model flags every time.
+
+Recommended:
+
+```bash
+why --setup
+```
+
+This writes config to:
+
+```bash
+~/.config/why-cli/.env
+```
+
+You can also create that file manually.
+
+Example:
+
+```env
+WHY_PROVIDER=ollama
+
+OPENAI_API_KEY=
+OPENAI_MODEL=gpt-4.1
+OPENAI_BASE_URL=https://api.openai.com/v1
+
+OLLAMA_HOST=http://127.0.0.1:11434
+OLLAMA_MODEL=gemma3:4b
+
+WHY_SKILL=debug,fix
+```
+
+Supported config locations:
+
+- `.env.local` in the current folder
+- `.env` in the current folder
+- `.env.local` in parent folders
+- `.env` in parent folders
+- `~/.config/why-cli/.env`
+- `~/.env`
+
+Check provider health:
+
+```bash
+why --doctor
+```
+
+## Providers
+
+Supported providers:
+
+- `auto`
+- `openai`
+- `ollama`
+- `none`
+
+Examples:
+
+```bash
+why --provider openai --explain -- npm test
+why --provider ollama --model gemma3:4b -- npm run build
+why --provider none -- npm start
+```
+
+## Common Commands
+
+Run commands:
+
+```bash
+why -- npm run build
+why -- npm start
+why -- python3 script.py
+why node -v
+why npm -v
+why cat README.md
+```
+
+Simulate commands:
+
+```bash
+why --simulate -- git add .
+why --simulate -- git commit -m "test"
+why --simulate -- git push
+why --simulate -- npm install
+why --simulate -- npm install express
+why --simulate -- npm publish
+why --simulate -- rm test.txt
+why --simulate -- mkdir test-folder
+why --simulate -- touch demo.txt
+```
+
+Run risky commands for real:
+
+```bash
+why --run -- git init
+why --run -- git commit -m "ship"
+why --run -- npm publish
+```
+
+## Failure Examples
+
+Missing package:
+
+```bash
+why --simulate -- npm install some-invalid-package-xyz
+```
+
+Missing file:
+
+```bash
+why --simulate -- rm non-existing-file
+why --simulate -- git add non-existing-file
+```
+
+Existing directory:
+
+```bash
+mkdir existing-folder
+why --simulate -- mkdir existing-folder
+```
+
+Wrong Git push target:
+
+```bash
+why --simulate -- git push origin wrong-branch
+```
+
+Bad build:
+
+```bash
+why --explain -- npm run build
+```
+
+## Long-Running Commands
+
+`why-cli` can stream logs for servers, watchers, and dev processes.
+
+Examples:
+
+```bash
+why -- npm start
+why --stream -- npm run dev
+why --no-stream -- npm run build
+```
+
+Use:
+
+- `--stream` to force live logs
+- `--no-stream` to wait until the command exits
+- `Ctrl+C` to stop the child process
+
+## Code-Aware Explanations
+
+When an error points to files in your project, `why-cli` can read local code context and include it in the explanation.
+
+That helps with cases like:
+
+- TypeScript build errors
+- import or module resolution failures
+- stack traces with file paths
+- runtime failures pointing into your app code
+
+This is most useful when you run `why` inside the project that failed.
+
+## Skills
+
+Skills shape how the AI explains the result.
+
+Built-in skills:
+
+- `debug`
+- `teach`
+- `fix`
+- `tests`
+- `security`
+- `perf`
+
+Examples:
+
+```bash
+why --skill debug --skill fix -- npm run build
+why --provider ollama --skill teach -- python3 script.py
+why --list-skills
+```
+
+You can also set default skills in your config:
+
+```env
+WHY_SKILL=debug,fix
+```
+
+## Flags
+
+```text
+-h, --help
+-v, --version
+-s, --silent
+--json
+--no-color
+-r, --raw
+-e, --explain
+--mode <auto|run|simulate>
+--simulate
+--run
+--execute
+--provider <auto|none|openai|ollama>
+--model <name>
+--cwd <path>
+--timeout <ms>
+--skill <name>
+--list-skills
+--doctor
+--setup
+--stream
+--no-stream
+--api-key <key>
+--api-key-env <name>
+--openai-base-url <url>
+--ollama-host <url>
+```
+
+## Notes
+
+- Shell builtins like `cd` cannot change your parent shell session through `why-cli`.
+- In `auto` mode, risky commands are often simulated instead of executed.
+- If a command starts with flags that confuse parsing, use `--` before the command.
+
+Example:
+
+```bash
+why -- node -v
+why --simulate -- git status
+```
+
+
+
+## CI/CD
+
+GitHub Actions is included.
+
+CI workflow:
+
+- file: `.github/workflows/ci.yml`
+- runs on pushes to `main` and on pull requests
+- tests Node.js `18` and `20`
+- runs `npm ci`
+- runs `npm run build`
+- runs `npm pack --dry-run`
+
+Release workflow:
+
+- file: `.github/workflows/release.yml`
+- runs on tags like `v1.1.0`
+- builds the project
+- publishes to npm
+

package/dist/cli/index.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const package_json_1 = __importDefault(require("../../package.json"));
+const args_1 = require("../core/args");
+const env_1 = require("../core/env");
+const provider_health_1 = require("../core/provider-health");
+const runner_1 = require("../core/runner");
+const setup_1 = require("../core/setup");
+const skills_1 = require("../core/skills");
+const logger_1 = require("../utils/logger");
+async function main() {
+    let options;
+    try {
+        options = (0, args_1.parseArgs)(process.argv.slice(2));
+    }
+    catch (error) {
+        console.error(error.message);
+        console.error("\nRun `why --help` to see available flags.");
+        process.exit(1);
+    }
+    if (options.version) {
+        console.log(package_json_1.default.version);
+        return;
+    }
+    if (options.help) {
+        console.log((0, args_1.renderHelp)(package_json_1.default.version));
+        return;
+    }
+    if (options.listSkills) {
+        console.log((0, skills_1.formatSkillList)());
+        return;
+    }
+    const cwd = options.cwd ? options.cwd : process.cwd();
+    const loadedEnv = (0, env_1.loadEnv)(cwd);
+    if (options.provider === "auto") {
+        const configuredProvider = (0, env_1.resolveEnvAlias)(["WHY_PROVIDER"]);
+        if (configuredProvider === "openai" || configuredProvider === "ollama" || configuredProvider === "none" || configuredProvider === "auto") {
+            options.provider = configuredProvider;
+        }
+    }
+    if (!options.model) {
+        if (options.provider === "openai") {
+            options.model = (0, env_1.resolveEnvAlias)(["OPENAI_MODEL", "openaimodel"]);
+        }
+        else if (options.provider === "ollama") {
+            options.model = (0, env_1.resolveEnvAlias)(["OLLAMA_MODEL", "ollamamodel"]);
+        }
+    }
+    if (options.skills.length === 0) {
+        const configuredSkills = (0, env_1.resolveEnvAlias)(["WHY_SKILL"]);
+        if (configuredSkills) {
+            options.skills = configuredSkills.split(",").map((value) => value.trim()).filter(Boolean);
+        }
+    }
+    const logger = new logger_1.Logger({
+        color: options.color,
+        silent: options.silent,
+        json: options.json,
+    });
+    if (options.setup) {
+        await (0, setup_1.runSetup)(options, logger);
+        return;
+    }
+    if (options.doctor) {
+        const [openai, ollama] = await Promise.all([(0, provider_health_1.checkOpenAIHealth)(options), (0, provider_health_1.checkOllamaHealth)(options)]);
+        if (options.json) {
+            logger.printJson({
+                envFile: loadedEnv.filePath ?? null,
+                openai,
+                ollama,
+            });
+            return;
+        }
+        logger.heading("why-cli doctor", loadedEnv.filePath ? `Loaded ${loadedEnv.filePath}` : "No .env file found");
+        logger.list([
+            `openai: ${openai.configured ? "configured" : "missing config"}, ${openai.reachable ? "reachable" : "not reachable"} - ${openai.message}`,
+            `ollama: ${ollama.configured ? "configured" : "missing config"}, ${ollama.reachable ? "reachable" : "not reachable"} - ${ollama.message}`,
+        ], "info");
+        return;
+    }
+    if (!options.command) {
+        console.error("Please provide a command. Run `why --help` for usage.");
+        process.exit(1);
+    }
+    try {
+        const session = await (0, runner_1.runCommand)(options, logger);
+        session.envFilePath = loadedEnv.filePath;
+        (0, runner_1.printCommandReport)(session, options, logger);
+        process.exit(session.ok ? 0 : 1);
+    }
+    catch (error) {
+        console.error(`why-cli failed to start the command: ${error.message}`);
+        process.exit(1);
+    }
+}
+void main();
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"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"}