[01] Real Devtools Provider Adoption

[artiphishle]

Goal

Add Ankh package metadata for @ankhorage/devtools while keeping this package focused on primitive tools.

devtools should continue to own wrappers/config for:

• eslint
• prettier
• knip

It should not own local emulator/app workflows; those belong in @ankhorage/dev.

Suggested metadata

{
  "ankh": {
    "category": "devtools",
    "provider": "./dist/ankh.provider.js",
    "capabilities": [
      "devtools.lint",
      "devtools.format",
      "devtools.knip"
    ]
  }
}

Target commands

ankh devtools lint
ankh devtools format
ankh devtools knip

These may simply delegate to the existing package binaries.

Acceptance criteria

• package.json.ankh metadata exists.
• Provider commands are optional but metadata is valid.
• Existing binaries continue to work unchanged.
• @ankhorage/doctor can validate this package as an adopted Ankhorage package.

[artiphishle]

ankhorage/devtools#16 — Real Devtools Provider Adoption

Summary

Implement @ankhorage/devtools as a real Ankh provider, not metadata-only.

This issue should:

• add truthful package.json.ankh metadata
• add a real provider manifest and handlers for lint, format, and knip
• preserve the existing standalone binaries
• add the minimum package-shape/script work needed so @ankhorage/doctor validate . can pass
• keep docs manual, with a lightweight docs validation script
• avoid Paradox, @ankhorage/dev, CI-policy behavior, and any future command surface

Locked provider surface:

• category: devtools
• commands: lint, format, knip
• capabilities:
  • devtools.lint
  • devtools.format
  • devtools.knip

Public and Internal Interfaces

Add the shared runner API explicitly:

export type DevtoolsToolName = 'lint' | 'format' | 'knip';

export type DevtoolsRunResult = {
  exitCode: number;
};

export type DevtoolsCommandDefinition = {
  path: readonly [DevtoolsToolName];
  capability: 'devtools.lint' | 'devtools.format' | 'devtools.knip';
  summary: string;
  packageName: 'eslint' | 'prettier' | 'knip';
  binName: 'eslint' | 'prettier' | 'knip';
};

export async function runDevtoolsCommand(
  command: DevtoolsCommandDefinition,
  argv: readonly string[],
  options?: {
    cwd?: string;
    env?: NodeJS.ProcessEnv;
  },
): Promise<DevtoolsRunResult>;

Execution boundary rules:

• process.exit is allowed only in executable CLI entry files
• process.exit is forbidden in shared runner code
• process.exit is forbidden in provider code

Call sites should follow this shape:

• standalone binaries:
  • const result = await runDevtoolsCommand(command, process.argv.slice(2));
  • process.exit(result.exitCode);
• provider handlers:
  • const result = await runDevtoolsCommand(command, request.argv);
  • return { exitCode: result.exitCode };

Implementation Changes

Package shape and metadata

Update package.json to:

• add top-level ankh:
  • category: "devtools"
  • provider: "./dist/ankh.provider.js"
  • capabilities: ["devtools.lint", "devtools.format", "devtools.knip"]
• add the missing doctor-required scripts:
  • typecheck
  • docs
  • docs:check
  • changeset
  • changeset:status
• keep existing binaries unchanged:
  • ankhorage-eslint
  • ankhorage-prettier
  • ankhorage-knip
• add @ankhorage/ankh as a devDependency for type-only provider imports
• keep @ankhorage/paradox absent
• keep the public scope limited to devtools primitives only

Do not:

• add dev category metadata
• advertise any capability without a working handler
• add future commands

Shared command table and safe delegation runner

Add one shared internal command table as the single source of truth for:

• provider command descriptors
• provider handlers
• tests
• standalone binary wiring

The exact three entries should be:

• lint -> devtools.lint -> package eslint -> bin eslint
• format -> devtools.format -> package prettier -> bin prettier
• knip -> devtools.knip -> package knip -> bin knip

Implement runDevtoolsCommand() to:

• resolve the delegated package binary from installed package metadata
• execute it safely
• preserve argv unchanged
• preserve cwd
• preserve env
• inherit stdio
• return the child exit code
• treat spawn errors as exit code 1
• treat signals as non-zero failures with a clear message
• never call process.exit

Execution strategy:

• use process.execPath only when the resolved target is known to be a Node-executable JS entry
• otherwise execute the resolved binary path directly in a platform-safe way
• keep this decision internal to the runner so callers only consume { exitCode }

Refactor current helper logic so:

• package/binary resolution can be reused by both standalone binaries and provider handlers
• the old process-exiting behavior moves out to CLI entry boundaries only

Provider manifest

Add src/ankh.provider.ts with a default export typed via:

• import type { AnkhRuntimeCommandProvider } from '@ankhorage/ankh'

The provider should be generated from the shared command table and include:

• id: "@ankhorage/devtools"
• category: "devtools"
• version from package version
• exact capabilities:
  • devtools.lint
  • devtools.format
  • devtools.knip
• exact commands:
  • path: ["lint"]
  • path: ["format"]
  • path: ["knip"]
• handlers for each command path

Handlers must:

• accept untouched remaining argv from @ankhorage/ankh
• delegate through runDevtoolsCommand()
• return { exitCode }
• not parse or reinterpret tool output

Manual docs validation

Keep the handwritten README.md as the source of truth.

Add:

• docs: bun run docs:check
• docs:check: bun scripts/check-docs.ts

check-docs.ts should:

• assert README.md exists
• assert README mentions:
  • ankh devtools lint
  • ankh devtools format
  • ankh devtools knip
  • category devtools
  • capabilities devtools.lint, devtools.format, devtools.knip
  • existing standalone binaries if still documented
• exit 1 with a clear error if docs are stale or incomplete
• exit 0 otherwise

README updates should document:

• @ankhorage/devtools now participates in Ankh discovery
• it owns primitive lint/format/knip tooling
• ankh devtools lint|format|knip delegates to the underlying tools
• existing ankhorage-eslint, ankhorage-prettier, and ankhorage-knip binaries still work
• this package is not the home for emulator/app/local-dev workflows

Test Plan

Add tests that prove:

Package metadata and package-shape

• package.json.ankh exactly matches:
  • category devtools
  • provider ./dist/ankh.provider.js
  • capabilities devtools.lint, devtools.format, devtools.knip
• required scripts now exist:
  • build
  • typecheck
  • lint
  • lint:fix
  • format
  • format:check
  • test
  • knip
  • docs
  • changeset
  • changeset:status
  • version-packages
• existing bins remain present
• no @ankhorage/paradox dependency is introduced
• no extra/future capabilities are advertised

Provider surface integrity

• provider default export conforms to AnkhRuntimeCommandProvider
• provider descriptors expose only lint, format, and knip
• every descriptor has exactly one matching handler
• every handler has exactly one matching descriptor
• provider capabilities exactly match the command table surface

Delegation behavior

• lint delegates to the expected underlying binary
• format delegates to the expected underlying binary
• knip delegates to the expected underlying binary
• pass-through argv is preserved unchanged
• cwd/env are preserved
• child exit codes propagate
• spawn errors produce exit code 1
• signal termination produces a non-zero exit code and clear message

Shared-runner proof

• standalone binaries and provider handlers both use runDevtoolsCommand()
• there is no duplicate per-command execution implementation
• shared runner code never calls process.exit

Docs validation

• docs check passes when README mentions the shipped provider surface
• docs check fails with a clear message when one required command/capability reference is missing

Changeset and Validation

Use a minor changeset for @ankhorage/devtools.

Run after implementation:

• bun install
• bun run build
• bun run typecheck
• bun run lint:fix
• bun run format:check
• bun run test
• bun run knip
• bun run docs

Manual acceptance, not CI wiring in this issue:

• bunx @ankhorage/doctor validate .

Assumptions and Defaults

• This issue includes the minimum package-shape fixes needed for doctor#2 compliance, because the current repo would otherwise fail before Ankh metadata matters.
• It does not add doctor validation to CI yet; roadmap step 10 remains separate.
• It does not adopt Paradox; manual README + docs validation is the chosen path here.
• It does not add an aggregate standalone ankhorage-devtools CLI.
• It does not touch @ankhorage/ankh, @ankhorage/contracts, or @ankhorage/dev.
• It does not expand beyond lint, format, and knip.