dw-sdlc 0.0.0-stage → 0.2.0

package/dist/agentic-config.d.ts

@@ -0,0 +1,167 @@
+export declare const COMMITTED_FILE = ".ai/agentic.config.json";
+export declare const LOCAL_FILE = ".ai/agentic.config.local.json";
+/** The schema's path inside this package. */
+export declare const SCHEMA_FILE = "config/agentic.config.schema.json";
+export declare const SCHEMA_PATH: string;
+export declare const COMMIT_CONVENTIONS: readonly ["ticket-key", "conventional"];
+export type CommitConvention = (typeof COMMIT_CONVENTIONS)[number];
+export type NodePackageManager = "pnpm" | "npm" | "yarn" | "bun";
+export type ForcePush = "deny" | "ask" | "lease";
+export type CommitOnProtected = "deny" | "allow";
+export type EnvPolicy = "deny" | "git";
+/** Which env files may be read: `deny` list, then `allow` list, then `policy` for the rest. */
+export type EnvFiles = {
+    policy: EnvPolicy;
+    allow: string[];
+    deny: string[];
+};
+export type Guardrails = {
+    forcePush: ForcePush;
+    commitOnProtected: CommitOnProtected;
+    envFiles: EnvFiles;
+    protectedBranches: string[];
+};
+/** `guardrails` as one layer writes it: every key optional, `envFiles` key by key. */
+export type GuardrailsLayer = Partial<Omit<Guardrails, "envFiles">> & {
+    envFiles?: Partial<EnvFiles>;
+};
+/** A repository's own script under `gate.checks.run`, reported as a Check under `name`. */
+export type RunCheck = {
+    name: string;
+    command: string;
+};
+/**
+ * `run`, and under each other key a Check the package ships, as the schema takes it: `true`, `false` or
+ * its options. `src/checks/` reads the setting of each.
+ */
+export type GateChecks = {
+    run: RunCheck[];
+    [check: string]: unknown;
+};
+/** The Gate: its command, the steps run in order, the Checks run after them. */
+export type Gate = {
+    command?: string;
+    steps: string[];
+    checks: GateChecks;
+};
+/** `gate` as one layer writes it: every key optional, `checks` Check by Check. */
+export type GateLayer = {
+    command?: string;
+    steps?: string[];
+    checks?: Partial<GateChecks>;
+};
+/** One layer as written in a file: every key optional, unknown top-level keys tolerated. */
+export type AgenticConfig = {
+    $schema?: string;
+    version?: 1;
+    baseBranch?: string;
+    packageManagers?: {
+        node?: NodePackageManager;
+        ruby?: "bundler";
+    };
+    guardrails?: GuardrailsLayer;
+    commit?: {
+        convention?: CommitConvention;
+        pattern?: string;
+        trailer?: string;
+    };
+    gate?: GateLayer;
+    worktree?: {
+        setup?: string[];
+    };
+};
+/** What the guards see: every layer applied, every key present. */
+export type ResolvedConfig = {
+    version: 1;
+    baseBranch: string;
+    packageManagers: {
+        node?: NodePackageManager;
+        ruby?: "bundler";
+    };
+    guardrails: Guardrails;
+    commit: {
+        convention: CommitConvention;
+        pattern: string;
+        trailer?: string;
+    };
+    gate: Gate;
+    worktree: {
+        setup: string[];
+    };
+};
+/** The layers merged, before `commit.pattern` falls back to the preset its convention names. */
+type Merged = Omit<ResolvedConfig, "commit"> & {
+    commit: {
+        convention: CommitConvention;
+        pattern?: string;
+        trailer?: string;
+    };
+};
+export type Problem = {
+    file: string;
+    path: string;
+    message: string;
+};
+export type LayerState = "absent" | "valid" | "invalid";
+export type Resolution = {
+    config: ResolvedConfig;
+    problems: Problem[];
+    layers: {
+        committed: LayerState;
+        local: LayerState;
+    };
+    /** The checkout each layer was read from: the root, or the main checkout for a worktree lacking it. */
+    sources: {
+        committed: string | undefined;
+        local: string | undefined;
+    };
+};
+/** Strictest value first; the local override may only move towards the front. */
+export declare const STRICTNESS: {
+    readonly forcePush: readonly ["deny", "ask", "lease"];
+    readonly commitOnProtected: readonly ["deny", "allow"];
+    readonly envFiles: readonly ["deny", "git"];
+};
+/** What the guards run on while any layer is invalid. */
+export declare const STRICTEST_GUARDRAILS: Guardrails;
+/** What a repository gets with nothing declared. */
+export declare const DEFAULT_GUARDRAILS: Guardrails;
+/**
+ * Whether an `envFiles` glob selects the file at `relativePath` (to the repository root, or the
+ * basename outside one). `*` and `?` as in a shell pattern, `*` crossing `/`; a leading `**` and a
+ * slash mean at any depth. The same rule `hooks/block-env-access.sh` applies with `[[ == ]]`.
+ */
+export declare function matchesEnvGlob(glob: string, relativePath: string): boolean;
+export declare const COMMIT_PATTERNS: Record<CommitConvention, string>;
+/**
+ * The schema's public `$id`: what a written config points its `$schema` at. Stable across plugin
+ * installs, where `SCHEMA_PATH` moves with every version.
+ */
+export declare function schemaId(): string;
+/** Parses and validates one document; `file` names it in every problem. */
+export declare function validateDocument(file: string, text: string): {
+    value: AgenticConfig;
+} | {
+    problems: Problem[];
+};
+/** The top level of the repository holding `dir`, or undefined outside one. */
+export declare function findRepository(dir: string): string | undefined;
+/** The top level of the repository holding `dir`, or `dir` itself outside one. */
+export declare function repositoryRoot(dir: string): string;
+/**
+ * The main checkout of the linked worktree at `root`, or undefined for a main checkout or outside a
+ * repository: a linked worktree's git dir differs from the common one, which sits in the main checkout.
+ */
+export declare function mainCheckout(root: string): string | undefined;
+/**
+ * The bottom layer: the package manager the lockfile implies, the Gate command the manifest's `check`
+ * script implies, plus the defaults every key falls back to. `commit.pattern` is left to
+ * `resolveConfig`, which fills it from the convention when no layer sets one.
+ */
+export declare function inferConfig(root: string): Merged;
+/**
+ * Local over committed over inferred, for the repository at `root`. A linked worktree reads a layer it
+ * lacks from its main checkout, where a repository that keeps `.ai/` out of git has the only copy.
+ */
+export declare function resolveConfig(root: string): Resolution;
+export {};

package/dist/agentic-config.js

@@ -0,0 +1,305 @@
+// Reads what a repository declares for an agent: the committed config, the machine's local layer over it,
+// and what the repository implies; an invalid layer is dropped whole. The guardrails plugin's
+// `hooks/config.jq` is the same merge for the guards; this file is the reference, and the tests run both.
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { validate } from "./json-schema.js";
+export const COMMITTED_FILE = ".ai/agentic.config.json";
+export const LOCAL_FILE = ".ai/agentic.config.local.json";
+/** The schema's path inside this package. */
+export const SCHEMA_FILE = "config/agentic.config.schema.json";
+export const SCHEMA_PATH = join(import.meta.dirname, "..", SCHEMA_FILE);
+export const COMMIT_CONVENTIONS = ["ticket-key", "conventional"];
+/** Strictest value first; the local override may only move towards the front. */
+export const STRICTNESS = {
+    forcePush: ["deny", "ask", "lease"],
+    commitOnProtected: ["deny", "allow"],
+    envFiles: ["deny", "git"]
+};
+/** What the guards run on while any layer is invalid. */
+export const STRICTEST_GUARDRAILS = {
+    forcePush: "deny",
+    commitOnProtected: "deny",
+    envFiles: { policy: "deny", allow: [], deny: [] },
+    protectedBranches: ["master", "main", "production"]
+};
+/** What a repository gets with nothing declared. */
+export const DEFAULT_GUARDRAILS = {
+    forcePush: "lease",
+    commitOnProtected: "allow",
+    envFiles: { policy: "git", allow: ["**/.env.example", "**/.env.sample", "**/.env.template"], deny: [] },
+    protectedBranches: ["master", "main", "production"]
+};
+function cloneGuardrails(source) {
+    return {
+        forcePush: source.forcePush,
+        commitOnProtected: source.commitOnProtected,
+        envFiles: { policy: source.envFiles.policy, allow: [...source.envFiles.allow], deny: [...source.envFiles.deny] },
+        protectedBranches: [...source.protectedBranches]
+    };
+}
+/**
+ * Whether an `envFiles` glob selects the file at `relativePath` (to the repository root, or the
+ * basename outside one). `*` and `?` as in a shell pattern, `*` crossing `/`; a leading `**` and a
+ * slash mean at any depth. The same rule `hooks/block-env-access.sh` applies with `[[ == ]]`.
+ */
+export function matchesEnvGlob(glob, relativePath) {
+    const anyDepth = glob.startsWith("**/");
+    const pattern = anyDepth ? glob.slice(3) : glob;
+    const source = pattern
+        .split("")
+        .map((char) => {
+        if (char === "*") {
+            return ".*";
+        }
+        if (char === "?") {
+            return ".";
+        }
+        return char.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    })
+        .join("");
+    return new RegExp(`^${anyDepth ? "(.*/)?" : ""}${source}$`).test(relativePath);
+}
+// The preset each convention names. `ticket-key` is a ticket key ahead of a short type list;
+// `conventional` is Conventional Commits. Both are POSIX ERE, because `grep -E` runs them.
+export const COMMIT_PATTERNS = {
+    "ticket-key": "^\\[[A-Z]+-[0-9]+\\] (feat|fix|refactor|docs|chore|test|perf|ci|revert): .+",
+    conventional: "^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\\([^)]+\\))?!?: .+"
+};
+const NODE_LOCKFILES = [
+    ["pnpm-lock.yaml", "pnpm"],
+    ["package-lock.json", "npm"],
+    ["yarn.lock", "yarn"],
+    ["bun.lock", "bun"],
+    ["bun.lockb", "bun"]
+];
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function show(value) {
+    return JSON.stringify(value);
+}
+let schema;
+function loadSchema() {
+    schema ??= JSON.parse(readFileSync(SCHEMA_PATH, "utf8"));
+    return schema;
+}
+/**
+ * The schema's public `$id`: what a written config points its `$schema` at. Stable across plugin
+ * installs, where `SCHEMA_PATH` moves with every version.
+ */
+export function schemaId() {
+    const loaded = loadSchema();
+    if (typeof loaded === "object" && loaded !== null && "$id" in loaded && typeof loaded.$id === "string") {
+        return loaded.$id;
+    }
+    throw new Error(`${SCHEMA_PATH} declares no string $id`);
+}
+/** Parses and validates one document; `file` names it in every problem. */
+export function validateDocument(file, text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        return { problems: [{ file, path: "", message: `not JSON: ${messageOf(error)}` }] };
+    }
+    const problems = validate(loadSchema(), parsed).map(({ path, message }) => ({ file, path, message }));
+    if (problems.length > 0) {
+        return { problems };
+    }
+    // The schema is the runtime twin of `AgenticConfig`: a document it accepts has this shape.
+    return { value: parsed };
+}
+/** `file` from the first of `checkouts` that has it. */
+function readLayer(checkouts, file) {
+    const source = checkouts.find((checkout) => existsSync(join(checkout, file)));
+    if (source === undefined) {
+        return { state: "absent", problems: [] };
+    }
+    const result = validateDocument(file, readFileSync(join(source, file), "utf8"));
+    if ("problems" in result) {
+        return { state: "invalid", problems: result.problems, source };
+    }
+    return { state: "valid", value: result.value, problems: [], source };
+}
+/** The top level of the repository holding `dir`, or undefined outside one. */
+export function findRepository(dir) {
+    const toplevel = spawnSync("git", ["-C", dir, "rev-parse", "--show-toplevel"], { encoding: "utf8" });
+    return toplevel.status === 0 ? toplevel.stdout.trim() : undefined;
+}
+/** The top level of the repository holding `dir`, or `dir` itself outside one. */
+export function repositoryRoot(dir) {
+    return findRepository(dir) ?? dir;
+}
+/**
+ * The main checkout of the linked worktree at `root`, or undefined for a main checkout or outside a
+ * repository: a linked worktree's git dir differs from the common one, which sits in the main checkout.
+ */
+export function mainCheckout(root) {
+    const args = ["-C", root, "rev-parse", "--path-format=absolute", "--git-dir", "--git-common-dir"];
+    const result = spawnSync("git", args, { encoding: "utf8" });
+    if (result.status !== 0) {
+        return undefined;
+    }
+    const [gitDir, commonDir] = result.stdout.trim().split("\n");
+    return gitDir === undefined || commonDir === undefined || gitDir === commonDir ? undefined : dirname(commonDir);
+}
+function inferPackageManagers(root) {
+    const managers = {};
+    const lockfile = NODE_LOCKFILES.find(([file]) => existsSync(join(root, file)));
+    if (lockfile !== undefined) {
+        managers.node = lockfile[1];
+    }
+    return managers;
+}
+/** Whether `package.json` at `root` declares a `check` script; a missing or unreadable manifest has none. */
+function hasCheckScript(root) {
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+    }
+    catch {
+        return false;
+    }
+    if (typeof manifest !== "object" || manifest === null || !("scripts" in manifest)) {
+        return false;
+    }
+    const { scripts } = manifest;
+    return typeof scripts === "object" && scripts !== null && "check" in scripts && typeof scripts.check === "string";
+}
+/** The Gate with nothing declared: `pnpm check` where the manifest has a `check` script, else no command. */
+function inferGate(root) {
+    const gate = { steps: [], checks: { run: [] } };
+    if (hasCheckScript(root)) {
+        gate.command = "pnpm check";
+    }
+    return gate;
+}
+/**
+ * The bottom layer: the package manager the lockfile implies, the Gate command the manifest's `check`
+ * script implies, plus the defaults every key falls back to. `commit.pattern` is left to
+ * `resolveConfig`, which fills it from the convention when no layer sets one.
+ */
+export function inferConfig(root) {
+    return {
+        version: 1,
+        baseBranch: "auto",
+        packageManagers: inferPackageManagers(root),
+        guardrails: cloneGuardrails(DEFAULT_GUARDRAILS),
+        commit: { convention: "conventional" },
+        gate: inferGate(root),
+        worktree: { setup: [] }
+    };
+}
+function applyLayer(base, layer) {
+    return {
+        version: 1,
+        baseBranch: layer.baseBranch ?? base.baseBranch,
+        packageManagers: { ...base.packageManagers, ...layer.packageManagers },
+        guardrails: {
+            ...base.guardrails,
+            ...layer.guardrails,
+            envFiles: { ...base.guardrails.envFiles, ...layer.guardrails?.envFiles }
+        },
+        commit: { ...base.commit, ...layer.commit },
+        gate: { ...base.gate, ...layer.gate, checks: { ...base.gate.checks, ...layer.gate?.checks } },
+        worktree: { setup: layer.worktree?.setup ?? base.worktree.setup }
+    };
+}
+function rank(key, value) {
+    const order = STRICTNESS[key];
+    return order.indexOf(value);
+}
+const LOOSENS = "the local file may tighten guardrails, never loosen them";
+/**
+ * Every guardrail the local layer sets less strictly than what it would override: a lower-ranked
+ * `forcePush`, `commitOnProtected` or `envFiles.policy`, an added `envFiles.allow` entry, a dropped
+ * `envFiles.deny` entry, a dropped protected branch.
+ */
+function loosenings(base, local) {
+    if (local === undefined) {
+        return [];
+    }
+    const problems = [];
+    if (local.forcePush !== undefined && rank("forcePush", local.forcePush) > rank("forcePush", base.forcePush)) {
+        const message = `${show(local.forcePush)} loosens ${show(base.forcePush)}; ${LOOSENS}`;
+        problems.push({ file: LOCAL_FILE, path: "guardrails.forcePush", message });
+    }
+    if (local.commitOnProtected !== undefined &&
+        rank("commitOnProtected", local.commitOnProtected) > rank("commitOnProtected", base.commitOnProtected)) {
+        const message = `${show(local.commitOnProtected)} loosens ${show(base.commitOnProtected)}; ${LOOSENS}`;
+        problems.push({ file: LOCAL_FILE, path: "guardrails.commitOnProtected", message });
+    }
+    const policy = local.envFiles?.policy;
+    if (policy !== undefined && rank("envFiles", policy) > rank("envFiles", base.envFiles.policy)) {
+        const message = `${show(policy)} loosens ${show(base.envFiles.policy)}; ${LOOSENS}`;
+        problems.push({ file: LOCAL_FILE, path: "guardrails.envFiles.policy", message });
+    }
+    if (local.envFiles?.allow !== undefined) {
+        const known = new Set(base.envFiles.allow);
+        const added = local.envFiles.allow.filter((glob) => !known.has(glob));
+        if (added.length > 0) {
+            const message = `adds ${added.map(show).join(", ")}; the local file may drop allowed env files, never add them`;
+            problems.push({ file: LOCAL_FILE, path: "guardrails.envFiles.allow", message });
+        }
+    }
+    if (local.envFiles?.deny !== undefined) {
+        const kept = new Set(local.envFiles.deny);
+        const dropped = base.envFiles.deny.filter((glob) => !kept.has(glob));
+        if (dropped.length > 0) {
+            const message = `drops ${dropped.map(show).join(", ")}; the local file may add denied env files, never drop them`;
+            problems.push({ file: LOCAL_FILE, path: "guardrails.envFiles.deny", message });
+        }
+    }
+    if (local.protectedBranches !== undefined) {
+        const kept = new Set(local.protectedBranches);
+        const dropped = base.protectedBranches.filter((branch) => !kept.has(branch));
+        if (dropped.length > 0) {
+            const message = `drops ${dropped.map(show).join(", ")}; the local file may add protected branches, never remove them`;
+            problems.push({ file: LOCAL_FILE, path: "guardrails.protectedBranches", message });
+        }
+    }
+    return problems;
+}
+/** `commit.pattern` from the convention's preset when no layer set one; a set pattern wins. */
+function finalize(merged) {
+    const pattern = merged.commit.pattern ?? COMMIT_PATTERNS[merged.commit.convention];
+    return { ...merged, commit: { ...merged.commit, pattern } };
+}
+/**
+ * Local over committed over inferred, for the repository at `root`. A linked worktree reads a layer it
+ * lacks from its main checkout, where a repository that keeps `.ai/` out of git has the only copy.
+ */
+export function resolveConfig(root) {
+    const shared = mainCheckout(root);
+    const checkouts = shared === undefined ? [root] : [root, shared];
+    const committed = readLayer(checkouts, COMMITTED_FILE);
+    const local = readLayer(checkouts, LOCAL_FILE);
+    const problems = [...committed.problems, ...local.problems];
+    let localState = local.state;
+    let config = inferConfig(root);
+    if (committed.value !== undefined) {
+        config = applyLayer(config, committed.value);
+    }
+    if (local.value !== undefined) {
+        const loosened = loosenings(config.guardrails, local.value.guardrails);
+        if (loosened.length > 0) {
+            problems.push(...loosened);
+            localState = "invalid";
+        }
+        else {
+            config = applyLayer(config, local.value);
+        }
+    }
+    if (problems.length > 0) {
+        config = { ...config, guardrails: cloneGuardrails(STRICTEST_GUARDRAILS) };
+    }
+    return {
+        config: finalize(config),
+        problems,
+        layers: { committed: committed.state, local: localState },
+        sources: { committed: committed.source, local: local.source }
+    };
+}

package/dist/catalogue.d.ts

@@ -0,0 +1,36 @@
+export type Group = {
+    id: string;
+    name: string;
+};
+export type Primitive = {
+    id: string;
+    name: string;
+    group: string;
+    summary: string;
+    code: string[];
+    docs: string[];
+};
+export type Catalogue = {
+    version: 1;
+    groups: Group[];
+    primitives: Primitive[];
+};
+/** Where a repository keeps its catalogue unless its config says otherwise. */
+export declare const CATALOGUE_FILE = ".ai/primitives.json";
+export type CatalogueRead = {
+    state: "missing";
+} | {
+    state: "invalid";
+    problems: string[];
+} | {
+    state: "valid";
+    catalogue: Catalogue;
+    text: string;
+};
+/** The catalogue at `file` under `root`, or why there is none to read. */
+export declare function readCatalogue(root: string, file: string): CatalogueRead;
+/**
+ * The Primitives whose `code` names `path`, relative to the repository root: of those, the ones whose
+ * entry is nearest the path, so a file wins over the directory holding it. Empty when none names it.
+ */
+export declare function primitivesNaming(catalogue: Catalogue, path: string): Primitive[];

package/dist/catalogue.js

@@ -0,0 +1,74 @@
+// The Primitives catalogue: what a repository exposes to an agent, where the code of each lives and
+// which documents explain it. Read and held to its shape here; the `primitives` Check judges what it
+// says and `dw-sdlc primitives --paths` answers from it.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { validate } from "./json-schema.js";
+/** Where a repository keeps its catalogue unless its config says otherwise. */
+export const CATALOGUE_FILE = ".ai/primitives.json";
+const STRINGS = { type: "array", items: { type: "string", minLength: 1 }, minItems: 1 };
+const NAMED = { type: "string", minLength: 1 };
+const SCHEMA = {
+    type: "object",
+    required: ["version", "groups", "primitives"],
+    properties: {
+        version: { const: 1 },
+        groups: {
+            type: "array",
+            items: {
+                type: "object",
+                required: ["id", "name"],
+                properties: { id: NAMED, name: NAMED },
+                additionalProperties: false
+            }
+        },
+        primitives: {
+            type: "array",
+            items: {
+                type: "object",
+                required: ["id", "name", "group", "summary", "code", "docs"],
+                properties: { id: NAMED, name: NAMED, group: NAMED, summary: NAMED, code: STRINGS, docs: STRINGS },
+                additionalProperties: false
+            }
+        }
+    },
+    additionalProperties: false
+};
+/** The catalogue at `file` under `root`, or why there is none to read. */
+export function readCatalogue(root, file) {
+    const path = join(root, file);
+    if (!existsSync(path)) {
+        return { state: "missing" };
+    }
+    const text = readFileSync(path, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        return { state: "invalid", problems: [`not JSON: ${error instanceof Error ? error.message : String(error)}`] };
+    }
+    const problems = validate(SCHEMA, parsed).map(({ path: at, message }) => (at === "" ? message : `${at}: ${message}`));
+    if (problems.length > 0) {
+        return { state: "invalid", problems };
+    }
+    // The schema above is the runtime twin of `Catalogue`: a document it accepts has this shape.
+    return { state: "valid", catalogue: parsed, text };
+}
+/**
+ * How near the `code` entry `entry`, a file or a directory, names `path`: the length of the entry when
+ * it is the path or a directory above it, -1 when it is neither.
+ */
+function covers(entry, path) {
+    const prefix = entry.replace(/\/+$/, "");
+    return path === prefix || path.startsWith(`${prefix}/`) ? prefix.length : -1;
+}
+/**
+ * The Primitives whose `code` names `path`, relative to the repository root: of those, the ones whose
+ * entry is nearest the path, so a file wins over the directory holding it. Empty when none names it.
+ */
+export function primitivesNaming(catalogue, path) {
+    const nearest = catalogue.primitives.map((primitive) => Math.max(-1, ...primitive.code.map((entry) => covers(entry, path))));
+    const best = Math.max(-1, ...nearest);
+    return best === -1 ? [] : catalogue.primitives.filter((_, index) => nearest[index] === best);
+}

package/dist/checks/agents-map.d.ts

@@ -0,0 +1,7 @@
+import { type Check } from "./check.ts";
+export type AgentsMapOptions = {
+    file: string;
+    maxLines: number;
+    maxBytes: number;
+};
+export declare const agentsMap: Check<AgentsMapOptions>;