@nathapp/nax-agent 0.1.0

package/dist/tools/nax-owned-writes.js

@@ -0,0 +1,259 @@
+/**
+ * Which paths nax refuses to let an agent touch, and to which tools.
+ *
+ * A separate file rather than an addition to src/tools/policy.ts, for the same
+ * reason src/tools/deny-paths.ts is one: that file carries the containment
+ * seam and sits at the project's file-size ratchet, while this is a narrower
+ * concern -- it has nothing to do with resolving or containing a path, only
+ * with refusing one containment would otherwise allow.
+ *
+ * Segment-exact, never a prefix or substring match: `.naxignore`,
+ * `docs/nax/config.json` and `.nax/mono/api/notes.md` are ordinary paths a
+ * tool must still reach.
+ */
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { realOrRaw } from "#src/internal/realpath";
+/**
+ * The one top-level `.nax/` entry agents may write freely: the scratchpad.
+ * Must equal the last segment of SCRATCHPAD_DIR (pinned by a test; importing
+ * it here would close a scratchpad -> policy -> nax-owned-writes cycle).
+ */
+export const NAX_SCRATCHPAD_ENTRY = "scratchpad";
+/**
+ * Top-level `.nax/` entries an allowWrite opt-in can never open (nax#2260):
+ * config is the trust anchor for ungated commands, `mono` holds package
+ * configs, and `features` holds every PRD plus the running feature's state.
+ */
+const NAX_NEVER_OPT_IN = new Set(["config.json", "mono", "features"]);
+/**
+ * Entries nax loads as human-authored input. The sandbox denies these even
+ * when absent, so an agent cannot create one: a new `.nax/rules/x.md` would be
+ * injected into every later session's prompt, and `hooks.json` / `plugins/`
+ * run unsandboxed on the next `nax run`. `templates/` and `prompts/` are where
+ * `prompts.overrides` points. nax creates none of them mid-run (CLI only).
+ */
+export const NAX_ALWAYS_DENIED_ENTRIES = [
+    "config.json",
+    "mono",
+    "rules",
+    "context.md",
+    "hooks.json",
+    "plugins",
+    "templates",
+    "prompts",
+];
+/**
+ * A test file directly inside a feature dir: the acceptance and suggested
+ * tests under their per-language names (`.nax-acceptance.test.ts`,
+ * `_nax_acceptance_test.py`, `.nax-acceptance.rs`, ...) or a custom
+ * `acceptance.testPath`, which is itself a test file name.
+ */
+const FEATURE_TEST_FILE = /^\.nax-(acceptance|suggested)|[._-](test|spec)\.[a-z0-9]+$/i;
+const NO_OPT_INS = new Set();
+/**
+ * Top-level `.nax/` entries a human opened for agent writes by listing them in
+ * `execution.sandbox.filesystem.allowWrite` (nax#2260). Only an exact entry
+ * counts -- `.nax/rules`, never `.nax/rules/a.md` -- and never the scratchpad
+ * (always open) or a NAX_NEVER_OPT_IN entry. Relative entries resolve against
+ * `root`, as the sandbox's own write roots do.
+ */
+export function naxWriteOptIns(root, allowWrite) {
+    const naxDir = resolve(root, ".nax");
+    const names = allowWrite
+        .map((p) => relative(naxDir, isAbsolute(p) ? resolve(p) : resolve(root, p)))
+        .filter((rel) => rel !== "" && !rel.startsWith("..") && !rel.includes(sep) && !isAbsolute(rel))
+        .filter((name) => name !== NAX_SCRATCHPAD_ENTRY && !NAX_NEVER_OPT_IN.has(name));
+    return new Set(names);
+}
+/** `.nax/config.json`, or `.nax/mono/<package...>/config.json`, as root-relative segments. */
+function isNaxConfigSegments(segments) {
+    if (segments[0] !== ".nax" || segments[segments.length - 1] !== "config.json")
+        return false;
+    return segments.length === 2 || (segments.length >= 4 && segments[1] === "mono");
+}
+/**
+ * Is `resolved` one of nax's own CONFIG files, relative to `root`?
+ *
+ * `.nax/config.json`, and `.nax/mono/<package>/config.json` in a monorepo.
+ *
+ * Why these at all: `quality.commands` and `acceptance.command` are run by key
+ * through a shell and never pass the permission gate -- they are trusted
+ * because a HUMAN wrote them. That trust rests entirely on a model being
+ * unable to write them. An agent holding `Write` under the default
+ * `unrestricted` profile could otherwise add a quality command and receive an
+ * ungated shell on the next run, routing around every `Bash(...)` rule, the
+ * lexer's construct refusals and containment itself.
+ *
+ * Refused to EVERY tool, reads included -- this is the pre-existing behaviour
+ * and it is deliberate.
+ */
+export function isNaxConfigFile(root, resolved) {
+    const rel = relative(realOrRaw(root), resolved);
+    if (rel === "" || rel.startsWith(".."))
+        return false;
+    // `.nax/config.json` (2), or `.nax/mono/<package>/config.json` at ANY package
+    // depth (>= 4). The real override path is nested -- `loadConfigForWorkdir`
+    // reads `.nax/mono/<packageDir>/config.json` where packageDir is the
+    // repo-relative package path (`src/config/loader.ts:382`), so a normal
+    // `packages/*` layout is 5 segments, not 4. A length-exact rule left every
+    // such override writable whenever the story's root was the repo root.
+    return isNaxConfigSegments(rel.split(sep));
+}
+/**
+ * The path-bearing tools that MUTATE. Read, Grep, Glob and Git are read-only
+ * and are deliberately absent: an agent legitimately reads its own PRD, and
+ * refusing that would break ordinary work to close one hole.
+ *
+ * Bash and Exec are absent because they carry no path fields -- a shell
+ * redirect into `.nax/` is gated by the human-authored `Bash(...)` rules and
+ * the lexer, which is a different seam from this one.
+ */
+export const NAX_OWNED_WRITE_TOOLS = new Set(["Write", "Edit", "Delete", "GitCommit"]);
+/**
+ * nax's run-control files at the root: the command channel an agent could
+ * otherwise use to PAUSE, ABORT or SKIP stories without writing any code.
+ *
+ * `.queue.txt.processing` is the atomic-rename target the queue handler reads
+ * from (src/execution/queue-handler.ts), so guarding only `.queue.txt` would
+ * leave the same hole one rename downstream.
+ */
+export const QUEUE_CONTROL_FILES = new Set([".queue.txt", ".queue.txt.processing"]);
+/**
+ * Is this path one nax owns the writes to, independent of WHICH tool is asking?
+ *
+ * `naxOwnedWriteRefusal` answers the same question for the four file-writing
+ * tools and returns prose. This predicate is the tool-agnostic half, extracted
+ * so the `raw` bash screen (ADR-030) can consult exactly the same path set
+ * without being in `NAX_OWNED_WRITE_TOOLS`. One definition, two callers.
+ *
+ * @param rel - Path relative to the permitted root, `/`-joined.
+ */
+export function isNaxOwnedWritePath(rel) {
+    return naxOwnedKind(rel) !== undefined;
+}
+/**
+ * Which kind of nax-owned write path `rel` is, or undefined when it is not one.
+ *
+ * `/`-joined and root-relative, like `isNaxOwnedWritePath`. Never returns
+ * `"config"` -- nax config files are recognised by the lexical
+ * `isNaxConfigFile` pass, which callers (`protectedHit` in policy-bash-raw.ts)
+ * run FIRST. Keeping the two apart is what lets the raw screen name the kind it
+ * matched without duplicating the config rule here.
+ */
+export function naxOwnedKind(rel) {
+    const segments = rel.split("/");
+    // SEC-5: the run-control file lives at the root, so match it exactly there
+    // and not at any other depth -- a nested `sub/.queue.txt` is an ordinary
+    // file, not the queue nax reads.
+    if (segments.length === 1 && QUEUE_CONTROL_FILES.has(segments[0] ?? ""))
+        return "queue";
+    if (segments[0] === ".nax" && segments[1] === "features" && segments[segments.length - 1] === "prd.json") {
+        return "prd";
+    }
+    return undefined;
+}
+/**
+ * Refusal text for a Bash command that names (verb "names") or redirects into
+ * (verb "redirects into") a nax-owned file.
+ *
+ * Kind-specific on purpose. The previous screen returned one modification-only
+ * sentence for every kind, which read as "you cannot WRITE this" -- so an agent
+ * that only wanted to READ a PRD retried a command it will never be allowed to
+ * run. Each branch now says what the file IS and what the agent can do instead.
+ *
+ * The text never spells `.nax/features/` literally: `src/tools/` is covered by
+ * the `check:feature-dir-ssot` gate, so the PRD branch names the token the agent
+ * used (`hit`) rather than the tree layout.
+ *
+ * US-002: `opts.sandboxWrapped` (an available launcher) swaps only the PRD
+ * sentence -- reading through Bash is then allowed, writing still is not.
+ * `config` and `queue` are unchanged in both modes.
+ */
+export function naxOwnedBashRefusal(tool, kind, hit, verb, opts) {
+    switch (kind) {
+        case "prd":
+            return (`${tool} command ${verb} "${hit}", which holds this story's acceptance criteria. ` +
+                "nax updates it itself during the run, so it shows as modified. " +
+                (opts?.sandboxWrapped === true
+                    ? "Reading it through Bash is allowed; writing it is not -- nax updates it itself. "
+                    : "Bash commands naming it are refused, reads included -- leave it as is. ") +
+                "To view it, use the `Read` tool.");
+        case "queue":
+            return (`${tool} command ${verb} "${hit}", which is nax's run-control queue. ` +
+                "Bash commands naming it are refused, reads included -- change the run through the queue command.");
+        case "config":
+            return (`${tool} command ${verb} "${hit}", which is nax configuration. ` +
+                "Bash commands naming it are refused, reads included -- nax configuration is not changed from inside a run.");
+    }
+}
+/**
+ * Why `tool` may not touch `rel`, or `undefined` when it may.
+ *
+ * `rel` MUST be the canonical, posix-separated, root-relative spelling the
+ * policy itself derived -- never the caller's own. Matching the caller's
+ * spelling means this guard and the policy that approved the call are reading
+ * different strings, and every alternate spelling ("./x", "a/../x") walks past
+ * the guard. Same rule, and the same reason, as `matchesDenyPaths`.
+ *
+ * The PRD defines the acceptance criteria the story is judged against. An
+ * agent that can rewrite it can pass any review without writing any code,
+ * which defeats the review layer without touching a config file.
+ *
+ * The queue file is the other half of the same concern: it is the run-control
+ * channel, and a write there can pause, abort or skip stories outright.
+ */
+export function naxOwnedWriteRefusal(tool, rel, exemptRel, optIns = NO_OPT_INS) {
+    if (!NAX_OWNED_WRITE_TOOLS.has(tool))
+        return undefined;
+    if (!isNaxOwnedWritePath(rel)) {
+        return exemptRel !== undefined && rel === exemptRel ? undefined : naxStateRefusal(rel, optIns);
+    }
+    const segments = rel.split("/");
+    // SEC-5: the run-control file lives at the root, so match it exactly
+    // there and not at any other depth -- a nested `sub/.queue.txt` is an
+    // ordinary file, not the queue nax reads.
+    if (segments.length === 1) {
+        return `"${rel}" is nax's own run state: it carries the PAUSE/ABORT/SKIP commands that control this run, so no tool may modify it. Change the run through the queue command, not by writing its file.`;
+    }
+    // nax#2115: the plan session is the ONE writer of a PRD -- its op declares
+    // `fileOutput: (input) => input.outputPath` and every plan prompt instructs
+    // the agent to write the PRD there rather than reply with it. #2095 added
+    // this guard without an exemption, which severed that contract and left
+    // `nax plan` unable to produce a PRD in ANY mode.
+    //
+    // The exemption is PATH-EXACT, not role-shaped: the plan session may write
+    // the single path its own op declared, and nothing else. A sibling feature's
+    // PRD stays refused even to the plan session, so a planner cannot reach
+    // across features to rewrite criteria it is not authoring. `exemptRel` must
+    // be the caller's canonical, posix-separated, root-relative spelling --
+    // derived by the policy itself, never taken from the agent's own arguments.
+    if (exemptRel !== undefined && rel === exemptRel)
+        return undefined;
+    return `"${rel}" is nax's own run state: it holds the acceptance criteria this story is judged against, so no tool may modify it. Change the code, not the criteria.`;
+}
+/**
+ * nax#2260: everything else under `.nax/` is nax's own state. Writable: the
+ * scratchpad, test files directly inside a feature dir (FEATURE_TEST_FILE --
+ * the tool-audit ledgers show these are the only file-tool writes agents need
+ * there; the feature's context.md, spec and state files stay refused), and
+ * opted-in entries. Config files are left to the earlier, more specific
+ * `isNaxConfigFile` refusal, which covers reads too.
+ *
+ * Only a leading `.nax/` segment is matched, so a monorepo package's own
+ * `.nax/` is excluded on purpose -- see `naxDenies` in
+ * src/sandbox/policy-builder.ts for why that is mostly safe to delete and
+ * where the one gap (package `rules/`) remains.
+ */
+function naxStateRefusal(rel, optIns) {
+    const segments = rel.split("/");
+    if (segments[0] !== ".nax" || isNaxConfigSegments(segments))
+        return undefined;
+    const entry = segments[1];
+    if (segments.length > 2 && (entry === NAX_SCRATCHPAD_ENTRY || optIns.has(entry ?? "")))
+        return undefined;
+    if (segments.length === 4 && entry === "features" && FEATURE_TEST_FILE.test(segments[3] ?? ""))
+        return undefined;
+    return (`"${rel}" is nax's own state, which agents do not modify. Under .nax/, write only to your scratchpad ` +
+        "(.nax/scratchpad/) or to a feature's acceptance test file. " +
+        "A human can open a path for a story by listing it in execution.sandbox.filesystem.allowWrite in the project config.");
+}

package/dist/tools/package-managers-table.d.ts

@@ -0,0 +1,146 @@
+/**
+ * The package-manager knowledge table for the install-shaped exec branch.
+ *
+ * Each entry is DATA — a description of one manager's install verbs (and
+ * their aliases), its no-scripts mechanism, how to rewrite argv for a
+ * package-scoped versus repo-root-scoped call, and which incoming flags
+ * would smuggle in a second workspace member if we spliced our own scoping
+ * flag in beside them. No branching policy lives here; `normalizeExec` in
+ * `package-managers.ts` is the only place that interprets these fields.
+ *
+ * Facts this table encodes, verified against each tool's own documentation
+ * (see task-4 brief, 2026-09-06) plus two review-driven fix rounds:
+ *
+ * - Yarn 2+ ("Berry") has no `--ignore-scripts` flag; it honours the
+ *   `enableScripts` setting, overridable per-invocation via the
+ *   `YARN_ENABLE_SCRIPTS` environment variable. Yarn 1 ("Classic") takes
+ *   `--ignore-scripts`. Passing `--ignore-scripts` to Yarn 2+ is a hard
+ *   error, so version detection that is inconclusive must default to the
+ *   Yarn 2+ branch — the env var is inert on Yarn 1, the flag is fatal on
+ *   Yarn 2+, and failing toward the inert option is the safe direction.
+ * - pnpm's `--filter` requires the `./` prefix to select by path
+ *   (`--filter ./packages/foo`); the bare form (`packages/foo`) is parsed as
+ *   a package NAME and silently selects nothing.
+ * - `yarn workspace <name>` and `cargo add -p <name>` take the manifest
+ *   NAME, not a path.
+ *
+ * pip and uv no-scripts mechanisms: I could not confirm a mechanism from
+ * either tool's own documentation that actually suppresses arbitrary code
+ * execution during an install the way `--ignore-scripts` does for npm/bun/
+ * yarn-classic:
+ *
+ * - pip has no `--ignore-scripts` equivalent at all. `--only-binary :all:`
+ *   forces wheel-only resolution (no sdist, so no `setup.py` executes for
+ *   any package pip resolves), but it is a resolution-strategy flag, not a
+ *   scripts switch — it errors the whole install if a required dependency
+ *   ships no wheel, rather than degrading gracefully. Wiring it in as if it
+ *   were "the no-scripts flag" would look like protection where none was
+ *   verified, and I have not confirmed it is safe as a blanket default
+ *   here. Left as `{ none: true }`.
+ * - uv installs prebuilt wheels by default and only builds from source
+ *   (running a build backend, e.g. `setup.py`/PEP 517 hooks) when a
+ *   dependency has no wheel for the target platform, same as pip. There is
+ *   no uv flag documented as suppressing that fallback build step itself —
+ *   `--no-build-isolation` changes how a source build is isolated, it does
+ *   not prevent one from happening, so it is not a substitute either. Left
+ *   as `{ none: true }` per the brief's instruction not to invent a switch.
+ *
+ * Both gaps mean pip/uv installs get cwd/scoping normalization but no
+ * scripts-suppression hardening. This should be tracked as a follow-up
+ * rather than silently accepted.
+ *
+ * Install-verb ALIASES (fix round 1, Critical finding A): each manager's
+ * install verb has common short aliases the model can reach for just as
+ * easily as the canonical spelling (`npm i` is as ordinary an invocation as
+ * `npm install`). They are listed here as additional single-token verb
+ * sequences, matched by `classifyExec` exactly like the canonical verb in
+ * both its position-anchored match and its fail-closed scan — never as a
+ * special case in the matcher itself. Sources: npm's own `install` command
+ * aliases (`i`, `in`, `ins`, `inst`, `insta`, `instal`, `install`, `add`) and
+ * its `install-test`/`it` alias pair; pnpm's `i`/`install-test` aliases of
+ * `install`; bun's `i`/`a` aliases of `install`/`add`. Yarn Classic and
+ * Berry do not document a short alias for `install`/`add`, so none is
+ * added — checked and confirmed empty, not merely unresearched.
+ *
+ * Workspace-scoping SMUGGLING (fix round 1, Critical finding 2 + addendum
+ * A/C): before this table splices in its own scoping flag or no-scripts
+ * flag, `normalizeExec` screens the incoming argv for tokens that would
+ * change what gets targeted if left in place — a second `-w`/`--filter`
+ * naming another member, or a `--ignore-scripts`/`--no-ignore-scripts` the
+ * model added itself. `scopingConflict` is each entry's screen for the
+ * first kind; the second kind (`SCRIPTS_CONTROL_FLAG`) is universal and
+ * lives in `package-managers.ts` since it isn't manager-specific data. Both
+ * DENY rather than strip: dropping a flag the model wrote changes the
+ * request while reporting success, which is worse than a visible refusal.
+ * Coverage: npm `-w`/`--workspace`/`--workspaces`/`--workspace-root`/
+ * `--include-workspace-root`; pnpm `--filter`/`-f`/`-w`/`--workspace-root`/
+ * `--filter-prod`/`--include-workspace-root`; cargo `-p`/`--package`; uv
+ * `--package`/`--all-packages`. Yarn's `workspace`/`workspaces` leading
+ * subcommand is not screened here — see the comment on yarn's
+ * `scopingConflict` for why that path is already unreachable by
+ * construction.
+ *
+ * Directory-redirect CONTAINMENT (fix round 2): `target` is a closed enum
+ * precisely so no path can arrive from the model — `normalizeExec` computes
+ * cwd, the model never supplies one. A directory-redirect flag inside argv
+ * (`bun add --cwd /elsewhere x`) hands that choice straight back, ignoring
+ * whatever cwd this table computed. This is the containment property
+ * itself, not a scoping nicety, so it is screened for EVERY manager entry
+ * via `globalDirectoryFlags`/`installDirectoryFlags`, denied on the same
+ * deny-never-strip basis as scoping/scripts-control flags.
+ *
+ * A flag global to the manager (works with any subcommand, not just an
+ * install verb) is screened for BOTH install-shaped and generic calls —
+ * `normalizeExec` checks it before branching on classification kind at all,
+ * because a generic call (`bun x tsc --cwd /elsewhere`) escapes the same
+ * containment otherwise. An install-specific flag is screened only when the
+ * call is already install-shaped, since it has no effect (or no meaning) on
+ * a generic invocation of that manager.
+ *
+ * | manager | global (`globalDirectoryFlags`) | install-only (`installDirectoryFlags`) |
+ * |---|---|---|
+ * | bun | `--cwd` | — |
+ * | yarn | `--cwd`, `-C` (fix round 3 — `-C` is added for symmetry with pnpm; not confirmed as a documented yarn alias, but an over-denial here is the safe direction) | — |
+ * | pnpm | `--dir`, `-C` | — |
+ * | npm | — | — (`--prefix` changes npm's effective directory; already denied by `DENIED_FLAGS` in `exec-guard.ts` regardless of manager — not duplicated here) |
+ * | cargo | `--manifest-path` (accepted by nearly every cargo subcommand, `add`/`fetch` included) | — |
+ * | pip | `--python` (a general pip option, valid before or after the subcommand, that redirects which interpreter/environment gets installed into) | `--target`, `-t` (documented short alias, fix round 3), `--root` (install-destination overrides, meaningful only for `pip install`; `--prefix` is likewise install-scoped but already covered by the same shared `DENIED_FLAGS` entry as npm's, so also not duplicated) |
+ * | uv | `--directory`, `--project` (both are documented as general uv options, accepted ahead of the subcommand, that change what "the project" means for the whole invocation) | — |
+ * | go | `-C` (a general go flag: "change to dir before running the command") | — |
+ *
+ * `uv pip <anything>` (fix round 3, finding 3) is denied at classification
+ * time, not treated as a directory-redirect flag gap — see the comment on
+ * `isNestedPipInvocation` in `package-managers.ts` for why nesting one
+ * manager's semantics inside another's entry was rejected in favor of a
+ * flat denial.
+ */
+import type { NormalizeResult, NoScripts, WorkspaceContext } from "./package-managers-types.ts";
+export interface ManagerEntry {
+    /** Install verbs AND their aliases. A verb outside this list makes the call generic, not denied. */
+    readonly installVerbs: readonly (readonly string[])[];
+    readonly noScripts: (ctx: WorkspaceContext) => NoScripts;
+    /** True when the manager needs the member's manifest NAME rather than its path. Read centrally by `normalizeExec`. */
+    readonly needsPackageName: boolean;
+    /**
+     * Returns the incoming flag/token that would smuggle in a scoping
+     * decision of its own (another workspace member, or "all packages") if
+     * this table spliced its own scoping flag in beside it — or `undefined`
+     * when the argv is clean. Checked before any rewriting.
+     */
+    readonly scopingConflict: (argv: readonly string[]) => string | undefined;
+    /**
+     * Returns the incoming flag that redirects the working directory (or the
+     * install destination/environment) this manager operates on, when that
+     * flag is global to the manager — checked for BOTH install-shaped and
+     * generic calls, since `target` being a closed enum only holds if no
+     * argv-supplied path can override it.
+     */
+    readonly globalDirectoryConflict: (argv: readonly string[]) => string | undefined;
+    /** Same as `globalDirectoryConflict`, but for a flag that only applies to
+     * (or only makes sense for) an install verb — checked only when the call
+     * is already install-shaped. */
+    readonly installDirectoryConflict: (argv: readonly string[]) => string | undefined;
+    readonly packageForm: (argv: readonly string[], ctx: WorkspaceContext) => NormalizeResult;
+    readonly rootForm: (argv: readonly string[], ctx: WorkspaceContext) => NormalizeResult;
+}
+export declare const MANAGER_TABLE: Readonly<Record<string, ManagerEntry>>;