approval-md 0.4.3 → 0.4.6

package/dist/src/core/date-argv.d.ts

@@ -0,0 +1,83 @@
+/**
+ * `date` in its display forms (APRV-508).
+ *
+ * The classifier's `date-read` row asks this file one question of an argv and
+ * the assignments in front of it: is this a `date` that only PRINTS a time,
+ * reading no file to do it?
+ *
+ * `date` has two jobs. One prints a time; the other sets the system clock, and
+ * the setting forms are spelled with the same binary and overlapping flags.
+ * So this reads the argv the way an option parser does and answers `false` for
+ * anything it does not recognise as display-only. `false` is the fail-closed
+ * answer: the classifier row does not match, and the command keeps the
+ * `unclassified` refusal it had before this row existed.
+ *
+ * Two implementations are in scope, and an argv is accepted only where both
+ * read it as a display: GNU coreutils (getopt) and uutils coreutils 0.10, the
+ * `date` the hosted Agent Village boxes run (clap). Where they differ the
+ * stricter reading wins: a required value may not start with `-` (getopt takes
+ * it as the value, clap may take it as the next flag), and long options match
+ * by EXACT name only (getopt and clap both accept a unique prefix, so `--se`
+ * is `--set` to both).
+ *
+ * Accepted, and nothing else:
+ *
+ * - no arguments at all (`date`);
+ * - at most one operand, and it must start with `+` (the output format). Any
+ *   other operand is a clock setting (`MMDDhhmm[[CC]YY][.ss]`) on GNU, BSD and
+ *   uutils alike;
+ * - `-u`, `--utc`, `--universal` (print in UTC);
+ * - `-R`, `--rfc-2822`, `--rfc-email`;
+ * - `-I` alone or with an ATTACHED precision (`-Iseconds`), and `--iso-8601`
+ *   alone or with `=precision`;
+ * - `--rfc-3339=FMT` or `--rfc-3339 FMT`, FMT one of `date`, `seconds`, `ns`;
+ * - `-d STRING`, `-ud STRING`, `--date=STRING`, `--date STRING`: the string is
+ *   parsed and printed, never applied to the clock. A `TZ="…"` inside the
+ *   string names a zone and is held to {@link isZoneValue};
+ * - `--debug`, `--resolution`, `-h`/`--help`, `-V`/`--version`, which print
+ *   diagnostics or text and read nothing;
+ * - the clusters `-uR`, `-Ru` and `-ud`, and no other: a cluster is accepted
+ *   only by its exact spelling.
+ *
+ * Declined, so `unclassified` as before:
+ *
+ * - `-s`/`--set` (sets the clock), in any spelling or cluster;
+ * - `-f`/`--file` (reads a file's lines and echoes the bad ones back; on BSD
+ *   `-f` is an input format that sets the clock without `-j`);
+ * - `-r`/`--reference` in EVERY spelling. It prints a file's modification
+ *   time, which is a read of that file's metadata, and the agents this row
+ *   exists for need the clock rather than a file's mtime. Admitting it would
+ *   put a second spelling of `stat` behind a row whose whole claim is that it
+ *   reads no file, so it stays refused;
+ * - BSD's `-j`/`-v`/`-n`, a bare `--`, every long-option abbreviation, an
+ *   attached short value (`-d@0`, `-d=@0`), and every cluster not listed;
+ * - any word this file cannot read literally: one carrying `$`, a backtick, a
+ *   glob or a brace, since the shell may split or expand it into flags this
+ *   parse never saw. The classifier also declines a segment with a
+ *   substituted word;
+ * - an assignment other than {@link DATE_ENV_NAMES}, and one of those whose
+ *   value could name a file (`TZ=/etc/x`, `TZ=:../x`, `LC_ALL=/tmp/x`): a zone
+ *   or locale value that is a path makes `date` open that file.
+ */
+/** Assignments a display `date` may carry: the zone, and the locale it prints in. */
+export declare const DATE_ENV_NAMES: readonly string[];
+/** Is this a zone value that names no file outside the zone database? */
+export declare function isZoneValue(value: string): boolean;
+/**
+ * May this `NAME=value` word stand in front of a display `date`?
+ *
+ * Only the zone and locale names, and only with a value that cannot name a
+ * file: a zone outside the database or a locale that is a path makes `date`
+ * open whatever the value names.
+ */
+export declare function isDateAssignment(word: string): boolean;
+/**
+ * Is this `date` argv a display form? `args` is the words after the binary,
+ * quotes already removed; `assignments` the `NAME=value` words in front of it.
+ *
+ * A strict allow-grammar: every word must be one of the exact spellings below,
+ * a value in a position one of them opens, or the single `+FORMAT` operand.
+ * Anything else (a cluster not listed, an abbreviation, `--`, an `=` joined
+ * to a short flag) answers `false`.
+ */
+export declare function isDateDisplay(args: readonly string[], assignments?: readonly string[]): boolean;

package/dist/src/core/date-argv.js

@@ -0,0 +1,212 @@
+/**
+ * `date` in its display forms (APRV-508).
+ *
+ * The classifier's `date-read` row asks this file one question of an argv and
+ * the assignments in front of it: is this a `date` that only PRINTS a time,
+ * reading no file to do it?
+ *
+ * `date` has two jobs. One prints a time; the other sets the system clock, and
+ * the setting forms are spelled with the same binary and overlapping flags.
+ * So this reads the argv the way an option parser does and answers `false` for
+ * anything it does not recognise as display-only. `false` is the fail-closed
+ * answer: the classifier row does not match, and the command keeps the
+ * `unclassified` refusal it had before this row existed.
+ *
+ * Two implementations are in scope, and an argv is accepted only where both
+ * read it as a display: GNU coreutils (getopt) and uutils coreutils 0.10, the
+ * `date` the hosted Agent Village boxes run (clap). Where they differ the
+ * stricter reading wins: a required value may not start with `-` (getopt takes
+ * it as the value, clap may take it as the next flag), and long options match
+ * by EXACT name only (getopt and clap both accept a unique prefix, so `--se`
+ * is `--set` to both).
+ *
+ * Accepted, and nothing else:
+ *
+ * - no arguments at all (`date`);
+ * - at most one operand, and it must start with `+` (the output format). Any
+ *   other operand is a clock setting (`MMDDhhmm[[CC]YY][.ss]`) on GNU, BSD and
+ *   uutils alike;
+ * - `-u`, `--utc`, `--universal` (print in UTC);
+ * - `-R`, `--rfc-2822`, `--rfc-email`;
+ * - `-I` alone or with an ATTACHED precision (`-Iseconds`), and `--iso-8601`
+ *   alone or with `=precision`;
+ * - `--rfc-3339=FMT` or `--rfc-3339 FMT`, FMT one of `date`, `seconds`, `ns`;
+ * - `-d STRING`, `-ud STRING`, `--date=STRING`, `--date STRING`: the string is
+ *   parsed and printed, never applied to the clock. A `TZ="…"` inside the
+ *   string names a zone and is held to {@link isZoneValue};
+ * - `--debug`, `--resolution`, `-h`/`--help`, `-V`/`--version`, which print
+ *   diagnostics or text and read nothing;
+ * - the clusters `-uR`, `-Ru` and `-ud`, and no other: a cluster is accepted
+ *   only by its exact spelling.
+ *
+ * Declined, so `unclassified` as before:
+ *
+ * - `-s`/`--set` (sets the clock), in any spelling or cluster;
+ * - `-f`/`--file` (reads a file's lines and echoes the bad ones back; on BSD
+ *   `-f` is an input format that sets the clock without `-j`);
+ * - `-r`/`--reference` in EVERY spelling. It prints a file's modification
+ *   time, which is a read of that file's metadata, and the agents this row
+ *   exists for need the clock rather than a file's mtime. Admitting it would
+ *   put a second spelling of `stat` behind a row whose whole claim is that it
+ *   reads no file, so it stays refused;
+ * - BSD's `-j`/`-v`/`-n`, a bare `--`, every long-option abbreviation, an
+ *   attached short value (`-d@0`, `-d=@0`), and every cluster not listed;
+ * - any word this file cannot read literally: one carrying `$`, a backtick, a
+ *   glob or a brace, since the shell may split or expand it into flags this
+ *   parse never saw. The classifier also declines a segment with a
+ *   substituted word;
+ * - an assignment other than {@link DATE_ENV_NAMES}, and one of those whose
+ *   value could name a file (`TZ=/etc/x`, `TZ=:../x`, `LC_ALL=/tmp/x`): a zone
+ *   or locale value that is a path makes `date` open that file.
+ */
+/** Assignments a display `date` may carry: the zone, and the locale it prints in. */
+export const DATE_ENV_NAMES = ["TZ", "LANG", "LANGUAGE", "LC_ALL", "LC_TIME"];
+/** Characters the shell may expand into more words, or into other words. */
+const UNREADABLE_WORD = /[$`*?[\]{}]/u;
+/** Long options that take no value, by exact spelling. */
+const LONG_BARE = [
+    "--utc",
+    "--universal",
+    "--rfc-2822",
+    "--rfc-email",
+    "--iso-8601",
+    "--debug",
+    "--resolution",
+    "--help",
+    "--version",
+];
+/**
+ * Short words that take no value, by exact spelling. Clusters are admitted
+ * only as listed here: no general cluster parsing, so a letter this file does
+ * not know can never ride inside one.
+ */
+const SHORT_BARE = ["-u", "-R", "-h", "-V", "-I", "-uR", "-Ru"];
+/** The `-I` / `--iso-8601` precisions, attached (`-Iseconds`, `--iso-8601=ns`). */
+const ISO_PRECISIONS = ["date", "hours", "minutes", "seconds", "ns"];
+/** The `--rfc-3339` precisions. */
+const RFC3339_PRECISIONS = ["date", "seconds", "ns"];
+/** Words that take the NEXT word as a date string. */
+const DATE_VALUE_WORDS = ["-d", "-ud", "--date"];
+/**
+ * A tz database name (`Asia/Kolkata`, `Etc/GMT+5`, `UTC`), optionally behind
+ * the POSIX `:`. Every segment is a name: no leading `/`, no `.` anywhere, so
+ * neither an absolute path nor a `..` climb out of the zoneinfo directory.
+ */
+const ZONE_NAME = /^:?[A-Za-z_][A-Za-z0-9_+-]*(?:\/[A-Za-z0-9_+-]+)*$/u;
+/**
+ * A POSIX TZ rule with no transition dates (`IST-5:30`, `EST5EDT`, `<+0530>-5:30`).
+ * A rule never names a file.
+ */
+const POSIX_ZONE = /^(?:[A-Za-z]{3,}|<[A-Za-z0-9+-]{3,}>)[+-]?\d{1,2}(?::\d{2}){0,2}(?:(?:[A-Za-z]{3,}|<[A-Za-z0-9+-]{3,}>)(?:[+-]?\d{1,2}(?::\d{2}){0,2})?)?$/u;
+/** A locale name (`C`, `C.UTF-8`, `en_US.UTF-8`, `en:fr`), never a path. */
+const LOCALE_VALUE = /^[A-Za-z0-9_@.:-]*$/u;
+/** Is this a zone value that names no file outside the zone database? */
+export function isZoneValue(value) {
+    if (value === "")
+        return true;
+    if (value.includes(".."))
+        return false;
+    return ZONE_NAME.test(value) || POSIX_ZONE.test(value);
+}
+/**
+ * May this `NAME=value` word stand in front of a display `date`?
+ *
+ * Only the zone and locale names, and only with a value that cannot name a
+ * file: a zone outside the database or a locale that is a path makes `date`
+ * open whatever the value names.
+ */
+export function isDateAssignment(word) {
+    const equals = word.indexOf("=");
+    if (equals <= 0)
+        return false;
+    const name = word.slice(0, equals);
+    const value = word.slice(equals + 1);
+    if (!DATE_ENV_NAMES.includes(name))
+        return false;
+    if (UNREADABLE_WORD.test(value) || value.includes("~"))
+        return false;
+    if (name === "TZ")
+        return isZoneValue(value);
+    return !value.includes("..") && LOCALE_VALUE.test(value);
+}
+/**
+ * Does a `-d` string carry only zones that name no file?
+ *
+ * GNU (and the parser uutils uses) accept a leading `TZ="Zone"` inside the
+ * date string, and resolve it as the variable would be resolved.
+ */
+function isDateString(value) {
+    // Case-insensitive (refutation S2): GNU's prefix is `TZ=` exactly, but a
+    // parser that folds case would read `tz="/etc/x"` as a zone path too.
+    const embedded = /TZ\s*=\s*(?:"([^"]*)"|'([^']*)'|(\S*))/giu;
+    for (let match = embedded.exec(value); match !== null; match = embedded.exec(value)) {
+        const zone = match[1] ?? match[2] ?? match[3] ?? "";
+        if (!isZoneValue(zone))
+            return false;
+    }
+    return true;
+}
+/** A required value: present, not flag-shaped, and readable as a date string. */
+function isRequiredValue(value) {
+    return value !== undefined && !value.startsWith("-") && isDateString(value);
+}
+/**
+ * Is this `date` argv a display form? `args` is the words after the binary,
+ * quotes already removed; `assignments` the `NAME=value` words in front of it.
+ *
+ * A strict allow-grammar: every word must be one of the exact spellings below,
+ * a value in a position one of them opens, or the single `+FORMAT` operand.
+ * Anything else (a cluster not listed, an abbreviation, `--`, an `=` joined
+ * to a short flag) answers `false`.
+ */
+export function isDateDisplay(args, assignments = []) {
+    if (!assignments.every((word) => isDateAssignment(word)))
+        return false;
+    if (args.some((arg) => UNREADABLE_WORD.test(arg)))
+        return false;
+    const seen = new Set();
+    let operands = 0;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        // A flag word given twice: clap (uutils) refuses it, getopt takes the last.
+        if (arg.startsWith("-")) {
+            if (seen.has(arg))
+                return false;
+            seen.add(arg);
+        }
+        if (LONG_BARE.includes(arg) || SHORT_BARE.includes(arg))
+            continue;
+        if (arg.startsWith("-I") && ISO_PRECISIONS.includes(arg.slice(2)))
+            continue;
+        if (arg.startsWith("--iso-8601=") && ISO_PRECISIONS.includes(arg.slice("--iso-8601=".length)))
+            continue;
+        if (arg.startsWith("--rfc-3339=") && RFC3339_PRECISIONS.includes(arg.slice("--rfc-3339=".length)))
+            continue;
+        if (arg === "--rfc-3339") {
+            index += 1;
+            if (!RFC3339_PRECISIONS.includes(args[index] ?? ""))
+                return false;
+            continue;
+        }
+        if (arg.startsWith("--date=")) {
+            if (!isDateString(arg.slice("--date=".length)))
+                return false;
+            continue;
+        }
+        if (DATE_VALUE_WORDS.includes(arg)) {
+            index += 1;
+            if (!isRequiredValue(args[index]))
+                return false;
+            continue;
+        }
+        // An operand: exactly one, and only an output format. Anything else is a
+        // flag this grammar does not list, or a clock setting.
+        if (!arg.startsWith("+"))
+            return false;
+        operands += 1;
+        if (operands > 1)
+            return false;
+    }
+    return true;
+}
+//# sourceMappingURL=date-argv.js.map

package/dist/src/core/date-argv.js.map

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

package/dist/src/core/exec-code.d.ts

@@ -0,0 +1,77 @@
+/**
+ * The `exec.code` gate: what the attested policy says about opaque agent code
+ * (APRV-510, 0.4.5 candidate).
+ *
+ * `python3 -c`, `node -e` and kin, an interpreter running a file that is not a
+ * skill script, and a Hermes `execute_code` call are all programs whose effect
+ * no classifier reads. Before this module every one of them was refused before
+ * policy (`hook-opaque`, `hook-unclassified`, `hook-hermes-execute-code-unbound`),
+ * and that stays the answer for every policy that does not speak: the gate is
+ * CLOSED unless the operator's policy opens it, key by key.
+ *
+ * Two keys, each opening one thing, and an absent key is the closed answer:
+ *
+ * - `exec.code.custody: attested` opens the class for the shell forms. It is the
+ *   operator's statement that credential custody is in place: opaque code run by
+ *   an agent that can read the tenant's credentials is a way round every gate
+ *   that guards them, so the class may not exist without that statement.
+ * - `exec.code.execute_code: hooked`, beside the first, opens Hermes's
+ *   `execute_code`. It is the operator's statement that a tool call made from
+ *   inside the `execute_code` kernel re-fires the hook, which only a live probe
+ *   can establish (`docs/hermes-hook.md`); without it one `execute_code` call
+ *   would be an unbounded bypass of the adapter.
+ *
+ * Pure: a function of the parsed policy and nothing else. It decides whether a
+ * call may be CLASSIFIED `exec.code`; what the class then resolves to is the
+ * policy's ordinary class resolution (an `exec.code` row, an `exec.*` row, or
+ * `defaults.autonomy`), unchanged.
+ */
+import type { Policy } from "./policy-load.js";
+/** The `exec` policy block (schema/policy.schema.json, APRV-510). */
+export interface ExecBlock {
+    code?: {
+        custody?: "attested" | "unattested";
+        execute_code?: "hooked" | "unhooked";
+    };
+}
+/** The class an opened program is judged under. Mirrors `command-class.ts`. */
+export declare const EXEC_CODE_POLICY_CLASS = "exec.code";
+/** The policy line that opens the class, as a refusal names it. */
+export declare const EXEC_CODE_CUSTODY_KEY = "exec.code.custody: attested";
+/** The policy line that opens Hermes `execute_code`, as a refusal names it. */
+export declare const EXEC_CODE_EXECUTE_KEY = "exec.code.execute_code: hooked";
+/**
+ * Why the gate is closed, which decides the refusal's code and words.
+ *
+ * - `silent`: the policy says nothing about `exec.code` (no `exec` block and no
+ *   `exec.code` class row), or there is no policy. The refusal is today's,
+ *   byte for byte.
+ * - `unattested`: the policy names `exec.code` (an `exec` block, or a class row
+ *   for it) without `custody: attested`. The refusal is
+ *   `hook-exec-code-custody-unattested`, naming the key.
+ * - `window`: an open window is standing. A window suspends the policy's
+ *   answer, and opening this class is a policy statement, so it is not reached
+ *   through one; the refusal is today's.
+ * - `harness`: the adapter binds native bytes this class's payload cannot
+ *   carry (Codex), so the class is not opened there; the refusal is today's.
+ */
+export type ExecCodeClosed = "silent" | "unattested" | "window" | "harness";
+export interface ExecCodeGate {
+    /** May a shell segment be classified `exec.code`? */
+    shell: boolean;
+    /** May a Hermes `execute_code` call be classified `exec.code`? */
+    executeCode: boolean;
+    /** Why `shell` is false; `null` when it is true. */
+    closed: ExecCodeClosed | null;
+}
+/** The gate with everything closed for `reason`. */
+export declare function closedExecCodeGate(reason: ExecCodeClosed): ExecCodeGate;
+/**
+ * Does the policy name `exec.code` anywhere? An `exec` block, or a `classes`
+ * key that is exactly `exec.code`. A family row (`exec.*`) is not a mention:
+ * it was written for `exec.local`, and a policy that predates the class keeps
+ * its refusals byte for byte.
+ */
+export declare function execCodeMentioned(policy: Policy): boolean;
+/** What `policy` opens. `null` (no policy loaded) opens nothing. */
+export declare function execCodeGate(policy: Policy | null): ExecCodeGate;

package/dist/src/core/exec-code.js

@@ -0,0 +1,60 @@
+/**
+ * The `exec.code` gate: what the attested policy says about opaque agent code
+ * (APRV-510, 0.4.5 candidate).
+ *
+ * `python3 -c`, `node -e` and kin, an interpreter running a file that is not a
+ * skill script, and a Hermes `execute_code` call are all programs whose effect
+ * no classifier reads. Before this module every one of them was refused before
+ * policy (`hook-opaque`, `hook-unclassified`, `hook-hermes-execute-code-unbound`),
+ * and that stays the answer for every policy that does not speak: the gate is
+ * CLOSED unless the operator's policy opens it, key by key.
+ *
+ * Two keys, each opening one thing, and an absent key is the closed answer:
+ *
+ * - `exec.code.custody: attested` opens the class for the shell forms. It is the
+ *   operator's statement that credential custody is in place: opaque code run by
+ *   an agent that can read the tenant's credentials is a way round every gate
+ *   that guards them, so the class may not exist without that statement.
+ * - `exec.code.execute_code: hooked`, beside the first, opens Hermes's
+ *   `execute_code`. It is the operator's statement that a tool call made from
+ *   inside the `execute_code` kernel re-fires the hook, which only a live probe
+ *   can establish (`docs/hermes-hook.md`); without it one `execute_code` call
+ *   would be an unbounded bypass of the adapter.
+ *
+ * Pure: a function of the parsed policy and nothing else. It decides whether a
+ * call may be CLASSIFIED `exec.code`; what the class then resolves to is the
+ * policy's ordinary class resolution (an `exec.code` row, an `exec.*` row, or
+ * `defaults.autonomy`), unchanged.
+ */
+/** The class an opened program is judged under. Mirrors `command-class.ts`. */
+export const EXEC_CODE_POLICY_CLASS = "exec.code";
+/** The policy line that opens the class, as a refusal names it. */
+export const EXEC_CODE_CUSTODY_KEY = "exec.code.custody: attested";
+/** The policy line that opens Hermes `execute_code`, as a refusal names it. */
+export const EXEC_CODE_EXECUTE_KEY = "exec.code.execute_code: hooked";
+/** The gate with everything closed for `reason`. */
+export function closedExecCodeGate(reason) {
+    return { shell: false, executeCode: false, closed: reason };
+}
+/**
+ * Does the policy name `exec.code` anywhere? An `exec` block, or a `classes`
+ * key that is exactly `exec.code`. A family row (`exec.*`) is not a mention:
+ * it was written for `exec.local`, and a policy that predates the class keeps
+ * its refusals byte for byte.
+ */
+export function execCodeMentioned(policy) {
+    if (policy.exec !== undefined)
+        return true;
+    return Object.prototype.hasOwnProperty.call(policy.classes ?? {}, EXEC_CODE_POLICY_CLASS);
+}
+/** What `policy` opens. `null` (no policy loaded) opens nothing. */
+export function execCodeGate(policy) {
+    if (policy === null)
+        return closedExecCodeGate("silent");
+    const code = policy.exec?.code;
+    if (code?.custody !== "attested") {
+        return closedExecCodeGate(execCodeMentioned(policy) ? "unattested" : "silent");
+    }
+    return { shell: true, executeCode: code.execute_code === "hooked", closed: null };
+}
+//# sourceMappingURL=exec-code.js.map

package/dist/src/core/exec-code.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec-code.js","sourceRoot":"","sources":["../../../src/core/exec-code.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAYH,+EAA+E;AAC/E,MAAM,CAAC,MAAM,sBAAsB,GAAG,WAAW,CAAC;AAElD,mEAAmE;AACnE,MAAM,CAAC,MAAM,qBAAqB,GAAG,6BAA6B,CAAC;AAEnE,+EAA+E;AAC/E,MAAM,CAAC,MAAM,qBAAqB,GAAG,gCAAgC,CAAC;AA4BtE,oDAAoD;AACpD,MAAM,UAAU,kBAAkB,CAAC,MAAsB;IACvD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AAC9D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAc;IAC9C,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAC3C,OAAO,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,EAAE,EAAE,sBAAsB,CAAC,CAAC;AAC5F,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,YAAY,CAAC,MAAqB;IAChD,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IACzD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC;IAC/B,IAAI,IAAI,EAAE,OAAO,KAAK,UAAU,EAAE,CAAC;QACjC,OAAO,kBAAkB,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IACjF,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,YAAY,KAAK,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AACpF,CAAC"}

package/dist/src/core/git-push-argv.d.ts

@@ -0,0 +1,111 @@
+/**
+ * `git push` read the way git 2.50's option parser reads it (APRV-517).
+ *
+ * The classifier's `git-push` row used to look for flags by exact spelling:
+ * `--delete` and `-d`, `--force` and `-f`. git's parser accepts more than
+ * that, and every extra spelling it accepts did the same thing as the one it
+ * stands for while classifying as a plain push:
+ *
+ * - a short bundle: `-ud`, `-du`, `-fd`, `-dn` carry `-d` (and `-f`);
+ * - a long-option abbreviation by unique prefix: `--de`, `--del`, `--dele`
+ *   and `--delet` are `--delete`, `--m` is `--mirror`, `--pru` is `--prune`;
+ * - a deleting option the exact list never named: `--prune` removes every
+ *   remote ref a wildcard refspec no longer matches;
+ * - the words after a value-taking option (`-o x`, `--repo x`) shift the
+ *   positionals, and a global option in front of `push` (`git --no-pager
+ *   push origin`) shifted them too.
+ *
+ * So this file is the closed rule: it walks the argv exactly as git's
+ * `parse-options.c` does over the option table of `builtin/push.c` in git
+ * 2.50, and reports what the push does rather than which words it contains.
+ * Anything it cannot walk is a refusal, never a guess:
+ *
+ * - `unreadable`: a word the shell may split or expand into words this walk
+ *   never saw (`$`, a backtick, a glob, a brace expansion), a word that came
+ *   out of a command substitution, or an assignment or global option in
+ *   front of `push` that steers which configuration git reads (`GIT_*=`,
+ *   `HOME=`, `XDG_CONFIG_HOME=`, `--git-dir=`, `--work-tree=`,
+ *   `--config-env=`: `remote.origin.push=:refs/heads/main` deletes the trunk
+ *   with no refspec on the command line, and `remote.<name>.mirror` turns a
+ *   plain push into a mirror). Any of these can hold `-d`, `:main` or `+main`;
+ * - `unparseable`: an option git does not know, an ambiguous abbreviation, a
+ *   value where none is taken, a missing value, or a global option in front
+ *   of `push` this file does not know. git refuses all of these itself, so
+ *   refusing them costs nothing, and a newer git that grew an option this
+ *   table lacks is refused rather than read as a plain push;
+ * - `runs-program`: `--receive-pack` / `--exec` name the program git starts
+ *   for the far side, which for a local or `file://` remote runs on this
+ *   machine, and `git --exec-path=` picks where git finds its helpers. What it runs is a command line this classifier is not reading,
+ *   the reason `find -exec` is opaque (APRV-283).
+ *
+ * Negations (`--no-delete`) never clear a flag an earlier word set: a push
+ * that both deletes and un-deletes is read as deleting, which only ever picks
+ * the stricter class for a spelling nobody writes.
+ *
+ * The walk is checked against the real binary: tests/git-push-delete-spellings
+ * runs every deleting spelling against a bare local remote and asserts the ref
+ * is gone, and the generated differential there runs the corpus through git
+ * and asserts every deletion and every forced update it observed was
+ * classified at least that strictly.
+ */
+/** What an option does to the push, for the options whose effect matters. */
+type PushEffect = "force" | "mirror" | "remove" | "prune" | "tags" | "all" | "submodules" | "program" | "help";
+interface PushOption {
+    /** The long name as `builtin/push.c` spells it (`no-verify` keeps its `no-`). */
+    long: string;
+    short?: string;
+    /** `required`: the next word when not `=`-joined. `optional`: `=`-joined only. */
+    value: "none" | "required" | "optional";
+    /** `PARSE_OPT_NONEG`: no `--no-` form. */
+    noneg?: boolean;
+    /** `OPT_ALIAS`: an abbreviation matching this and its target is not ambiguous. */
+    aliasOf?: string;
+    effect?: PushEffect;
+}
+/**
+ * `git push -h` on git 2.50, in `builtin/push.c` order. Order matters only for
+ * which candidate an ambiguity error names, never for which option matches.
+ */
+export declare const GIT_PUSH_OPTIONS: readonly PushOption[];
+/** Can the shell turn this word into a different word, or into several? */
+export declare function isUnreadablePushWord(word: string): boolean;
+/** What a `git push` argv does, as far as its class is concerned. */
+export interface GitPushReading {
+    /** `--force`, `-f`, `--force-with-lease`, `--force-if-includes`, `--mirror`. */
+    force: boolean;
+    /** `--delete` / `-d`: every refspec is a ref being removed. */
+    remove: boolean;
+    /** `--prune`: removes the remote refs a refspec pattern no longer matches. */
+    prune: boolean;
+    /** `--tags` / `--follow-tags`. */
+    tags: boolean;
+    /** `--all`, `--branches`, `--mirror`, or a submodule push: the trunk among them. */
+    all: boolean;
+    /** Non-option words: the repository, then the refspecs. */
+    positionals: string[];
+}
+export type GitPushParse = {
+    ok: true;
+    reading: GitPushReading;
+} | {
+    ok: false;
+    kind: "unreadable" | "unparseable" | "runs-program";
+    detail: string;
+};
+/**
+ * Split the words after `git` at the `push` subcommand: the global options in
+ * front of it, and the push's own argv after it.
+ */
+export declare function splitGitPush(gitArgs: readonly string[]): {
+    globals: string[];
+    words: string[];
+} | null;
+/**
+ * Walk a `git push` argv (the words after `push`) the way git does.
+ *
+ * `assignments` are the `NAME=value` words in front of `git`, `substituted`
+ * says whether any word came out of a command substitution, and `globals` are
+ * the git options in front of `push` ({@link splitGitPush}).
+ */
+export declare function parseGitPushArgv(words: readonly string[], assignments?: readonly string[], substituted?: boolean, globals?: readonly string[]): GitPushParse;
+export {};