jev-affected 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.3.0
+
+- Add a repository-owned `jev-affected.yml` for dogfooding this project.
+- Analyze committed, working-tree, or staged changes with explicit input modes.
+- Detect pull-request base branches across GitHub Actions, GitLab CI, Buildkite,
+  and mapped CircleCI pipeline values.
+- Inspect and safely clear the Git-local semantic decision cache.
+- Avoid treating source text that mentions Git submodule markers as an actual
+  submodule diff.
+
+## 0.2.0
+
+- Read API credentials from the process environment only.
+- Reject literal API keys in YAML configuration.
+- Accept `TYPESAFEAI_API_KEY` as a compatibility fallback.
+
 ## 0.1.0
 
 - YAML semantic task conditions, deterministic globs and protected tasks.

package/EVALUATION.md

@@ -34,10 +34,10 @@ Run on 2026-09-21 with `jev-1.13.0` and `skipBelow: 0.10`:
 | False skips | 0 |
 | Invalid cases | 0 |
 | Cases with reduction | 6 |
-| Task reduction | 46.43% |
-| Unnecessary-run rate | 45.83% |
+| Task reduction | 42.86% |
+| Unnecessary-run rate | 50.00% |
 | API calls | 7 |
-| Total latency | 2,139 ms |
+| Total latency | 2,126 ms |
 | Input tokens | 2,882 |
 | Output tokens | 476 |
 
@@ -47,7 +47,7 @@ Selected tasks by fixture:
 | --- | ---: |
 | API field | 3 / 4 |
 | Authentication | 4 / 4 |
-| Comment | 1 / 4 |
+| Comment | 2 / 4 |
 | Database schema | 3 / 4 |
 | Documentation | 0 / 4 |
 | Logging | 1 / 4 |
@@ -65,8 +65,8 @@ pnpm eval:live
 
 `pnpm eval` uses deterministic synthetic answers and verifies evaluation and
 decision plumbing without making a network request. `pnpm eval:live` reads
-`TYPESAFE_API_KEY` from the process environment or a local `.env` file and sends
-the fixture inputs to Jev.
+`TYPESAFE_API_KEY` from the process environment and sends the fixture inputs to
+Jev. Dotenv files are not loaded.
 
 ## Limits
 

package/README.md

@@ -2,7 +2,7 @@
 
 <p align="center"><strong>Semantic task routing for software development.</strong></p>
 <p align="center">Run tasks based on what changed, not where it changed.</p>
-<p align="center">v0.1.0 Public Beta · Node.js 20+ · TypeScript · MIT · Jev-powered</p>
+<p align="center">v0.3.0 Public Beta · Node.js 20+ · TypeScript · MIT · Jev-powered</p>
 
 ![Illustrative offline fixture demo, not live Jev output](assets/demo.gif)
 
@@ -30,13 +30,7 @@ npm install -D jev-affected
 npx jev-affected init
 ```
 
-Create `.env` in the repository root. The CLI loads it automatically:
-
-```dotenv
-TYPESAFE_API_KEY=your_api_key_here
-```
-
-`.env` is ignored by this repository's generated `.gitignore`. Never put the key in `jev-affected.yml` or commit it. An existing process environment value takes precedence over `.env`. You can also set it for the current shell:
+Set the API key in the process environment. The CLI does not read dotenv files or accept API keys in `jev-affected.yml`.
 
 ```powershell
 $env:TYPESAFE_API_KEY = "your_api_key_here"
@@ -46,6 +40,8 @@ $env:TYPESAFE_API_KEY = "your_api_key_here"
 export TYPESAFE_API_KEY="your_api_key_here"
 ```
 
+For persistent local use, configure the variable in your shell profile or operating-system credential environment. Open a new terminal after changing persistent environment variables. `TYPESAFEAI_API_KEY` is accepted as a compatibility fallback.
+
 Configure your own trusted commands, commit your changes on a feature branch, then:
 
 ```sh
@@ -54,7 +50,14 @@ npx jev-affected plan --base main
 npx jev-affected run --base main
 ```
 
-`plan` performs analysis but never executes task commands. `run` executes configured commands. **Only committed changes are included**: default head is `HEAD`, not the working tree. Commit agent edits before planning.
+`plan` performs analysis but never executes task commands. `run` executes configured commands. The default mode compares committed changes. Use `--working-tree` to include branch commits, staged changes, unstaged changes and untracked files, or `--staged` to analyze only the Git index.
+
+```sh
+npx jev-affected plan --working-tree --base main
+npx jev-affected plan --staged
+```
+
+`--working-tree` accepts `--base` but not `--head`. `--staged` compares the index with `HEAD` and cannot be combined with `--base` or `--head`.
 
 ## How it works
 
@@ -125,12 +128,13 @@ Low model probabilities are estimates, not a guarantee that a task is unnecessar
 | `inspect` | Preview sanitized analysis inputs locally; no request |
 | `doctor` | Check Node, config, Git base, API key and models endpoint |
 | `eval [--live]` | Evaluate fixture decisions and false-skip rate |
+| `cache [status\|clear]` | Inspect or remove the Git-local decision cache |
 
-Common flags: `--base`, `--head`, `--config`, `--no-cache`, `--json`, `--help`, `--version`. JSON task output includes a stable `version: 1`. During `run --json`, child output goes to stderr, keeping stdout parseable.
+Common flags: `--base`, `--head`, `--working-tree`, `--staged`, `--config`, `--no-cache`, `--json`, `--help`, `--version`. JSON task output includes a stable `version: 1`. During `run --json`, child output goes to stderr, keeping stdout parseable.
 
 Exit codes: `0` success; `1` failed executed task or failed evaluation gate; `2` config/argument/base or doctor check error; `3` internal/I/O failure. API failures do not fail a normal plan or run by themselves.
 
-Base priority: CLI → config → GitHub PR base branch → `origin/main` → `main` → `master`. The comparison starts at the merge-base with head. Explicit invalid bases fail instead of silently choosing another branch. Fetch full history in CI.
+Base priority: CLI → config → detected CI target → `origin/HEAD` → `origin/main` → `main` → `master`. The comparison starts at the merge-base with head. Explicit invalid bases fail instead of silently choosing another branch. Fetch full history in CI.
 
 ## CI
 
@@ -145,9 +149,18 @@ Base priority: CLI → config → GitHub PR base branch → `origin/main` → `m
 
 Install dependencies first. Do not expose credentials to untrusted PR code. Nx, Turbo and other runners can be invoked as configured commands; no plugins are required.
 
+Target branches are detected from GitHub Actions, GitLab CI and Buildkite variables. CircleCI exposes the PR base as a pipeline value rather than a legacy job environment variable; map it to `CIRCLE_PR_BASE_BRANCH` in the job when using automatic detection. `--base` and `base` in configuration remain the explicit overrides.
+
+| CI | Base input |
+| --- | --- |
+| GitHub Actions | `GITHUB_BASE_REF` |
+| GitLab CI | merge-request diff base SHA, target branch, then default branch |
+| Buildkite | `BUILDKITE_PULL_REQUEST_BASE_BRANCH` |
+| CircleCI | `CIRCLE_PR_BASE_BRANCH` supplied from the PR base pipeline value |
+
 ## Agents
 
-After committing edits, run `jev-affected plan --json` and execute all tasks whose `decision` is `run`, or use `jev-affected run`. `inspect` lets you review what could leave the repository first.
+Run `jev-affected plan --json --working-tree` while editing, or use the default committed mode after committing. Execute all tasks whose `decision` is `run`, or use `jev-affected run` with the same mode. `inspect` lets you review what could leave the repository first.
 
 The package includes a reusable agent skill at [`skills/jev-affected`](skills/jev-affected). Point a compatible coding agent at that directory, or copy it into the agent's skills directory, to give it the safe planning and execution workflow.
 
@@ -163,6 +176,8 @@ const plan = await createPlan({ config, base: 'main' });
 
 Automatic caches store probabilities and model metadata in `.git/jev-affected/cache` (including Git worktree support). Keys include state, questions, configuration and pinned actual model version. Corrupt cache entries fall back to RUN. **Moving aliases such as `jev-latest` bypass caching**, because an alias cannot safely establish its current actual version without another request. Pin an actual `jev-x.y.z` version to enable reuse. Neither patches nor API keys are stored in cache payloads. Cache writes are the only local side effect of `plan`; `--no-cache` disables them.
 
+Use `jev-affected cache status` to inspect entry count and size, and `jev-affected cache clear` to remove only the cache directory resolved inside Git metadata. Both commands support `--json` and do not require a project configuration file.
+
 ## Evaluation
 
 ```sh
@@ -176,7 +191,7 @@ See [EVALUATION.md](EVALUATION.md) for the methodology, release gates, latest li
 
 ## Privacy
 
-No backend and no telemetry. Data is read locally; semantic inputs go directly to TypeSafe through its SDK. By default, `.env*`, PEM/key files, and names containing `credentials`, `secret` or `token` are withheld. Custom exclusions add to these defaults. Filename exclusions cannot find every secret embedded in arbitrary source files: inspect inputs and use appropriate repository practices. SDK logging is explicitly disabled.
+No backend and no telemetry. Data is read locally; semantic inputs go directly to TypeSafe through its SDK. API keys are read from the process environment only. By default, `.env*`, PEM/key files, and names containing `credentials`, `secret` or `token` are withheld. Custom exclusions add to these defaults. Filename exclusions cannot find every secret embedded in arbitrary source files: inspect inputs and use appropriate repository practices. SDK logging is explicitly disabled.
 
 `TYPESAFE_BASE_URL` is honored by the official SDK; inspect this environment setting before use. Review [TypeSafe's data-processing terms](https://typesafe.ai/legal/mca) for your organization.
 
@@ -188,11 +203,11 @@ No backend and no telemetry. Data is read locally; semantic inputs go directly t
 
 **What if Jev is down?** Candidate tasks run. Deterministic rules and protected tasks still apply.
 
-**Are uncommitted files included?** No, v0.1 compares commits. Explicit refs make the input reproducible.
+**Are uncommitted files included?** Only with `--working-tree` or `--staged`. Default mode compares commits so explicit refs remain reproducible.
 
 ## Roadmap
 
-v0.1 focuses on inspectable semantic dependencies and safe task plans. Later candidates: working-tree mode, historical evaluations, watch mode, task groups and Nx/Turbo adapters. No GUI, SaaS, MCP server or autonomous command generation is included.
+The current release focuses on inspectable semantic dependencies and safe plans for committed, working-tree and staged changes. Later candidates include historical evaluations, watch mode, task groups and Nx/Turbo adapters. No GUI, SaaS, MCP server or autonomous command generation is included.
 
 ## Contributing and license
 

package/SECURITY.md

@@ -10,7 +10,7 @@ Do not post secrets or exploit details in a public issue. Once the public reposi
 
 ## Secret handling
 
-Set TYPESAFE_API_KEY through your environment or CI secret store. The application disables SDK logging and does not emit provider error bodies. Exclusion globs are additive; they cannot detect every embedded secret. Inspect your inputs before enabling remote analysis.
+Set TYPESAFE_API_KEY through the process environment or CI secret store. The CLI does not load dotenv files and rejects literal API keys in its YAML configuration. The application disables SDK logging and does not emit provider error bodies. Exclusion globs are additive; they cannot detect every embedded secret. Inspect your inputs before enabling remote analysis.
 
 ## External API calls
 

package/dist/cache.d.ts

@@ -0,0 +1,8 @@
+export interface CacheInfo {
+    path: string;
+    entries: number;
+    bytes: number;
+}
+export declare function cacheDirectory(cwd?: string): Promise<string>;
+export declare function inspectCache(cwd?: string): Promise<CacheInfo>;
+export declare function clearCache(cwd?: string): Promise<CacheInfo>;

package/dist/cache.js

@@ -0,0 +1,35 @@
+import { readdir, rm, stat } from "node:fs/promises";
+import { isAbsolute, relative, resolve } from "node:path";
+import { ConfigError } from "./config.js";
+import { git } from "./git.js";
+export async function cacheDirectory(cwd = process.cwd()) {
+    const common = resolve(cwd, (await git(cwd, "rev-parse", "--git-common-dir")).trim());
+    const directory = resolve(cwd, (await git(cwd, "rev-parse", "--git-path", "jev-affected/cache")).trim());
+    const fromCommon = relative(common, directory);
+    if (!fromCommon || fromCommon.startsWith("..") || isAbsolute(fromCommon))
+        throw new ConfigError("Cannot resolve a safe Git cache directory.");
+    return directory;
+}
+export async function inspectCache(cwd = process.cwd()) {
+    const path = await cacheDirectory(cwd);
+    let names;
+    try {
+        names = (await readdir(path)).filter((name) => name.endsWith(".json"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { path, entries: 0, bytes: 0 };
+        throw error;
+    }
+    const sizes = await Promise.all(names.map(async (name) => (await stat(resolve(path, name))).size));
+    return {
+        path,
+        entries: names.length,
+        bytes: sizes.reduce((total, size) => total + size, 0),
+    };
+}
+export async function clearCache(cwd = process.cwd()) {
+    const info = await inspectCache(cwd);
+    await rm(info.path, { recursive: true, force: true });
+    return info;
+}

package/dist/cli.js

@@ -4,13 +4,12 @@ import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 import { TypeSafeClient } from "@typesafe-ai/sdk";
-import { config as loadEnvFile } from "dotenv";
-import { ConfigError, loadConfig, template } from "./config.js";
+import { clearCache, inspectCache } from "./cache.js";
+import { ConfigError, loadConfig, resolveApiKey, template } from "./config.js";
 import { evaluate } from "./eval.js";
 import { executePlan } from "./executor.js";
 import { collectChanges, matches } from "./git.js";
 import { createPlan } from "./planner.js";
-loadEnvFile({ quiet: true });
 function render(plan) {
     return [
         `jev-affected\n\nBase ${plan.base}\nHead ${plan.head}\nModel ${plan.model ?? "not analyzed"}`,
@@ -36,6 +35,8 @@ async function main() {
                 help: { type: "boolean", short: "h" },
                 version: { type: "boolean", short: "v" },
                 "no-cache": { type: "boolean" },
+                "working-tree": { type: "boolean" },
+                staged: { type: "boolean" },
                 fixtures: { type: "string" },
                 live: { type: "boolean" },
             },
@@ -54,13 +55,15 @@ async function main() {
         console.log(`jev-affected — Semantic task routing, powered by Jev.
 
 Usage: jev-affected <command> [options]
-Commands: init, plan, run, why <task>, inspect, doctor, eval
+Commands: init, plan, run, why <task>, inspect, doctor, eval, cache [status|clear]
 Options:
   --base <ref>       Compare from merge-base(ref, head)
   --head <ref>       Head commit (default HEAD; committed changes only)
   --config <file>    YAML configuration
   --json            Machine-readable output
   --no-cache        Bypass the local decision cache
+  --working-tree    Include committed, staged, unstaged and untracked changes
+  --staged          Analyze only changes staged against HEAD
   --parallel        Execute selected commands concurrently
   --concurrency <n>  Maximum parallel commands
   --fixtures <dir>  Evaluation fixtures (default evals/fixtures)
@@ -70,11 +73,39 @@ Options:
 inspect never sends requests. plan never executes task commands.`);
         return;
     }
-    if (!["init", "plan", "run", "why", "inspect", "doctor", "eval"].includes(command))
+    if (![
+        "init",
+        "plan",
+        "run",
+        "why",
+        "inspect",
+        "doctor",
+        "eval",
+        "cache",
+    ].includes(command))
         throw new ConfigError("Unknown command. See --help.");
-    if (positionals.length > (command === "why" ? 2 : 1))
+    if (positionals.length > (["why", "cache"].includes(command) ? 2 : 1))
         throw new ConfigError("Unexpected positional arguments.");
+    if (v["working-tree"] && v.staged)
+        throw new ConfigError("Use --working-tree or --staged, not both.");
+    if (v["working-tree"] && v.head)
+        throw new ConfigError("--working-tree cannot be combined with --head.");
+    if (v.staged && (v.base || v.head))
+        throw new ConfigError("--staged cannot be combined with --base or --head.");
     const emit = (x) => console.log(JSON.stringify(x, null, 2));
+    if (command === "cache") {
+        const action = positionals[1] ?? "status";
+        if (!["status", "clear"].includes(action))
+            throw new ConfigError("Use cache status or cache clear.");
+        const info = action === "clear" ? await clearCache() : await inspectCache();
+        if (v.json)
+            emit({ action, ...info });
+        else if (action === "clear")
+            console.log(`Cleared ${info.entries} cache entries (${info.bytes} bytes).`);
+        else
+            console.log(`Cache: ${info.entries} entries, ${info.bytes} bytes\n${info.path}`);
+        return;
+    }
     if (command === "init") {
         try {
             await writeFile(String(v.config ?? "jev-affected.yml"), template, {
@@ -105,6 +136,8 @@ inspect never sends requests. plan never executes task commands.`);
         base: typeof v.base === "string" ? v.base : undefined,
         head: typeof v.head === "string" ? v.head : undefined,
         cache: !v["no-cache"],
+        workingTree: !!v["working-tree"],
+        staged: !!v.staged,
     };
     if (command === "why" &&
         (!positionals[1] || !Object.hasOwn(config.tasks, positionals[1])))
@@ -140,11 +173,12 @@ inspect never sends requests. plan never executes task commands.`);
         return;
     }
     if (command === "doctor") {
+        const apiKey = resolveApiKey();
         const checks = {
             node: Number(process.versions.node.split(".")[0]) >= 20,
             config: true,
             tasks: Object.keys(config.tasks).length.toString(),
-            apiKey: !!process.env.TYPESAFE_API_KEY?.trim(),
+            apiKey: !!apiKey,
         };
         try {
             await collectChanges(config, opts);
@@ -156,6 +190,7 @@ inspect never sends requests. plan never executes task commands.`);
         if (checks.apiKey) {
             try {
                 await new TypeSafeClient({
+                    apiKey,
                     logLevel: "off",
                     timeout: config.analysis.timeoutMs,
                     retry: { maxRetries: 0 },

package/dist/config.d.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 export declare class ConfigError extends Error {
 }
+export declare const API_KEY_VARS: readonly ["TYPESAFE_API_KEY", "TYPESAFEAI_API_KEY"];
 export declare const secretPatterns: string[];
 export declare const configSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
@@ -37,5 +38,6 @@ export declare const configSchema: z.ZodObject<{
 }, z.core.$strict>;
 export type Config = z.infer<typeof configSchema>;
 export declare function parseConfig(value: unknown): Config;
+export declare function resolveApiKey(env?: NodeJS.ProcessEnv): string | undefined;
 export declare function loadConfig(path?: string): Promise<Config>;
 export declare const template = "version: 1\nmodel: jev-latest\ndefaults:\n  skipBelow: 0.10\ntasks:\n  unit:\n    command: npm test\n    when: Could this change alter runtime application behavior?\n  typecheck:\n    command: npm run typecheck\n    always: true\n";

package/dist/config.js

@@ -3,6 +3,7 @@ import { parse } from "yaml";
 import { z } from "zod";
 export class ConfigError extends Error {
 }
+export const API_KEY_VARS = ["TYPESAFE_API_KEY", "TYPESAFEAI_API_KEY"];
 const probability = z.number().min(0).max(1);
 const limits = z
     .object({
@@ -68,11 +69,23 @@ export const configSchema = z
 })
     .strict();
 export function parseConfig(value) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        const source = value;
+        if (Object.hasOwn(source, "apiKey") || Object.hasOwn(source, "api_key"))
+            throw new ConfigError("API keys are not supported in jev-affected.yml. Set TYPESAFE_API_KEY in the process environment or CI secret store.");
+    }
     const r = configSchema.safeParse(value);
     if (!r.success)
         throw new ConfigError(r.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("\n"));
     return r.data;
 }
+export function resolveApiKey(env = process.env) {
+    for (const name of API_KEY_VARS) {
+        const value = env[name]?.trim();
+        if (value)
+            return value;
+    }
+}
 export async function loadConfig(path = "jev-affected.yml") {
     try {
         return parseConfig(parse(await readFile(path, "utf8")));

package/dist/git.d.ts

@@ -14,8 +14,12 @@ export interface ChangeState {
     incomplete: boolean;
     warnings: string[];
 }
-export declare function collectChanges(config: Config, options?: {
+export interface ChangeOptions {
     cwd?: string;
     base?: string;
     head?: string;
-}): Promise<ChangeState>;
+    workingTree?: boolean;
+    staged?: boolean;
+}
+export declare function detectCiBaseCandidates(env?: NodeJS.ProcessEnv): string[];
+export declare function collectChanges(config: Config, options?: ChangeOptions): Promise<ChangeState>;

package/dist/git.js

@@ -1,4 +1,6 @@
 import { execFile } from "node:child_process";
+import { stat } from "node:fs/promises";
+import { resolve as resolvePath } from "node:path";
 import { promisify } from "node:util";
 import picomatch from "picomatch";
 import { ConfigError, secretPatterns } from "./config.js";
@@ -12,38 +14,88 @@ export async function git(cwd, ...args) {
     })).stdout;
 }
 export const matches = (path, patterns) => patterns.length > 0 && picomatch(patterns, { dot: true })(path);
+const branchRefs = (value) => {
+    const branch = value?.trim().replace(/^refs\/heads\//, "");
+    if (!branch || branch === "false")
+        return [];
+    if (branch.startsWith("origin/") || /^[0-9a-f]{7,40}$/.test(branch))
+        return [branch];
+    return [`origin/${branch}`, branch];
+};
+export function detectCiBaseCandidates(env = process.env) {
+    const refs = [
+        ...branchRefs(env.GITHUB_BASE_REF),
+        ...(env.GITLAB_CI === "true"
+            ? [
+                ...branchRefs(env.CI_MERGE_REQUEST_DIFF_BASE_SHA),
+                ...branchRefs(env.CI_MERGE_REQUEST_TARGET_BRANCH_NAME),
+                ...branchRefs(env.CI_DEFAULT_BRANCH),
+            ]
+            : []),
+        ...(env.BUILDKITE === "true"
+            ? branchRefs(env.BUILDKITE_PULL_REQUEST_BASE_BRANCH)
+            : []),
+        ...(env.CIRCLECI === "true" ? branchRefs(env.CIRCLE_PR_BASE_BRANCH) : []),
+    ];
+    return [...new Set(refs)];
+}
+const hasUnsupportedPatch = (patch) => /^Binary files .+ differ$/m.test(patch) ||
+    /^[+-]Subproject commit [0-9a-f]{7,}(?:-dirty)?$/m.test(patch);
+async function untrackedPatch(cwd, path) {
+    try {
+        return await git(cwd, "diff", "--no-index", "--no-ext-diff", "--no-textconv", "--unified=3", "--", "/dev/null", path);
+    }
+    catch (error) {
+        const result = error;
+        if (Number(result.code) === 1 && typeof result.stdout === "string")
+            return result.stdout;
+        throw error;
+    }
+}
 export async function collectChanges(config, options = {}) {
     const cwd = options.cwd ?? process.cwd();
+    if (options.workingTree && options.staged)
+        throw new ConfigError("Use --working-tree or --staged, not both.");
+    if (options.workingTree && options.head)
+        throw new ConfigError("--working-tree cannot be combined with --head.");
+    if (options.staged && (options.base || options.head))
+        throw new ConfigError("--staged cannot be combined with --base or --head.");
     const resolve = async (ref) => (await git(cwd, "rev-parse", "--verify", "--end-of-options", `${ref}^{commit}`)).trim();
-    let head;
+    let headCommit;
     try {
-        head = await resolve(options.head ?? "HEAD");
+        headCommit = await resolve(options.head ?? "HEAD");
     }
     catch {
         throw new ConfigError("Cannot resolve head commit.");
     }
-    const explicit = options.base ?? config.base;
+    const explicit = options.staged ? "HEAD" : (options.base ?? config.base);
     const candidates = explicit
         ? [explicit]
         : [
-            process.env.GITHUB_BASE_REF
-                ? `origin/${process.env.GITHUB_BASE_REF}`
-                : undefined,
+            ...detectCiBaseCandidates(),
+            "origin/HEAD",
             "origin/main",
             "main",
             "master",
-        ].filter((x) => !!x);
+        ];
     let base;
     for (const ref of candidates) {
         try {
-            base = (await git(cwd, "merge-base", await resolve(ref), head)).trim();
+            base = options.staged
+                ? await resolve("HEAD")
+                : (await git(cwd, "merge-base", await resolve(ref), headCommit)).trim();
             break;
         }
         catch { }
     }
     if (!base)
         throw new ConfigError("Cannot resolve Git base. Fetch the base branch or pass --base.");
-    const parts = (await git(cwd, "diff", "--name-status", "-z", "--find-renames", base, head, "--")).split("\0");
+    const comparison = options.staged
+        ? ["--cached", base]
+        : options.workingTree
+            ? [base]
+            : [base, headCommit];
+    const parts = (await git(cwd, "diff", "--name-status", "-z", "--find-renames", ...comparison, "--")).split("\0");
     const files = [];
     for (let i = 0; i < parts.length && parts[i];) {
         const status = parts[i++];
@@ -59,9 +111,23 @@ export async function collectChanges(config, options = {}) {
         else
             files.push({ status, path });
     }
+    if (options.workingTree) {
+        const tracked = new Set(files.flatMap((file) => [
+            file.path,
+            ...(file.oldPath ? [file.oldPath] : []),
+        ]));
+        for (const path of (await git(cwd, "ls-files", "--others", "--exclude-standard", "-z", "--")).split("\0")) {
+            if (path && !tracked.has(path))
+                files.push({ status: "A", path });
+        }
+    }
     const state = {
         base,
-        head,
+        head: options.staged
+            ? "INDEX"
+            : options.workingTree
+                ? "WORKTREE"
+                : headCommit,
         files: [],
         diff: "",
         incomplete: false,
@@ -78,9 +144,19 @@ export async function collectChanges(config, options = {}) {
             continue;
         state.files.push(file);
         try {
-            const patch = await git(cwd, "diff", "--no-ext-diff", "--no-textconv", "--find-renames", "--unified=3", base, head, "--", ...paths);
-            if (patch.includes("Binary files ") ||
-                patch.includes("Subproject commit ")) {
+            if (options.workingTree && file.status === "A") {
+                const size = (await stat(resolvePath(cwd, file.path))).size;
+                if (Buffer.byteLength(state.diff) + size >
+                    config.analysis.maxDiffBytes) {
+                    state.incomplete = true;
+                    state.warnings.push("Diff exceeds analysis limit; running all tasks.");
+                    continue;
+                }
+            }
+            const patch = options.workingTree && file.status === "A"
+                ? await untrackedPatch(cwd, file.path)
+                : await git(cwd, "diff", "--no-ext-diff", "--no-textconv", "--find-renames", "--unified=3", ...(options.staged ? ["--cached", base] : comparison), "--", ...paths);
+            if (hasUnsupportedPatch(patch)) {
                 state.incomplete = true;
                 state.warnings.push("Binary or submodule change; running all tasks.");
             }

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-export { type Config, ConfigError, loadConfig, parseConfig } from "./config.js";
+export { type CacheInfo, cacheDirectory, clearCache, inspectCache, } from "./cache.js";
+export { API_KEY_VARS, type Config, ConfigError, loadConfig, parseConfig, resolveApiKey, } from "./config.js";
 export { executePlan } from "./executor.js";
-export { type ChangeState, collectChanges } from "./git.js";
+export { type ChangedFile, type ChangeOptions, type ChangeState, collectChanges, detectCiBaseCandidates, } from "./git.js";
 export { createPlan, type Plan, type TaskDecision } from "./planner.js";
 export { type AnalysisInput, type AnalysisResult, type DecisionProvider, JevProvider, } from "./provider.js";

package/dist/index.js

@@ -1,5 +1,6 @@
-export { ConfigError, loadConfig, parseConfig } from "./config.js";
+export { cacheDirectory, clearCache, inspectCache, } from "./cache.js";
+export { API_KEY_VARS, ConfigError, loadConfig, parseConfig, resolveApiKey, } from "./config.js";
 export { executePlan } from "./executor.js";
-export { collectChanges } from "./git.js";
+export { collectChanges, detectCiBaseCandidates, } from "./git.js";
 export { createPlan } from "./planner.js";
 export { JevProvider, } from "./provider.js";

package/dist/planner.d.ts

@@ -1,5 +1,5 @@
 import { type Config } from "./config.js";
-import { type ChangeState } from "./git.js";
+import { type ChangeOptions, type ChangeState } from "./git.js";
 import { type AnalysisResult, type DecisionProvider } from "./provider.js";
 export interface TaskDecision {
     id: string;
@@ -28,10 +28,7 @@ export interface Plan {
 }
 export declare function createPlan(input: {
     config: Config;
-    cwd?: string;
-    base?: string;
-    head?: string;
     state?: ChangeState;
     provider?: DecisionProvider;
     cache?: boolean;
-}): Promise<Plan>;
+} & ChangeOptions): Promise<Plan>;

package/dist/planner.js

@@ -1,8 +1,9 @@
 import { createHash } from "node:crypto";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
-import { parseConfig, secretPatterns } from "./config.js";
-import { collectChanges, git, matches } from "./git.js";
+import { cacheDirectory } from "./cache.js";
+import { parseConfig, resolveApiKey, secretPatterns, } from "./config.js";
+import { collectChanges, matches, } from "./git.js";
 import { JevProvider, } from "./provider.js";
 export async function createPlan(input) {
     const start = Date.now(), config = parseConfig(input.config), cwd = input.cwd ?? process.cwd();
@@ -60,7 +61,7 @@ export async function createPlan(input) {
         const pinned = /^jev-\d+\.\d+\.\d+$/.test(config.model);
         if (input.cache !== false && !input.provider && pinned) {
             try {
-                const dir = resolve(cwd, (await git(cwd, "rev-parse", "--git-path", "jev-affected/cache")).trim());
+                const dir = await cacheDirectory(cwd);
                 const key = createHash("sha256")
                     .update(JSON.stringify({
                     version: 1,
@@ -87,6 +88,7 @@ export async function createPlan(input) {
                     questions,
                     model: config.model,
                     timeoutMs: config.analysis.timeoutMs,
+                    apiKey: resolveApiKey(),
                 });
             }
             if (!result.model || !/^jev-\d+\.\d+\.\d+$/.test(result.model))

package/dist/provider.d.ts

@@ -4,6 +4,7 @@ export interface AnalysisInput {
     questions: Record<string, string>;
     model: string;
     timeoutMs: number;
+    apiKey?: string;
 }
 export interface AnalysisResult {
     model: string;

package/dist/provider.js

@@ -2,6 +2,7 @@ import { noul, TypeSafeClient } from "@typesafe-ai/sdk";
 export class JevProvider {
     async analyze(input) {
         const client = new TypeSafeClient({
+            apiKey: input.apiKey,
             logLevel: "off",
             timeout: input.timeoutMs,
             retry: { maxRetries: 0 },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jev-affected",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Semantic task routing for software development, powered by Jev.",
   "type": "module",
   "license": "MIT",
@@ -46,7 +46,6 @@
     "SECURITY.md",
     "CODE_OF_CONDUCT.md",
     "EVALUATION.md",
-    ".env.example",
     "evals",
     "skills"
   ],
@@ -65,7 +64,6 @@
   },
   "dependencies": {
     "@typesafe-ai/sdk": "^0.6.0",
-    "dotenv": "^17.2.2",
     "picomatch": "^4.0.7",
     "yaml": "^2.9.1",
     "zod": "^4.6.5"

package/skills/jev-affected/SKILL.md

@@ -13,12 +13,13 @@ projects and `npx jev-affected` elsewhere.
 1. Confirm the current directory is a Git repository and locate
    `jev-affected.yml`. Run `jev-affected init` only when setup is requested and no
    configuration exists.
-2. Ensure the relevant edits are committed. Version 0.1 compares commits and does
-   not include working-tree changes.
-3. On first use, or when privacy matters, run
-   `jev-affected inspect --base <ref>`. This previews the sanitized input locally
-   without sending a request.
-4. Run `jev-affected plan --json --base <ref>` and use its task decisions as the
+2. Choose the input mode. Use the default mode for committed branch changes,
+   `--working-tree --base <ref>` while editing, or `--staged` for the exact Git
+   index before a commit.
+3. On first use, or when privacy matters, run `jev-affected inspect` with the
+   same mode and base flags intended for planning. This previews the sanitized
+   input locally without sending a request.
+4. Run `jev-affected plan --json` with those same flags and use its task decisions as the
    record of what should run. Do not invent task reasons or commands.
 5. Run `jev-affected run --base <ref>` only when execution is requested. Commands
    come from the repository configuration and should be treated as repository
@@ -26,15 +27,18 @@ projects and `npx jev-affected` elsewhere.
 6. Report the selected and skipped task counts, actual model version, warnings,
    fallback decisions, and any failed task commands.
 
+Use `jev-affected cache status` to inspect the Git-local decision cache. Use
+`jev-affected cache clear` when a fresh semantic decision is needed; it removes
+only the cache directory resolved inside Git metadata.
+
 Use an explicit base ref in CI and shallow clones. Fetch enough history for Git to
 compute the merge base.
 
 ## Credentials and data
 
-Set `TYPESAFE_API_KEY` in the process environment or a repository-local `.env`
-file. Never print the value, commit `.env`, or store the key in
-`jev-affected.yml`. An existing process environment value takes precedence over
-`.env`.
+Set `TYPESAFE_API_KEY` in the process environment or CI secret store. Never
+print the value or store the key in `jev-affected.yml`. The CLI does not load
+dotenv files. `TYPESAFEAI_API_KEY` is accepted as a compatibility fallback.
 
 `inspect` stays local. `plan`, `why`, and `run` can send the sanitized committed
 diff and configured semantic questions to the provider. Review `inspect` output

package/.env.example

@@ -1,3 +0,0 @@
-# Copy this file to .env and replace the placeholder.
-# .env is ignored by Git. Never commit a real API key.
-TYPESAFE_API_KEY=replace_with_your_typesafe_api_key