Browse documentation

@dads-framework/toolbox

On this page

The optional dad command line. It initializes and adopts Dads projects, explains which package owns a path, plans and runs the verification a change earns, and inspects HTTP and code-health rules. Application runtime packages can operate without it.

What Dad does for you

Dad answers the two questions nobody writes down: who owns this file, and what has to pass before it ships. He answers them from the project's own declarations, so the answer does not change with who is asking.

Try it

From a Dads application such as the generated starter, install the Toolbox and ask which package owns the notes route.

Shell
npm install --save-dev @dads-framework/toolbox
npx dad orient domains/notes/server/routes.ts --json

The result contains ok: true and identifies the owner, its verification commands, and the path to its README. Run npx dad doctor explain enmeshment to see the explanation for that diagnostic.

To create a project that already includes the Toolbox, run npm create dads@0.3.0 my-app with Node 24 and Docker Compose running.

Dads is the framework; its packages live under @dads-framework/*, and dad is the executable this package exposes. dad --help (or dad help) prints the command index. Run dad add --help for the generator index.

Run the command from the generated app root. The starter’s dads.project.json declares ownership and verification, and domains/notes/server/routes.ts is the file passed to orient.

Commands

Add --json to the documented command to emit machine-readable output. Without it, most commands print the same object pretty-printed; orient, explain, skills:sync, and verify have their own plain-text form, and only the JSON form is a contract.

Projects

dad init <path> [--existing] [--name <name>] [--dry-run] [--skip-install] [--json]

Applies the same idempotent recipes as create-dads. --existing writes an isolated project under <path>/dads beside an existing application, --dry-run previews the owned files, and --skip-install leaves dependency installation to another tool. Use npm start in the generated app to start Docker, or use npm create dads@0.3.0 to install and start a new app in one step.

Generated projects include Git hooks, a shared CI shell job, and optional GitHub Actions and GitLab CI adapters. Run npm run hooks:install at the Git repository root to activate staged checks and exact-tree push verification. CI setup

dad skills:sync [--json]

Links .cursor/skills, .claude/skills, and .codex/skills at ../.agents/skills so every harness reads one skill library. Each harness is reported as created or correct.

Orientation

The documentation field in JSON points to the owning README or project guide. dad doctor explain includes the relevant diagnostic guide. When the project has no local guide, the command links this package README.

dad orient <path> [--json] — and dad explain <path>, the same command under the name an agent tends to reach for — names the package that owns a path, its responsibility, its skills, and its verification commands. A path no declared package owns is an error, not an empty answer.

dad inspect http-operation "GET /products/:id" --json reads matching route declarations in the project's TypeScript sources. The report includes the source location, method, path, schemas, and whether the route declares access.

Diagnosis

dad doctor [path] [--profile standard|strict] [--issue <id>]* [--json] [--today YYYY-MM-DD]

Reports a repository against the seventeen failure modes DAD.md names and docs/daddy-issues.md defines. The path defaults to the working directory. --issue may be repeated and narrows the report to the issues it names; the ids are the companion's heading anchors, daddy-issues through dad-has-issues-too.

It reads the hand-written files (tracked files when the path is a git repository, otherwise a walk that skips node_modules, build output, and dot-directories, and in both cases skipping *.generated.ts), the package declarations in dads.project.json or, failing that, every workspace package.json, and the output of the commands a signal declares it must run. The local hook runtime signal also reads the ignored .dads/hook-timings.jsonl when the checkout has collected samples. It never reads the clock: a date arrives through --today or the signals that need one report that they were not measured.

Each issue prints one line per signal — the id, the number, the threshold, the profile the threshold came from, and the state — followed by the sentence from DAD.md the rule answers with. A signal is over when a key is above its ceiling, ok when none is, report when this profile gives it no threshold, and not measured when its input was absent or unreadable. A signal that ran and found nothing says 0 seen; only a signal that could not run says it was not measured. Nothing is ever at warn.

The issue's verdict is one of three:

  • present: a signal with a threshold in this profile is over it.
  • partial: no threshold was crossed, and a signal this profile only reports but the strict profile judges saw something. A signal no profile judges is information, not evidence, and moves no verdict.
  • absent: everything else, including an issue no signal reads yet, which the report says in place of its signal lines.

A floor moves no verdict. Its judge is the recorded baseline the gate below reads; in the report it prints its number and says report.

--profile picks the posture. standard is the default; strict may only tighten a threshold, never loosen one, and a line whose threshold the strict profile supplied says strict beside it.

The report exits 0. Pass --online to enable network checks. Unknown options are rejected.

dad doctor [path] --gate|--update|--seed|--report|--file <path>|--base <ref> [--today YYYY-MM-DD] [--reason <text>] [--key <key>] [--json]

The gate is the same measurement, judged against a recorded baseline instead of described. It reads and writes .agents/source-budgets.json: a ceiling is a number that may not grow, a floor is a number that may not shrink, and an entry in the baseline is an exception that may only ever move toward the threshold. Every flag below implies the gate, so --gate is written only when no other mode is. The gate exits 1 on any violation.

--gate judges every signal the active profile gives a number to, and every floor, which is judged against the number it was recorded at. A signal this profile only reports is not gated, because there is nothing to judge it against. A signal that cannot answer — no history to read, no --today for a signal that counts days — says so as a warning, fails nothing, and leaves its recorded entries alone.

--update applies every downward move and writes the baseline: it lowers a mark to the number measured, deletes an entry whose key came back under the threshold, and raises a floor. It never adds a ceiling entry and never raises a mark, because a new offender is a split rather than a recording.

--seed --today YYYY-MM-DD [--reason <text>] [--key <key>] records an exception for a key that is over its ceiling and not yet listed, with the reason it was given and the date it was given. It only ever adds: an entry the baseline already holds is left exactly as it is, so seeding twice cannot loosen anything. --key narrows it to one key, which is how an exception gets a reason of its own rather than one shared with every other key seeded that day.

--report lists every key that is listed or over its threshold, largest first, with its mark; --json adds the same rows as an inventory array.

--file <path> judges a repository-relative path, including newly created files. Repeat the option to check several paths in one run. File checks leave repository-wide floors, Git history, and network checks to the full gate.

--base <ref> compares this baseline against the one at a ref and fails on every direction of loosening — a mark that rose, a floor that fell or was removed, an entry that lost its reason, an ESLint suppressions file that grew. An entry the ref does not carry is a new exception: it is listed and it does not fail, because a reviewer is the right gate for a new exception.

A floor may fall in one case. Where the entry carries movedTo, naming another key in the same section, and that key rose in the same comparison by at least the fall, the fall is a count that moved — a package split — and it is listed as a move rather than failed on. The entry still needs its reason, a movedTo that names its own key or a key the section does not record is an error in every mode, and no mode writes the field: only whoever made the split can say where the count went.

--seed and --update are exclusive; --base only reads, so it combines with neither; --file combines with neither --base nor --seed; --reason and --key are refused without --seed; --seed is refused without --today.

dad baseline init [path] --reason <text> [--today YYYY-MM-DD] [--json]

Adopt the code-health ratchet in a standalone TypeScript repository. The command records existing findings with a reason in .agents/source-budgets.json and sets up the strict threshold profile in .agents/source-ratchet.json. The CI gate measures the proposed source and checks the adopted policy and baseline against a trusted ref. See the standalone ratchet CI recipe.

dad doctor explain <issue-id> [--json]

Prints one issue: the sentence from the essay, the links to both documents, the companion's numbered test with the signal that answers each question, the signals Dad measures today with their thresholds, and the cure. It is a subcommand of doctor because dad explain <path> is already the orientation alias above.

Changed verification

dad test:recommend --changed [--base <ref>] [--json]

A read-only candidate plan. It reads the declared task graph, finds changed owners and their dependent verification, and reports why each task is run, pending-provider, reuse-candidate, or unknown-scope. It never claims a check ran, and it exits 1 when the plan is incomplete.

Changed scope is the comparison base — HEAD, or an explicit --base <ref> — plus staged, unstaged, untracked, renamed, and deleted paths. An invalid explicit base is an error. A default clean scope has no trusted baseline and therefore selects the configured conservative full fallback. Unknown executable scope does the same, instead of returning an empty success.

dad verify --changed [--base <ref>] [--full] [--no-cache] [--json]

Executes the same selection in dependency order and reports every selected task as:

  • executed: the task ran against its captured inputs.
  • reused: a supported controlled task has an exact matching successful local receipt for the current consumed inputs and provider artifact.
  • failed: the selected task ran and failed.
  • blocked: a prerequisite failed, so the task was not credited.
  • not-applicable: no work was required for that task.

--full disables Dad result reuse for the selected graph. So does the cache being off: with CI set, or with --no-cache, no receipt is even looked up, so a CI run never credits evidence left by an earlier run. Repository-wide delivery verification remains a separate project command.

What Dad may reuse

Reuse is deliberately limited to Dad's mechanically validated artifact-consumer adapter. The graph runs from one isolated checkout and manifest snapshot. It captures an immutable copy of declared source, tests, fixtures, configuration, resolved dependencies, lockfile, generated artifacts, command, toolchain, platform, and non-secret environment inputs. A task receives credit only after successful execution and required outputs. The receipt identifies the exact snapshot it proves, including the hash derived from the executing Dad toolbox. Consumed artifact bytes must equal the current provider output fingerprint.

Workspace snapshots preserve plain directories as directories. For a Git workspace, Dad captures the working-source inventory and real HEAD in independent metadata so root Git checks can discover the snapshot and run against its copied files. Dad records available local main-branch references and a checkout-relative hook path for the history and hook checks. Those facts enter receipt identity. The snapshot has no configured remote, and its index represents the captured source available to verification.

Shell commands, live services, mutable integrations, secret-dependent tasks, and unknown inputs always execute. Provider failure blocks its consumers even when an old output exists. Missing, corrupt, foreign, interrupted, or stale receipts cause execution; they never fabricate success.

Receipts live under the ignored .dads/verification/ directory. They are local evidence, not source files or shared authority. Do not edit, commit, or copy them between projects. Deleting them is safe and simply forces the relevant work to run again.

The first concrete proof lives in fixtures/boundary-verification. It executes the real compiled artifact consumer, demonstrates a source-only provider change that preserves exact artifact bytes, and independently proves that changes to policy output, consumer code, tests, configuration, engine, binding, lockfile, toolchain, or declared environment execute again. Full and optimized verification both catch an injected consumer failure; the optimization changes work performed, not the expected answer.

Test selection passthrough

dad test plan|run|explain|init [--manifest <path>] [--base <ref>] [--head <ref>] [--all] [--task <id>]* [--jobs <n>] [--report [path]] [--force] --json

A passthrough to @dads-framework/testing's dad-test command line, which owns those four subcommands and their options; the exit code is the one that command returns. Note that dad init and dad explain <path> above are unrelated commands with the same names.

Domain boundaries

dad check boundaries [--json] resolves project imports and checks domain, neutral library, and composition ownership. The checker exits unsuccessfully on violations and identifies the source, target, and fix. Starters include it in local and CI verification. See the domain boundaries guide for default paths, custom roots, and a two-API example.

Generators

dad add --help lists the nine commands for domains, endpoints, tables, access, flags, email, pages, resources, and dependency libraries. In the starter, preview a domain on the staff API with npx dad add domain inventory --api staff --dry-run --json. The preview lists the planned files and registration without editing the project. Generator guide

Dependency libraries

dad add library <name> [--dry-run] [--json] creates an application-owned TypeScript package in libraries/<name> with a public export, declarations, a smoke test, and workspace and ownership entries. Run npm install to update workspace links and the lockfile. See the dependency library guide for the workflow from an owning repository to a consuming repository.

Use it

The package also exports the surface the CLI is built from, which is how create-dads reuses the same recipes:

  • Projects: initializeDadsProject, deriveDadsProjectName, parseDadsInitializationArguments, dependenciesAreInstalled, recordDadsDependencyInstallation.
  • Orientation: loadDadsProject, findDadsProjectRoot, parseDadsProject, orientProjectPath, recommendChangedVerification, synchronizeAgentSkills.

What it refuses to do

  • No runtime dependency in the other direction. Framework packages never import this one, so a project can drop the CLI and keep the framework.
  • No ownership it was not told about. orient and the changed plan read dads.project.json; a path no declared package owns is an error rather than a default.
  • No overwriting. Initialization and library creation preserve existing files.
  • No skip it cannot prove. Reuse requires an exact receipt for the current inputs; anything missing, stale, foreign, or corrupt executes again.
  • No treating an empty scope as a clean bill of health. Without a trusted baseline, selection widens to the configured full fallback.
  • No verdict without a number. doctor prints the reading, the threshold, and where the threshold came from on every line. See the Doctor command reference for gate and report modes.
  • No clock. doctor takes a date only from --today, so two runs over one tree print the same bytes.

Contract

Commands take arguments as shown above. Every value option may appear once and requires a value; dad init additionally rejects a repeated flag and a second positional argument.

A successful --json run prints one line beginning {"ok":true,…}. init reports initialization and installed. add library reports result. test:recommend prints changedScope, recommendation, and notApplicable; verify prints those plus report. A failure prints {"ok":false,"error":"<message>"} on stderr and exits 1; without --json the same message is written as Dad: <message>.

changedScope is { comparisonBase, paths, workspaceIdentity }. A recommendation carries packages, tasks, unownedPaths, unknownPaths, usedFullFallback, complete, and issues; each task has taskId, packageName, command, state, reason, and dependsOn. A verification report carries ok, full, results, counts by status, and issues; each result has taskId, command, status, reason, snapshotId, receiptId, and outputs. Without --json, verify prints one padded line per task followed by executed=<n> reused=<n> failed=<n> blocked=<n> not-applicable=<n>.

Errors, and when each happens:

Message When
Could not find dads.project.json from <path>. No Dads project above the working directory
orient requires a project-relative path. orient or explain with no path
No declared package owns <path>. orient, explain, on an unowned path
inspect requires http-operation "<METHOD /path>". A malformed inspect invocation
--profile must be standard or strict. doctor with any other profile
No daddy issue is named <id>. doctor --issue or doctor explain with an unknown id
--today must be a date written YYYY-MM-DD. doctor --today with anything else
doctor takes at most one path. / doctor explain requires an issue id. A malformed doctor invocation
No literal HTTP operation named <name> was found. inspect matched nothing
Refusing to initialize non-empty directory <path>. … init target holds files and no dads.project.json
Refusing to overwrite conflicting file <path>. An owned file exists with different content
Unknown option <option>. / Option <option> was provided more than once. A bad init argument list
<option> requires a value. / <option> may only be provided once. A value option given wrongly
Invalid verification base <ref>. --base names no commit
Unable to read the changed git scope[: <detail>] Git could not report the changed paths
Refusing to replace existing package script <name>. … A recipe script name is already taken
npm install failed[: <detail>] Dependency installation failed

The package requires Node.js 22 or newer.

Daddy issues this prevents

"Which tests do I need to run for this?" has two bad answers: all of them, every time, because nobody could say; and none of them, because somebody once decided it was unrelated and wrote nothing down. Here the plan is read from the project's own declarations, and every skip is backed by a receipt that names what it proved.

Generate application code

Use dad add domain|endpoint|table|access|flag|email|page|resource in a kit starter. Choose an API explicitly when exposing a domain. The generator reference lists output files, dependencies, and dry-run behavior. See Generate application code.