korchasa/configure-deno-commands

Configure Deno Commands

This skill ensures a standardized development interface using Deno tasks and scripts.

Context

This skill can be invoked:

• Standalone: When a user wants to fix or update their Deno commands.
• From init: During project initialization to set up the standard interface.

Standard Interface

The project must support these commands in deno.json:

• deno task check: Comprehensive verification (build, lint, fmt, static analysis, tests).
• deno task test: Run all tests or a specific test if a path is provided.
• deno task dev: Run in development mode with watch mode.
• deno task prod: Run in production mode.

Rules & Constraints

1. Idempotency: Check existing scripts/ and deno.json tasks before creating. Do not overwrite existing scripts unless user confirms.
2. Scripts Location: All complex logic must reside in .ts files within the scripts/ directory.
3. Task Definitions: deno.json should point to these scripts.
4. Standard Interface Compliance: The check.ts script must implement the full verification checklist.
5. Exit Codes: Scripts must return non-zero exit codes on failure to break CI/CD and agent workflows.
6. No External Dependencies: Generated scripts must only use Deno built-in APIs and @std/ stdlib. No cliffy, no npm packages.
7. Parallel Execution: Independent checks (fmt, lint, test, type-check) MUST run in parallel, not sequentially.
8. Sequential Prerequisites: If the project has build/codegen steps whose output is needed by subsequent checks, those steps MUST complete before parallel checks start.
9. Buffered Output: Each parallel command's stdout/stderr MUST be buffered (piped, not inherited) to prevent interleaving.
10. Real-Time Progress: Print a status line when each command starts and when it finishes (pass/fail).
11. Output Ordering: After all checks complete, print buffered output of passed checks first, then ALL failed checks at the end — for easy debugging.
12. No Output Loss: ALL stdout and stderr from every check MUST be printed regardless of success/failure.
13. Subprocess Spawn Safety (fork-loop prevention): Any .ts file under scripts/ that calls Deno.Command, Deno.run, or otherwise spawns a subprocess at module top level MUST wrap the spawn in if (import.meta.main) { … }. Reason: deno test -A scripts/ walks the directory and imports every file to discover Deno.test(…) calls. Importing a file with an unguarded top-level Deno.Command("deno", ["test", "-A", …]) immediately spawns another deno test, which imports the same file again — recursive fork-bomb that exhausts the host within seconds. This pattern crashed the dev host on 2026-05-09 (multiple WindowServer kernel panics).
14. Prefer inline deno.json tasks over wrapper scripts: If a task is a single command (deno test -A, deno run --watch -A src/main.ts), declare it directly in deno.json "tasks". Generate a scripts/<name>.ts file ONLY for orchestration that needs Deno-script logic (e.g. parallel runs, conditional sequencing, output buffering). scripts/check.ts qualifies; scripts/test.ts and scripts/dev.ts do not — they should be inline tasks. When the user explicitly asks for a scripts/test.ts wrapper, apply rule 13 AND require an explicit path argument (do NOT call deno test -A without a path from inside scripts/ — that triggers the recursion above).

Workflow

1. Analyze: Check existing deno.json and scripts/.
2. Scaffold Scripts: Create scripts/check.ts if missing. The script must satisfy all Rules & Constraints above (parallel execution, buffered output, failed-last ordering, no external deps).
3. Configure Tasks: Update deno.json tasks to reference the scripts.
4. Verify: Run deno task check to ensure everything works.

Examples

deno.json tasks (preferred — inline tasks for single-command operations)

{
  "tasks": {
    "check": "deno run -A scripts/check.ts",
    "test": "deno test -A",
    "dev": "deno run --watch -A src/main.ts",
    "prod": "deno run -A src/main.ts"
  }
}

scripts/test.ts (only when user explicitly asks for a wrapper)

#!/usr/bin/env -S deno run -A
// Guard against re-entry: `deno test -A scripts/` would otherwise import
// this file, execute the spawn at top level, and cause a recursive
// fork-bomb (rule 13 in SKILL.md).
if (import.meta.main) {
  const path = Deno.args[0];
  if (!path) {
    console.error("usage: scripts/test.ts <path>  (passing no path triggers recursion)");
    Deno.exit(2);
  }
  const { code } = await new Deno.Command("deno", {
    args: ["test", "-A", path],
  }).spawn().status;
  Deno.exit(code);
}

Verification

• [ ] scripts/check.ts exists and is executable.
• [ ] deno.json contains all standard tasks.
• [ ] deno task check passes cleanly.