@nathapp/nax-agent 0.87.0 → 0.88.0-canary.1

package/dist/tools/nax-revert.js

@@ -0,0 +1,233 @@
+/**
+ * Reverts of nax's run state (`.nax/`) through git, for the Bash guard
+ * (#2490, #2493).
+ *
+ * Three ways a revert reaches `.nax/`:
+ * 1. an operand that names a `.nax` path (`git checkout -- .nax/x`);
+ * 2. a WHOLE-TREE pathspec (`git checkout .`, `git restore --source=HEAD~1 .`,
+ *    `:/`, `*`, the root directory itself, a pathspec made only of exclusions),
+ *    unless a full `.nax` exclusion follows `--`;
+ * 3. `git reset --hard`, which has no pathspec form at all.
+ *
+ * For `git checkout` an operand is a PATH only after `--`, when it exists on
+ * disk relative to a frame, or when it resolves into `.nax` from the root; so
+ * `git checkout feature/.nax` (a branch whose name has a `.nax` segment) is
+ * not a revert. `git restore` has no branch operand, so all its operands are paths.
+ */
+import { existsSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import { NAX_OWNED_RUN_STATE_EXPLANATION } from "./denial-redirect.js";
+import { findNaxDirs } from "./nax-dirs.js";
+/**
+ * The pathspec that covers EVERY `.nax` directory AND the files inside them, named in advice texts. Real git:
+ * the glob must end in `/**` (the bare `.nax` glob matches only the directory entry) and be anchored at the
+ * top (a relative glob is taken from the working directory).
+ */
+export const COVERING_EXCLUSION = "':(top,exclude,glob)**/.nax/**'";
+/** `:(a,b)body` split on commas; git does not abbreviate long magic names. */
+function parseMagic(spec) {
+    const match = /^:\(([^)]*)\)(.*)$/s.exec(spec);
+    return match === null ? undefined : { elements: match[1].split(","), body: match[2] };
+}
+/**
+ * The path an exclusion pathspec excludes, or undefined when `spec` is not one: `:!X`, `:^X`, or a long form
+ * with an element exactly `exclude` and no `attr:` element (an `attr:` spec is an attribute filter whatever
+ * else it says).
+ */
+export function exclusionBody(spec) {
+    const short = /^:[!^](.*)$/s.exec(spec);
+    if (short !== null)
+        return short[1];
+    const magic = parseMagic(spec);
+    if (magic === undefined || !magic.elements.includes("exclude"))
+        return undefined;
+    return magic.elements.some((e) => e.startsWith("attr")) ? undefined : magic.body;
+}
+export const isExclusionSpec = (spec) => exclusionBody(spec) !== undefined;
+/** Exactly the covering form, magic in any order. */
+export function isCoveringExclusion(spec) {
+    const magic = parseMagic(spec);
+    if (magic === undefined || magic.body !== "**/.nax/**" || magic.elements.length !== 3)
+        return false;
+    return ["top", "exclude", "glob"].every((e) => magic.elements.includes(e));
+}
+/** `--force` -> true for `--f`, `--fo`, `--force`: any option abbreviation of `long` (`--x=v` too). */
+export function isLongPrefix(word, long) {
+    const name = word.split("=")[0];
+    return name.startsWith("--") && name.length >= 3 && long.startsWith(name);
+}
+/** True when `.nax` is a path segment of `path`. */
+export function hasNaxSegment(path) {
+    return path.split(/[\\/]/).includes(".nax");
+}
+/** True when `operand`, resolved from any frame, lands on or under a `.nax` directory. */
+export function operandTouchesNax(operand, ctx) {
+    if (hasNaxSegment(operand))
+        return true;
+    return ctx.frames.some((frame) => {
+        const rel = relative(ctx.root, resolve(frame, operand));
+        return !rel.startsWith("..") && hasNaxSegment(rel);
+    });
+}
+/**
+ * An exclusion that covers EVERY `.nax` the guard knows of. The covering glob always does. The literal forms
+ * (`:!.nax`, `:^.nax/`, `:(exclude).nax`) name only `<root>/.nax` (resolved from EVERY frame, or from the root
+ * under `top`), so they count only while that is the single `.nax` there is.
+ */
+export function isFullNaxExclusion(spec, ctx) {
+    if (isCoveringExclusion(spec))
+        return true;
+    const target = exclusionBody(spec);
+    if (target === undefined)
+        return false;
+    const rootNax = join(ctx.root, ".nax");
+    if (findNaxDirs(ctx).some((dir) => dir !== rootNax))
+        return false;
+    const path = target.replace(/\/(?:\*\*)?$/, "");
+    const top = parseMagic(spec)?.elements.includes("top") === true;
+    return (top ? [ctx.root] : ctx.frames).every((frame) => resolve(frame, path) === rootNax);
+}
+/** Options whose value occupies the next word, per verb. */
+const VALUE_FLAGS = {
+    checkout: new Set(["-b", "-B", "--orphan", "--pathspec-from-file"]),
+    restore: new Set(["-s", "--source", "--pathspec-from-file"]),
+    clean: new Set(["-e", "--exclude"]),
+};
+function splitOperands(verb, args) {
+    const valueFlags = VALUE_FLAGS[verb] ?? new Set();
+    const before = [];
+    const after = [];
+    const flags = [];
+    let hasSeparator = false;
+    for (let i = 0; i < args.length; i += 1) {
+        const word = args[i];
+        if (hasSeparator)
+            after.push(word);
+        else if (word === "--")
+            hasSeparator = true;
+        else if (word.startsWith("-") && word !== "-") {
+            flags.push(word);
+            if (valueFlags.has(word))
+                i += 1;
+        }
+        else
+            before.push(word);
+    }
+    return { before, after, hasSeparator, flags };
+}
+/** A checkout operand that is a path although no `--` marks it: it exists on disk, or lands in `.nax` from the root. */
+function isUnmarkedCheckoutPath(word, ctx) {
+    return ctx.frames.some((frame) => {
+        const target = resolve(frame, word);
+        if (existsSync(target))
+            return true;
+        return relative(ctx.root, target).split(/[\\/]/)[0] === ".nax";
+    });
+}
+function pathOperands(verb, ops, ctx) {
+    if (verb === "restore")
+        return [...ops.before, ...ops.after];
+    return [...ops.after, ...ops.before.filter((word) => isUnmarkedCheckoutPath(word, ctx))];
+}
+/** True when `spec` selects a directory that holds one of the `.nax` directories (or all of them, from the top). */
+function coversNax(spec, ctx, nax) {
+    if (isExclusionSpec(spec))
+        return false;
+    const magic = /^:(?:\(([^)]*)\)|\/)?(.*)$/s.exec(spec);
+    const top = magic !== null && (spec.startsWith(":/") || /(?:^|,)top(?:,|$)/.test(magic[1] ?? ""));
+    const body = (magic === null ? spec : magic[2]).replace(/(?:^|\/)\*{1,2}$/, "");
+    const bases = top ? [ctx.root] : ctx.frames;
+    return bases.some((base) => {
+        const dir = resolve(base, body === "" ? "." : body);
+        return nax.some((candidate) => candidate === dir || candidate.startsWith(`${dir}${sep}`));
+    });
+}
+/** `--staged` and every unambiguous abbreviation git accepts (`--st`), or a short cluster of only `S`. */
+const STAGED_FLAG = /^(?:--st|-S+$)/;
+/** Flags that change nothing about WHAT is restored. */
+const NEUTRAL_RESTORE_FLAG = /^(?:-q|--quiet|--progress|--no-progress)$/;
+/**
+ * `restore --staged` touches only the index. Fails closed: every flag must be `--staged` (or an
+ * abbreviation) or a neutral one, so `--wor` / `-SW` / `--source=...` / an unknown flag all count as
+ * touching the worktree.
+ */
+function touchesIndexOnly(flags) {
+    return (flags.some((f) => STAGED_FLAG.test(f)) && flags.every((f) => STAGED_FLAG.test(f) || NEUTRAL_RESTORE_FLAG.test(f)));
+}
+const treeRefusal = (verb) => `${NAX_OWNED_RUN_STATE_EXPLANATION} A whole-tree \`git ${verb}\` reverts it too. ` +
+    `Exclude it: \`git ${verb} -- . ${COVERING_EXCLUSION}\`.`;
+const RESET_REFUSAL = `${NAX_OWNED_RUN_STATE_EXPLANATION} \`git reset --hard\` (and \`--keep\` / \`--merge\`) resets the whole tree, ` +
+    "`.nax/` included, and has no pathspec form. " +
+    `To discard changes outside it use \`git checkout -- . ${COVERING_EXCLUSION}\`; to unstage use plain \`git reset\`.`;
+const DISCARD_REFUSAL = `${NAX_OWNED_RUN_STATE_EXPLANATION} This command discards or deletes working-tree changes across the whole tree, ` +
+    `\`.nax/\` included. Name the files, or exclude it: \`-- . ${COVERING_EXCLUSION}\` (not available for forced checkouts and switches).`;
+function wholeTreeRefusal(verb, ops, ctx) {
+    const nax = findNaxDirs(ctx);
+    if (nax.length === 0 || (verb === "restore" && touchesIndexOnly(ops.flags)))
+        return undefined;
+    if (ops.hasSeparator && ops.after.some((spec) => isFullNaxExclusion(spec, ctx)))
+        return undefined;
+    const specs = ops.hasSeparator ? ops.after : ops.before;
+    const exclusionOnly = specs.length > 0 && specs.every(isExclusionSpec);
+    return exclusionOnly || specs.some((spec) => coversNax(spec, ctx, nax)) ? treeRefusal(verb) : undefined;
+}
+/** `-f` (alone or in a cluster) or `--force` and its abbreviations. */
+const isForceFlag = (word) => isLongPrefix(word, "--force") || (/^-[A-Za-z]+$/.test(word) && word.includes("f"));
+/** A forced checkout throws local changes away whatever it names. */
+function forcedCheckoutRefusal(verb, ops, ctx) {
+    if (verb !== "checkout" || !ops.flags.some(isForceFlag) || findNaxDirs(ctx).length === 0)
+        return undefined;
+    return ops.hasSeparator && ops.after.some((spec) => isFullNaxExclusion(spec, ctx)) ? undefined : DISCARD_REFUSAL;
+}
+/** The refusal for `git checkout` / `git restore` with these arguments, or undefined. */
+export function revertRefusal(verb, args, ctx) {
+    const ops = splitOperands(verb, args);
+    // An exclusion NAMES `.nax` to keep it out; it is not an operand that touches it.
+    const names = pathOperands(verb, ops, ctx).some((word) => !isExclusionSpec(word) && operandTouchesNax(word, ctx));
+    if (names)
+        return NAX_OWNED_RUN_STATE_EXPLANATION;
+    return wholeTreeRefusal(verb, ops, ctx) ?? forcedCheckoutRefusal(verb, ops, ctx);
+}
+/** `git reset --hard` / `--keep` / `--merge` (any abbreviation git accepts) while a `.nax/` exists. */
+export function resetRefusal(args, ctx) {
+    const dangerous = ["--hard", "--keep", "--merge"];
+    if (!args.some((word) => dangerous.some((long) => isLongPrefix(word, long))))
+        return undefined;
+    return findNaxDirs(ctx).length > 0 ? RESET_REFUSAL : undefined;
+}
+const hasFlag = (flags, long, short) => flags.some((f) => isLongPrefix(f, long) || (/^-[A-Za-z]+$/.test(f) && f.includes(short)));
+/**
+ * `git clean -n` / `--dry-run`. In a short cluster `-e` takes the rest of the cluster as its value
+ * (`-fdenx` is `-f -d -e nx`, a real clean), so only an `n` before any `e` counts.
+ */
+const isCleanDryRun = (flags) => flags.some((f) => isLongPrefix(f, "--dry-run") || (/^-[A-Za-z]+$/.test(f) && f.slice(1).split("e")[0].includes("n")));
+/** Operands (and `--opt=value` values) of a discard verb that name a `.nax` path. */
+function namesNax(ops, ctx) {
+    const values = ops.flags.filter((f) => f.includes("=")).map((f) => f.slice(f.indexOf("=") + 1));
+    return [...ops.before, ...ops.after, ...values].some((word) => !isExclusionSpec(word) && operandTouchesNax(word, ctx));
+}
+/** Does this switch / clean / checkout-index / read-tree invocation wipe the tree (given no covering exclusion)? */
+function wipesTree(verb, ops, ctx) {
+    const f = ops.flags;
+    if (verb === "switch")
+        return f.some(isForceFlag) || f.some((w) => isLongPrefix(w, "--discard-changes"));
+    if (verb === "clean") {
+        const covered = ops.hasSeparator && ops.after.some((spec) => isFullNaxExclusion(spec, ctx));
+        return !covered && !isCleanDryRun(f);
+    }
+    if (verb === "checkout-index")
+        return hasFlag(f, "--all", "a") && hasFlag(f, "--force", "f");
+    if (verb === "read-tree")
+        return f.some((w) => isLongPrefix(w, "--reset")) && hasFlag(f, "--update", "u");
+    return false;
+}
+const NAMED_PATH_VERBS = new Set(["checkout-index", "read-tree", "clean"]);
+/** `switch -f`, `clean`, `checkout-index -a -f`, `read-tree -u --reset`: other ways to wipe the tree. */
+export function discardRefusal(verb, args, ctx) {
+    const ops = splitOperands(verb, args);
+    if (NAMED_PATH_VERBS.has(verb) && namesNax(ops, ctx))
+        return NAX_OWNED_RUN_STATE_EXPLANATION;
+    if (findNaxDirs(ctx).length === 0)
+        return undefined;
+    return wipesTree(verb, ops, ctx) ? DISCARD_REFUSAL : undefined;
+}

package/dist/tools/nax-state-guard.d.ts

@@ -0,0 +1,18 @@
+import { type NaxGuardContext } from "./nax-dirs.ts";
+export type { NaxDirIndex, NaxGuardContext } from "./nax-dirs.ts";
+export { createNaxDirIndex } from "./nax-dirs.ts";
+/**
+ * The refusal for one command segment (its words, `git` possibly behind
+ * wrappers and global options), or undefined. A segment whose git invocation
+ * cannot be located is NOT judged here; see the BACKSTOP in the header. One
+ * that CAN be located but met a global option this reader does not know is
+ * judged by the structured rules and then, with a `.nax/` present, by the BACKSTOP.
+ */
+export declare function naxStateRefusal(segment: readonly string[], ctx: NaxGuardContext): string | undefined;
+/**
+ * `naxStateRefusal` over command TEXT: the raw command string in every Bash
+ * mode, and the string behind `bash -c` / `eval`. Tracks `cd` itself, applies
+ * the structured rules to each segment, and the coarse BACKSTOP (see the
+ * header) to segments whose git invocation it could not read.
+ */
+export declare function naxStateRefusalInText(command: string, ctx: NaxGuardContext): string | undefined;