dw-sdlc 0.0.0-stage → 0.2.0

package/dist/markdown.js

@@ -0,0 +1,115 @@
+// The parts of a markdown file the Checks read: its ATX headings with the anchors GitHub gives them,
+// the rows of a table under a heading, its links, and its prose with the code masked; and the anchors
+// of a file on disk. A line inside a fenced code block is never any of them.
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+/** A code fence at any indent, so one inside a list item counts. */
+const FENCE = /^[ \t]*(`{3,}|~{3,})/;
+const ATX = /^ {0,3}(#{1,6})[ \t]+(.*?)(?:[ \t]+#+)?[ \t]*$/;
+/** Each line with its 1-based number, `fenced` when a code fence opens, closes or encloses it. */
+function scan(text) {
+    let fence;
+    return text.split("\n").map((line, index) => {
+        const marker = FENCE.exec(line)?.[1];
+        if (fence === undefined && marker !== undefined) {
+            fence = marker;
+            return { text: line, line: index + 1, fenced: true };
+        }
+        if (fence !== undefined && marker !== undefined && marker[0] === fence[0] && marker.length >= fence.length) {
+            fence = undefined;
+            return { text: line, line: index + 1, fenced: true };
+        }
+        return { text: line, line: index + 1, fenced: fence !== undefined };
+    });
+}
+/**
+ * GitHub's anchor for a heading: its text as rendered, lowercased, every character but a letter, a
+ * digit, a space, `-` and `_` dropped, each space a hyphen.
+ */
+function slug(text) {
+    const rendered = text.replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1");
+    return rendered
+        .toLowerCase()
+        .replace(/[^\p{L}\p{M}\p{N}\p{Pc} -]/gu, "")
+        .replaceAll(" ", "-");
+}
+/** Every ATX heading in `text`, a repeated anchor numbered `-1`, `-2` as GitHub numbers it. */
+export function headings(text) {
+    const seen = new Map();
+    return scan(text).flatMap(({ text: line, line: number, fenced }) => {
+        const match = fenced ? null : ATX.exec(line);
+        if (match === null) {
+            return [];
+        }
+        const [, hashes = "", content = ""] = match;
+        const base = slug(content);
+        const count = seen.get(base) ?? 0;
+        seen.set(base, count + 1);
+        return [{ level: hashes.length, text: content, anchor: count === 0 ? base : `${base}-${count}`, line: number }];
+    });
+}
+function cells(line) {
+    return line
+        .trim()
+        .replace(/^\|/, "")
+        .replace(/\|$/, "")
+        .split("|")
+        .map((cell) => cell.trim());
+}
+/**
+ * The body rows of the tables in the section under the heading whose text is `title`, up to the next
+ * heading of its level or above; empty when there is no such heading.
+ */
+export function tableRows(text, title) {
+    const all = headings(text);
+    const start = all.find((heading) => heading.text.toLowerCase() === title.toLowerCase());
+    if (start === undefined) {
+        return [];
+    }
+    const end = all.find((heading) => heading.line > start.line && heading.level <= start.level)?.line ?? Infinity;
+    const rows = scan(text)
+        .filter(({ line, fenced }) => line > start.line && line < end && !fenced)
+        .filter(({ text: line }) => line.trim().startsWith("|"))
+        .map(({ text: line, line: number }) => ({ cells: cells(line), line: number }));
+    // A table's header row is the one above its delimiter row, which holds only dashes, colons and spaces.
+    const isDelimiter = (row) => row !== undefined && row.cells.every((cell) => /^:?-+:?$/.test(cell));
+    return rows.filter((row, index) => !isDelimiter(row) && !isDelimiter(rows[index + 1]));
+}
+/** Every backticked span in `text`, without its backticks. */
+export function codeSpans(text) {
+    return Array.from(text.matchAll(/`([^`]+)`/g), ([, span = ""]) => span);
+}
+/** A code span: a run of backticks, then the text up to the next run of as many. */
+const CODE_SPAN = /(?<!`)(`+)(?!`).*?(?<!`)\1(?!`)/g;
+/** `text` with each fenced line and each code span blanked to spaces, so every offset and line is kept. */
+export function prose(text) {
+    return scan(text)
+        .map(({ text: line, fenced }) => fenced ? " ".repeat(line.length) : line.replace(CODE_SPAN, (span) => " ".repeat(span.length)))
+        .join("\n");
+}
+/** The target of an inline link or image, `<…>` or up to a space or `)`, and of a link definition, `[label]: target`. */
+const INLINE_TARGET = /\]\(\s*(<[^>]*>|[^\s)]+)/g;
+const DEFINITION = /^ {0,3}\[(?!\^)[^\]]+\]:[ \t]*(<[^>]*>|\S+)/;
+/** Every link target in the prose of `text`, its angle brackets dropped, with its 1-based line. */
+export function links(text) {
+    return prose(text)
+        .split("\n")
+        .flatMap((line, index) => {
+        const definition = DEFINITION.exec(line)?.[1];
+        const targets = [
+            ...Array.from(line.matchAll(INLINE_TARGET), ([, target = ""]) => target),
+            ...(definition === undefined ? [] : [definition])
+        ];
+        return targets.map((target) => ({ target: target.replace(/^<(.*)>$/, "$1"), line: index + 1 }));
+    });
+}
+/** The anchors of the headings of `path` under `root`; none when it is not a file. */
+export function anchorsOf(root, path, cache) {
+    let anchors = cache.get(path);
+    if (anchors === undefined) {
+        const full = join(root, path);
+        anchors = new Set(statSync(full).isFile() ? headings(readFileSync(full, "utf8")).map(({ anchor }) => anchor) : []);
+        cache.set(path, anchors);
+    }
+    return anchors;
+}

package/dist/pins.d.ts

@@ -0,0 +1,16 @@
+/** Versions by package name: what package.json pins, or what a catalog lists. */
+export type Pins = Record<string, string>;
+/**
+ * The default catalog in pnpm-workspace.yaml's text: each `name: version` line of its top-level
+ * `catalog:` block, a comment after the key allowed. Without the block, it is empty.
+ */
+export declare function parseCatalog(yaml: string): Pins;
+/**
+ * The pins in a package.json's text, one naming the default catalog replaced by what `catalog` lists
+ * for it; a missing or malformed section pins nothing.
+ */
+export declare function parsePins(json: string, catalog: Pins): Pins;
+/** The pins of the repository at `root`; throws when its package.json is not JSON. */
+export declare function readPins(root: string): Pins;
+/** `ref` with each `{name}` replaced by the exact version `pins` holds for package `name`. */
+export declare function resolveRef(ref: string, pins: () => Pins): string;

package/dist/pins.js

@@ -0,0 +1,82 @@
+// The exact version a repository pins for a package, for a ref that names one: the root package.json's
+// dependencies and devDependencies, a catalog pin read through pnpm-workspace.yaml's default catalog. A
+// ref without `{name}` reads neither file, so a broken manifest fails only the References that name one.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const EXACT_VERSION = /^\d+\.\d+\.\d+(?:-[\w.]+)?$/;
+/** The two ways a pin names the default catalog: by its name, or by pnpm's shorthand. */
+const DEFAULT_CATALOG = new Set(["catalog:", "catalog:default"]);
+/**
+ * The default catalog in pnpm-workspace.yaml's text: each `name: version` line of its top-level
+ * `catalog:` block, a comment after the key allowed. Without the block, it is empty.
+ */
+export function parseCatalog(yaml) {
+    const lines = yaml.split(/\r?\n/);
+    const start = lines.findIndex((line) => /^catalog:\s*(?:#.*)?$/.test(line));
+    const catalog = {};
+    if (start === -1) {
+        return catalog;
+    }
+    for (const line of lines.slice(start + 1)) {
+        if (line.trim() === "" || line.trim().startsWith("#")) {
+            continue;
+        }
+        const entry = /^\s+(["']?)([^"'\s:]+)\1:\s*(["']?)([^"'\s#]+)\3\s*(?:#.*)?$/.exec(line);
+        if (entry === null) {
+            break;
+        }
+        catalog[entry[2] ?? ""] = entry[4] ?? "";
+    }
+    return catalog;
+}
+/**
+ * The pins in a package.json's text, one naming the default catalog replaced by what `catalog` lists
+ * for it; a missing or malformed section pins nothing.
+ */
+export function parsePins(json, catalog) {
+    const manifest = JSON.parse(json);
+    const pins = {};
+    if (typeof manifest !== "object" || manifest === null) {
+        return pins;
+    }
+    for (const key of ["dependencies", "devDependencies"]) {
+        const section = Reflect.get(manifest, key);
+        if (typeof section !== "object" || section === null) {
+            continue;
+        }
+        for (const [name, version] of Object.entries(section)) {
+            if (typeof version === "string") {
+                pins[name] = DEFAULT_CATALOG.has(version) ? (catalog[name] ?? version) : version;
+            }
+        }
+    }
+    return pins;
+}
+/** The pins of the repository at `root`; throws when its package.json is not JSON. */
+export function readPins(root) {
+    const manifest = join(root, "package.json");
+    if (!existsSync(manifest)) {
+        return {};
+    }
+    const workspace = join(root, "pnpm-workspace.yaml");
+    const catalog = existsSync(workspace) ? parseCatalog(readFileSync(workspace, "utf8")) : {};
+    try {
+        return parsePins(readFileSync(manifest, "utf8"), catalog);
+    }
+    catch (error) {
+        throw new Error(`package.json: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+}
+/** `ref` with each `{name}` replaced by the exact version `pins` holds for package `name`. */
+export function resolveRef(ref, pins) {
+    return ref.replaceAll(/\{([^{}]+)\}/g, (_, name) => {
+        const version = pins()[name];
+        if (version === undefined) {
+            throw new Error(`ref ${ref} names ${name}, which package.json does not depend on`);
+        }
+        if (!EXACT_VERSION.test(version)) {
+            throw new Error(`ref ${ref} needs an exact version of ${name}, and its pin is ${version}`);
+        }
+        return version;
+    });
+}

package/dist/references-key.d.ts

@@ -0,0 +1,31 @@
+/** The committed config, the only file the key is read from. */
+export declare const CONFIG = ".ai/agentic.config.json";
+export type Reference = {
+    dir: string;
+    repository: string;
+    ref: string;
+    only: string[];
+    skip: string[];
+    what: string;
+    when: string;
+};
+export type KeyProblem = {
+    path: string;
+    message: string;
+};
+export declare function isObject(value: unknown): value is Record<string, unknown>;
+/** The References `value` declares, or the first problem in it, named by its path under the key. */
+export declare function parseReferences(value: unknown): {
+    references: Reference[];
+} | {
+    problem: KeyProblem;
+};
+/**
+ * The References the committed config at `root` declares, `undefined` without the file or the key,
+ * or the problem that stops the read: the file is not a JSON object, or the key fails the parser.
+ */
+export declare function readReferences(root: string): {
+    references: Reference[] | undefined;
+} | {
+    problem: string;
+};

package/dist/references-key.js

@@ -0,0 +1,149 @@
+// The strict parser of the `references` key, the authority at runtime, and the reader of the committed
+// config that holds it. `config/references.schema.json` documents the same contract, and
+// `test/references-key.test.ts` runs one case list through both. The first problem stops the parse.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/** The committed config, the only file the key is read from. */
+export const CONFIG = ".ai/agentic.config.json";
+const FIELDS = ["dir", "repository", "ref", "only", "skip", "what", "when"];
+const REQUIRED = ["dir", "repository", "ref", "what", "when"];
+const DIR_NAME = /^[A-Za-z0-9_][A-Za-z0-9_.-]*$/;
+// No whitespace and no leading `-`, which git would read as an option.
+const GIT_ARGUMENT = /^[^\s-]\S*$/;
+const INSIDE_CLONE = /^(?!\/)(?!(?:.*\/)?\.\.(?:\/|$)).+$/;
+class KeyError extends Error {
+    path;
+    constructor(path, message) {
+        super(message);
+        this.path = path;
+    }
+}
+function kind(value) {
+    if (value === null) {
+        return "null";
+    }
+    if (Array.isArray(value)) {
+        return "a list";
+    }
+    return typeof value === "object" ? "an object" : `a ${typeof value}`;
+}
+export function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function nonEmpty(value, path) {
+    if (typeof value !== "string") {
+        throw new KeyError(path, `must be a string, not ${kind(value)}`);
+    }
+    if (value === "") {
+        throw new KeyError(path, "must not be empty");
+    }
+    return value;
+}
+function matching(value, path, pattern, rule) {
+    const string = nonEmpty(value, path);
+    if (!pattern.test(string)) {
+        throw new KeyError(path, `${JSON.stringify(string)} must be ${rule}`);
+    }
+    return string;
+}
+/** A list of paths inside the clone, empty when absent. */
+function paths(value, path) {
+    if (value === undefined) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new KeyError(path, `must be a list of paths, not ${kind(value)}`);
+    }
+    return value.map((item, index) => matching(item, `${path}[${index}]`, INSIDE_CLONE, "relative to the clone and stay inside it"));
+}
+/** `only`: absent, or at least one path, so a typo never checks out nothing. */
+function onlyPaths(value, path) {
+    if (Array.isArray(value) && value.length === 0) {
+        throw new KeyError(path, "must name at least one path");
+    }
+    return paths(value, path);
+}
+/** Whether `path` lies below the directory `dir`, a trailing `/` on either aside. */
+function below(path, dir) {
+    return path.replace(/\/+$/, "").startsWith(`${dir.replace(/\/+$/, "")}/`);
+}
+function parseEntry(value, path) {
+    if (!isObject(value)) {
+        throw new KeyError(path, `must be an object, not ${kind(value)}`);
+    }
+    const unknown = Object.keys(value).find((field) => !FIELDS.includes(field));
+    if (unknown !== undefined) {
+        throw new KeyError(path, `unknown field ${JSON.stringify(unknown)}`);
+    }
+    const missing = REQUIRED.find((field) => !Object.hasOwn(value, field));
+    if (missing !== undefined) {
+        throw new KeyError(path, `missing field ${JSON.stringify(missing)}`);
+    }
+    const reference = {
+        dir: matching(value.dir, `${path}.dir`, DIR_NAME, "one directory name: letters, digits, _, . and -, not starting with . or -"),
+        repository: matching(value.repository, `${path}.repository`, GIT_ARGUMENT, "a URL git can fetch, with no whitespace and no leading -"),
+        ref: matching(value.ref, `${path}.ref`, GIT_ARGUMENT, "a branch or a tag, with no whitespace and no leading -"),
+        only: onlyPaths(value.only, `${path}.only`),
+        skip: paths(value.skip, `${path}.skip`),
+        what: nonEmpty(value.what, `${path}.what`),
+        when: nonEmpty(value.when, `${path}.when`)
+    };
+    const { only, skip } = reference;
+    const outside = only.length === 0 ? -1 : skip.findIndex((skipped) => !only.some((kept) => below(skipped, kept)));
+    if (outside !== -1) {
+        throw new KeyError(`${path}.skip[${outside}]`, `${JSON.stringify(skip[outside])} must lie inside one of the only paths`);
+    }
+    return reference;
+}
+/** The References `value` declares, or the first problem in it, named by its path under the key. */
+export function parseReferences(value) {
+    try {
+        if (!Array.isArray(value)) {
+            throw new KeyError("references", `must be a list of entries, not ${kind(value)}`);
+        }
+        const references = [];
+        for (const [index, item] of value.entries()) {
+            const reference = parseEntry(item, `references[${index}]`);
+            const holder = references.findIndex(({ dir }) => dir === reference.dir);
+            if (holder !== -1) {
+                throw new KeyError(`references[${index}].dir`, `${JSON.stringify(reference.dir)} is the dir of references[${holder}] too`);
+            }
+            references.push(reference);
+        }
+        return { references };
+    }
+    catch (error) {
+        if (error instanceof KeyError) {
+            return { problem: { path: error.path, message: error.message } };
+        }
+        throw error;
+    }
+}
+/**
+ * The References the committed config at `root` declares, `undefined` without the file or the key,
+ * or the problem that stops the read: the file is not a JSON object, or the key fails the parser.
+ */
+export function readReferences(root) {
+    const path = join(root, CONFIG);
+    if (!existsSync(path)) {
+        return { references: undefined };
+    }
+    let config;
+    try {
+        config = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        return { problem: `${CONFIG}: not JSON: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    if (!isObject(config)) {
+        return { problem: `${CONFIG}: not a JSON object` };
+    }
+    if (!Object.hasOwn(config, "references")) {
+        return { references: undefined };
+    }
+    const parsed = parseReferences(config.references);
+    if ("problem" in parsed) {
+        return { problem: `${CONFIG}: ${parsed.problem.path}: ${parsed.problem.message}` };
+    }
+    return { references: parsed.references };
+}

package/dist/report.d.ts

@@ -0,0 +1,13 @@
+export type Failure = {
+    file?: string;
+    line?: number;
+    rule: string;
+    message: string;
+    remedy: string;
+};
+/** `file:line: rule: message — remedy`, without the location where the failure has none. */
+export declare function failureLine({ file, line, rule, message, remedy }: Failure): string;
+/** `::error file=…,line=…,title=<rule>::<message> — <remedy>`, an annotation on the file where there is one. */
+export declare function annotation({ file, line, rule, message, remedy }: Failure): string;
+/** The failure as JSON: every key present, null where it has no file or line. */
+export declare function failureJson({ file, line, rule, message, remedy }: Failure): Record<string, unknown>;

package/dist/report.js

@@ -0,0 +1,29 @@
+// A failure of the Gate as every consumer reads it: one line naming the file and line where there is
+// one, the rule, what is wrong and the remedy; the same as a GitHub Actions workflow annotation; the
+// same as JSON.
+/** `file:line: rule: message — remedy`, without the location where the failure has none. */
+export function failureLine({ file, line, rule, message, remedy }) {
+    const where = file === undefined ? "" : `${file}${line === undefined ? "" : `:${line}`}: `;
+    return `${where}${rule}: ${message} — ${remedy}`;
+}
+// The escaping `@actions/core` applies to a workflow command: `%`, CR and LF in the message, and `:` and
+// `,` too in a property.
+function escapeData(text) {
+    return text.replaceAll("%", "%25").replaceAll("\r", "%0D").replaceAll("\n", "%0A");
+}
+function escapeProperty(text) {
+    return escapeData(text).replaceAll(":", "%3A").replaceAll(",", "%2C");
+}
+/** `::error file=…,line=…,title=<rule>::<message> — <remedy>`, an annotation on the file where there is one. */
+export function annotation({ file, line, rule, message, remedy }) {
+    const properties = [
+        ...(file === undefined ? [] : [`file=${escapeProperty(file)}`]),
+        ...(line === undefined ? [] : [`line=${line}`]),
+        `title=${escapeProperty(rule)}`
+    ];
+    return `::error ${properties.join(",")}::${escapeData(`${message} — ${remedy}`)}`;
+}
+/** The failure as JSON: every key present, null where it has no file or line. */
+export function failureJson({ file, line, rule, message, remedy }) {
+    return { file: file ?? null, line: line ?? null, rule, message, remedy };
+}

package/dist/router-block.d.ts

@@ -0,0 +1,13 @@
+import type { Reference } from "./references-key.ts";
+/** The block the key gives: one row per Reference in the key's order, or one line when it has none. */
+export declare function renderBlock(references: Reference[]): string;
+/**
+ * The Router's text with `block` in place of the one between its markers: as it is when the two say
+ * the same rows, the block replaced when they differ, appended when the Router has no markers; or
+ * the problem with a Router that has one marker without the other.
+ */
+export declare function withBlock(router: string, block: string): {
+    text: string;
+} | {
+    problem: string;
+};

package/dist/router-block.js

@@ -0,0 +1,60 @@
+// The Router's block: a table of each Reference's `dir` and `when`, written from the `references` key
+// between two markers. The setup writes it and the Sync checks it; the rest of the Router is the
+// author's. A block is in step when its rows say what the key says, not its bytes, which a formatter pads.
+const START = "<!-- references:start — written from .ai/agentic.config.json by the setup; edit the key -->";
+const END = "<!-- references:end -->";
+const START_LINE = /^<!-- references:start\b.*-->\s*$/;
+const END_LINE = /^<!-- references:end -->\s*$/;
+const NONE = "No Reference is declared yet: `/sdlc-references-add <repository>` adds one.";
+/** The block the key gives: one row per Reference in the key's order, or one line when it has none. */
+export function renderBlock(references) {
+    const body = references.length === 0
+        ? [NONE]
+        : [
+            "| dir | reach for it when |",
+            "| --- | --- |",
+            ...references.map((reference) => `| \`${reference.dir}\` | ${reference.when.replaceAll("|", "\\|")} |`)
+        ];
+    return `${[START, ...body, END].join("\n")}\n`;
+}
+/** A table's delimiter row, dashes of any count. */
+const DELIMITER = /^\|(?:\s*-+\s*\|)+$/;
+/** What `lines` say once a formatter's work is undone: no blank lines, every cell trimmed, a run of dashes three. */
+function normalized(lines) {
+    return lines
+        .map((line) => line.trim())
+        .filter((line) => line !== "")
+        .map((line) => {
+        const cells = line.split("|").map((cell) => cell.trim());
+        return (DELIMITER.test(line) ? cells.map((cell) => cell.replaceAll(/-+/g, "---")) : cells).join("|");
+    })
+        .join("\n");
+}
+/**
+ * The Router's text with `block` in place of the one between its markers: as it is when the two say
+ * the same rows, the block replaced when they differ, appended when the Router has no markers; or
+ * the problem with a Router that has one marker without the other.
+ */
+export function withBlock(router, block) {
+    const lines = router.split("\n");
+    const start = lines.findIndex((line) => START_LINE.test(line));
+    const end = lines.findIndex((line) => END_LINE.test(line));
+    if (start === -1 && end === -1) {
+        const head = router === "" || router.endsWith("\n") ? router : `${router}\n`;
+        return { text: `${head}${head === "" ? "" : "\n"}${block}` };
+    }
+    if (start === -1 || end === -1) {
+        const lone = start === -1
+            ? "references:end marker without a references:start"
+            : "references:start marker without a references:end";
+        return { problem: `has a ${lone}; fix the pair by hand first` };
+    }
+    if (end < start) {
+        return { problem: "has its references:end marker before references:start; fix the pair by hand first" };
+    }
+    const next = block.trimEnd().split("\n");
+    if (normalized(lines.slice(start + 1, end)) === normalized(next.slice(1, -1))) {
+        return { text: router };
+    }
+    return { text: [...lines.slice(0, start), ...next, ...lines.slice(end + 1)].join("\n") };
+}

package/dist/setup-rules.d.ts

@@ -0,0 +1,22 @@
+import { type EnvFiles } from "./agentic-config.ts";
+/** The auto-mode exception that lets a lease push through the classifier's default force-push block. */
+export declare const LEASE_RULE = "Force push with --force-with-lease or --force-if-includes to a branch that is not master, main or production: allowed. The guardrails plugin's hook refuses a bare --force, -f or +refspec and any force to a protected branch, so the lease form is the safe one and needs no prompt.";
+/** The irreversible set for the user file; `git stash clear` also in the rtk form a permission rule sees once rtk rewrites it. */
+export declare const GLOBAL_DENY: string[];
+/**
+ * The rules the setup removes from a repository's deny list. The guard lets a forced delete of a
+ * landed branch through, and a deny rule would refuse it whatever the guard decides.
+ */
+export declare const RETIRED_DENY: string[];
+/**
+ * The env files the guard refuses in this repository, relative to its root: the verdict
+ * `hooks/block-env-access.sh` gives under `envFiles`, one predicate per file git knows — tracked,
+ * untracked or ignored. The tracked, allowed ones stay readable.
+ */
+export declare function refusedEnvFiles(root: string, envFiles: EnvFiles): string[];
+/**
+ * The permissions.deny a repository gets: the git and gh sets twice, then Read and Edit per refused
+ * env file. A rule written here stays until someone removes it, so while a config layer is invalid
+ * the env rules come from the defaults, not from the strictest set the guards run on meanwhile.
+ */
+export declare function repositoryDeny(root: string): string[];

package/dist/setup-rules.js

@@ -0,0 +1,98 @@
+// The permission rules the setup writes: the lease exception and the irreversible set for the user
+// file, and a repository's deny backstop for a machine without jq.
+import { spawnSync } from "node:child_process";
+import { DEFAULT_GUARDRAILS, matchesEnvGlob, resolveConfig } from "./agentic-config.js";
+/** The auto-mode exception that lets a lease push through the classifier's default force-push block. */
+export const LEASE_RULE = "Force push with --force-with-lease or --force-if-includes to a branch that is not master, main or production: allowed. The guardrails plugin's hook refuses a bare --force, -f or +refspec and any force to a protected branch, so the lease form is the safe one and needs no prompt.";
+/** The irreversible set for the user file; `git stash clear` also in the rtk form a permission rule sees once rtk rewrites it. */
+export const GLOBAL_DENY = [
+    "Bash(rm -rf /)",
+    "Bash(rm -rf /*)",
+    "Bash(rm -rf ~)",
+    "Bash(rm -rf ~/)",
+    "Bash(rm -rf $HOME)",
+    "Bash(rm -rf .)",
+    "Bash(rm -rf ..)",
+    "Bash(shred *)",
+    "Bash(find * -delete)",
+    "Bash(git stash clear)",
+    "Bash(rtk git stash clear)"
+];
+// Exact or end-anchored spellings only. A prefix rule such as `git push --force *` would also match
+// `git push --force-with-lease`, the one form the plugin lets through; the hooks cover the rest.
+const GIT_DENY = [
+    "git push --force",
+    "git push -f",
+    "git push * --force",
+    "git push * -f",
+    "git push --delete *",
+    "git push * --delete *",
+    "git reset --hard",
+    "git reset --hard *",
+    "git clean -fd",
+    "git clean -fd *",
+    "git clean -fdx",
+    "git clean -xdf",
+    "git clean -df",
+    "git clean -f -d",
+    "git clean --force",
+    "git checkout .",
+    "git checkout -- .",
+    "git restore .",
+    "git restore -- .",
+    "git branch -f *",
+    "git branch --force *",
+    "git stash clear",
+    "git stash drop",
+    "git stash drop *",
+    "git worktree remove --force *",
+    "git worktree remove -f *"
+];
+// The gh commands the guards refuse. rtk rewrites `gh` as it does `git`, so they take both forms too.
+const GH_DENY = ["gh repo delete", "gh repo delete *"];
+/**
+ * The rules the setup removes from a repository's deny list. The guard lets a forced delete of a
+ * landed branch through, and a deny rule would refuse it whatever the guard decides.
+ */
+export const RETIRED_DENY = ["Bash(git branch -D *)", "Bash(rtk git branch -D *)"];
+const ENV_NAME = /^\.env(\..+)?$|^\.envrc$/;
+function git(root, args) {
+    const result = spawnSync("git", ["-C", root, ...args], { encoding: "utf8" });
+    return result.status === 0 ? result.stdout.trim() : undefined;
+}
+function listedIn(globs, file) {
+    return globs.some((glob) => matchesEnvGlob(glob, file));
+}
+function isEnvName(file) {
+    return ENV_NAME.test(file.slice(file.lastIndexOf("/") + 1));
+}
+function gitFiles(root, ...flags) {
+    const listed = git(root, ["-c", "core.quotePath=false", "ls-files", ...flags, "--exclude-standard"]) ?? "";
+    return listed.split("\n").filter((file) => file !== "");
+}
+/**
+ * The env files the guard refuses in this repository, relative to its root: the verdict
+ * `hooks/block-env-access.sh` gives under `envFiles`, one predicate per file git knows — tracked,
+ * untracked or ignored. The tracked, allowed ones stay readable.
+ */
+export function refusedEnvFiles(root, envFiles) {
+    const tracked = new Set(gitFiles(root, "-c"));
+    const known = new Set([...tracked, ...gitFiles(root, "-o"), ...gitFiles(root, "-o", "-i")]);
+    const refused = (file) => listedIn(envFiles.deny, file) ||
+        (!listedIn(envFiles.allow, file) && (envFiles.policy === "deny" || !tracked.has(file)));
+    return [...known].filter(isEnvName).filter(refused).toSorted();
+}
+/**
+ * The permissions.deny a repository gets: the git and gh sets twice, then Read and Edit per refused
+ * env file. A rule written here stays until someone removes it, so while a config layer is invalid
+ * the env rules come from the defaults, not from the strictest set the guards run on meanwhile.
+ */
+export function repositoryDeny(root) {
+    const rules = [...GIT_DENY, ...GH_DENY].flatMap((command) => [`Bash(${command})`, `Bash(rtk ${command})`]);
+    const resolved = resolveConfig(root);
+    const envFiles = resolved.problems.length === 0 ? resolved.config.guardrails.envFiles : DEFAULT_GUARDRAILS.envFiles;
+    for (const file of refusedEnvFiles(root, envFiles)) {
+        rules.push(`Read(./${file})`, `Edit(./${file})`);
+    }
+    return rules;
+}