Skip to content

Repository verification wrapper

Decisions

Decision Choice Why
Verification tasks format, typecheck, and build These are the repository's existing quality and production checks; there is no configured test runner yet
Default tasks Run format, typecheck, and build when no task names are supplied A default invocation should cover the complete active verification surface
Test task Recognize test as a future-compatible placeholder and report it as unavailable without failing verification Keeps the CLI extensible without inventing test infrastructure or making a missing script look like an implementation failure
Execution model Run the root package scripts directly through pnpm run This is a single-package repository with no Turbo task prefixes or package graph to normalize
Output contract Preserve task selection, --json, --raw, help, compact findings, and exit codes; remove Turbo/package grouping assumptions Retains the useful agent-facing interface while matching this repository's output
Script filename Keep scripts/verify.ts The supplied script already exists at this path in the workspace; runtime behavior should remain directly executable by Node
Package wiring Add one package script that invokes the verifier Makes the wrapper discoverable and usable through the normal pnpm run interface
Documentation and CI No additional documentation or CI changes This task is limited to adoption of the local verifier; existing repository docs do not define a verification wrapper

Prerequisites

  • Preserve the existing format, typecheck, and build commands in package.json; the verifier must call them rather than duplicate their implementation.
  • Confirm that the verifier can be run with the repository's installed Node and pnpm versions and does not require Turbo, Vitest, or another new dependency.
  • Keep the script's root resolution based on its own location so it behaves consistently when invoked from another working directory.
  • Treat package.json as the source of truth for task availability. The test placeholder must detect the absent script instead of attempting to spawn an invalid command.
  • Keep process output collection cross-platform and preserve nonzero exit codes from active tasks.
  • Do not introduce route, component, Directus, data, or schema changes; this task has no server boundary or authorization implications.

Step 1 - Define the repository task contract

Goal: Replace the Turbo-oriented task assumptions with an explicit contract for this single-package repository.

Scope

  • In: scripts/verify.ts, define the supported task names, default task list, usage text, and task metadata for format, typecheck, build, and placeholder test.
  • In: scripts/verify.ts, determine task availability from the root package.json scripts without hard-coding a second command implementation.
  • In: scripts/verify.ts, preserve argument validation, duplicate task removal, help handling, --json, --raw, and exit-code semantics.
  • Out: Adding a test framework, changing existing package scripts, or introducing a workspace/Turbo abstraction.

Acceptance criteria

  • No-argument execution selects format, typecheck, and build in a deterministic order.
  • Explicit format, typecheck, and build task names are accepted.
  • Explicit test is accepted and identified as unavailable when no root test script exists.
  • Unknown task names and flags produce usage errors with exit code 2.
  • --help, --json, and --raw remain supported.

Step 2 - Execute active tasks and represent unavailable test

Goal: Run the active package scripts directly and make the future test slot informative without masking real failures.

Scope

  • In: scripts/verify.ts, invoke pnpm run <task> from the repository root for active tasks and collect stdout/stderr and exit status.
  • In: scripts/verify.ts, handle an unavailable test task without spawning a nonexistent command; represent it as a clear unavailable result with a successful status.
  • In: scripts/verify.ts, retain spawn-failure handling and ensure a signal-terminated or otherwise missing process status is treated as failure for active tasks.
  • In: scripts/verify.ts, remove Turbo-specific prefix parsing, package-directory harvesting, failed-package tracking, and package-group assumptions.
  • Out: Modifying the output of the underlying pnpm tasks or adding task-specific shell pipelines.

Acceptance criteria

  • Active tasks execute the corresponding existing package script exactly once.
  • A failing active task produces a nonzero verifier result and preserves enough raw output to diagnose the failure.
  • A spawn failure produces a nonzero result and an actionable message.
  • Selecting test alone reports that testing is not configured and exits successfully.
  • Selecting test alongside active tasks does not prevent active tasks from running.
  • The verifier does not require Turbo output prefixes, package names, or a monorepo layout.

Step 3 - Adapt diagnostic parsing and reporting

Goal: Keep compact agent-readable findings for this project's direct pnpm output while retaining raw output for parser misses.

Scope

  • In: scripts/verify.ts, retain or adapt TypeScript diagnostic parsing for the direct pnpm run typecheck output, including repository-relative file paths where the compiler emits them.
  • In: scripts/verify.ts, retain Prettier write/error reporting and add build failure fallback reporting based on the active task's output.
  • In: scripts/verify.ts, define a task result shape that supports active success/failure, unavailable status, parsed findings, and optional raw output without package grouping.
  • In: scripts/verify.ts, update text and JSON reporting so status labels, counts, unavailable test state, summary, and raw-output guidance are consistent.
  • Out: Building a general parser for every possible compiler/bundler output format or suppressing raw output when structured parsing finds nothing.

Acceptance criteria

  • Typecheck findings include file, line, column, diagnostic code, and message when emitted in the expected TypeScript format.
  • Format output identifies rewritten files and surfaces formatter errors.
  • Build failures report actionable fallback output even when no specialized parser matches.
  • Text output clearly distinguishes passed, failed, and unavailable tasks.
  • JSON output is machine-readable, omits raw output unless --raw is supplied, and includes enough task status for automation.
  • --raw includes the untouched task output for active tasks.

Step 4 - Wire the verifier into package scripts

Goal: Make the adopted wrapper available through the project's standard pnpm workflow without changing existing commands.

Scope

  • In: package.json, add a concise script entry that invokes scripts/verify.ts using the repository's supported Node execution path.
  • In: scripts/verify.ts, ensure the selected runtime can execute the TypeScript file under the current package configuration without adding an unnecessary dependency.
  • Out: Renaming the existing format, typecheck, build, or test package scripts; adding CI configuration; changing lockfiles unless a runtime dependency is strictly required.

Acceptance criteria

  • The verifier can be invoked through a documented package script name chosen during implementation.
  • Existing pnpm format, pnpm typecheck, and pnpm build commands remain unchanged.
  • The package remains valid under its current ESM and TypeScript configuration.
  • No new runtime dependency is added unless the existing Node toolchain cannot execute the chosen script path.

Step 5 - Verify the adopted wrapper

Goal: Confirm the wrapper works for successful, failing, selected-task, unavailable-test, raw, and JSON flows.

Acceptance criteria

  • pnpm typecheck passes.
  • pnpm format completes successfully.
  • pnpm build passes.
  • The verifier's default command runs format, typecheck, and build and exits successfully.
  • Explicit task selection runs only the requested active tasks.
  • test reports unavailable and exits successfully without installing or invoking a test runner.
  • --json emits valid structured output for both active tasks and the unavailable test result.
  • --raw includes underlying output and preserves a useful failure trail.
  • Invalid flags and task names exit with code 2 and show usage.
  • A deliberately failing active command or equivalent local probe confirms the verifier returns exit code 1 and does not swallow the failure.

Risks / open questions

  • The supplied script is TypeScript but its usage text says verify.mjs; implementation must choose an execution path already supported by the repository rather than silently relying on a missing TypeScript runtime.
  • Direct pnpm output differs from Turbo output, so parser patterns may need a small validation pass against actual command output before finalizing the compact report.
  • format uses --write, so running the verifier can modify files by design. The plan preserves the existing package command and does not introduce a separate check-only formatter.
  • Treating unavailable test as successful is intentional for future compatibility; once a test runner is added, the task should become an active failing check.