@outfitter/tooling 0.2.1 → 0.2.3

package/.markdownlint-cli2.jsonc

@@ -1,66 +1,66 @@
 {
-  // Outfitter markdownlint preset
-  // https://github.com/DavidAnson/markdownlint
+	// Outfitter markdownlint preset
+	// https://github.com/DavidAnson/markdownlint
 
-  "config": {
-    // Headings
-    "MD003": { "style": "atx" },           // ATX-style headings (# Heading)
-    "MD022": { "lines_above": 1, "lines_below": 1 }, // Blank lines around headings
-    "MD024": { "siblings_only": true },    // Allow duplicate headings in different sections
-    "MD041": false,                         // First line doesn't need to be h1 (frontmatter, etc.)
+	"config": {
+		// Headings
+		"MD003": { "style": "atx" }, // ATX-style headings (# Heading)
+		"MD022": { "lines_above": 1, "lines_below": 1 }, // Blank lines around headings
+		"MD024": { "siblings_only": true }, // Allow duplicate headings in different sections
+		"MD041": false, // First line doesn't need to be h1 (frontmatter, etc.)
 
-    // Line length - disabled for prose flexibility
-    "MD013": false,
+		// Line length - disabled for prose flexibility
+		"MD013": false,
 
-    // Lists
-    "MD004": { "style": "dash" },           // Unordered list style: dash (-)
-    "MD007": { "indent": 2 },               // List indentation: 2 spaces
-    "MD032": true,                          // Blank lines around lists
+		// Lists
+		"MD004": { "style": "dash" }, // Unordered list style: dash (-)
+		"MD007": { "indent": 2 }, // List indentation: 2 spaces
+		"MD032": true, // Blank lines around lists
 
-    // Code blocks
-    "MD040": true,                          // Fenced code blocks should have a language
-    "MD046": { "style": "fenced" },         // Code block style: fenced (```)
-    "MD048": { "style": "backtick" },       // Code fence style: backticks
+		// Code blocks
+		"MD040": true, // Fenced code blocks should have a language
+		"MD046": { "style": "fenced" }, // Code block style: fenced (```)
+		"MD048": { "style": "backtick" }, // Code fence style: backticks
 
-    // Links
-    "MD034": true,                          // No bare URLs (use <url> or [text](url))
+		// Links
+		"MD034": true, // No bare URLs (use <url> or [text](url))
 
-    // Whitespace
-    "MD009": { "br_spaces": 2 },            // Allow 2 trailing spaces for <br>
-    "MD010": { "spaces_per_tab": 2 },       // Tabs to spaces
-    "MD012": { "maximum": 1 },              // Max 1 consecutive blank line
-    "MD047": true,                          // Files should end with newline
+		// Whitespace
+		"MD009": { "br_spaces": 2 }, // Allow 2 trailing spaces for <br>
+		"MD010": { "spaces_per_tab": 2 }, // Tabs to spaces
+		"MD012": { "maximum": 1 }, // Max 1 consecutive blank line
+		"MD047": true, // Files should end with newline
 
-    // HTML - allow for GitHub-specific elements
-    "MD033": {
-      "allowed_elements": [
-        "details",
-        "summary",
-        "kbd",
-        "br",
-        "sup",
-        "sub",
-        "img",
-        "picture",
-        "source",
-        "a"
-      ]
-    },
+		// HTML - allow for GitHub-specific elements
+		"MD033": {
+			"allowed_elements": [
+				"details",
+				"summary",
+				"kbd",
+				"br",
+				"sup",
+				"sub",
+				"img",
+				"picture",
+				"source",
+				"a"
+			]
+		},
 
-    // Emphasis
-    "MD049": { "style": "asterisk" },       // Emphasis style: *italic*
-    "MD050": { "style": "asterisk" }        // Strong style: **bold**
-  },
+		// Emphasis
+		"MD049": { "style": "asterisk" }, // Emphasis style: *italic*
+		"MD050": { "style": "asterisk" } // Strong style: **bold**
+	},
 
-  // Ignore patterns
-  "ignores": [
-    "node_modules/**",
-    "**/node_modules/**",
-    "dist/**",
-    "**/dist/**",
-    ".turbo/**",
-    "**/.turbo/**",
-    "CHANGELOG.md",
-    "**/CHANGELOG.md"
-  ]
+	// Ignore patterns
+	"ignores": [
+		"node_modules/**",
+		"**/node_modules/**",
+		"dist/**",
+		"**/dist/**",
+		".turbo/**",
+		"**/.turbo/**",
+		"CHANGELOG.md",
+		"**/CHANGELOG.md"
+	]
 }

package/README.md

@@ -68,21 +68,36 @@ bunx @outfitter/tooling upgrade-bun 1.4.0 --no-install
 
 ### `tooling pre-push`
 
-TDD-aware pre-push test hook. Detects RED phase branches and skips tests by design.
+TDD-aware pre-push strict verification hook. Detects RED phase branches and skips verification by design.
 
 RED phase branches follow these patterns:
 - `*-tests` (e.g., `feature/auth-tests`)
 - `*/tests` (e.g., `feature/auth/tests`)
 - `*_tests` (e.g., `feature/auth_tests`)
 
+Verification order:
+1. Run `verify:ci` if present.
+2. Otherwise run strict fallback: `typecheck`, `check|lint`, `build`, `test`.
+
 ```bash
 # Normal usage (in lefthook.yml)
 bunx @outfitter/tooling pre-push
 
-# Force skip tests
+# Force skip verification
 bunx @outfitter/tooling pre-push --force
 ```
 
+### `tooling check-boundary-invocations`
+
+Validate that root/app scripts do not execute `packages/*/src/*` directly.
+
+```bash
+bunx @outfitter/tooling check-boundary-invocations
+```
+
+When this fails, replace direct source execution with canonical command surfaces
+(`outfitter repo ...` in monorepo scripts, or package bins for standalone use).
+
 ## Configuration Presets
 
 ### Biome
@@ -124,7 +139,7 @@ extends:
 
 Default hooks:
 - **pre-commit**: Runs ultracite on staged files, typechecks
-- **pre-push**: Runs build, then TDD-aware tests via `tooling pre-push`
+- **pre-push**: Runs TDD-aware strict verification via `tooling pre-push`
 
 ### markdownlint
 
@@ -147,6 +162,18 @@ Available blocks:
 - `bootstrap` — Project bootstrap script
 - `scaffolding` — Full starter kit (combines all above)
 
+## Monorepo Command Mapping
+
+Within this monorepo, maintenance checks are routed via `outfitter repo`:
+
+```bash
+bun run apps/outfitter/src/cli.ts repo check exports --cwd .
+bun run apps/outfitter/src/cli.ts repo check readme --cwd .
+bun run apps/outfitter/src/cli.ts repo check registry --cwd .
+bun run apps/outfitter/src/cli.ts repo check tree --cwd .
+bun run apps/outfitter/src/cli.ts repo check boundary-invocations --cwd .
+```
+
 ## Exports
 
 | Export | Description |

package/biome.json

@@ -1,74 +1,81 @@
 {
-  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
-  "root": false,
-  "javascript": {
-    "globals": ["Bun"]
-  },
-  "linter": {
-    "rules": {
-      "complexity": {
-        "useLiteralKeys": "off",
-        "noVoid": "off",
-        "noExcessiveCognitiveComplexity": "off"
-      },
-      "performance": {
-        "useTopLevelRegex": "off"
-      },
-      "style": {
-        "useBlockStatements": "off"
-      },
-      "suspicious": {
-        "noConsole": "error"
-      }
-    }
-  },
-  "vcs": {
-    "enabled": true,
-    "clientKind": "git",
-    "useIgnoreFile": true
-  },
-  "files": {
-    "ignoreUnknown": true,
-    "includes": ["!**/node_modules", "!**/dist", "!**/.turbo", "!**/*.gen.ts"]
-  },
-  "overrides": [
-    {
-      "includes": ["packages/*/src/index.ts", "apps/*/src/index.ts", "**/index.ts"],
-      "linter": {
-        "rules": {
-          "performance": {
-            "noBarrelFile": "off"
-          }
-        }
-      }
-    },
-    {
-      "includes": ["**/*.test.ts", "**/__tests__/**/*"],
-      "linter": {
-        "rules": {
-          "suspicious": {
-            "useAwait": "off",
-            "noConsole": "off"
-          },
-          "performance": {
-            "noDelete": "off"
-          }
-        }
-      }
-    },
-    {
-      "includes": [
-        "apps/**/*.ts",
-        "scripts/**/*.ts",
-        "**/scripts/**/*.ts"
-      ],
-      "linter": {
-        "rules": {
-          "suspicious": {
-            "noConsole": "off"
-          }
-        }
-      }
-    }
-  ]
+	"$schema": "https://biomejs.dev/schemas/2.3.12/schema.json",
+	"root": false,
+	"javascript": {
+		"globals": ["Bun"]
+	},
+	"linter": {
+		"rules": {
+			"complexity": {
+				"useLiteralKeys": "off",
+				"noVoid": "off",
+				"noExcessiveCognitiveComplexity": "off"
+			},
+			"performance": {
+				"useTopLevelRegex": "off"
+			},
+			"style": {
+				"useBlockStatements": "off"
+			},
+			"suspicious": {
+				"noConsole": "error"
+			}
+		}
+	},
+	"vcs": {
+		"enabled": true,
+		"clientKind": "git",
+		"useIgnoreFile": true
+	},
+	"files": {
+		"ignoreUnknown": true,
+		"includes": [
+			"**",
+			"!**/node_modules",
+			"!**/dist",
+			"!**/.turbo",
+			"!**/*.gen.ts",
+			"!registry/registry.json"
+		]
+	},
+	"overrides": [
+		{
+			"includes": [
+				"packages/*/src/index.ts",
+				"apps/*/src/index.ts",
+				"**/index.ts"
+			],
+			"linter": {
+				"rules": {
+					"performance": {
+						"noBarrelFile": "off"
+					}
+				}
+			}
+		},
+		{
+			"includes": ["**/*.test.ts", "**/__tests__/**/*"],
+			"linter": {
+				"rules": {
+					"suspicious": {
+						"useAwait": "off",
+						"noConsole": "off"
+					},
+					"performance": {
+						"noDelete": "off"
+					}
+				}
+			}
+		},
+		{
+			"includes": ["apps/**/*.ts", "scripts/**/*.ts", "**/scripts/**/*.ts"],
+			"linter": {
+				"rules": {
+					"suspicious": {
+						"noConsole": "off"
+					}
+				}
+			}
+		}
+	]
 }

package/dist/cli/check-boundary-invocations.d.ts

@@ -0,0 +1,34 @@
+interface ScriptLocation {
+	readonly file: string;
+	readonly scriptName: string;
+	readonly command: string;
+}
+interface BoundaryViolation extends ScriptLocation {
+	readonly rule: "root-runs-package-src" | "cd-package-then-runs-src";
+}
+interface ReadScriptEntriesOptions {
+	readonly appManifestRelativePaths?: readonly string[];
+	readonly readPackageJson?: (filePath: string) => Promise<{
+		scripts?: Record<string, string>;
+	}>;
+}
+/**
+* Detect whether a single script command violates boundary invocation rules.
+*/
+declare function detectBoundaryViolation(location: ScriptLocation): BoundaryViolation | null;
+/**
+* Find all boundary violations across package/app script maps.
+*/
+declare function findBoundaryViolations(entries: readonly {
+	file: string;
+	scripts: Readonly<Record<string, string>>;
+}[]): BoundaryViolation[];
+declare function readScriptEntries(cwd: string, options?: ReadScriptEntriesOptions): Promise<{
+	file: string;
+	scripts: Record<string, string>;
+}[]>;
+/**
+* Run boundary invocation checks against root/apps package scripts.
+*/
+declare function runCheckBoundaryInvocations(): Promise<void>;
+export { runCheckBoundaryInvocations, readScriptEntries, findBoundaryViolations, detectBoundaryViolation, ScriptLocation, BoundaryViolation };

package/dist/cli/check-boundary-invocations.js

@@ -0,0 +1,14 @@
+// @bun
+import {
+  detectBoundaryViolation,
+  findBoundaryViolations,
+  readScriptEntries,
+  runCheckBoundaryInvocations
+} from "../shared/@outfitter/tooling-r9976n43.js";
+import"../shared/@outfitter/tooling-dvwh9qve.js";
+export {
+  runCheckBoundaryInvocations,
+  readScriptEntries,
+  findBoundaryViolations,
+  detectBoundaryViolation
+};

package/dist/cli/check-bunup-registry.d.ts

@@ -0,0 +1,36 @@
+/** Result of checking bunup workspace registration */
+interface RegistryCheckResult {
+	readonly ok: boolean;
+	readonly missing: string[];
+}
+/**
+* Extract the package name from a build script containing `bunup --filter`.
+*
+* @example
+* extractBunupFilterName("bunup --filter @outfitter/logging")
+* // => "@outfitter/logging"
+*
+* extractBunupFilterName("cd ../.. && bunup --filter @outfitter/types")
+* // => "@outfitter/types"
+*
+* extractBunupFilterName("tsc --noEmit")
+* // => null
+*/
+declare function extractBunupFilterName(script: string): string | null;
+/**
+* Find packages that have `bunup --filter` build scripts but are not
+* registered in the bunup workspace config.
+*
+* @param packagesWithFilter - Package names that have `bunup --filter` in their build script
+* @param registeredNames - Package names registered in bunup.config.ts
+* @returns Result with sorted list of missing packages
+*/
+declare function findUnregisteredPackages(packagesWithFilter: string[], registeredNames: string[]): RegistryCheckResult;
+/**
+* Run bunup registry check across all workspace packages.
+*
+* Scans packages/*/package.json for build scripts containing `bunup --filter`,
+* then verifies each is registered in bunup.config.ts.
+*/
+declare function runCheckBunupRegistry(): Promise<void>;
+export { runCheckBunupRegistry, findUnregisteredPackages, extractBunupFilterName, RegistryCheckResult };

package/dist/cli/check-bunup-registry.js

@@ -0,0 +1,12 @@
+// @bun
+import {
+  extractBunupFilterName,
+  findUnregisteredPackages,
+  runCheckBunupRegistry
+} from "../shared/@outfitter/tooling-t17gnh9b.js";
+import"../shared/@outfitter/tooling-dvwh9qve.js";
+export {
+  runCheckBunupRegistry,
+  findUnregisteredPackages,
+  extractBunupFilterName
+};

package/dist/cli/check-changeset.d.ts

@@ -0,0 +1,64 @@
+/**
+* Check-changeset command — validates PRs touching package source include a changeset.
+*
+* Pure core functions for detecting changed packages and verifying changeset
+* presence. The CLI runner in {@link runCheckChangeset} handles git discovery
+* and output.
+*
+* @packageDocumentation
+*/
+/** Result of checking whether changesets are required */
+interface ChangesetCheckResult {
+	readonly ok: boolean;
+	readonly missingFor: string[];
+}
+/**
+* Extract unique package names from changed file paths.
+*
+* Only considers files matching the pattern "packages/NAME/src/..." and
+* ignores apps/, root files, and package-level config.
+*
+* @param files - List of changed file paths relative to repo root
+* @returns Sorted array of unique package names
+*/
+declare function getChangedPackagePaths(files: string[]): string[];
+/**
+* Extract changeset filenames from changed file paths.
+*
+* Only considers files matching `.changeset/*.md`, excluding README.md.
+* This checks the git diff rather than disk, ensuring only changesets added
+* in the current PR are counted.
+*
+* @param files - List of changed file paths relative to repo root
+* @returns Array of changeset filenames (e.g. `["happy-turtle.md"]`)
+*/
+declare function getChangedChangesetFiles(files: string[]): string[];
+/**
+* Determine whether a changeset is required and present.
+*
+* Returns `ok: true` when either no packages were changed or at least one
+* changeset file exists. Returns `ok: false` with the list of changed
+* packages when changesets are missing.
+*
+* @param changedPackages - Package names with source changes
+* @param changesetFiles - Changeset filenames found in `.changeset/`
+*/
+declare function checkChangesetRequired(changedPackages: string[], changesetFiles: string[]): ChangesetCheckResult;
+interface CheckChangesetOptions {
+	readonly skip?: boolean;
+}
+/**
+* Run check-changeset to verify PRs include changeset files.
+*
+* Uses `git diff --name-only origin/main...HEAD` to detect changed files,
+* then checks for changeset presence when package source files are modified.
+*
+* Skips silently when:
+* - `NO_CHANGESET=1` env var is set
+* - `--skip` flag is passed
+* - `GITHUB_EVENT_NAME=push` (post-merge on main)
+* - No packages have source changes
+* - Git diff fails (local dev without origin)
+*/
+declare function runCheckChangeset(options?: CheckChangesetOptions): Promise<void>;
+export { runCheckChangeset, getChangedPackagePaths, getChangedChangesetFiles, checkChangesetRequired, CheckChangesetOptions, ChangesetCheckResult };

package/dist/cli/check-changeset.js

@@ -0,0 +1,14 @@
+// @bun
+import {
+  checkChangesetRequired,
+  getChangedChangesetFiles,
+  getChangedPackagePaths,
+  runCheckChangeset
+} from "../shared/@outfitter/tooling-3w8vr2w3.js";
+import"../shared/@outfitter/tooling-dvwh9qve.js";
+export {
+  runCheckChangeset,
+  getChangedPackagePaths,
+  getChangedChangesetFiles,
+  checkChangesetRequired
+};

package/dist/cli/check-clean-tree.d.ts

@@ -0,0 +1,36 @@
+/**
+* Check-clean-tree command — asserts the working tree has no modified or untracked files.
+*
+* Pure core functions for parsing git output and determining tree cleanliness.
+* The CLI runner in {@link runCheckCleanTree} handles git invocation and output.
+*
+* @packageDocumentation
+*/
+/** Status of the working tree after verification steps */
+interface TreeStatus {
+	readonly clean: boolean;
+	readonly modified: string[];
+	readonly untracked: string[];
+}
+/**
+* Parse `git diff --name-only` output into a list of modified file paths.
+*/
+declare function parseGitDiff(diffOutput: string): string[];
+/**
+* Parse `git ls-files --others --exclude-standard` output into a list of untracked file paths.
+*/
+declare function parseUntrackedFiles(lsOutput: string): string[];
+/**
+* Determine if the tree status represents a clean working tree.
+*/
+declare function isCleanTree(status: TreeStatus): boolean;
+interface CheckCleanTreeOptions {
+	readonly paths?: string[];
+}
+/**
+* Run clean-tree check against the current working directory.
+*
+* Exits 0 if clean, 1 if dirty files are found.
+*/
+declare function runCheckCleanTree(options?: CheckCleanTreeOptions): Promise<void>;
+export { runCheckCleanTree, parseUntrackedFiles, parseGitDiff, isCleanTree, TreeStatus, CheckCleanTreeOptions };

package/dist/cli/check-clean-tree.js

@@ -0,0 +1,14 @@
+// @bun
+import {
+  isCleanTree,
+  parseGitDiff,
+  parseUntrackedFiles,
+  runCheckCleanTree
+} from "../shared/@outfitter/tooling-1y8w5ahg.js";
+import"../shared/@outfitter/tooling-dvwh9qve.js";
+export {
+  runCheckCleanTree,
+  parseUntrackedFiles,
+  parseGitDiff,
+  isCleanTree
+};

package/dist/cli/check-exports.d.ts

@@ -0,0 +1,2 @@
+import { CheckExportsOptions, CheckResult, CompareInput, ExportDrift, ExportMap, PackageResult, compareExports, entryToSubpath, runCheckExports } from "../shared/@outfitter/tooling-q0d60xb3";
+export { runCheckExports, entryToSubpath, compareExports, PackageResult, ExportMap, ExportDrift, CompareInput, CheckResult, CheckExportsOptions };

package/dist/cli/check-exports.js

@@ -0,0 +1,12 @@
+// @bun
+import {
+  compareExports,
+  entryToSubpath,
+  runCheckExports
+} from "../shared/@outfitter/tooling-tf22zt9p.js";
+import"../shared/@outfitter/tooling-dvwh9qve.js";
+export {
+  runCheckExports,
+  entryToSubpath,
+  compareExports
+};

package/dist/cli/check-readme-imports.d.ts

@@ -0,0 +1,60 @@
+import { ExportMap } from "../shared/@outfitter/tooling-q0d60xb3";
+/** An import example extracted from a markdown code block */
+interface ImportExample {
+	/** Package name, e.g. "@outfitter/cli" */
+	readonly packageName: string;
+	/** Export subpath, e.g. "./output" or "." */
+	readonly subpath: string;
+	/** Full import specifier, e.g. "@outfitter/cli/output" */
+	readonly fullSpecifier: string;
+	/** File where the import was found */
+	readonly file: string;
+	/** 1-based line number */
+	readonly line: number;
+}
+/** Result of checking imports in a single file */
+interface ImportCheckResult {
+	readonly file: string;
+	readonly valid: ImportExample[];
+	readonly invalid: ImportExample[];
+}
+/**
+* Parse a full import specifier into package name and subpath.
+*
+* Only recognizes `@outfitter/*` scoped packages.
+*
+* @example
+* parseSpecifier("@outfitter/cli/output")
+* // { packageName: "@outfitter/cli", subpath: "./output" }
+*
+* parseSpecifier("@outfitter/contracts")
+* // { packageName: "@outfitter/contracts", subpath: "." }
+*/
+declare function parseSpecifier(specifier: string): {
+	packageName: string;
+	subpath: string;
+} | null;
+/**
+* Extract import specifiers from markdown content.
+*
+* Only extracts imports from fenced code blocks (typescript, ts,
+* javascript, js). Skips blocks preceded by a non-contractual HTML comment.
+* Deduplicates by full specifier within a single file.
+*/
+declare function extractImports(content: string, file: string): ImportExample[];
+/**
+* Check whether a subpath exists in a package.json map.
+*/
+declare function isExportedSubpath(subpath: string, exports: ExportMap): boolean;
+interface CheckReadmeImportsOptions {
+	readonly json?: boolean;
+}
+/**
+* Run check-readme-imports across all workspace packages.
+*
+* Finds README.md files in `packages/` and `docs/packages/`, extracts
+* import examples, and validates each subpath against the corresponding
+* package.json exports.
+*/
+declare function runCheckReadmeImports(options?: CheckReadmeImportsOptions): Promise<void>;
+export { runCheckReadmeImports, parseSpecifier, isExportedSubpath, extractImports, ImportExample, ImportCheckResult, ExportMap, CheckReadmeImportsOptions };