@ankhorage/devtools 1.1.1 → 1.2.0

package/README.md

@@ -1,26 +1,29 @@
 # devtools
 
-Shared ESLint, Prettier, and Knip configuration for modern TypeScript projects.
+Shared development tools and repository standards for Ankhorage TypeScript projects.
 
-## What you get
+## What it owns
 
-- Consistent linting across repos
-- 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
+`@ankhorage/devtools` is the single source of truth for these equal, separate concerns:
 
-## Features
+```text
+src/
+├── cli/
+└── tools/
+    ├── eslint/
+    ├── prettier/
+    ├── knip/
+    ├── workflows/
+    └── vscode/
+```
+
+- `eslint`: shared flat ESLint configuration and the bundled ESLint runner
+- `prettier`: shared Prettier configuration and the bundled Prettier runner
+- `knip`: shared Knip configuration and the bundled Knip runner
+- `workflows`: canonical `.github/workflows/ci.yml` and `release.yml`
+- `vscode`: canonical `.vscode/settings.json` and `extensions.json`
 
-- Flat ESLint config (latest standard)
-- Preconfigured plugin ecosystem
-- Prettier integration
-- Shared Knip config factories
-- `ankhorage-eslint`, `ankhorage-prettier`, and `ankhorage-knip` binaries
-- `ankh devtools lint`, `ankh devtools format`, and `ankh devtools knip`
-- Monorepo-friendly
+There is no generic template layer around these concerns. Each tool owns its canonical files and behavior.
 
 ## Installation
 
@@ -28,23 +31,43 @@ Shared ESLint, Prettier, and Knip configuration for modern TypeScript projects.
 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.
+The package owns the ESLint, Prettier, and Knip versions used by consuming repositories. Do not install those tools directly unless a repository intentionally opts out of the shared Ankhorage toolchain.
+
+## Ankh provider
 
-It also participates in Ankh package discovery with:
+The package is discovered under the `devtools` category and exposes these capabilities:
 
-- category: `devtools`
-- capabilities:
-  - `devtools.lint`
-  - `devtools.format`
-  - `devtools.knip`
+- `devtools.lint`
+- `devtools.format`
+- `devtools.knip`
+- `devtools.sync`
+- `devtools.status`
+- `devtools.workflows.sync`
+- `devtools.workflows.status`
+- `devtools.vscode.sync`
+- `devtools.vscode.status`
 
-`@ankhorage/devtools` owns primitive lint/format/knip tooling. Local emulator, app, and workstation workflows belong in `@ankhorage/dev`.
+The canonical command prefix is always:
+
+```bash
+ankh devtools ...
+```
+
+## Tool commands
+
+```bash
+ankh devtools lint -- --max-warnings=0 .
+ankh devtools format -- --check .
+ankh devtools knip -- --production
+```
 
-## Usage
+These commands delegate to the same bundled tools as the package binaries:
 
-### Scripts
+- `ankh devtools lint` → `ankhorage-eslint`
+- `ankh devtools format` → `ankhorage-prettier`
+- `ankh devtools knip` → `ankhorage-knip`
 
-Use the devtools-owned binaries in package scripts:
+Recommended package scripts:
 
 ```json
 {
@@ -58,165 +81,169 @@ Use the devtools-owned binaries in package scripts:
 }
 ```
 
-### Ankh commands
+## Repository synchronization
 
-When discovered by `@ankhorage/ankh`, the package exposes:
+### Synchronize all managed files
 
 ```bash
-ankh devtools lint -- --max-warnings=0 .
-ankh devtools format -- --check .
-ankh devtools knip -- --production
+ankh devtools sync .
 ```
 
-These provider-backed commands delegate to the same underlying tools as the standalone binaries:
+The target path is optional and defaults to the current working directory:
+
+```bash
+ankh devtools sync
+```
 
-- `ankh devtools lint` -> `ankhorage-eslint`
-- `ankh devtools format` -> `ankhorage-prettier`
-- `ankh devtools knip` -> `ankhorage-knip`
+### Report drift without changing files
 
-### ESLint
+```bash
+ankh devtools status .
+```
 
-Create an `eslint.config.js` file:
+`status` exits with code `1` when any managed file is missing or outdated. It exits with code `0` when all managed files are current.
 
-```js
-import { createConfig } from '@ankhorage/devtools/eslint';
+Example output:
 
-export default createConfig({
-  files: ['src/**/*.{ts,tsx}'],
-  project: ['./tsconfig.json'],
-  tsconfigRootDir: import.meta.dirname,
-});
+```text
+✓ .github/workflows/ci.yml
+✗ .github/workflows/release.yml outdated
++ .vscode/settings.json missing
+✓ .vscode/extensions.json
 ```
 
-### Prettier
+### Synchronize one concern
 
-Create a Prettier config file:
+```bash
+ankh devtools workflows sync .
+ankh devtools vscode sync .
+```
 
-```js
-export { default } from '@ankhorage/devtools/prettier';
+### Report one concern
+
+```bash
+ankh devtools workflows status .
+ankh devtools vscode status .
 ```
 
-CommonJS repos can use:
+### Preview synchronization
 
-```js
-module.exports = require('@ankhorage/devtools/prettier');
+```bash
+ankh devtools sync . --dry-run
+ankh devtools workflows sync . --dry-run
+ankh devtools vscode sync . --dry-run
 ```
 
-### Knip
+A dry run reports `would create` and `would update` actions without writing any files.
 
-Create a repo-local `knip.config.ts` file:
+## Synchronization guarantees
 
-```ts
-import { createKnipConfig } from '@ankhorage/devtools/knip';
+Synchronization is deterministic and idempotent:
 
-export default createKnipConfig();
-```
+- missing managed files are created
+- outdated managed files are replaced with the canonical package version
+- current managed files are left untouched
+- unrelated files are never modified
+- unknown files in `.github/workflows` and `.vscode` are never deleted
+- repeating `sync` after a successful run produces only `unchanged` results
+- invalid target paths and write failures return a non-zero exit code
 
-Repos can add narrow repo-specific patterns when needed:
+The canonical files are packaged with `@ankhorage/devtools`; synchronization does not fetch mutable files from GitHub at runtime.
 
-```ts
-import { createKnipConfig } from '@ankhorage/devtools/knip';
+## Managed GitHub Actions workflows
 
-export default createKnipConfig({
-  entry: ['scripts/release.ts'],
-  project: ['scripts/**/*.ts'],
-  ignore: ['fixtures/**'],
-  ignoreBinaries: ['custom-tool'],
-  ignoreFiles: ['examples/fixture.ts'],
-});
+`workflows` owns exactly:
+
+```text
+.github/workflows/ci.yml
+.github/workflows/release.yml
 ```
 
-For workspaces-based monorepos, use the monorepo preset:
+The CI workflow:
 
-```ts
-import { createKnipMonorepoConfig } from '@ankhorage/devtools/knip';
+- checks out full history
+- installs the pinned Bun version
+- installs dependencies with `bun install --frozen-lockfile`
+- runs `bunx @ankhorage/ankh doctor validate .`
+- conditionally runs build, lint, format check, Knip, tests, and typecheck when scripts exist
+- conditionally runs `changeset:status` for pull requests when the script exists
 
-export default createKnipMonorepoConfig({
-  root: {
-    ignoreFiles: ['.prettierrc.js', 'eslint.config.js'],
-  },
-});
-```
+The release workflow:
 
-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:
+- checks out full history
+- configures Bun and Node for npm publishing
+- installs dependencies with the frozen lockfile
+- conditionally builds
+- runs the Changesets release PR/publish flow
+- protects release execution with a concurrency group
+- skips cleanly when no Changesets configuration exists
 
-```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'],
-    },
-  },
-});
+## Managed VS Code configuration
+
+`vscode` owns exactly:
+
+```text
+.vscode/settings.json
+.vscode/extensions.json
 ```
 
-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.
+The shared settings use the workspace TypeScript SDK, enable the workspace-SDK prompt, configure intentional ESLint save actions, and enforce basic whitespace/newline consistency.
 
-### CI
+The extension recommendations are limited to the standard Ankhorage workflow:
 
-Run the scripts in CI after dependencies are installed:
+- Bun
+- ESLint
+- Prettier
+- YAML
+- GitHub Actions
 
-```yaml
-- name: Run lint
-  run: bun run lint
+`launch.json` is intentionally not managed globally. Libraries, CLIs, Expo packages, services, and integration repositories require different debug configurations.
 
-- name: Run format check
-  run: bun run format:check
+## ESLint
 
-- name: Run Knip
-  run: bun run knip
-```
+Create `eslint.config.mjs`:
 
-For workflows that support optional scripts, use the same guard style as the other devtools checks:
+```js
+import { createConfig } from '@ankhorage/devtools/eslint';
 
-```yaml
-- name: Run Knip
-  run: |
-    if node -e "const p=require('./package.json'); process.exit(p.scripts?.knip ? 0 : 1)"; then
-      bun run knip
-    else
-      echo "No knip script found; skipping."
-    fi
+export default createConfig({
+  files: ['src/**/*.{ts,tsx}'],
+  project: ['./tsconfig.json'],
+  tsconfigRootDir: import.meta.dirname,
+});
 ```
 
-## Use Cases
+## Prettier
 
-- Monorepos with shared standards
-- Teams that want strict, predictable linting
-- Projects avoiding duplicated config
-- Repos that need consistent unused-file, unused-export, and dependency checks
+ES modules:
 
-## Why this exists
+```js
+export { default } from '@ankhorage/devtools/prettier';
+```
 
-Maintaining ESLint, Prettier, and Knip configs across multiple repositories leads to:
+CommonJS:
 
-- duplication
-- inconsistency
-- drift over time
+```js
+module.exports = require('@ankhorage/devtools/prettier');
+```
+
+## Knip
 
-This package centralizes tooling so all projects stay aligned.
+```ts
+import { createKnipConfig } from '@ankhorage/devtools/knip';
 
-## Scope
+export default createKnipConfig();
+```
 
-Includes:
+Monorepos can use `createKnipMonorepoConfig` and add narrow repository-specific entries, projects, ignores, binaries, dependencies, or workspace overrides.
 
-- 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
+## Adding another managed concern
 
-Excludes:
+A new concern should:
 
-- runtime code
-- build tooling
-- local dev workflows
+1. live in its own sibling directory under `src/tools`
+2. define only the files and behavior it owns
+3. expose deterministic status and synchronization through the shared managed-file engine
+4. add provider commands under `ankh devtools`
+5. include source-tree, built-package, dry-run, status, and idempotence coverage
+6. document overwrite and exit-code behavior

package/dist/cli/bin/eslint.js

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

package/dist/cli/bin/knip.js

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

package/dist/cli/bin/prettier.js

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

package/dist/cli/commands.d.ts

@@ -0,0 +1,25 @@
+export type DevtoolsToolName = 'format' | 'knip' | 'lint';
+type DevtoolsManagedScope = 'all' | 'vscode' | 'workflows';
+type DevtoolsManagedOperation = 'status' | 'sync';
+type DevtoolsCapability = 'devtools.format' | 'devtools.knip' | 'devtools.lint' | 'devtools.status' | 'devtools.sync' | 'devtools.vscode.status' | 'devtools.vscode.sync' | 'devtools.workflows.status' | 'devtools.workflows.sync';
+interface DevtoolsCommandBase {
+    readonly path: readonly [string, ...string[]];
+    readonly capability: DevtoolsCapability;
+    readonly summary: string;
+}
+export interface DevtoolsExternalCommandDefinition extends DevtoolsCommandBase {
+    readonly kind: 'external';
+    readonly toolName: DevtoolsToolName;
+    readonly packageName: 'eslint' | 'knip' | 'prettier';
+    readonly binName: 'eslint' | 'knip' | 'prettier';
+}
+export interface DevtoolsRepositoryCommandDefinition extends DevtoolsCommandBase {
+    readonly kind: 'repository';
+    readonly scope: DevtoolsManagedScope;
+    readonly operation: DevtoolsManagedOperation;
+}
+export type DevtoolsCommandDefinition = DevtoolsExternalCommandDefinition | DevtoolsRepositoryCommandDefinition;
+export declare function getDevtoolsCommands(): readonly DevtoolsCommandDefinition[];
+export declare function findDevtoolsCommandByPath(path: readonly string[]): DevtoolsCommandDefinition | null;
+export declare function getDevtoolsToolCommand(toolName: DevtoolsToolName): DevtoolsExternalCommandDefinition;
+export {};

package/dist/cli/commands.js

@@ -0,0 +1,92 @@
+const DEVTOOLS_COMMANDS = [
+    {
+        kind: 'external',
+        toolName: 'lint',
+        path: ['lint'],
+        capability: 'devtools.lint',
+        summary: 'Run the shared ESLint toolchain.',
+        packageName: 'eslint',
+        binName: 'eslint',
+    },
+    {
+        kind: 'external',
+        toolName: 'format',
+        path: ['format'],
+        capability: 'devtools.format',
+        summary: 'Run the shared Prettier toolchain.',
+        packageName: 'prettier',
+        binName: 'prettier',
+    },
+    {
+        kind: 'external',
+        toolName: 'knip',
+        path: ['knip'],
+        capability: 'devtools.knip',
+        summary: 'Run the shared Knip toolchain.',
+        packageName: 'knip',
+        binName: 'knip',
+    },
+    {
+        kind: 'repository',
+        path: ['sync'],
+        capability: 'devtools.sync',
+        summary: 'Synchronize all centrally managed repository files.',
+        scope: 'all',
+        operation: 'sync',
+    },
+    {
+        kind: 'repository',
+        path: ['status'],
+        capability: 'devtools.status',
+        summary: 'Report drift for all centrally managed repository files.',
+        scope: 'all',
+        operation: 'status',
+    },
+    {
+        kind: 'repository',
+        path: ['workflows', 'sync'],
+        capability: 'devtools.workflows.sync',
+        summary: 'Synchronize the canonical GitHub Actions workflows.',
+        scope: 'workflows',
+        operation: 'sync',
+    },
+    {
+        kind: 'repository',
+        path: ['workflows', 'status'],
+        capability: 'devtools.workflows.status',
+        summary: 'Report drift for the canonical GitHub Actions workflows.',
+        scope: 'workflows',
+        operation: 'status',
+    },
+    {
+        kind: 'repository',
+        path: ['vscode', 'sync'],
+        capability: 'devtools.vscode.sync',
+        summary: 'Synchronize the canonical VS Code workspace configuration.',
+        scope: 'vscode',
+        operation: 'sync',
+    },
+    {
+        kind: 'repository',
+        path: ['vscode', 'status'],
+        capability: 'devtools.vscode.status',
+        summary: 'Report drift for the canonical VS Code workspace configuration.',
+        scope: 'vscode',
+        operation: 'status',
+    },
+];
+export function getDevtoolsCommands() {
+    return DEVTOOLS_COMMANDS;
+}
+export function findDevtoolsCommandByPath(path) {
+    return (DEVTOOLS_COMMANDS.find((command) => command.path.length === path.length &&
+        command.path.every((segment, index) => segment === path[index])) ?? null);
+}
+export function getDevtoolsToolCommand(toolName) {
+    for (const command of DEVTOOLS_COMMANDS) {
+        if (command.kind === 'external' && command.toolName === toolName) {
+            return command;
+        }
+    }
+    throw new Error(`Unknown devtools tool command: ${toolName}`);
+}

package/dist/cli/index.d.ts

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

package/dist/cli/index.js

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs';
-import { getDevtoolsCommands } from '../internal/devtoolsCommands.js';
-import { runDevtoolsCommand } from '../internal/runDevtoolsCommand.js';
+import { getDevtoolsCommands } from './commands.js';
+import { runProviderCommand } from './runProviderCommand.js';
 const packageVersion = readPackageVersion();
 const commands = getDevtoolsCommands();
 const provider = {
@@ -16,8 +16,7 @@ const provider = {
     handlers: commands.map((command) => ({
         path: [...command.path],
         handler: async (request) => {
-            const result = await runDevtoolsCommand(command, request.argv);
-            return { exitCode: result.exitCode };
+            return await runProviderCommand(command, request.argv, request.context);
         },
     })),
 };

package/dist/cli/runExternalTool.d.ts

@@ -0,0 +1,31 @@
+import type { DevtoolsExternalCommandDefinition } from './commands.js';
+export interface DevtoolsRunResult {
+    readonly exitCode: number;
+}
+interface DevtoolsRunnerOptions {
+    readonly cwd?: string;
+    readonly env?: NodeJS.ProcessEnv;
+}
+interface ResolvedExecutionTarget {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly 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: {
+    readonly cwd: string;
+    readonly env: NodeJS.ProcessEnv;
+    readonly shell: boolean;
+    readonly stdio: 'inherit';
+}) => SpawnedProcess;
+interface DevtoolsRunnerDependencies {
+    readonly logError: (message: string) => void;
+    readonly resolveExecutionTarget: (command: DevtoolsExternalCommandDefinition) => Promise<ResolvedExecutionTarget>;
+    readonly spawnProcess: SpawnProcess;
+}
+export declare function runExternalTool(command: DevtoolsExternalCommandDefinition, argv: readonly string[], options?: DevtoolsRunnerOptions): Promise<DevtoolsRunResult>;
+export declare function runExternalToolWithDependencies(command: DevtoolsExternalCommandDefinition, argv: readonly string[], options: DevtoolsRunnerOptions | undefined, dependencies: DevtoolsRunnerDependencies): Promise<DevtoolsRunResult>;
+export {};

package/dist/{internal/runDevtoolsCommand.js → cli/runExternalTool.js}

@@ -11,10 +11,10 @@ const defaultRunnerDependencies = {
     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 runExternalTool(command, argv, options) {
+    return await runExternalToolWithDependencies(command, argv, options, defaultRunnerDependencies);
 }
-export async function runDevtoolsCommandWithDependencies(command, argv, options, dependencies) {
+export async function runExternalToolWithDependencies(command, argv, options, dependencies) {
     let executionTarget;
     try {
         executionTarget = await dependencies.resolveExecutionTarget(command);

package/dist/cli/runProviderCommand.d.ts

@@ -0,0 +1,8 @@
+import type { DevtoolsCommandDefinition } from './commands.js';
+import { type DevtoolsRepositoryCommandContext } from './runRepositoryCommand.js';
+export interface DevtoolsProviderCommandContext extends DevtoolsRepositoryCommandContext {
+    readonly env: Readonly<Record<string, string | undefined>>;
+}
+export declare function runProviderCommand(command: DevtoolsCommandDefinition, argv: readonly string[], context: DevtoolsProviderCommandContext): Promise<{
+    readonly exitCode: number;
+}>;

package/dist/cli/runProviderCommand.js

@@ -0,0 +1,11 @@
+import { runExternalTool } from './runExternalTool.js';
+import { runRepositoryCommand, } from './runRepositoryCommand.js';
+export async function runProviderCommand(command, argv, context) {
+    if (command.kind === 'external') {
+        return await runExternalTool(command, argv, {
+            cwd: context.cwd,
+            env: { ...context.env },
+        });
+    }
+    return await runRepositoryCommand(command, argv, context);
+}

package/dist/cli/runRepositoryCommand.d.ts

@@ -0,0 +1,16 @@
+import type { DevtoolsRepositoryCommandDefinition } from './commands.js';
+export interface DevtoolsRepositoryCommandContext {
+    readonly cwd: string;
+    writeStdout(text: string): void;
+    writeStderr(text: string): void;
+}
+export interface DevtoolsRepositoryCommandResult {
+    readonly exitCode: number;
+}
+interface ParsedRepositoryArguments {
+    readonly dryRun: boolean;
+    readonly targetPath: string | undefined;
+}
+export declare function runRepositoryCommand(command: DevtoolsRepositoryCommandDefinition, argv: readonly string[], context: DevtoolsRepositoryCommandContext): Promise<DevtoolsRepositoryCommandResult>;
+export declare function parseRepositoryArguments(argv: readonly string[], allowDryRun: boolean): ParsedRepositoryArguments;
+export {};