@ankhorage/devtools 1.0.5 → 1.1.0

package/README.md

@@ -8,6 +8,7 @@ Shared ESLint, Prettier, and Knip configuration for modern TypeScript projects.
 - Zero-config Prettier setup
 - Shared Knip static-analysis defaults
 - Bundled tool binaries for ESLint, Prettier, and Knip
+- Ankh provider commands for lint, format, and Knip
 - Strict TypeScript rules without compromise
 - One source of truth for tooling
 
@@ -16,8 +17,9 @@ Shared ESLint, Prettier, and Knip configuration for modern TypeScript projects.
 - Flat ESLint config (latest standard)
 - Preconfigured plugin ecosystem
 - Prettier integration
-- Shared Knip config factory
+- Shared Knip config factories
 - `ankhorage-eslint`, `ankhorage-prettier`, and `ankhorage-knip` binaries
+- `ankh devtools lint`, `ankh devtools format`, and `ankh devtools knip`
 - Monorepo-friendly
 
 ## Installation
@@ -28,6 +30,16 @@ bun add -D @ankhorage/devtools
 
 The package owns the ESLint, Prettier, and Knip toolchain. Consuming repos should not install `eslint`, `prettier`, or `knip` directly unless they intentionally need a different version from the shared Ankhorage toolchain.
 
+It also participates in Ankh package discovery with:
+
+- category: `devtools`
+- capabilities:
+  - `devtools.lint`
+  - `devtools.format`
+  - `devtools.knip`
+
+`@ankhorage/devtools` owns primitive lint/format/knip tooling. Local emulator, app, and workstation workflows belong in `@ankhorage/dev`.
+
 ## Usage
 
 ### Scripts
@@ -46,6 +58,22 @@ Use the devtools-owned binaries in package scripts:
 }
 ```
 
+### Ankh commands
+
+When discovered by `@ankhorage/ankh`, the package exposes:
+
+```bash
+ankh devtools lint -- --max-warnings=0 .
+ankh devtools format -- --check .
+ankh devtools knip -- --production
+```
+
+These provider-backed commands delegate to the same underlying tools as the standalone binaries:
+
+- `ankh devtools lint` -> `ankhorage-eslint`
+- `ankh devtools format` -> `ankhorage-prettier`
+- `ankh devtools knip` -> `ankhorage-knip`
+
 ### ESLint
 
 Create an `eslint.config.js` file:
@@ -98,7 +126,41 @@ export default createKnipConfig({
 });
 ```
 
-The shared config intentionally keeps defaults narrow so Knip can use its own zero-config package discovery. Prefer explicit `entry`, `project`, `ignoreBinaries`, `ignoreDependencies`, or `ignoreFiles` over broad ignores.
+For workspaces-based monorepos, use the monorepo preset:
+
+```ts
+import { createKnipMonorepoConfig } from '@ankhorage/devtools/knip';
+
+export default createKnipMonorepoConfig({
+  root: {
+    ignoreFiles: ['.prettierrc.js', 'eslint.config.js'],
+  },
+});
+```
+
+By default, the monorepo preset configures Knip workspaces for the root package, `packages/*`, and `apps/*`. Repos can override those defaults or add extra workspace globs:
+
+```ts
+import { createKnipMonorepoConfig } from '@ankhorage/devtools/knip';
+
+export default createKnipMonorepoConfig({
+  workspaceGlobs: ['packages/*', 'apps/*', 'examples/*'],
+  workspaceDefaults: {
+    ignoreFiles: ['fixtures/**'],
+  },
+  workspaces: {
+    '.': {
+      ignoreFiles: ['.prettierrc.js', 'eslint.config.js'],
+    },
+    'apps/editor': {
+      ignoreFiles: ['babel.config.js'],
+      ignoreDependencies: ['babel-preset-expo'],
+    },
+  },
+});
+```
+
+The shared config intentionally keeps defaults narrow so Knip can still report real unused files, exports, dependencies, and binaries. Prefer explicit `entry`, `project`, `ignoreBinaries`, `ignoreDependencies`, or `ignoreFiles` over broad ignores.
 
 ### CI
 
@@ -151,8 +213,10 @@ Includes:
 - ESLint configuration and binary wrapper
 - Prettier configuration and binary wrapper
 - Knip configuration and binary wrapper
+- Ankh provider descriptors and handlers for lint, format, and Knip
 
 Excludes:
 
 - runtime code
 - build tooling
+- local dev workflows

package/dist/ankh.provider.d.ts

@@ -0,0 +1,18 @@
+declare const provider: {
+    id: string;
+    category: string;
+    version: string;
+    capabilities: ("devtools.format" | "devtools.knip" | "devtools.lint")[];
+    commands: {
+        path: [import("./internal/devtoolsCommands.js").DevtoolsToolName];
+        capability: "devtools.format" | "devtools.knip" | "devtools.lint";
+        summary: string;
+    }[];
+    handlers: {
+        path: [import("./internal/devtoolsCommands.js").DevtoolsToolName];
+        handler: (request: import("@ankhorage/ankh").AnkhCommandExecutionRequest) => Promise<{
+            exitCode: number;
+        }>;
+    }[];
+};
+export default provider;

package/dist/ankh.provider.js

@@ -0,0 +1,37 @@
+import { readFileSync } from 'node:fs';
+import { getDevtoolsCommands } from './internal/devtoolsCommands.js';
+import { runDevtoolsCommand } from './internal/runDevtoolsCommand.js';
+const packageVersion = readPackageVersion();
+const commands = getDevtoolsCommands();
+const provider = {
+    id: '@ankhorage/devtools',
+    category: 'devtools',
+    version: packageVersion,
+    capabilities: commands.map((command) => command.capability),
+    commands: commands.map((command) => ({
+        path: [...command.path],
+        capability: command.capability,
+        summary: command.summary,
+    })),
+    handlers: commands.map((command) => ({
+        path: [...command.path],
+        handler: async (request) => {
+            const result = await runDevtoolsCommand(command, request.argv);
+            return { exitCode: result.exitCode };
+        },
+    })),
+};
+export default provider;
+function readPackageVersion() {
+    const packageJson = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    if (!isRecord(packageJson) || !isNonEmptyString(packageJson.version)) {
+        throw new Error('package.json must define a non-empty version string.');
+    }
+    return packageJson.version;
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim() !== '';
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}

package/dist/eslint-cli.js

@@ -1,3 +1,4 @@
 #!/usr/bin/env node
-import { runPackageBin } from './internal/runPackageBin.js';
-runPackageBin('eslint', 'eslint');
+import { runStandaloneDevtoolsCommand } from './internal/runStandaloneDevtoolsCommand.js';
+const result = await runStandaloneDevtoolsCommand('lint', process.argv.slice(2));
+process.exit(result.exitCode);

package/dist/internal/devtoolsCommands.d.ts

@@ -0,0 +1,11 @@
+export type DevtoolsToolName = 'format' | 'knip' | 'lint';
+export interface DevtoolsCommandDefinition {
+    path: readonly [DevtoolsToolName];
+    capability: 'devtools.format' | 'devtools.knip' | 'devtools.lint';
+    summary: string;
+    packageName: 'eslint' | 'knip' | 'prettier';
+    binName: 'eslint' | 'knip' | 'prettier';
+}
+export declare function getDevtoolsCommands(): readonly DevtoolsCommandDefinition[];
+export declare function findDevtoolsCommandByPath(path: readonly string[]): DevtoolsCommandDefinition | null;
+export declare function getDevtoolsCommand(toolName: DevtoolsToolName): DevtoolsCommandDefinition;

package/dist/internal/devtoolsCommands.js

@@ -0,0 +1,39 @@
+const DEVTOOLS_COMMANDS = [
+    {
+        path: ['lint'],
+        capability: 'devtools.lint',
+        summary: 'Run the shared ESLint toolchain.',
+        packageName: 'eslint',
+        binName: 'eslint',
+    },
+    {
+        path: ['format'],
+        capability: 'devtools.format',
+        summary: 'Run the shared Prettier toolchain.',
+        packageName: 'prettier',
+        binName: 'prettier',
+    },
+    {
+        path: ['knip'],
+        capability: 'devtools.knip',
+        summary: 'Run the shared Knip toolchain.',
+        packageName: 'knip',
+        binName: 'knip',
+    },
+];
+export function getDevtoolsCommands() {
+    return DEVTOOLS_COMMANDS;
+}
+export function findDevtoolsCommandByPath(path) {
+    if (path.length !== 1) {
+        return null;
+    }
+    return DEVTOOLS_COMMANDS.find((command) => command.path[0] === path[0]) ?? null;
+}
+export function getDevtoolsCommand(toolName) {
+    const command = DEVTOOLS_COMMANDS.find((candidate) => candidate.path[0] === toolName);
+    if (command === undefined) {
+        throw new Error(`Unknown devtools command: ${toolName}`);
+    }
+    return command;
+}

package/dist/internal/readmeDocs.d.ts

@@ -0,0 +1 @@
+export declare function getReadmeDocumentationErrors(readmeContents: string): string[];

package/dist/internal/readmeDocs.js

@@ -0,0 +1,17 @@
+const REQUIRED_README_SNIPPETS = [
+    'ankh devtools lint',
+    'ankh devtools format',
+    'ankh devtools knip',
+    'ankhorage-eslint',
+    'ankhorage-prettier',
+    'ankhorage-knip',
+    'devtools',
+    'devtools.lint',
+    'devtools.format',
+    'devtools.knip',
+];
+export function getReadmeDocumentationErrors(readmeContents) {
+    return REQUIRED_README_SNIPPETS.flatMap((snippet) => readmeContents.includes(snippet)
+        ? []
+        : [`README.md is missing required documentation snippet: ${snippet}`]);
+}

package/dist/internal/runDevtoolsCommand.d.ts

@@ -0,0 +1,31 @@
+import type { DevtoolsCommandDefinition, DevtoolsToolName } from './devtoolsCommands.js';
+export type { DevtoolsCommandDefinition, DevtoolsToolName };
+export interface DevtoolsRunResult {
+    exitCode: number;
+}
+interface DevtoolsRunnerOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}
+interface ResolvedExecutionTarget {
+    command: string;
+    args: readonly string[];
+    shell: boolean;
+}
+interface SpawnedProcess {
+    on(event: 'error', listener: (error: Error) => void): SpawnedProcess;
+    on(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): SpawnedProcess;
+}
+type SpawnProcess = (command: string, args: readonly string[], options: {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    shell: boolean;
+    stdio: 'inherit';
+}) => SpawnedProcess;
+interface DevtoolsRunnerDependencies {
+    readonly logError: (message: string) => void;
+    readonly resolveExecutionTarget: (command: DevtoolsCommandDefinition) => Promise<ResolvedExecutionTarget>;
+    readonly spawnProcess: SpawnProcess;
+}
+export declare function runDevtoolsCommand(command: DevtoolsCommandDefinition, argv: readonly string[], options?: DevtoolsRunnerOptions): Promise<DevtoolsRunResult>;
+export declare function runDevtoolsCommandWithDependencies(command: DevtoolsCommandDefinition, argv: readonly string[], options: DevtoolsRunnerOptions | undefined, dependencies: DevtoolsRunnerDependencies): Promise<DevtoolsRunResult>;

package/dist/internal/runDevtoolsCommand.js

@@ -0,0 +1,118 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, extname, join, resolve } from 'node:path';
+const require = createRequire(import.meta.url);
+const defaultRunnerDependencies = {
+    logError: (message) => {
+        console.error(message);
+    },
+    resolveExecutionTarget,
+    spawnProcess: (command, args, options) => spawn(command, args, options),
+};
+export async function runDevtoolsCommand(command, argv, options) {
+    return runDevtoolsCommandWithDependencies(command, argv, options, defaultRunnerDependencies);
+}
+export async function runDevtoolsCommandWithDependencies(command, argv, options, dependencies) {
+    let executionTarget;
+    try {
+        executionTarget = await dependencies.resolveExecutionTarget(command);
+    }
+    catch (error) {
+        dependencies.logError(`Failed to resolve ${command.binName}: ${getErrorMessage(error)}`);
+        return { exitCode: 1 };
+    }
+    const cwd = options?.cwd ?? process.cwd();
+    const env = options?.env ?? process.env;
+    return await new Promise((resolveResult) => {
+        let settled = false;
+        const settle = (result) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            resolveResult(result);
+        };
+        const child = dependencies.spawnProcess(executionTarget.command, [...executionTarget.args, ...argv], {
+            cwd,
+            env,
+            shell: executionTarget.shell,
+            stdio: 'inherit',
+        });
+        child.on('error', (error) => {
+            dependencies.logError(`Failed to start ${command.binName}: ${getErrorMessage(error)}`);
+            settle({ exitCode: 1 });
+        });
+        child.on('exit', (code, signal) => {
+            if (signal !== null) {
+                dependencies.logError(`${command.binName} exited with signal ${signal}.`);
+                settle({ exitCode: 1 });
+                return;
+            }
+            settle({ exitCode: code ?? 1 });
+        });
+    });
+}
+async function resolveExecutionTarget(command) {
+    const binPath = await readPackageBinPath(command.packageName, command.binName);
+    if (await shouldExecuteWithNode(binPath)) {
+        return {
+            command: process.execPath,
+            args: [binPath],
+            shell: false,
+        };
+    }
+    return {
+        command: binPath,
+        args: [],
+        shell: process.platform === 'win32',
+    };
+}
+function findPackageJsonPath(packageName) {
+    let currentDirectory = dirname(require.resolve(packageName));
+    while (currentDirectory !== dirname(currentDirectory)) {
+        const packageJsonPath = join(currentDirectory, 'package.json');
+        if (existsSync(packageJsonPath)) {
+            return packageJsonPath;
+        }
+        currentDirectory = dirname(currentDirectory);
+    }
+    throw new Error(`Could not find package metadata for ${packageName}.`);
+}
+async function readPackageBinPath(packageName, binName) {
+    const packageJsonPath = findPackageJsonPath(packageName);
+    const packageJson = JSON.parse(await readFile(packageJsonPath, 'utf8'));
+    if (!isRecord(packageJson)) {
+        throw new Error(`Package metadata for ${packageName} is not an object.`);
+    }
+    const { bin } = packageJson;
+    let relativeBinPath;
+    if (typeof bin === 'string') {
+        relativeBinPath = bin;
+    }
+    else if (isRecord(bin)) {
+        const namedBin = bin[binName];
+        if (typeof namedBin === 'string') {
+            relativeBinPath = namedBin;
+        }
+    }
+    if (relativeBinPath === undefined) {
+        throw new Error(`Package ${packageName} does not expose a ${binName} binary.`);
+    }
+    return resolve(dirname(packageJsonPath), relativeBinPath);
+}
+async function shouldExecuteWithNode(binPath) {
+    const extension = extname(binPath).toLowerCase();
+    if (extension === '.cjs' || extension === '.js' || extension === '.mjs') {
+        return true;
+    }
+    const firstLine = (await readFile(binPath, 'utf8')).split('\n', 1)[0] ?? '';
+    return firstLine.startsWith('#!') && firstLine.includes('node');
+}
+function getErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}

package/dist/internal/runStandaloneDevtoolsCommand.d.ts

@@ -0,0 +1,3 @@
+import type { DevtoolsToolName } from './runDevtoolsCommand.js';
+import { type DevtoolsRunResult } from './runDevtoolsCommand.js';
+export declare function runStandaloneDevtoolsCommand(toolName: DevtoolsToolName, argv: readonly string[]): Promise<DevtoolsRunResult>;

package/dist/internal/runStandaloneDevtoolsCommand.js

@@ -0,0 +1,5 @@
+import { getDevtoolsCommand } from './devtoolsCommands.js';
+import { runDevtoolsCommand } from './runDevtoolsCommand.js';
+export async function runStandaloneDevtoolsCommand(toolName, argv) {
+    return runDevtoolsCommand(getDevtoolsCommand(toolName), argv);
+}

package/dist/knip-cli.js

@@ -1,3 +1,4 @@
 #!/usr/bin/env node
-import { runPackageBin } from './internal/runPackageBin.js';
-runPackageBin('knip', 'knip');
+import { runStandaloneDevtoolsCommand } from './internal/runStandaloneDevtoolsCommand.js';
+const result = await runStandaloneDevtoolsCommand('knip', process.argv.slice(2));
+process.exit(result.exitCode);

package/dist/knip.d.ts

@@ -10,4 +10,11 @@ export interface DevtoolsKnipWorkspaceConfigOptions {
 export interface DevtoolsKnipConfigOptions extends DevtoolsKnipWorkspaceConfigOptions {
     workspaces?: Record<string, DevtoolsKnipWorkspaceConfigOptions>;
 }
+export interface DevtoolsKnipMonorepoConfigOptions {
+    root?: DevtoolsKnipWorkspaceConfigOptions;
+    workspaceDefaults?: DevtoolsKnipWorkspaceConfigOptions;
+    workspaceGlobs?: string[];
+    workspaces?: Record<string, DevtoolsKnipWorkspaceConfigOptions>;
+}
 export declare function createKnipConfig(options?: DevtoolsKnipConfigOptions): KnipConfig;
+export declare function createKnipMonorepoConfig(options?: DevtoolsKnipMonorepoConfigOptions): KnipConfig;

package/dist/knip.js

@@ -1,3 +1,4 @@
+const DEFAULT_MONOREPO_WORKSPACE_GLOBS = ['packages/*', 'apps/*'];
 export function createKnipConfig(options = {}) {
     return {
         ...(options.entry === undefined ? {} : { entry: options.entry }),
@@ -11,3 +12,20 @@ export function createKnipConfig(options = {}) {
         ...(options.workspaces === undefined ? {} : { workspaces: options.workspaces }),
     };
 }
+export function createKnipMonorepoConfig(options = {}) {
+    const explicitWorkspaces = options.workspaces ?? {};
+    const workspaceGlobs = options.workspaceGlobs ?? [...DEFAULT_MONOREPO_WORKSPACE_GLOBS];
+    const workspaces = {
+        '.': options.root ?? {},
+    };
+    for (const workspaceGlob of workspaceGlobs) {
+        workspaces[workspaceGlob] = {
+            ...(options.workspaceDefaults ?? {}),
+            ...(explicitWorkspaces[workspaceGlob] ?? {}),
+        };
+    }
+    for (const [workspaceGlob, workspaceConfig] of Object.entries(explicitWorkspaces)) {
+        workspaces[workspaceGlob] = workspaceConfig;
+    }
+    return createKnipConfig({ workspaces });
+}

package/dist/prettier-cli.js

@@ -1,3 +1,4 @@
 #!/usr/bin/env node
-import { runPackageBin } from './internal/runPackageBin.js';
-runPackageBin('prettier', 'prettier');
+import { runStandaloneDevtoolsCommand } from './internal/runStandaloneDevtoolsCommand.js';
+const result = await runStandaloneDevtoolsCommand('format', process.argv.slice(2));
+process.exit(result.exitCode);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/devtools",
-  "version": "1.0.5",
+  "version": "1.1.0",
   "description": "Shared Lint and Format Configuration for Ankhorage",
   "homepage": "https://github.com/ankhorage/devtools#readme",
   "bugs": {
@@ -14,6 +14,15 @@
   "publishConfig": {
     "access": "public"
   },
+  "ankh": {
+    "category": "devtools",
+    "provider": "./dist/ankh.provider.js",
+    "capabilities": [
+      "devtools.lint",
+      "devtools.format",
+      "devtools.knip"
+    ]
+  },
   "keywords": [
     "typescript",
     "eslint",
@@ -49,13 +58,18 @@
     "examples"
   ],
   "scripts": {
-    "build": "tsc && cp src/prettier.cjs dist/prettier.cjs",
+    "build": "rm -rf dist tsconfig.tsbuildinfo && tsc && cp src/prettier.cjs dist/prettier.cjs",
+    "typecheck": "bun x tsc --noEmit -p tsconfig.test.json",
     "knip": "knip",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix --max-warnings=0",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
+    "docs": "bun run docs:check",
+    "docs:check": "bun scripts/check-docs.ts",
     "test": "bun test",
+    "changeset": "changeset",
+    "changeset:status": "changeset status --since=origin/main",
     "version-packages": "changeset version"
   },
   "dependencies": {
@@ -71,6 +85,7 @@
     "typescript-eslint": "^8.24.0"
   },
   "devDependencies": {
+    "@ankhorage/ankh": "^0.4.0",
     "@changesets/cli": "^2.30.0",
     "@types/bun": "^1.3.13",
     "@types/node": "^25.2.3",

package/dist/internal/runPackageBin.d.ts

@@ -1 +0,0 @@
-export declare function runPackageBin(packageName: string, binName: string): void;

package/dist/internal/runPackageBin.js

@@ -1,58 +0,0 @@
-import { spawn } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
-import { createRequire } from 'node:module';
-import { dirname, join, resolve } from 'node:path';
-const require = createRequire(import.meta.url);
-function isRecord(value) {
-    return typeof value === 'object' && value !== null;
-}
-function findPackageJsonPath(packageName) {
-    let currentDirectory = dirname(require.resolve(packageName));
-    while (currentDirectory !== dirname(currentDirectory)) {
-        const packageJsonPath = join(currentDirectory, 'package.json');
-        if (existsSync(packageJsonPath)) {
-            return packageJsonPath;
-        }
-        currentDirectory = dirname(currentDirectory);
-    }
-    throw new Error(`Could not find package metadata for ${packageName}.`);
-}
-function readPackageBinPath(packageName, binName) {
-    const packageJsonPath = findPackageJsonPath(packageName);
-    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
-    if (!isRecord(packageJson)) {
-        throw new Error(`Package metadata for ${packageName} is not an object.`);
-    }
-    const { bin } = packageJson;
-    let relativeBinPath;
-    if (typeof bin === 'string') {
-        relativeBinPath = bin;
-    }
-    else if (isRecord(bin)) {
-        const namedBin = bin[binName];
-        if (typeof namedBin === 'string') {
-            relativeBinPath = namedBin;
-        }
-    }
-    if (relativeBinPath === undefined) {
-        throw new Error(`Package ${packageName} does not expose a ${binName} binary.`);
-    }
-    return resolve(dirname(packageJsonPath), relativeBinPath);
-}
-export function runPackageBin(packageName, binName) {
-    const binPath = readPackageBinPath(packageName, binName);
-    const child = spawn(process.execPath, [binPath, ...process.argv.slice(2)], {
-        stdio: 'inherit',
-    });
-    child.on('error', (error) => {
-        console.error(error);
-        process.exit(1);
-    });
-    child.on('exit', (code, signal) => {
-        if (signal !== null) {
-            console.error(`${binName} exited with signal ${signal}.`);
-            process.exit(1);
-        }
-        process.exit(code ?? 1);
-    });
-}