@ankhorage/devtools 1.1.2 → 1.2.0

package/dist/cli/runRepositoryCommand.js

@@ -0,0 +1,108 @@
+import { inspectManagedFiles, resolveManagedTargetDirectory, syncManagedFiles, } from '../tools/shared/managedFiles.js';
+import { vscodeManagedFiles } from '../tools/vscode/index.js';
+import { workflowManagedFiles } from '../tools/workflows/index.js';
+export async function runRepositoryCommand(command, argv, context) {
+    let parsedArguments;
+    try {
+        parsedArguments = parseRepositoryArguments(argv, command.operation === 'sync');
+    }
+    catch (error) {
+        context.writeStderr(`${getErrorMessage(error)}\n`);
+        return { exitCode: 1 };
+    }
+    try {
+        const targetDirectory = await resolveManagedTargetDirectory(context.cwd, parsedArguments.targetPath);
+        const definitions = getManagedFiles(command.scope);
+        if (command.operation === 'status') {
+            const statuses = await inspectManagedFiles(targetDirectory, definitions);
+            writeStatusOutput(statuses, context);
+            return {
+                exitCode: statuses.some((status) => status.state !== 'current') ? 1 : 0,
+            };
+        }
+        const results = await syncManagedFiles(targetDirectory, definitions, {
+            dryRun: parsedArguments.dryRun,
+        });
+        writeSyncOutput(results, context);
+        return { exitCode: 0 };
+    }
+    catch (error) {
+        context.writeStderr(`${getErrorMessage(error)}\n`);
+        return { exitCode: 1 };
+    }
+}
+export function parseRepositoryArguments(argv, allowDryRun) {
+    let dryRun = false;
+    let targetPath;
+    for (const argument of argv) {
+        if (argument === '--dry-run') {
+            if (!allowDryRun) {
+                throw new Error('--dry-run is only valid for sync commands.');
+            }
+            dryRun = true;
+            continue;
+        }
+        if (argument.startsWith('-')) {
+            throw new Error(`Unknown option: ${argument}`);
+        }
+        if (targetPath !== undefined) {
+            throw new Error('Only one target path may be provided.');
+        }
+        targetPath = argument;
+    }
+    return { dryRun, targetPath };
+}
+function getManagedFiles(scope) {
+    if (scope === 'workflows') {
+        return workflowManagedFiles;
+    }
+    if (scope === 'vscode') {
+        return vscodeManagedFiles;
+    }
+    return [...workflowManagedFiles, ...vscodeManagedFiles];
+}
+function writeStatusOutput(statuses, context) {
+    for (const status of statuses) {
+        if (status.state === 'current') {
+            context.writeStdout(`✓ ${status.relativePath}\n`);
+        }
+        else if (status.state === 'missing') {
+            context.writeStdout(`+ ${status.relativePath} missing\n`);
+        }
+        else {
+            context.writeStdout(`✗ ${status.relativePath} outdated\n`);
+        }
+    }
+}
+function writeSyncOutput(results, context) {
+    for (const result of results) {
+        const prefix = getActionPrefix(result.action);
+        context.writeStdout(`${prefix} ${result.relativePath} ${formatAction(result.action)}\n`);
+    }
+}
+function getActionPrefix(action) {
+    if (action === 'unchanged') {
+        return '✓';
+    }
+    if (action === 'created' || action === 'would-create') {
+        return '+';
+    }
+    return '↻';
+}
+function formatAction(action) {
+    switch (action) {
+        case 'created':
+            return 'created';
+        case 'updated':
+            return 'updated';
+        case 'unchanged':
+            return 'unchanged';
+        case 'would-create':
+            return 'would create';
+        case 'would-update':
+            return 'would update';
+    }
+}
+function getErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/cli/runStandaloneTool.d.ts

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

package/dist/cli/runStandaloneTool.js

@@ -0,0 +1,5 @@
+import { getDevtoolsToolCommand } from './commands.js';
+import { runExternalTool } from './runExternalTool.js';
+export async function runStandaloneTool(toolName, argv) {
+    return await runExternalTool(getDevtoolsToolCommand(toolName), argv);
+}

package/dist/internal/readmeDocs.js

@@ -2,13 +2,13 @@ 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',
+    'ankh devtools sync',
+    'ankh devtools status',
+    'ankh devtools workflows sync',
+    'ankh devtools vscode sync',
+    'devtools.workflows.sync',
+    'devtools.vscode.sync',
+    '--dry-run',
 ];
 export function getReadmeDocumentationErrors(readmeContents) {
     return REQUIRED_README_SNIPPETS.flatMap((snippet) => readmeContents.includes(snippet)

package/dist/{eslint.d.ts → tools/eslint/index.d.ts}

@@ -6,3 +6,4 @@ export declare const defaultRestrictedImports: readonly [{
     readonly message: "Forbidden in Ankhorage packages. Use '@ankhorage/react-native-reanimated-dnd-web' directly.";
 }];
 export declare function createConfig(options: DevtoolsConfigOptions): ReturnType<typeof tseslint.config>;
+export type { DevtoolsConfigOptions, FlatConfigItem } from './types.js';

package/dist/tools/eslint/types.d.ts

@@ -0,0 +1,18 @@
+import type tseslint from 'typescript-eslint';
+type FlatConfig = ReturnType<typeof tseslint.config>;
+export type FlatConfigItem = FlatConfig[number];
+interface RestrictedImport {
+    readonly name: string;
+    readonly message: string;
+}
+export interface DevtoolsConfigOptions {
+    readonly tsconfigRootDir: string;
+    readonly project: string[];
+    readonly files: string[];
+    readonly allowDefaultProject?: string[];
+    readonly additionalIgnores?: string[];
+    readonly restrictedImports?: RestrictedImport[];
+    readonly overrides?: FlatConfigItem[];
+    readonly includePrettier?: boolean;
+}
+export {};

package/dist/tools/knip/index.d.ts

@@ -0,0 +1,20 @@
+import type { KnipConfig } from 'knip';
+export interface DevtoolsKnipWorkspaceConfigOptions {
+    readonly entry?: string[];
+    readonly project?: string[];
+    readonly ignore?: string[];
+    readonly ignoreBinaries?: string[];
+    readonly ignoreDependencies?: (string | RegExp)[];
+    readonly ignoreFiles?: string[];
+}
+export interface DevtoolsKnipConfigOptions extends DevtoolsKnipWorkspaceConfigOptions {
+    readonly workspaces?: Record<string, DevtoolsKnipWorkspaceConfigOptions>;
+}
+export interface DevtoolsKnipMonorepoConfigOptions {
+    readonly root?: DevtoolsKnipWorkspaceConfigOptions;
+    readonly workspaceDefaults?: DevtoolsKnipWorkspaceConfigOptions;
+    readonly workspaceGlobs?: string[];
+    readonly workspaces?: Record<string, DevtoolsKnipWorkspaceConfigOptions>;
+}
+export declare function createKnipConfig(options?: DevtoolsKnipConfigOptions): KnipConfig;
+export declare function createKnipMonorepoConfig(options?: DevtoolsKnipMonorepoConfigOptions): KnipConfig;

package/dist/tools/shared/managedFiles.d.ts

@@ -0,0 +1,20 @@
+export interface ManagedFileDefinition {
+    readonly relativePath: string;
+    readonly sourceUrl: URL;
+}
+type ManagedFileState = 'current' | 'missing' | 'outdated';
+type ManagedFileSyncAction = 'unchanged' | 'created' | 'updated' | 'would-create' | 'would-update';
+export interface ManagedFileStatus {
+    readonly relativePath: string;
+    readonly state: ManagedFileState;
+}
+export interface ManagedFileSyncResult {
+    readonly relativePath: string;
+    readonly action: ManagedFileSyncAction;
+}
+export declare function resolveManagedTargetDirectory(cwd: string, requestedPath: string | undefined): Promise<string>;
+export declare function inspectManagedFiles(targetDirectory: string, definitions: readonly ManagedFileDefinition[]): Promise<readonly ManagedFileStatus[]>;
+export declare function syncManagedFiles(targetDirectory: string, definitions: readonly ManagedFileDefinition[], options: {
+    readonly dryRun: boolean;
+}): Promise<readonly ManagedFileSyncResult[]>;
+export {};

package/dist/tools/shared/managedFiles.js

@@ -0,0 +1,84 @@
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+export async function resolveManagedTargetDirectory(cwd, requestedPath) {
+    const targetDirectory = resolve(cwd, requestedPath ?? '.');
+    let targetStats;
+    try {
+        targetStats = await stat(targetDirectory);
+    }
+    catch (error) {
+        throw new Error(`Target directory does not exist: ${targetDirectory}`, { cause: error });
+    }
+    if (!targetStats.isDirectory()) {
+        throw new Error(`Target path is not a directory: ${targetDirectory}`);
+    }
+    return targetDirectory;
+}
+export async function inspectManagedFiles(targetDirectory, definitions) {
+    return await Promise.all(definitions.map(async (definition) => {
+        const canonicalContents = await readCanonicalContents(definition);
+        const targetPath = resolve(targetDirectory, definition.relativePath);
+        try {
+            const targetContents = await readFile(targetPath, 'utf8');
+            return {
+                relativePath: definition.relativePath,
+                state: targetContents === canonicalContents ? 'current' : 'outdated',
+            };
+        }
+        catch (error) {
+            if (isMissingFileError(error)) {
+                return {
+                    relativePath: definition.relativePath,
+                    state: 'missing',
+                };
+            }
+            throw new Error(`Failed to inspect managed file: ${targetPath}`, { cause: error });
+        }
+    }));
+}
+export async function syncManagedFiles(targetDirectory, definitions, options) {
+    const statuses = await inspectManagedFiles(targetDirectory, definitions);
+    const definitionsByPath = new Map(definitions.map((definition) => [definition.relativePath, definition]));
+    const results = [];
+    for (const status of statuses) {
+        if (status.state === 'current') {
+            results.push({ relativePath: status.relativePath, action: 'unchanged' });
+            continue;
+        }
+        const definition = definitionsByPath.get(status.relativePath);
+        if (definition === undefined) {
+            throw new Error(`Missing managed file definition for ${status.relativePath}.`);
+        }
+        if (options.dryRun) {
+            results.push({
+                relativePath: status.relativePath,
+                action: status.state === 'missing' ? 'would-create' : 'would-update',
+            });
+            continue;
+        }
+        const targetPath = resolve(targetDirectory, definition.relativePath);
+        await mkdir(dirname(targetPath), { recursive: true });
+        await writeFile(targetPath, await readCanonicalContents(definition), 'utf8');
+        results.push({
+            relativePath: status.relativePath,
+            action: status.state === 'missing' ? 'created' : 'updated',
+        });
+    }
+    return results;
+}
+async function readCanonicalContents(definition) {
+    try {
+        return await readFile(definition.sourceUrl, 'utf8');
+    }
+    catch (error) {
+        throw new Error(`Failed to read canonical managed file: ${definition.relativePath}`, {
+            cause: error,
+        });
+    }
+}
+function isMissingFileError(error) {
+    return isNodeError(error) && error.code === 'ENOENT';
+}
+function isNodeError(error) {
+    return error instanceof Error && 'code' in error;
+}

package/dist/tools/vscode/files/extensions.json

@@ -0,0 +1,9 @@
+{
+  "recommendations": [
+    "oven.bun-vscode",
+    "dbaeumer.vscode-eslint",
+    "esbenp.prettier-vscode",
+    "redhat.vscode-yaml",
+    "github.vscode-github-actions"
+  ]
+}

package/dist/tools/vscode/files/settings.json

@@ -0,0 +1,15 @@
+{
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.formatOnSave": false,
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit"
+  },
+  "eslint.validate": ["javascript", "javascriptreact", "typescript", "typescriptreact"],
+  "typescript.tsdk": "node_modules/typescript/lib",
+  "typescript.enablePromptUseWorkspaceTsdk": true,
+  "files.insertFinalNewline": true,
+  "files.trimFinalNewlines": true,
+  "files.trimTrailingWhitespace": true,
+  "editor.tabSize": 2,
+  "editor.detectIndentation": false
+}

package/dist/tools/vscode/index.d.ts

@@ -0,0 +1,7 @@
+export declare const vscodeManagedFiles: readonly [{
+    readonly relativePath: ".vscode/settings.json";
+    readonly sourceUrl: URL;
+}, {
+    readonly relativePath: ".vscode/extensions.json";
+    readonly sourceUrl: URL;
+}];

package/dist/tools/vscode/index.js

@@ -0,0 +1,10 @@
+export const vscodeManagedFiles = [
+    {
+        relativePath: '.vscode/settings.json',
+        sourceUrl: new URL('./files/settings.json', import.meta.url),
+    },
+    {
+        relativePath: '.vscode/extensions.json',
+        sourceUrl: new URL('./files/extensions.json', import.meta.url),
+    },
+];

package/dist/tools/workflows/files/ci.yml

@@ -0,0 +1,88 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: '1.3.13'
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Validate Ankhorage repository
+        run: bunx @ankhorage/ankh doctor validate .
+
+      - name: Run build
+        run: |
+          if node -e "const p=require('./package.json'); process.exit(p.scripts?.build ? 0 : 1)"; then
+            bun run build
+          else
+            echo "No build script found; skipping."
+          fi
+
+      - name: Run lint
+        run: |
+          if node -e "const p=require('./package.json'); process.exit(p.scripts?.lint ? 0 : 1)"; then
+            bun run lint
+          else
+            echo "No lint script found; skipping."
+          fi
+
+      - name: Run format check
+        run: |
+          if node -e "const p=require('./package.json'); process.exit(p.scripts?.['format:check'] ? 0 : 1)"; then
+            bun run format:check
+          else
+            echo "No format:check script found; skipping."
+          fi
+
+      - 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
+
+      - name: Run tests
+        run: |
+          if node -e "const p=require('./package.json'); process.exit(p.scripts?.test ? 0 : 1)"; then
+            bun run test
+          else
+            echo "No test script found; skipping."
+          fi
+
+      - name: Run typecheck
+        run: |
+          if node -e "const p=require('./package.json'); process.exit(p.scripts?.typecheck ? 0 : 1)"; then
+            bun run typecheck
+          else
+            echo "No typecheck script found; skipping."
+          fi
+
+      - name: Check changesets
+        if: github.event_name == 'pull_request'
+        run: |
+          if node -e "const p=require('./package.json'); process.exit(p.scripts?.['changeset:status'] ? 0 : 1)"; then
+            bun run changeset:status
+          else
+            echo "No changeset:status script found; skipping."
+          fi

package/dist/tools/workflows/files/release.yml

@@ -0,0 +1,65 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  pull-requests: write
+  id-token: write
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: '1.3.13'
+
+      - name: Setup Node for npm publishing
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org
+
+      - name: Update npm
+        run: npm install -g npm@latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build package
+        run: |
+          if node -e "const p=require('./package.json'); process.exit(p.scripts?.build ? 0 : 1)"; then
+            bun run build
+          else
+            echo "No build script found; skipping."
+          fi
+
+      - name: Create release pull request or publish to npm
+        if: hashFiles('.changeset/config.json') != ''
+        uses: changesets/action@v1
+        with:
+          version: bun run version-packages
+          publish: bunx changeset publish
+          commit: Version Packages
+          title: Version Packages
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+
+      - name: Skip release
+        if: hashFiles('.changeset/config.json') == ''
+        run: echo "No Changesets config found; skipping release."

package/dist/tools/workflows/index.d.ts

@@ -0,0 +1,7 @@
+export declare const workflowManagedFiles: readonly [{
+    readonly relativePath: ".github/workflows/ci.yml";
+    readonly sourceUrl: URL;
+}, {
+    readonly relativePath: ".github/workflows/release.yml";
+    readonly sourceUrl: URL;
+}];

package/dist/tools/workflows/index.js

@@ -0,0 +1,10 @@
+export const workflowManagedFiles = [
+    {
+        relativePath: '.github/workflows/ci.yml',
+        sourceUrl: new URL('./files/ci.yml', import.meta.url),
+    },
+    {
+        relativePath: '.github/workflows/release.yml',
+        sourceUrl: new URL('./files/release.yml', import.meta.url),
+    },
+];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ankhorage/devtools",
-  "version": "1.1.2",
-  "description": "Shared Lint and Format Configuration for Ankhorage",
+  "version": "1.2.0",
+  "description": "Shared development tools and repository standards for Ankhorage",
   "license": "MIT",
   "homepage": "https://github.com/ankhorage/devtools#readme",
   "bugs": {
@@ -21,7 +21,13 @@
     "capabilities": [
       "devtools.lint",
       "devtools.format",
-      "devtools.knip"
+      "devtools.knip",
+      "devtools.sync",
+      "devtools.status",
+      "devtools.workflows.sync",
+      "devtools.workflows.status",
+      "devtools.vscode.sync",
+      "devtools.vscode.status"
     ]
   },
   "keywords": [
@@ -29,15 +35,15 @@
     "eslint",
     "prettier",
     "knip",
-    "linting",
-    "formatting",
-    "static-analysis",
+    "github-actions",
+    "vscode",
+    "repository-sync",
     "developer-tools"
   ],
   "bin": {
-    "ankhorage-eslint": "./dist/eslint-cli.js",
-    "ankhorage-knip": "./dist/knip-cli.js",
-    "ankhorage-prettier": "./dist/prettier-cli.js"
+    "ankhorage-eslint": "./dist/cli/bin/eslint.js",
+    "ankhorage-knip": "./dist/cli/bin/knip.js",
+    "ankhorage-prettier": "./dist/cli/bin/prettier.js"
   },
   "exports": {
     "./cli": {
@@ -45,15 +51,15 @@
       "import": "./dist/cli/index.js"
     },
     "./eslint": {
-      "types": "./dist/eslint.d.ts",
-      "import": "./dist/eslint.js"
+      "types": "./dist/tools/eslint/index.d.ts",
+      "import": "./dist/tools/eslint/index.js"
     },
     "./knip": {
-      "types": "./dist/knip.d.ts",
-      "import": "./dist/knip.js"
+      "types": "./dist/tools/knip/index.d.ts",
+      "import": "./dist/tools/knip/index.js"
     },
     "./prettier": {
-      "require": "./dist/prettier.cjs"
+      "require": "./dist/tools/prettier/index.cjs"
     }
   },
   "files": [
@@ -63,7 +69,7 @@
     "examples"
   ],
   "scripts": {
-    "build": "rm -rf dist tsconfig.tsbuildinfo && tsc && cp src/prettier.cjs dist/prettier.cjs",
+    "build": "rm -rf dist tsconfig.tsbuildinfo && tsc && mkdir -p dist/tools/prettier dist/tools/workflows dist/tools/vscode && cp src/tools/prettier/index.cjs dist/tools/prettier/index.cjs && cp -R src/tools/workflows/files dist/tools/workflows/files && cp -R src/tools/vscode/files dist/tools/vscode/files",
     "typecheck": "bun x tsc --noEmit -p tsconfig.test.json",
     "doctor": "ankhorage-doctor validate .",
     "knip": "knip",

package/dist/eslint-cli.js

@@ -1,4 +0,0 @@
-#!/usr/bin/env node
-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

@@ -1,11 +0,0 @@
-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

@@ -1,39 +0,0 @@
-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;
-}