Skip to main content

For AI Agents

This page is for autonomous agents (Claude Code, Cursor, GitHub Copilot, CI bots, self-hosted assistants) that need to scaffold, audit, or fix JS/TS projects without human prompts. Every CLI command supports a non-interactive mode and emits structured JSON.

Quick orientation: llms.txt is a single-file index of every doc URL. The repo also ships an AGENTS.md for agents working from a checkout.

Agent-friendly command catalog​

All commands take -d <path> for the target directory (defaults to process.cwd()).

setup — scaffold a new project​

# Sane defaults per project type (no prompts)
npx @rtorcato/js-tooling setup --preset library -d ./my-lib --skip-install
npx @rtorcato/js-tooling setup --preset react-app -d ./my-app --skip-install
npx @rtorcato/js-tooling setup --preset nextjs-app -d ./my-site --skip-install

# Full control via a JSON config file
npx @rtorcato/js-tooling setup --config ./project.json --skip-install

# Get the JSON Schema for the config file
npx @rtorcato/js-tooling setup --config-schema > project-config.schema.json

# Preview without writing
npx @rtorcato/js-tooling setup --preset library --dry-run

Available presets: library, web-app, node-api, nextjs-app, react-app.

--dry-run output:

{
  "directory": "/Users/x/projects/my-lib",
  "config": { "projectName": "my-lib", "projectType": "library", "...": "..." },
  "files": [
    "package.json",
    ".editorconfig",
    ".nvmrc",
    "knip.json",
    "tsconfig.json",
    "biome.jsonc",
    "vitest.config.ts",
    "tsup.config.ts",
    "release.config.mjs",
    ".github/workflows/ci.yml",
    ".github/dependabot.yml",
    ".github/workflows/codeql.yml",
    "..."
  ]
}

doctor — audit an existing project​

npx @rtorcato/js-tooling doctor --json -d ./existing-repo

Output shape:

{
  "directory": "/path/to/repo",
  "results": [
    { "check": "Node", "status": "ok", "detail": "v24.16.0" },
    { "check": "TypeScript", "status": "ok", "detail": "tsconfig.json extends \"@rtorcato/js-tooling/typescript/*\"" },
    { "check": "Biome", "status": "drift", "detail": "biome.json found but does not extend \"@rtorcato/js-tooling/biome\"", "hint": "Run `npx @rtorcato/js-tooling copy biome` to scaffold" },
    { "check": "Dependabot", "status": "optional-missing", "detail": "no .github/dependabot.yml", "hint": "Run `npx @rtorcato/js-tooling fix dependabot` to scaffold weekly dep updates" }
  ]
}

Status values: ok, drift (file exists but doesn't extend the preset), missing (required file absent), optional-missing (optional convention absent).

fix — apply fixers for items doctor flagged​

# Walk every doctor finding, apply each (no prompts, no surprises)
npx @rtorcato/js-tooling fix --yes --json -d ./repo

# Apply a single fixer
npx @rtorcato/js-tooling fix dependabot --yes --json
npx @rtorcato/js-tooling fix engines --yes --json

# Preview without writing
npx @rtorcato/js-tooling fix --yes --dry-run --json

Output shape (FixJsonResult):

{
  "directory": "/path/to/repo",
  "target": null,
  "actions": [
    { "target": "engines", "check": "engines.node", "status": "applied", "doctorStatus": "drift", "filesWritten": ["package.json"] },
    { "target": "dependabot", "check": "Dependabot", "status": "applied", "doctorStatus": "optional-missing", "filesWritten": [".github/dependabot.yml"] },
    { "target": null, "check": "GitLab CI", "status": "unsupported", "doctorStatus": "optional-missing", "filesWritten": [] }
  ]
}

Action statuses: applied (fixer ran, files written), dry-run (would have written), skipped (user declined or fixer chose to skip), already-ok (no action needed), unsupported (no fixer registered for this check).

Drift policy: without --yes, drift cases default to "No" in the confirm prompt — your customisations are preserved. With --yes, drift IS overwritten. Safe-merge fixers (engines, husky, package-json) never overwrite even with --yes — they only add/merge.

list — enumerate the library's surface area​

npx @rtorcato/js-tooling list --json

Output shape:

{
  "tools": [
    {
      "name": "TypeScript",
      "description": "Base, React, Next.js, Node.js, Express tsconfig presets",
      "exports": [
        "@rtorcato/js-tooling/typescript/base",
        "@rtorcato/js-tooling/typescript/react",
        "..."
      ],
      "fixTarget": "tsconfig"
    },
    {
      "name": "Biome",
      "description": "Fast formatter and linter configuration",
      "exports": ["@rtorcato/js-tooling/biome"],
      "fixTarget": "biome"
    }
  ]
}

Use this to discover what's available and to map between named tools and the fix <target> command that scaffolds each.

"Set up tooling for this new repo"​

# 1. Decide the project type (or read from existing pkg deps)
PRESET=library  # or web-app, node-api, nextjs-app, react-app

# 2. Preview
npx @rtorcato/js-tooling setup --preset $PRESET --dry-run

# 3. Scaffold
npx @rtorcato/js-tooling setup --preset $PRESET -d . --skip-install

# 4. Install deps yourself (the CLI skips install when --skip-install is set)
pnpm install

"Bring this existing repo up to spec"​

# 1. Audit
DOCTOR=$(npx @rtorcato/js-tooling doctor --json -d .)

# 2. Parse, decide whether to fix everything or specific items
#    (For agents: filter results where status !== "ok" && status !== "optional-missing")

# 3. Apply all fixable findings
npx @rtorcato/js-tooling fix --yes --json -d .

# 4. Confirm
npx @rtorcato/js-tooling doctor --json -d .

"Add Dependabot to this repo (and nothing else)"​

npx @rtorcato/js-tooling fix dependabot --yes --json -d .

Exit codes​

  • setup — 0 on success, 1 on failure (validation error, write failure).
  • doctor — 0 if every check is ok or optional-missing; 1 if any drift or missing.
  • fix — always 0 (intent expressed; rerun doctor to confirm state). Unknown target → 1 with a JSON error payload.
  • list — 0.
  • copy — 0 on success, 1 on unknown config name.

Stable JSON shapes​

The TypeScript types for every JSON payload are exported from the package:

  • import type { CheckResult, CheckStatus } from '@rtorcato/js-tooling/...' (doctor)
  • import type { FixActionRecord, FixJsonResult } from '@rtorcato/js-tooling/...' (fix)
  • setup --config-schema ships the canonical ProjectConfig JSON Schema

Versions of these shapes follow semver (additive changes only within a major).