@jawache/flow 0.1.0

package/dist/types/packs/docs.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Two documentation audiences, one folder, nothing replicated.
+ *
+ * Every repo documents for exactly two readers who want opposite things: the end user wants the
+ * least possible cognitive load, and the agent wants almost nothing in context. So `docs/` has
+ * exactly two doors and everything inside follows its door's rules.
+ *
+ * @setup A `docs/` folder holding exactly `user/` and `agent/`, each with its own index —
+ * `docs/user/index.html` for people and `docs/agent/README.md` as a list of pointers. The two
+ * guardrails below refuse anything else at the top of the folder, so a repo with a different shape
+ * either moves its pages or does not bind this pack.
+ */
+export interface Doors {
+    /**
+     * The documentation folder, as a path from the repo root. Defaults to `docs`.
+     *
+     * Both guardrails and both breadcrumbs are scoped to it, so a repo whose pages live in
+     * `documentation/` names that here and keeps every rule.
+     */
+    readonly root?: string;
+    /**
+     * Filenames allowed to sit LOOSE at the top of that folder, beside the two doors. Defaults to
+     * none — every file belongs behind `user/` or `agent/`.
+     *
+     * A repo that keeps a `README.md` at the top of its docs folder names it here.
+     */
+    readonly allow?: readonly string[];
+}
+export declare const docs: import("../index.ts").Pack<{
+    /**
+     * Without it, an agent writing under `docs/` has no way to know there are two audiences. User
+     * pages fill with rationale nobody asked for, and agent pages fill with copies of what the code
+     * already says, which go stale silently while still reading as true.
+     */
+    docs: import("../index.ts").BreadcrumbSentence<"text" | "at" | "on" | "description", "touch">;
+    /**
+     * Without it, every user page is written in whatever style that session had, and the docs read
+     * as ten authors. Every source it cites is a public standard — Diátaxis, the Google developer
+     * style guide — so nothing in it is one repo's taste.
+     */
+    userDocsStyle: import("../index.ts").BreadcrumbSentence<"text" | "at" | "on" | "description", "touch">;
+    /**
+     * Without it, `docs/` grows a third folder nobody chose — notes, scratch, drafts — and the two
+     * doors stop being a rule. A folder with no declared audience is how a docs folder becomes a
+     * drawer, and neither audience's rules can be applied to what is in it.
+     */
+    docsShape: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "on" | "description", "write" | "commit">;
+    noMarkdownInUserDocs: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "on" | "description", "write" | "commit">;
+}, Doors | undefined>;

package/dist/types/packs/fcis.d.ts

@@ -0,0 +1,71 @@
+/** Where a repo's pure code lives, and what proves it. Stated by the repo; nothing is defaulted. */
+export interface Convention {
+    /** Every pure FILE — what the rails judge, one glob per shape the repo actually uses. */
+    readonly files: readonly string[];
+    /** Every pure HOME — where the teaching breadcrumb fires, and what the coverage gate watches. */
+    readonly homes: readonly string[];
+    /** The recipe that runs the coverage gate. */
+    readonly coverage: string;
+    /**
+     * ONE PURE FILE, spelled out — a path both `files` and `homes` match.
+     *
+     * `pureCovered` and `newPureFileNeedsReason` narrow inside their CHECK rather than through
+     * `.on(…)`, so their cases have to name a concrete path, and a path the pack invented would fall
+     * outside the repo's own convention and prove nothing. Asked for rather than computed: turning a
+     * caller's glob into a concrete path is arithmetic that does not belong in a pack. A repo knows
+     * one of its own pure files; nothing else does.
+     */
+    readonly example: string;
+    /**
+     * Where a pure file's test sits, as a template over the file's own path. Defaults to
+     * `{dir}/{name}.test.ts`.
+     *
+     * `{dir}` is the file's folder and `{name}` its basename without the extension.
+     * `pureHasTest` demands it exists and `pureExportsTested` reads it, so a repo whose tests live
+     * in `__tests__/` or end in `.spec.ts` states that here rather than turning both rules off.
+     */
+    readonly sibling?: string;
+    /**
+     * What a new pure file may be without owing a reason: a test. Defaults to a glob matching any
+     * file whose name carries `.test.`, at any depth.
+     *
+     * It is `newPureFileNeedsReason`'s exemption, and the `example` path with `.test` before its
+     * extension is what proves it, so the two are read together.
+     */
+    readonly tests?: string;
+}
+/**
+ * Functional Core, Imperative Shell (Bernhardt, "Boundaries", SCNA 2012).
+ *
+ * The one-stop shop for running FCIS in a repo: the model, the rules that hold both sides honest,
+ * the tests that prove the pure side, and the gate on growing it.
+ *
+ * EVERY RULE KEYS OFF ONE IDENTITY CONVENTION — the single way a repo names its pure code — and
+ * the pack DEMANDS it rather than guessing: `Convention` is a mandatory typed parameter, so a repo
+ * that binds this pack without saying where its pure code lives does not compile.
+ *
+ * The import FENCE is not here and cannot be: its layers ARE a repo's architecture. What the pack
+ * ships is the half that is true everywhere (no shell IMPORTS in pure); the fence lives in the
+ * guarded repo's own house pack, where its layers are.
+ *
+ * @setup A pure home the repo can name in globs, one real pure file to point at, and a coverage
+ * recipe — all four parameters. The sibling-test trio reads them, so a repo that cannot say where
+ * its pure code lives cannot bind this pack, by design.
+ * @adopt Expect the coverage gate and the sibling-test rules to fire on the first commit that
+ * touches pure code; both are scoped to the home you named, so the way to narrow them is to narrow
+ * that, never to disable the rule.
+ */
+export declare const fcis: import("../index.ts").Pack<{
+    /**
+     * Without it, the split is a rule with no model behind it: an agent moves a side effect out of a
+     * pure file because a guardrail refused it, learns nothing, and puts the next one back.
+     */
+    fcis: import("../index.ts").BreadcrumbSentence<"text" | "at" | "on" | "description", "touch">;
+    noSideEffectsInPure: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "on" | "ignore" | "description", "write" | "commit">;
+    noShellInPure: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "on" | "ignore" | "description", "write" | "commit">;
+    noThrowInPure: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "on" | "ignore" | "description", "write" | "commit">;
+    pureHasTest: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "on" | "ignore" | "description", "write" | "commit">;
+    pureExportsTested: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "on" | "ignore" | "description", "write" | "commit">;
+    pureCovered: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "description", "commit">;
+    newPureFileNeedsReason: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "description", "command">;
+}, Convention>;

package/dist/types/packs/flow.d.ts

@@ -0,0 +1,50 @@
+/** The one fact this pack cannot know: where this repo keeps the packs its config imports. */
+export interface Home {
+    /**
+     * Every glob covering a pack file `flow.config.ts` imports — one entry per folder a repo keeps
+     * its own packs in, and `[]` in a repo whose rules are all written inline in the config.
+     *
+     * MANDATORY, and empty is a real answer rather than the absence of one. An unstated list is a
+     * list nobody reviews, and here it decides what two rules watch: the nudge when you edit the
+     * guard, and the refusal to delete it. Both name it and neither defaults.
+     *
+     * The engine derives the REPAIR surface from the config's imports directly (`configSurface`),
+     * because it is asked in the broken state and can only read text. This is the same fact asked
+     * at a moment where the config loads, so it is stated once, here, and typed.
+     */
+    readonly packs: readonly string[];
+    /**
+     * The harness's own permission surface — the files an agent's tools and permissions are declared
+     * in. Defaults to Claude Code's: `.claude/settings.json`, `.claude/settings.local.json`,
+     * `.claude/agents/**` and `.claude/skills/**`.
+     *
+     * The edit nudge fires on these as well as on the guard itself, because a tool list and a hook
+     * registration decide what any rule here can ever see. A repo on another harness names its own
+     * files; a repo with none passes `[]`.
+     */
+    readonly hostSurface?: readonly string[];
+}
+/**
+ * flow's own orientation and self-protection, as a pack any repo binds.
+ *
+ * Every guarded repo wants these three: a note saying what is steering you, a nudge when you edit
+ * the steering itself, and a refusal when a command would delete it.
+ *
+ * @setup A `flow.config.ts` at the repo root and a folder for the packs the repo writes itself —
+ * whatever it is called, named here as the `packs` parameter. `flow init` writes both.
+ * @adopt Bind it first, before any other pack: it is the one every guarded repo wants whether or
+ * not it agrees with a single other opinion in this package.
+ */
+export declare const flow: import("../index.ts").Pack<{
+    /**
+     * Without it, an agent works in a guarded repo without knowing it is guarded: a refusal arrives
+     * with no model of where it came from, and the config that produced it is just another file.
+     */
+    orientation: import("../index.ts").BreadcrumbSentence<"text" | "at" | "description", "session">;
+    /**
+     * Without it, the steering layer gets edited like any other file — a rule loosened in passing,
+     * a hook rewritten mid-task — and the guard changes without anybody deciding that it should.
+     */
+    editingTheGuardrails: import("../index.ts").BreadcrumbSentence<"text" | "at" | "on" | "description", "touch">;
+    noDeleteGuardrails: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "on" | "description", "delete">;
+}, Home>;

package/dist/types/packs/git.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The working-tree paths a command line would discard OUTRIGHT, or [] when it is safe to run.
+ *
+ * Deliberately narrow — false negatives beat blocking real work. Every path here is one the
+ * command line itself declares: the `--` pathspec form of checkout, the restore forms that touch
+ * the tree, and `reset --hard` / `clean -f`, whose target is the tree itself.
+ *
+ * The BARE form of checkout — `git checkout <thing>` with no `--` — is not here and cannot be:
+ * whether `<thing>` is a path or a branch is a fact about the repo, not about the string, and this
+ * function is pure. `checkoutBarePaths` below names the candidates and the check asks git.
+ */
+export declare function discardPaths(command: string): string[];
+/**
+ * The words a bare `git checkout` might be aiming at — candidates, not answers.
+ *
+ * `git checkout <path>` discards that path exactly as `git checkout -- <path>` does, and until F3
+ * only the second was refused. The comment above this rule claimed the narrowing was deliberate
+ * ("branch switching passes"), and it was — but it bought that pass by missing the form a person
+ * actually types, which the F3 builder proved on itself by running `git checkout adapter/claude.ts`
+ * over an hour of uncommitted work and watching the guard allow it.
+ *
+ * An invocation carrying `--` is skipped: `discardPaths` already has it, and everything before the
+ * `--` there is a tree-ish by definition.
+ */
+export declare function checkoutBarePaths(command: string): string[];
+/** Of some porcelain lines, the paths with real uncommitted work. */
+export declare function dirtyIn(porcelain: string, includeUntracked: boolean): string[];
+/** Does this header line speak Conventional Commits for the given type set? */
+export declare function isConventional(header: string, types: readonly string[]): boolean;
+/**
+ * A release commit's header — the ONE shape allowed to write a version by hand.
+ *
+ * `release: …` · `release(scope): …` · `release(scope)!: …` · `chore(release): …`, and a `chore`
+ * ONLY with a release-ish scope.
+ *
+ * `chore` REQUIRES its release scope: a bare `chore:` licensing a hand-edited version is the one
+ * thing this rule exists to refuse. A `release(scope)` scope is free text — the word "release" is
+ * not demanded inside the parentheses, so `release(cli): 1.0.0` passes.
+ */
+export declare function isReleaseCommit(message: string): boolean;
+/**
+ * Does this diff change the version VALUE?
+ *
+ * Values on both sides, compared — never "an added line mentions version". Adding a key after the
+ * version rewrites its line (it gains a comma), and a rule that fired on every reformat is a rule
+ * whose message people stop reading.
+ */
+export declare function changesVersion(diff: string): boolean;
+/** What this pack cannot know: which recipe cuts a release, and which file carries the version. */
+export interface Release {
+    /**
+     * The file the release writes the version into. Defaults to `package.json`.
+     *
+     * `noHandEditedVersion` reads whatever this names out of the commit's own diff, so any manifest
+     * works there. `versionIsSemver` reads it as JSON, so a repo whose manifest is TOML or YAML names
+     * the file here and disables that one entry.
+     */
+    readonly versionFile?: string;
+    /**
+     * The type words a commit header may use. Defaults to the eleven of Conventional Commits plus
+     * `release`: feat · fix · docs · style · refactor · perf · test · build · ci · chore · revert ·
+     * release.
+     *
+     * A repo with its own vocabulary states the WHOLE list, never an addition — the refusal prints
+     * what it was given, so a half-list would refuse a type it then failed to mention.
+     */
+    readonly types?: readonly string[];
+    /**
+     * The recipe that computes the version from the history, writes the changelog, stamps the
+     * version file and tags — for example `just release` or `npm run release`.
+     *
+     * MANDATORY rather than defaulted, by the same rule tdd's suite recipe follows: a default is a
+     * rule that names the wrong command in every repo that spells it differently, and it names it in
+     * the one sentence a person reads at the moment they are blocked.
+     */
+    readonly release: string;
+}
+/**
+ * Conventional commit headers, computed versions, and nothing destroys uncommitted work.
+ *
+ * The `node/` sub-group is release discipline spelled in package.json, and package.json only.
+ *
+ * @setup A release path the repo really has, named as the `release` parameter: the recipe that
+ * computes the next version from the commit headers, writes the changelog and tags. The version
+ * rules refuse a hand-edited version in favour of it, so a repo without one has nowhere to send a
+ * blocked reader.
+ * @adopt Bind it in a repo that already writes conventional commits, or expect the header rule to
+ * refuse the first few commits while everyone re-learns the format — that is the rule working, and
+ * `flow status` will show it firing.
+ */
+export declare const git: import("../index.ts").Pack<{
+    /**
+     * Without it, the commit surface is learned by trial and refusal: an agent writes a header the
+     * changelog cannot read, reaches for a force push, or discards uncommitted work with a command
+     * that has no undo.
+     */
+    orientation: import("../index.ts").BreadcrumbSentence<"text" | "at" | "description", "session">;
+    noAiAttributionInCommits: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "description", "command">;
+    noGitDiscard: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "description", "command">;
+    noForcePush: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "description", "command">;
+    conventionalCommitFormat: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "description", "command">;
+    noShellSubstitutionInProse: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "description", "command">;
+    node: {
+        versionIsSemver: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "on" | "description", "write" | "commit">;
+        noHandEditedVersion: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "description", "command">;
+    };
+}, Release>;

package/dist/types/packs/index.d.ts

@@ -0,0 +1,10 @@
+export { docs } from "./docs.ts";
+export { fcis, type Convention } from "./fcis.ts";
+export { flow, type Home } from "./flow.ts";
+export { git, type Release } from "./git.ts";
+export { justfile, type Catalogue } from "./justfile.ts";
+export { node } from "./node.ts";
+export { secrets, type Seam } from "./secrets.ts";
+export { tdd, type Suite } from "./tdd.ts";
+export { typescript, type Gates } from "./typescript.ts";
+export { work, builder, checker, parent } from "./work.ts";

package/dist/types/packs/justfile.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Recipes with no `[doc(…)]` attribute, as `{ name, line }` (1-based).
+ *
+ * `[private]` recipes are SKIPPED, and that is a fix rather than a nicety: `just --list` hides
+ * them, so a private recipe is not in the catalogue and cannot owe the catalogue a description.
+ * The message has claimed this exemption from the day it was written and the walk never honoured
+ * it — a rule that refuses what its own sentence promises to allow is the worst kind, because the
+ * reader does the thing they were told to do and is refused anyway.
+ */
+export declare function undocumentedRecipes(text: string, exempt?: readonly string[]): {
+    name: string;
+    line: number;
+}[];
+export interface Catalogue {
+    /**
+     * Recipe names that owe no `[doc("…")]`. Usually empty, and MANDATORY so that it is empty on
+     * the record rather than by default — an exemption list nobody stated is one nobody reviews.
+     *
+     * A parameter rather than an override, because `exempt` is the CHECK's option and an override
+     * speaks only the sentence keys (at · for · on · ignore · message · disabled).
+     *
+     * `[private]` recipes need no entry — `just --list` hides them, so the check skips them.
+     */
+    readonly exempt: readonly string[];
+    /** The folder holding the code behind the recipes. Defaults to `tools`. */
+    readonly tools?: string;
+    /**
+     * Commands this repo has a recipe for, as a map from the command's pattern to the recipe that
+     * replaces it — `{ "npm run build": "just build" }`.
+     *
+     * OPTIONAL, and with no map there is no entry at all: which raw command a repo has wrapped is a
+     * fact only that repo has, and a rule with an empty list would be one more armed entry matching
+     * nothing. The patterns are regular expressions over the command line, so `npx vitest\\b` is a
+     * pattern and `npx vitest` is one too.
+     *
+     * The catalogue's whole promise is that the recipe is the thing to reach for; a breadcrumb says
+     * so once a session, and this refuses the raw command by name for the ones that matter.
+     */
+    readonly recipes?: Readonly<Record<string, string>>;
+}
+/**
+ * The justfile is the repo's TOOL CATALOGUE.
+ *
+ * The frame: the justfile plays the role MCP tools play elsewhere — the discovery surface an agent
+ * can reach for with confidence. `just --list` is the manifest and each `[doc]` string is a tool
+ * description. Every entry here is the same arrow pointing at it: the orientation says look here
+ * first, `node/noPackageScripts` closes the decoy surface agents habitually read, and `justfileDocs`
+ * keeps the manifest readable.
+ *
+ * @install `just` itself — `brew install just`, or see https://just.systems. Every rule here reads
+ * a `justfile` at the repo root and none of them shells out, so nothing else is needed.
+ * @setup A `justfile` at the root whose every non-private recipe carries a `[doc("…")]`, and a
+ * `package.json` whose `scripts` block holds nothing but `//`-prefixed comment keys. A repo with
+ * live npm scripts moves them into recipes first, or does not bind this pack.
+ */
+export declare const justfile: import("../index.ts").Pack<{
+    useTheRecipe?: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "description", "command">;
+    /**
+     * Without it, an agent discovers commands from package.json, from memory, or from a README that
+     * has drifted — and reaches for a tool this repo does not have, or hand-runs the chain a recipe
+     * already spells correctly.
+     */
+    orientation: import("../index.ts").BreadcrumbSentence<"text" | "at" | "description", "session">;
+    /**
+     * Without it, everything in the tools folder is treated the same way: one-shots get promoted
+     * into the catalogue until `just --list` is noise, or a genuinely repeatable tool is left with
+     * no recipe pointing at it and nobody finds it again.
+     */
+    toolsHome: import("../index.ts").BreadcrumbSentence<"text" | "at" | "on" | "description", "touch">;
+    node: {
+        /**
+         * Without it, package.json grows a second command surface — the one an agent reads FIRST, out
+         * of habit — and the two drift until the catalogue is no longer the truth about this repo.
+         */
+        noPackageScripts: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "on" | "description", "write" | "commit">;
+    };
+    /**
+     * Without it, `just --list` falls back to the last comment line above a recipe, which for a
+     * multi-line comment block is a mid-sentence fragment — a help screen assembled by accident, and
+     * a tool nobody can choose from its description.
+     */
+    justfileDocs: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "on" | "description", "write" | "commit">;
+}, Catalogue>;

package/dist/types/packs/node.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The dependency names whose entry differs between two package.json texts.
+ *
+ * Unparseable JSON on either side names every dependency both sides mention: a file being reshaped
+ * into something else is a change we cannot rule out. An empty string means the file did not exist
+ * on that side.
+ */
+export declare function movedDependencies(beforeText: string, afterText: string): string[];
+/**
+ * package.json discipline: reach for a maintained package, say why, pin it, move the lockfile with
+ * it.
+ *
+ * The dependencies breadcrumb's POLARITY is deliberate. It does not read as "adding a dependency is
+ * a risk"; it reads as "check whether it is already solved" — because the code we hand-roll to
+ * avoid a package has no users, no reviewers and no fixes coming, which is the larger risk most of
+ * the time.
+ *
+ * @setup A lockfile the repo commits — `package-lock.json`, `pnpm-lock.yaml`, `bun.lock`,
+ * `bun.lockb` or `yarn.lock`; `lockfileInStep` recognises all five and asks for whichever one the
+ * repo already has.
+ */
+export declare const node: import("../index.ts").Pack<{
+    /**
+     * Without it, the reflex is to hand-roll rather than to look, and a repo accumulates private
+     * versions of solved problems — code with no users, no reviewers and no fixes coming.
+     */
+    dependencies: import("../index.ts").BreadcrumbSentence<"text" | "at" | "on" | "description", "touch">;
+    /**
+     * Without it, a dependency arrives with no record of what else was considered, and the next
+     * person to ask "why do we depend on this" has only the package name to go on.
+     */
+    newDependencyNeedsReason: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "description", "command">;
+    /**
+     * Without it, a dependency moves in one commit and the lockfile in another (or never), so a
+     * fresh clone installs something nobody tested and the two files disagree about what this repo
+     * depends on.
+     */
+    lockfileInStep: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "description", "commit">;
+}, undefined>;

package/dist/types/packs/secrets.d.ts

@@ -0,0 +1,117 @@
+/**
+ * What this pack cannot know: how this repo spells the env files it commits, and the two commands
+ * that seal them and run against them.
+ *
+ * The two command names default to dotenvx's own, which is the honest floor — a repo that has
+ * wrapped them in recipes (`just dx`, `just env-encrypt`) hands those over instead, and every
+ * sentence a stuck reader meets then names a command that repo really has.
+ */
+export interface Seam {
+    /**
+     * The value prefixes that stay plaintext in a committed env file. Defaults to `["PUBLIC_"]`.
+     *
+     * A public value is one a bundler inlines at build time, so sealing it would break the build for
+     * nothing. `DOTENV_PUBLIC_KEY` is always allowed beside these — it is dotenvx's own header, not a
+     * repo's choice.
+     */
+    readonly publicPrefixes?: readonly string[];
+    /**
+     * The files that must never be committed. Defaults to `[".env.keys", ".env.*.local",
+     * ".dev.vars"]`.
+     *
+     * These are also what `envEncrypted` ignores: a file nobody commits cannot carry a committed
+     * plaintext value, and the two lists being one is what stops them drifting apart.
+     */
+    readonly localFiles?: readonly string[];
+    /** The committed env files, as a glob. Defaults to `.env*`. */
+    readonly envFiles?: string;
+    /**
+     * Extra credential shapes to scan staged content for, added to the six this pack ships (Stripe
+     * live keys, AWS access keys, private key headers, GitHub and Slack tokens). Defaults to none.
+     *
+     * One regular expression per shape. A vendor whose token this pack has never heard of is a fact
+     * only the repo has.
+     */
+    readonly extraSecretShapes?: readonly string[];
+    /**
+     * The repo's wrapper around dotenvx's runner, called as `<dx> <env> <cmd>` — it decrypts and
+     * injects, and every env-dependent command goes through it. Defaults to dotenvx itself, spelled
+     * `dotenvx run -f .env.<env> --`, which takes the env file rather than an environment name.
+     *
+     * A wrapper is worth having and this pack cannot guess its name: `just dx` is one fleet's
+     * spelling, and written in here it would send every reader of a refusal to a command their repo
+     * does not have, in the one sentence they read at the moment they are stuck.
+     */
+    readonly dx?: string;
+    /**
+     * Seals every env file in place, leaving the public prefixes plaintext. Defaults to dotenvx's
+     * own `dotenvx encrypt`, excluding the prefixes above by name.
+     */
+    readonly encrypt?: string;
+}
+/**
+ * Env files committed encrypted, decrypted through one seam, and the local-only files kept out of
+ * git.
+ *
+ * The orientation is at SESSION, and that is the whole design. Models arrive with a trained
+ * aversion to env files — usually correct, and reinforced by permission denials — which is exactly
+ * wrong for the dotenvx model, where the committed files are encrypted and reading them is the
+ * expected way to work. A touch breadcrumb cannot fix that: the sessions where an agent silently
+ * avoids env work are the sessions it never fires in. So it is said up front, every time.
+ *
+ * Three tiers, and every value lives in exactly one: committed-and-encrypted (`.env*`), local
+ * ephemera that must never be committed (`.env.keys`, `.dev.vars`, `.env.*.local`), and runtime
+ * secrets set per environment on the platform.
+ *
+ * @install dotenvx — https://dotenvx.com. It is what encrypts the committed files and what runs a
+ * command with them decrypted, and with nothing else in place every sentence below names it
+ * directly. The two command parameters are for a repo that has wrapped it in recipes of its own.
+ * @setup `.env.keys`, `.dev.vars` and `.env.*.local` in `.gitignore` — the rules below refuse them
+ * in a commit, and an ignore entry is what stops anyone reaching that refusal.
+ *
+ * Nothing else is required: unbound, the sentences name dotenvx itself. THIS PACK SHIPS NO FILE
+ * and nothing is copied into a repo. What a repo gains by wrapping the tool is one place to say
+ * which env file each environment means — REFERENCE below, not a file to match: it is a seam that
+ * works as written, to copy and then spell your own way. The environments are the repo's own fact,
+ * and so is the file list the sealing loop walks.
+ *
+ * ```just
+ * [doc("Run any command with this environment's secrets injected — the ONE env seam. Usage: just dx dev npm run build")]
+ * dx env +cmd:
+ *     dotenvx run {{ if env == "prod" { "-f .env.production -f .env" } else { "-f .env.development.local -f .env" } }} -- {{cmd}}
+ *
+ * [doc("Seal every env file in place — everything encrypted except PUBLIC_* (bundlers inline those at build).")]
+ * env-encrypt:
+ *     #!/usr/bin/env bash
+ *     set -euo pipefail
+ *     for f in .env .env.development.local .env.production; do
+ *       if [ -f "$f" ]; then dotenvx encrypt -f "$f" -ek 'PUBLIC_*'; fi
+ *     done
+ *
+ * [doc("List the variable NAMES in an env file — no values, nothing decrypted. Usage: just env-names .env")]
+ * env-names file=".env":
+ *     grep -oE '^[A-Za-z_][A-Za-z0-9_]*=' {{file}} | tr -d '=' | sort
+ * ```
+ *
+ * Bound, that repo hands over `dx: "just dx"` and `encrypt: "just env-encrypt"`. The third job is
+ * nobody's parameter — no sentence in this pack names it — and it is here because an env seam
+ * wants it.
+ * @adopt A repo with no `.env*` at all binds this for `noSecretsInCommits` alone, which is worth
+ * having in a repo that has never held a secret, and turns `envEncrypted` off BY NAME in its
+ * config with the reason on the record — an entry sitting dead is not the same as one opted out of.
+ */
+export declare const secrets: import("../index.ts").Pack<{
+    /**
+     * Without it, an agent avoids the env files on instinct — the trained reflex is right nearly
+     * everywhere else — and either works around the seam or asks a human for values that are
+     * committed, encrypted, three feet away.
+     */
+    orientation: import("../index.ts").BreadcrumbSentence<"text" | "at" | "description", "session">;
+    /**
+     * Without it, one plaintext value lands in a committed `.env` and the whole model is gone: the
+     * files are committed on the promise that everything in them is sealed.
+     */
+    envEncrypted: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "on" | "ignore" | "description", "write" | "commit">;
+    noKeysFileInCommits: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "on" | "description", "commit">;
+    noSecretsInCommits: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "on" | "ignore" | "description", "commit">;
+}, Seam | undefined>;

package/dist/types/packs/tdd.d.ts

@@ -0,0 +1,52 @@
+/** What this pack cannot know: the suite recipe, and how this repo spells a test file. */
+export interface Suite {
+    /**
+     * The recipe that runs the deterministic suite — for example `just test-commit` or `npm test`.
+     *
+     * MANDATORY rather than defaulted: which command is the gate is a repo's fact, and a default is
+     * a rule that runs the wrong suite in every repo whose gate has another name.
+     */
+    readonly run: string;
+    /**
+     * Every spelling of a test file. Defaults to the seven this fleet uses — `.test.` and `.spec.`
+     * with `.ts`, `.tsx`, `.js` and `.mjs`.
+     *
+     * The strategy breadcrumb fires on them and the four `vitestIdioms` rules judge them, so a repo
+     * that keeps its tests in `__tests__/` names that here rather than re-scoping five entries.
+     */
+    readonly tests?: readonly string[];
+}
+/**
+ * Test-first artefacts exist; tests test behaviour, not implementation; the suite gates the commit.
+ *
+ * `commitRunsTests` takes the suite recipe as a mandatory PARAMETER rather than defaulting to
+ * `just test`: which command is the deterministic gate is a repo's fact, and a default is a rule
+ * that runs the wrong suite in every repo whose gate has another name.
+ *
+ * The `vitest/` sub-group holds FRAMEWORK spellings rather than testing principles: a repo on
+ * another runner disables the four of them without losing the artefacts or the gate.
+ *
+ * @install vitest, unless the four `vitestIdioms` entries are disabled — every one of them reads a
+ * vitest spelling.
+ * @setup One recipe that runs the deterministic suite, named as the `run` parameter. It is what
+ * the commit gate runs, so it has to be the whole suite and it has to be green.
+ * @adopt A repo on another runner binds the pack and disables `vitest` and the `vitestIdioms`
+ * group by name, keeping the strategy breadcrumb and the commit gate — that split is why the
+ * framework rules are a sub-group rather than four loose entries.
+ */
+export declare const tdd: import("../index.ts").Pack<{
+    /**
+     * Without it, testing effort goes where it is easiest to write rather than where confidence is
+     * cheapest — a thick unit layer pinned to implementation details, which then refuses every
+     * behaviour-preserving refactor.
+     */
+    testingStrategy: import("../index.ts").BreadcrumbSentence<"text" | "at" | "on" | "description", "touch">;
+    vitest: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "on" | "description", "write" | "commit">;
+    vitestIdioms: {
+        noMockInternal: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "on" | "description", "write" | "commit">;
+        noOnlyInTests: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "on" | "description", "write" | "commit">;
+        noNetworkStubs: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "on" | "description", "write" | "commit">;
+        noEmptyTest: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "on" | "description", "write" | "commit">;
+    };
+    commitRunsTests: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "description", "commit">;
+}, Suite>;