secrets-axi 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cristian Mos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,150 @@
-# Temporary Holding Version
+# secrets-axi
 
-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.
+Agent-ergonomic **secrets guard**, built on the [AXI](https://axi.md) principles: token-efficient [TOON](https://toonformat.dev/) output, minimal schemas, definitive empty states, structured errors and next-step hints.
+
+It keeps secret values out of agent transcripts. A **Guard** hook denies the obvious reads of `.env` and credential files (and of secret-fetching CLIs) and tells the agent the command to run instead; a **Runner** runs that command with the secrets injected and every injected value masked in its output. Misuse of credentials the agent legitimately holds is out of scope: that is credential hygiene, not a reader guard.
+
+## Install
+
+Requires Node.js 20+.
+
+```sh
+npm install -g secrets-axi
+```
+
+Then install the Guard hook for your agent (Claude Code and Codex share one contract):
+
+```sh
+secrets-axi setup hooks     # PreToolUse hook + Read(...) deny rules for the built-in Secret Files
+secrets-axi setup status    # what is installed; recommends a sandbox denyRead (never writes it)
+secrets-axi setup uninstall # removes exactly the entries secrets-axi added
+```
+
+`--project` installs for the current repository only. The hook is one bundled file with `node:` builtins only (budget: under 30 ms per call, pinned by a test). Optionally add the on-demand Agent Skill, and one line in `CLAUDE.md` / `AGENTS.md`:
+
+```sh
+npx skills add cmosgh/secrets-axi --skill secrets-axi
+```
+
+```
+Use `secrets-axi run -- <command>` to run anything that needs .env or other secrets; never read or source .env yourself.
+```
+
+## Two faces
+
+### Guard (hook)
+
+Runs before every `Read`, `Edit`, `Write`, `Grep`, `Glob` and `Bash` call and decides from the literal call. Deterministic and listable: every decision comes from a [Policy](#policy) entry, `secrets-axi policy` prints them all, `secrets-axi check '<command>'` shows the decision the Guard would make and why.
+
+It always **denies**, never `ask` ("approve once" is how values end up in transcripts), and never rewrites a call except one case: a directory-wide search (the Grep tool, `grep -r`, `rg`, `ag`) gets the Secret File patterns added as exclusions.
+
+| Call | Decision |
+| --- | --- |
+| `Read` / `Edit` / `Write` of a Secret File | deny; Hint: `secrets-axi keys <file>` or `secrets-axi set <file> KEY=value` |
+| `Grep` with `path` a Secret File | deny; Hint: `secrets-axi keys <file>` |
+| `Grep` over a directory, `grep -r` / `rg` / `ag` without an explicit Secret File | rewrite: exclusions for the Secret File patterns |
+| `Bash` with a token that resolves to a Secret File | deny unless the program is an Allowed Consumer (`docker --env-file`, `dotenv -e`, `dotenvx run`, `secrets-axi`); Hint: `secrets-axi run -- <command>` |
+| `Bash` matching a Secret Fetch (`aws secretsmanager get-secret-value`, `op read`, `vault kv get`, ...) | deny; Hint: `secrets-axi run --aws-secret <id> -- <command>` or the source's run form |
+| `Bash` `git show <rev>:<secret file>` | deny; other git commands pass |
+
+What the agent is told instead, for `Read` of `.env` (the hook's `permissionDecisionReason`):
+
+```
+secrets-axi: .env is a Secret File - its values must not enter the transcript. Run `secrets-axi keys .env` for its variable names and shapes, or `secrets-axi run -- <command>` to run something with it loaded
+```
+
+A Hint is at most two lines with the exact replacement command, real paths and names filled in. Listing or describing secrets (names only) is not a Secret Fetch and passes.
+
+### Runner (CLI)
+
+Masking is the boundary, the hook is the nudge: every injected value is replaced by `<VARIABLE_NAME>` in the child's stdout and stderr, unconditionally, with no flag to switch it off (values shorter than four characters are not masked).
+
+| Command | What it does |
+| --- | --- |
+| `secrets-axi` | Home view: Guard status, Secret Files in the repository (name, key count), detected Secret Source, other env files not loaded, a warning when `.env` is tracked by git, the one `run` form to use |
+| `run [--env-file F]... [--aws-secret ID[=NAME]]... -- <cmd>` | Guarded Run: resolve the secrets, spawn `<cmd>` with them in its environment, mask its output |
+| `keys <file>` | Key listing: each variable's name, set or empty, and the shape of its value (length, character class). Values only for Reveal Keys (`NODE_ENV`, `PORT`, `VITE_*`, ...) |
+| `set <file> KEY=value`, `unset <file> KEY` | Edit in place; prints the key name and `set` / `replaced` / `removed`, never any other line |
+| `check '<command>'`, `check --read <path>` | Dry run of the Guard: the decision and the Policy entry behind it |
+| `policy` | Effective Policy with the layer each entry comes from |
+| `setup hooks\|status\|uninstall [--project]` | Hook and deny-rule management |
+
+`secrets-axi <command> --help` prints the flag reference; `--json` prints the decoded payload anywhere.
+
+```sh
+secrets-axi run -- pnpm test
+secrets-axi run --env-file .env.test -- pnpm vitest
+secrets-axi run --aws-secret prod/db -- node scripts/migrate.js
+secrets-axi keys .env
+secrets-axi set .env FEATURE_X=true
+secrets-axi check 'cat .env | grep DB'
+```
+
+#### Secret Sources
+
+The first match wins; `--source` overrides. A source only resolves values: the Runner merges them, spawns the child once and masks its output, so every source gets the same guarantee.
+
+1. `.env` made of `op://` references: `op inject` (detected, not supported yet)
+2. `doppler.yaml` / `.infisical.json`: that tool's export (detected, not supported yet)
+3. `.env.keys` present: `dotenvx get --all` (detected, not supported yet)
+4. plain `.env`: built-in parser
+5. AWS Secrets Manager / SSM entries from the Policy or `--aws-secret`: AWS SDK, merged over the env file (a JSON object becomes one variable per top-level key; a bare string needs `ID=NAME`)
+
+Only `.env` is loaded by default; `--env-file` is repeatable and ordered, and the Policy `envFiles` key sets the default. The `NODE_ENV` cascade (`.env.local`, `.env.production`, ...) is never applied.
+
+## Policy
+
+Three layers, merged in order: built-in, then `~/.config/secrets-axi/policy.json`, then `.secrets-axi.json` in the repository root. The repository file is optional, never required and never written by the tool. A repository layer may only add (and add Reveal Keys); `remove` entries are honoured from the user layer only, so a cloned repo can never switch the Guard off. `secrets-axi policy` shows each entry with its layer.
+
+| Key | What it lists |
+| --- | --- |
+| `secretFiles` | Secret File patterns by name (`.env`, `.env.*`, `*.pem`, `id_*`, `~/.aws/credentials`, `~/.npmrc`, ...), never by content; `.env.example`, `.env.sample`, `.env.template` and `*.pub` are exceptions |
+| `fetchCommands` | Secret Fetch command prefixes (`aws ssm get-parameter --with-decryption`, `op read`, `vault kv get`, `doppler secrets`, ...) |
+| `consumers` | Allowed Consumers: programs that load a Secret File without printing it |
+| `reveal` | Reveal Keys: variables whose value a key listing may show |
+| `envFiles` | Env files a Guarded Run loads, in order (default `.env`) |
+| `aws` | AWS Secrets Manager ids (`prod/db`) or `id=NAME` for string secrets |
+
+```json
+{
+  "secretFiles": ["config/*.secret"],
+  "reveal": ["STRIPE_PUBLISHABLE_KEY"],
+  "envFiles": [".env", ".env.test"],
+  "aws": ["prod/db", "prod/api-key=API_KEY"]
+}
+```
+
+## Known limits
+
+- The Guard sees the literal command: `python -c "open('.env')"` or `$(printf '.e''nv')` pass it. The hard layer (the `Read(...)` deny rules `setup hooks` writes) and the sandbox are the boundary for those; masking covers whatever a Guarded Run prints.
+- A Secret File tracked by git leaks through `git diff` / `git log -p`; secrets-axi warns in the home view, it cannot cover it.
+- A child of a Guarded Run can read the Secret File itself; Masking still covers what it prints. A value the Runner did not inject (a different Secret File the child reads on its own) is not masked, so load it through `run` too.
+- Masking is by substring: values under four characters are not masked, and a short or common value can hit unrelated output. Encoded forms (base64, URL-encoded) are not masked yet.
+- Membership of a Secret File is by name; a secret in an unnamed file is not seen (content sniffing is deferred).
+- 0.1 resolves plain `.env` and AWS. `op`, `doppler`, `dotenvx` and `infisical` are detected and reported as "not supported yet"; the OpenCode plugin and Windows are deferred.
+
+## Development
+
+```sh
+corepack pnpm install
+corepack pnpm run check   # typecheck, tests, build, skill freshness
+```
+
+`skills/secrets-axi/SKILL.md` is generated: `corepack pnpm run build:skill`. See `PLAN.md` for the spec, `GLOSSARY.md` for the vocabulary and `docs/adr/` for the design decisions (the hook is the nudge and masking is the boundary; deny with a Hint instead of rewriting; sources resolve and the Runner spawns).
+
+Fixture secrets in tests are obviously fake (`FAKE_...`) and never real values; every test asserts they do not appear in any output.
+
+<!-- axi-tools:start -->
+## Other AXI tools
+
+- [`atl-axi`](https://github.com/cmosgh/atl-axi): Atlassian Jira Cloud CLI for agents
+- [`bb-axi`](https://github.com/cmosgh/bb-axi): Bitbucket Cloud CLI for agents
+- [`hetzner-axi`](https://github.com/cmosgh/hetzner-axi): Hetzner Cloud CLI for agents
+- [`mongo-axi`](https://github.com/cmosgh/mongo-axi): Read-only MongoDB CLI for agents, plus `mongo-rw-axi` (write-capable MongoDB CLI for agents, loopback hosts only)
+- [`mysql-axi`](https://github.com/cmosgh/mysql-axi): Read-only MySQL CLI for agents, plus `mysql-rw-axi` (write-capable MySQL CLI for agents, loopback hosts only)
+- [`ts-axi`](https://github.com/cmosgh/ts-axi): TypeScript symbol CLI for agents
+<!-- axi-tools:end -->
+
+## License
+
+MIT

package/dist/bin/secrets-axi.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { tryFastPath } from "axi-sdk-js/fast-path";
+import { VERSION } from "../src/version.js";
+const argv = process.argv.slice(2);
+// The hook runs on every agent tool call: load only the guard, never the CLI graph.
+if (argv[0] === "hook") {
+    const { runHook } = await import("../src/hook/entry.js");
+    process.exitCode = await runHook();
+}
+else if (!tryFastPath(argv, { version: VERSION })) {
+    const { main } = await import("../src/cli.js");
+    await main();
+}

package/dist/src/args.js

@@ -0,0 +1,184 @@
+import { usageError } from "./errors.js";
+/**
+ * Flags agents commonly carry over from other CLIs. A targeted hint lets the
+ * agent self-correct in one turn instead of scanning the generic flag list.
+ */
+const RENAMED = {
+    "--env": "--env-file",
+    "--file": "--env-file",
+    "--secret": "--aws-secret",
+    "--all": "--fields all",
+    "--global": "(user scope is the default; --project targets the repository)",
+};
+/** Flags whose value is a positional argument in secrets-axi. */
+const POSITIONAL = {
+    "--command": "pass the command after `--`",
+    "--cmd": "pass the command after `--`",
+    "--key": "pass KEY or KEY=value as a positional argument",
+};
+/**
+ * Strict declarative parser: every flag must be declared, unknown flags fail
+ * loud with the valid set inline (AXI principle 6). Supports `--flag value`,
+ * `--flag=value`, boolean flags, repeatable flags, aliases and a `--`
+ * terminator. A bare `-` is a positional (stdin sentinel).
+ */
+export function parseArgs(args, specs, command) {
+    const byName = new Map();
+    for (const spec of specs) {
+        byName.set(spec.name, spec);
+        if (spec.alias)
+            byName.set(spec.alias, spec);
+    }
+    const parsed = {
+        values: new Map(),
+        bools: new Set(),
+        positionals: [],
+    };
+    const unknown = [];
+    for (let i = 0; i < args.length; i++) {
+        const token = args[i];
+        if (token === "--") {
+            parsed.positionals.push(...args.slice(i + 1));
+            break;
+        }
+        if (token === "-" || !token.startsWith("-")) {
+            parsed.positionals.push(token);
+            continue;
+        }
+        const eq = token.indexOf("=");
+        const name = eq === -1 ? token : token.slice(0, eq);
+        const inlineValue = eq === -1 ? undefined : token.slice(eq + 1);
+        if (name === "--help" || name === "-h")
+            continue;
+        const spec = byName.get(name);
+        if (!spec) {
+            if (!unknown.includes(name))
+                unknown.push(name);
+            continue;
+        }
+        if (spec.boolean) {
+            if (inlineValue !== undefined) {
+                throw usageError(`${spec.name} does not take a value`, [
+                    `Run \`${command} --help\``,
+                ]);
+            }
+            parsed.bools.add(spec.name);
+            continue;
+        }
+        let value = inlineValue;
+        if (value === undefined) {
+            const next = args[i + 1];
+            // A following declared flag (or `--`) means the value is missing. Other
+            // dash-leading tokens are accepted so bodies like "- item" still work.
+            if (next === undefined || next === "--" || byName.has(next)) {
+                throw usageError(`${spec.name} requires a value`, [
+                    `Run \`${command} --help\``,
+                ]);
+            }
+            value = next;
+            i++;
+        }
+        if (value.trim() === "") {
+            throw usageError(`${spec.name} requires a non-empty value`);
+        }
+        const existing = parsed.values.get(spec.name);
+        if (existing && !spec.repeatable) {
+            throw usageError(`${spec.name} may only be given once`);
+        }
+        parsed.values.set(spec.name, [...(existing ?? []), value]);
+    }
+    if (unknown.length > 0) {
+        const valid = specs.map((s) => s.name).join(", ") || "(none)";
+        const renamed = unknown
+            .filter((flag) => RENAMED[flag] && byName.has(RENAMED[flag]))
+            .map((flag) => `${flag} is not supported here; use ${RENAMED[flag]} instead`);
+        const positional = unknown
+            .filter((flag) => POSITIONAL[flag])
+            .map((flag) => `${flag} is not supported; ${POSITIONAL[flag]}`);
+        throw usageError(`unknown flag${unknown.length > 1 ? "s" : ""} ${unknown.join(", ")} for \`${command}\``, [
+            ...renamed,
+            ...positional,
+            `valid flags for \`${command}\`: ${valid} (--help always allowed)`,
+        ]);
+    }
+    return parsed;
+}
+export function flag(parsed, name) {
+    return parsed.values.get(name)?.[0];
+}
+export function flags(parsed, name) {
+    return parsed.values.get(name) ?? [];
+}
+export function bool(parsed, name) {
+    return parsed.bools.has(name);
+}
+export function requireFlag(parsed, name, usage) {
+    const value = flag(parsed, name);
+    if (value === undefined) {
+        throw usageError(`${name} is required`, [usage]);
+    }
+    return value;
+}
+export function intFlag(parsed, name, fallback, range) {
+    const raw = flag(parsed, name);
+    if (raw === undefined)
+        return fallback;
+    if (!/^\d+$/.test(raw)) {
+        throw usageError(`${name} must be a whole number, got '${raw}'`);
+    }
+    const value = Number(raw);
+    if (value < range.min || value > range.max) {
+        throw usageError(`${name} must be between ${range.min} and ${range.max}`);
+    }
+    return value;
+}
+export function enumFlag(parsed, name, allowed, fallback) {
+    const raw = flag(parsed, name);
+    if (raw === undefined)
+        return fallback;
+    const value = raw.toLowerCase();
+    if (!allowed.includes(value)) {
+        throw usageError(`invalid ${name} '${raw}'`, [
+            `valid values: ${allowed.join(", ")}`,
+        ]);
+    }
+    return value;
+}
+/** Require exactly `count` positionals; extra or missing ones are usage errors. */
+export function expectPositionals(parsed, count, usage) {
+    if (parsed.positionals.length !== count) {
+        const problem = parsed.positionals.length < count
+            ? "missing argument"
+            : `unexpected argument '${parsed.positionals[count]}'`;
+        throw usageError(problem, [`usage: ${usage}`]);
+    }
+    return parsed.positionals;
+}
+export function positiveId(raw, label) {
+    const cleaned = raw?.replace(/^#/, "");
+    if (!cleaned || !/^\d+$/.test(cleaned) || Number(cleaned) < 1) {
+        throw usageError(`invalid ${label} '${raw ?? ""}' - expected a positive number`);
+    }
+    return Number(cleaned);
+}
+/** Parse a comma-separated `--fields` value against the supported extras. */
+export function parseFields(raw, available) {
+    if (raw === undefined)
+        return [];
+    const requested = [
+        ...new Set(raw
+            .split(",")
+            .map((f) => f.trim().toLowerCase())
+            .filter(Boolean)),
+    ];
+    const bad = requested.filter((f) => f !== "all" && !available.includes(f));
+    if (bad.length > 0) {
+        throw usageError(`unknown field${bad.length > 1 ? "s" : ""}: ${bad.join(", ")}`, [
+            `available --fields: ${available.join(", ")} (or all)`,
+        ]);
+    }
+    if (requested.includes("all"))
+        return [...available];
+    // Columns keep the documented order whatever order they were asked in.
+    return available.filter((f) => requested.includes(f));
+}

package/dist/src/cli.js

@@ -0,0 +1,101 @@
+import { runAxiCli } from "axi-sdk-js";
+import { checkCommand, CHECK_HELP } from "./commands/check.js";
+import { SET_HELP, setCommand, UNSET_HELP, unsetCommand } from "./commands/edit.js";
+import { homeCommand } from "./commands/home.js";
+import { keysCommand, KEYS_HELP } from "./commands/keys.js";
+import { policyCommand, POLICY_HELP } from "./commands/policy.js";
+import { runCommand, RUN_HELP } from "./commands/run.js";
+import { setupCommand, SETUP_HELP } from "./commands/setup.js";
+import { AxiError, exitCodeForError } from "./errors.js";
+import { DESCRIPTION, TOP_HELP } from "./meta.js";
+import { renderErrorOutput, setJsonMode, toJson } from "./render.js";
+import { VERSION } from "./version.js";
+export { DESCRIPTION, TOP_HELP };
+const COMMAND_HELP = {
+    run: RUN_HELP,
+    keys: KEYS_HELP,
+    set: SET_HELP,
+    unset: UNSET_HELP,
+    check: CHECK_HELP,
+    policy: POLICY_HELP,
+    setup: SETUP_HELP,
+};
+function command(name, handler, ctx) {
+    return async (args) => {
+        const own = args.includes("--") ? args.slice(0, args.indexOf("--")) : args;
+        if (own.includes("-h") || own.includes("--help"))
+            return (COMMAND_HELP[name] ?? "").trimEnd();
+        return handler(args, ctx);
+    };
+}
+function formatError(error) {
+    const axi = error instanceof AxiError ? error : new AxiError(error instanceof Error ? error.message : String(error), "UNKNOWN");
+    return { output: `${renderErrorOutput(axi.message, axi.code, axi.suggestions)}\n`, exitCode: exitCodeForError(axi) };
+}
+export async function main(options = {}) {
+    const argv = options.argv ?? process.argv.slice(2);
+    // Flags after `--` belong to the child command of `run`, never to secrets-axi.
+    const own = argv.includes("--") ? argv.slice(0, argv.indexOf("--")) : argv;
+    const json = own.includes("--json");
+    setJsonMode(json);
+    const stdout = options.stdout ?? process.stdout;
+    const ctx = {
+        cwd: options.cwd ?? process.cwd(),
+        ...(options.home !== undefined ? { home: options.home } : {}),
+        ...(options.userPolicyPath !== undefined ? { userPolicyPath: options.userPolicyPath } : {}),
+        ...(options.io !== undefined ? { io: options.io } : {}),
+    };
+    // `run` bypasses the SDK dispatcher: its child's flags (`--help`, `--json`) are not ours, and its output is the child's.
+    if (argv[0] === "run" && !json) {
+        try {
+            const output = own.includes("-h") || own.includes("--help") ? RUN_HELP.trimEnd() : await runCommand(argv.slice(1), ctx);
+            if (output)
+                stdout.write(`${output}\n`);
+        }
+        catch (error) {
+            const { output, exitCode } = formatError(error);
+            stdout.write(output);
+            process.exitCode = exitCode;
+        }
+        return;
+    }
+    let buffered = "";
+    try {
+        await runAxiCli({
+            argv: json ? own.filter((a) => a !== "--json") : argv,
+            stdout: json ? { write: (chunk) => (buffered += chunk) } : stdout,
+            description: DESCRIPTION,
+            version: VERSION,
+            topLevelHelp: TOP_HELP,
+            home: (args) => homeCommand(args, ctx),
+            commands: {
+                run: command("run", runCommand, ctx),
+                keys: command("keys", keysCommand, ctx),
+                set: command("set", setCommand, ctx),
+                unset: command("unset", unsetCommand, ctx),
+                check: command("check", checkCommand, ctx),
+                policy: command("policy", policyCommand, ctx),
+                setup: command("setup", setupCommand, ctx),
+                hook: async () => "The hook entry is `secrets-axi hook` with a PreToolUse JSON object on stdin; agents call it, not people. Run `secrets-axi check '<command>'` for a dry run",
+            },
+            getCommandHelp: (name) => COMMAND_HELP[name],
+            renderUnknownCommand: (name) => `${renderErrorOutput(`unknown command '${name}'`, "VALIDATION_ERROR", [
+                "commands: run, keys, set, unset, check, policy, setup (no command = secrets overview)",
+                "Run `secrets-axi --help` for examples",
+            ])}\n`,
+            formatError,
+        });
+    }
+    finally {
+        setJsonMode(false);
+    }
+    if (!json)
+        return;
+    if (stdout === process.stdout) {
+        process.stdout.on("error", (error) => {
+            if (error.code !== "EPIPE")
+                throw error;
+        });
+    }
+    stdout.write(toJson(buffered));
+}

package/dist/src/commands/check.js

@@ -0,0 +1,40 @@
+import { flag, parseArgs } from "../args.js";
+import { usageError } from "../errors.js";
+import { decide } from "../hook/guard.js";
+import { loadPolicy } from "../policy.js";
+import { block, helpBlock, out } from "../render.js";
+export const CHECK_HELP = `usage: secrets-axi check '<shell command>' | --read <path> | --edit <path> | --grep <path|dir>
+Dry run of the Guard: the decision it would make for that tool call, the Policy rule behind it and the Hint the agent would get. Nothing is executed or read.
+examples[3]:
+  secrets-axi check 'cat .env | grep DB'
+  secrets-axi check 'docker run --env-file .env app'
+  secrets-axi check --read ~/.aws/credentials
+`;
+export async function checkCommand(args, ctx) {
+    const parsed = parseArgs(args, [{ name: "--read" }, { name: "--edit" }, { name: "--grep" }], "secrets-axi check");
+    const read = flag(parsed, "--read");
+    const edit = flag(parsed, "--edit");
+    const grep = flag(parsed, "--grep");
+    const command = parsed.positionals.join(" ");
+    const given = [read, edit, grep, command || undefined].filter((v) => v !== undefined).length;
+    if (given !== 1)
+        throw usageError("give exactly one of: a shell command, --read <path>, --edit <path>, --grep <path>");
+    const call = read
+        ? { tool: "Read", input: { file_path: read }, cwd: ctx.cwd }
+        : edit
+            ? { tool: "Edit", input: { file_path: edit, old_string: "", new_string: "" }, cwd: ctx.cwd }
+            : grep
+                ? { tool: "Grep", input: { pattern: "x", path: grep }, cwd: ctx.cwd }
+                : { tool: "Bash", input: { command }, cwd: ctx.cwd };
+    const { policy, broken } = loadPolicy(ctx.cwd, { userPath: ctx.userPolicyPath, home: ctx.home });
+    const decision = decide(call, policy, { home: ctx.home });
+    const base = { tool: call.tool, call: read ?? edit ?? grep ?? command };
+    if (decision.kind === "pass") {
+        return out(block({ ...base, decision: "pass" }), helpBlock(broken.map((b) => `Policy file ${b} is not valid JSON and was skipped`)));
+    }
+    if (decision.kind === "deny") {
+        return block({ ...base, decision: "deny", rule: decision.rule, ...(decision.file ? { file: decision.file } : {}), hint: decision.hint });
+    }
+    const rewritten = call.tool === "Bash" ? decision.input["command"] : decision.input["glob"];
+    return block({ ...base, decision: "rewrite", rule: decision.rule, rewritten, note: decision.note });
+}

package/dist/src/commands/edit.js

@@ -0,0 +1,56 @@
+import { closeSync, existsSync, openSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { expectPositionals, parseArgs } from "../args.js";
+import { axiError, usageError } from "../errors.js";
+import { setKey, unsetKey } from "../env.js";
+import { display } from "../hook/guard.js";
+import { expandHome } from "../policy.js";
+import { block, helpBlock, out } from "../render.js";
+export const SET_HELP = `usage: secrets-axi set <file> KEY=value
+Add or replace one variable in a dotenv file in place; every other line stays. Nothing but the key name is printed. A missing file is created (mode 600).
+examples[2]:
+  secrets-axi set .env FEATURE_X=true
+  secrets-axi set .env.local DATABASE_URL='postgres://u:p@localhost/db'
+`;
+export const UNSET_HELP = `usage: secrets-axi unset <file> KEY
+Remove every assignment of KEY from a dotenv file in place.
+examples[1]:
+  secrets-axi unset .env OLD_TOKEN
+`;
+const KEY = /^[A-Za-z_][A-Za-z0-9_.-]*$/;
+export async function setCommand(args, ctx) {
+    const parsed = parseArgs(args, [], "secrets-axi set");
+    if (parsed.positionals.length > 2)
+        throw usageError("expected <file> KEY=value (2 arguments)", ["Quote the pair when the value has spaces: `secrets-axi set .env 'MSG=hello world'`"]);
+    expectPositionals(parsed, 2, "secrets-axi set <file> KEY=value");
+    const [rawFile, assignment] = parsed.positionals;
+    const eq = assignment.indexOf("=");
+    if (eq <= 0)
+        throw usageError("expected KEY=value", ["Quote the whole pair when the value has spaces: `secrets-axi set .env 'MSG=hello world'`"]);
+    const key = assignment.slice(0, eq);
+    const value = assignment.slice(eq + 1);
+    if (!KEY.test(key))
+        throw usageError(`'${key}' is not a variable name`);
+    const abs = resolve(ctx.cwd, expandHome(rawFile, ctx.home));
+    if (!existsSync(abs)) {
+        if (!existsSync(dirname(abs)))
+            throw axiError(`directory does not exist: ${dirname(rawFile)}`, "NOT_FOUND");
+        closeSync(openSync(abs, "w", 0o600));
+    }
+    const result = setKey(abs, key, value);
+    const file = display(abs, ctx.cwd, ctx.home);
+    return out(block({ file, key: result.key, action: result.action, line: result.line }), helpBlock([`Run \`secrets-axi keys ${file}\` to see the variables`]));
+}
+export async function unsetCommand(args, ctx) {
+    const parsed = parseArgs(args, [], "secrets-axi unset");
+    expectPositionals(parsed, 2, "secrets-axi unset <file> KEY");
+    const [rawFile, key] = parsed.positionals;
+    if (!KEY.test(key))
+        throw usageError(`'${key}' is not a variable name`);
+    const abs = resolve(ctx.cwd, expandHome(rawFile, ctx.home));
+    if (!existsSync(abs))
+        throw axiError(`no such file: ${rawFile}`, "NOT_FOUND");
+    const result = unsetKey(abs, key);
+    const file = display(abs, ctx.cwd, ctx.home);
+    return block({ file, key: result.key, action: result.action, ...(result.line > 0 ? { line: result.line } : {}) });
+}

package/dist/src/commands/home.js

@@ -0,0 +1,65 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseArgs } from "../args.js";
+import { parseEnv } from "../env.js";
+import { loadPolicy } from "../policy.js";
+import { block, helpBlock, out } from "../render.js";
+import { guardStatus } from "../setup/index.js";
+import { detectSource } from "../sources/detect.js";
+import { findEnvFiles, scanSecretFiles } from "./scan.js";
+/** Session-start view: names and counts only, bounded scan, exit 0 anywhere. */
+export async function homeCommand(args, ctx) {
+    parseArgs(args, [], "secrets-axi");
+    const load = loadPolicy(ctx.cwd, { userPath: ctx.userPolicyPath, home: ctx.home });
+    const { policy } = load;
+    const scan = scanSecretFiles(ctx.cwd, policy);
+    const envFiles = findEnvFiles(ctx.cwd, policy);
+    const detected = detectSource(ctx.cwd, policy, envFiles);
+    const tracked = trackedByGit(ctx.cwd, scan.files);
+    const files = scan.files.map((f) => {
+        const count = /\.env|\.envrc|\.secrets/.test(f) ? keyCount(join(ctx.cwd, f)) : undefined;
+        return `${f}${count !== undefined ? ` (${count} keys)` : ""}${tracked.has(f) ? " TRACKED BY GIT" : ""}`;
+    });
+    let guard;
+    try {
+        const status = guardStatus({ scope: "user", cwd: ctx.cwd, homeDir: ctx.home });
+        const on = [status.claude.installed ? "Claude Code" : "", status.codex.installed ? "Codex" : ""].filter(Boolean);
+        guard = on.length > 0 ? `active (${on.join(", ")})` : "not installed";
+    }
+    catch {
+        guard = "unknown";
+    }
+    const source = detected.kind === "none" ? detected.reason : `${detected.kind} (${detected.reason})${detected.unsupported ? " - not supported yet" : ""}`;
+    const help = [
+        "Run `secrets-axi run -- <command>` instead of sourcing .env: secrets are injected and masked in the output",
+        ...(scan.files[0] ? [`Run \`secrets-axi keys ${scan.files.find((f) => f.startsWith(".env")) ?? scan.files[0]}\` for variable names and shapes (never values)`] : []),
+        ...(guard === "not installed" ? ["Run `secrets-axi setup hooks` to install the Guard for Claude Code and Codex"] : []),
+        ...(tracked.size > 0 ? [`${[...tracked].join(", ")} is tracked by git: \`git diff\`/\`git log -p\` can print it and the Guard cannot cover that; untrack it`] : []),
+        ...(load.broken.map((b) => `${b} is not valid JSON and was skipped`)),
+    ];
+    return out(block({
+        guard,
+        secret_files: files.length > 0 ? files : "none found",
+        ...(scan.capped ? { scan: "partial (large tree)" } : {}),
+        source,
+        ...(detected.otherEnvFiles.length > 0 ? { not_loaded: detected.otherEnvFiles.join(", ") } : {}),
+        ...(policy.aws.length > 0 ? { aws: policy.aws.join(", ") } : {}),
+    }), helpBlock(help));
+}
+function keyCount(path) {
+    try {
+        return parseEnv(readFileSync(path, "utf8")).length;
+    }
+    catch {
+        return undefined;
+    }
+}
+function trackedByGit(cwd, files) {
+    if (files.length === 0)
+        return new Set();
+    const result = spawnSync("git", ["ls-files", "--error-unmatch", "--", ...files], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    if (result.error || result.status === null)
+        return new Set();
+    return new Set(result.stdout.split("\n").filter(Boolean));
+}