@ankhorage/devtools 1.7.0 → 1.7.1

package/README.md

@@ -258,13 +258,17 @@ export default createKnipConfig();
 
 The canonical Bun policy is defined once in devtools and consumed by both package and workflow synchronization. The current policy is:
 
+<!-- devtools-bun-policy:start -->
+
 ```text
 Bun runtime       1.3.14
 packageManager    bun@1.3.14
 @types/bun        ^1.3.14
 ```
 
-Changing the policy in devtools therefore updates the repository-facing Bun version consistently instead of maintaining independent version literals in multiple templates.
+<!-- devtools-bun-policy:end -->
+
+Renovate owns the single `BUN_VERSION` literal in `src/policy/bunRuntimePolicy.ts`. Its trusted base-branch workflow invokes `bun scripts/sync-renovate-owner.ts sync repository` to regenerate `packageManager`, `@types/bun`, the Bun workflow setup versions, this documentation block, and `bun.lock`, then runs `bun scripts/sync-renovate-owner.ts status repository` to reject stale generated artifacts. Do not synchronize those values manually in a Renovate branch.
 
 ## Managed package contract
 
@@ -279,7 +283,7 @@ It owns:
 - `lint:fix`
 - `format`
 - `format:check`
-- `knip`
+- `knip:check`
 
 For normal consumers, `@ankhorage/devtools` is a devDependency. `@ankhorage/ankh` keeps devtools as a runtime dependency because it loads the provider. Devtools itself participates in the Bun runtime policy without attempting to install itself as a consumer dependency.
 

package/dist/cli/index.d.ts

@@ -4,12 +4,12 @@ declare const provider: {
     version: string;
     capabilities: ("devtools.format" | "devtools.knip" | "devtools.lint" | "devtools.status" | "devtools.sync" | "devtools.eslint.status" | "devtools.eslint.sync" | "devtools.knip.status" | "devtools.knip.sync" | "devtools.package.status" | "devtools.package.sync" | "devtools.prettier.status" | "devtools.prettier.sync" | "devtools.vscode.status" | "devtools.vscode.sync" | "devtools.workflows.status" | "devtools.workflows.sync")[];
     commands: {
-        path: [string, ...string[]];
+        path: string[];
         capability: "devtools.format" | "devtools.knip" | "devtools.lint" | "devtools.status" | "devtools.sync" | "devtools.eslint.status" | "devtools.eslint.sync" | "devtools.knip.status" | "devtools.knip.sync" | "devtools.package.status" | "devtools.package.sync" | "devtools.prettier.status" | "devtools.prettier.sync" | "devtools.vscode.status" | "devtools.vscode.sync" | "devtools.workflows.status" | "devtools.workflows.sync";
         summary: string;
     }[];
     handlers: {
-        path: [string, ...string[]];
+        path: string[];
         handler: (request: import("@ankhorage/ankh").AnkhCommandExecutionRequest) => Promise<{
             readonly exitCode: number;
         }>;

package/dist/internal/readmeDocs.js

@@ -1,3 +1,4 @@
+import { bunRuntimePolicy } from '../policy/bunRuntimePolicy.js';
 const REQUIRED_README_SNIPPETS = [
     'ankh devtools lint',
     'ankh devtools format',
@@ -19,6 +20,13 @@ const REQUIRED_README_SNIPPETS = [
     '--dry-run',
     "profile: 'auto'",
     '@ankhorage/utility/project',
+    '<!-- devtools-bun-policy:start -->',
+    '<!-- devtools-bun-policy:end -->',
+    'bun scripts/sync-renovate-owner.ts sync repository',
+    'bun scripts/sync-renovate-owner.ts status',
+    bunRuntimePolicy.version,
+    bunRuntimePolicy.packageManager,
+    bunRuntimePolicy.typesRange,
 ];
 export function getReadmeDocumentationErrors(readmeContents) {
     return REQUIRED_README_SNIPPETS.flatMap((snippet) => readmeContents.includes(snippet)

package/dist/owner/synchronizeRenovateOwnerAsync.d.ts

@@ -0,0 +1,6 @@
+export declare function synchronizeRenovateOwnerAsync(operation: OwnerSyncOperation, targetDirectory: string, options?: OwnerSyncOptions): Promise<void>;
+type OwnerSyncOperation = 'status' | 'sync';
+interface OwnerSyncOptions {
+    readonly runLockfileAsync?: (operation: OwnerSyncOperation, targetDirectory: string) => Promise<void>;
+}
+export {};

package/dist/owner/synchronizeRenovateOwnerAsync.js

@@ -0,0 +1,153 @@
+import { spawn } from 'node:child_process';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { applyBunRuntimePolicy } from '../policy/applyBunRuntimePolicy.js';
+import { nodeRuntimePolicy } from '../policy/bunRuntimePolicy.js';
+import { renderWorkflowAsync } from '../tools/workflows/renderWorkflowAsync.js';
+export async function synchronizeRenovateOwnerAsync(operation, targetDirectory, options = {}) {
+    const target = resolve(targetDirectory);
+    const policy = await readTargetBunPolicyAsync(target);
+    const definitions = await createManagedDefinitionsAsync(target, policy);
+    await assertDevtoolsTargetAsync(target);
+    if (operation === 'sync') {
+        await syncDefinitionsAsync(target, definitions);
+        await (options.runLockfileAsync ?? runBunLockfileAsync)(operation, target);
+    }
+    const outdatedPaths = await getOutdatedPathsAsync(target, definitions);
+    if (outdatedPaths.length > 0) {
+        throw new Error(`Stale Devtools owner policy artifacts: ${outdatedPaths.join(', ')}`);
+    }
+    if (operation === 'status') {
+        await (options.runLockfileAsync ?? runBunLockfileAsync)(operation, target);
+    }
+}
+async function assertDevtoolsTargetAsync(targetDirectory) {
+    const manifest = JSON.parse(await readFile(resolve(targetDirectory, 'package.json'), 'utf8'));
+    if (!isRecord(manifest) || manifest.name !== '@ankhorage/devtools') {
+        throw new Error('The Renovate owner sync target must be @ankhorage/devtools.');
+    }
+}
+async function createManagedDefinitionsAsync(targetDirectory, policy) {
+    const manifest = JSON.parse(await readFile(resolve(targetDirectory, 'package.json'), 'utf8'));
+    if (!isRecord(manifest)) {
+        throw new Error('Devtools package.json must contain a JSON object.');
+    }
+    const readme = await readFile(resolve(targetDirectory, 'README.md'), 'utf8');
+    const workflowPolicy = {
+        bunVersion: policy.version,
+        nodeVersion: nodeRuntimePolicy.setupVersion,
+    };
+    return [
+        {
+            relativePath: 'package.json',
+            contents: serializePackageManifest(applyBunRuntimePolicy(manifest, policy)),
+        },
+        {
+            relativePath: '.github/workflows/ci.yml',
+            contents: await renderWorkflowAsync(new URL('../tools/workflows/files/ci.yml', import.meta.url), workflowPolicy),
+        },
+        {
+            relativePath: '.github/workflows/release.yml',
+            contents: await renderWorkflowAsync(new URL('../tools/workflows/files/release.yml', import.meta.url), workflowPolicy),
+        },
+        {
+            relativePath: '.github/workflows/renovate.yml',
+            contents: await renderWorkflowAsync(new URL('../tools/workflows/files/renovate.yml', import.meta.url), workflowPolicy),
+        },
+        {
+            relativePath: 'README.md',
+            contents: replaceReadmePolicy(readme, policy),
+        },
+    ];
+}
+async function getOutdatedPathsAsync(targetDirectory, definitions) {
+    const results = await Promise.all(definitions.map(async ({ contents, relativePath }) => {
+        const current = await readFile(resolve(targetDirectory, relativePath), 'utf8').catch((error) => {
+            if (isNodeError(error) && error.code === 'ENOENT')
+                return null;
+            throw error;
+        });
+        return current === contents ? null : relativePath;
+    }));
+    return results.filter((relativePath) => relativePath !== null);
+}
+function isNodeError(error) {
+    return error instanceof Error && 'code' in error;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+async function readTargetBunPolicyAsync(targetDirectory) {
+    const contents = await readFile(resolve(targetDirectory, 'src/policy/bunRuntimePolicy.ts'), 'utf8');
+    const matches = [...contents.matchAll(BUN_VERSION_PATTERN)];
+    const version = matches.length === 1 ? matches[0]?.[1] : undefined;
+    if (version === undefined) {
+        throw new Error('Expected exactly one canonical BUN_VERSION literal in the target policy.');
+    }
+    return {
+        packageManager: `bun@${version}`,
+        typesRange: `^${version}`,
+        version,
+    };
+}
+function replaceReadmePolicy(readme, policy) {
+    const startIndex = readme.indexOf(README_POLICY_START);
+    const endIndex = readme.indexOf(README_POLICY_END);
+    if (startIndex === -1 || endIndex === -1 || endIndex < startIndex) {
+        throw new Error('README.md must contain one ordered Devtools Bun policy marker pair.');
+    }
+    if (readme.includes(README_POLICY_START, startIndex + README_POLICY_START.length) ||
+        readme.includes(README_POLICY_END, endIndex + README_POLICY_END.length)) {
+        throw new Error('README.md must contain exactly one Devtools Bun policy marker pair.');
+    }
+    const replacement = `${README_POLICY_START}\n\n${renderReadmePolicy(policy)}\n\n${README_POLICY_END}`;
+    return `${readme.slice(0, startIndex)}${replacement}${readme.slice(endIndex + README_POLICY_END.length)}`;
+}
+function renderReadmePolicy(policy) {
+    return `\`\`\`text
+Bun runtime       ${policy.version}
+packageManager    ${policy.packageManager}
+@types/bun        ${policy.typesRange}
+\`\`\``;
+}
+async function runBunLockfileAsync(operation, targetDirectory) {
+    const args = [
+        'install',
+        '--cwd',
+        targetDirectory,
+        '--ignore-scripts',
+        '--lockfile-only',
+        '--registry=https://registry.npmjs.org',
+    ];
+    if (operation === 'status')
+        args.push('--frozen-lockfile');
+    await new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn('bun', args, { stdio: 'inherit' });
+        child.once('error', rejectPromise);
+        child.once('exit', (code) => {
+            if (code === 0)
+                return resolvePromise();
+            rejectPromise(new Error(`Bun lockfile ${operation} exited with code ${code ?? 'unknown'}.`));
+        });
+    });
+}
+function serializePackageManifest(manifest) {
+    return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+async function syncDefinitionsAsync(targetDirectory, definitions) {
+    for (const { contents, relativePath } of definitions) {
+        const targetPath = resolve(targetDirectory, relativePath);
+        const current = await readFile(targetPath, 'utf8').catch((error) => {
+            if (isNodeError(error) && error.code === 'ENOENT')
+                return null;
+            throw error;
+        });
+        if (current === contents)
+            continue;
+        await mkdir(dirname(targetPath), { recursive: true });
+        await writeFile(targetPath, contents, 'utf8');
+    }
+}
+const BUN_VERSION_PATTERN = /const BUN_VERSION = '(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)';/gu;
+const README_POLICY_END = '<!-- devtools-bun-policy:end -->';
+const README_POLICY_START = '<!-- devtools-bun-policy:start -->';

package/dist/policy/applyBunRuntimePolicy.d.ts

@@ -0,0 +1,4 @@
+export declare function applyBunRuntimePolicy(manifest: Record<string, unknown>, policy: {
+    readonly packageManager: string;
+    readonly typesRange: string;
+}): Record<string, unknown>;

package/dist/policy/applyBunRuntimePolicy.js

@@ -0,0 +1,15 @@
+export function applyBunRuntimePolicy(manifest, policy) {
+    const devDependencies = toRecord(manifest.devDependencies);
+    devDependencies['@types/bun'] = policy.typesRange;
+    return {
+        ...manifest,
+        packageManager: policy.packageManager,
+        devDependencies,
+    };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function toRecord(value) {
+    return isRecord(value) ? { ...value } : {};
+}

package/dist/policy/bunRuntimePolicy.d.ts

@@ -1,9 +1,3 @@
-/**
- * Canonical runtime/tooling policies for Ankhorage repositories.
- *
- * Import these from `@ankhorage/devtools/policy` when another package needs to inspect
- * the managed Bun or Node baseline without defining an independent version authority.
- */
 export declare const bunRuntimePolicy: {
     readonly packageManager: "bun@1.3.14";
     readonly typesRange: "^1.3.14";

package/dist/policy/bunRuntimePolicy.js

@@ -4,10 +4,11 @@
  * Import these from `@ankhorage/devtools/policy` when another package needs to inspect
  * the managed Bun or Node baseline without defining an independent version authority.
  */
+const BUN_VERSION = '1.3.14';
 export const bunRuntimePolicy = {
-    packageManager: 'bun@1.3.14',
-    typesRange: '^1.3.14',
-    version: '1.3.14',
+    packageManager: `bun@${BUN_VERSION}`,
+    typesRange: `^${BUN_VERSION}`,
+    version: BUN_VERSION,
 };
 /**
  * Canonical Node LTS baseline for Node-based Ankhorage tooling and CI execution.

package/dist/tools/package/index.js

@@ -20,6 +20,7 @@
 import { readFileSync } from 'node:fs';
 import { readFile, writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
+import { applyBunRuntimePolicy } from '../../policy/applyBunRuntimePolicy.js';
 import { bunRuntimePolicy } from '../../policy/bunRuntimePolicy.js';
 const PACKAGE_PATH = 'package.json';
 const DEVTOOLS_PACKAGE_NAME = '@ankhorage/devtools';
@@ -80,7 +81,7 @@ export async function syncPackageManifest(targetDirectory, devtoolsVersion, opti
 }
 export function applyManagedPackageContract(manifest, devtoolsVersion) {
     if (manifest.name === DEVTOOLS_PACKAGE_NAME) {
-        return applyBunRuntimePolicy(manifest);
+        return applyBunRuntimePolicy(manifest, bunRuntimePolicy);
     }
     const scripts = { ...toRecord(manifest.scripts) };
     delete scripts.knip;
@@ -93,7 +94,7 @@ export function applyManagedPackageContract(manifest, devtoolsVersion) {
         ...normalizedDependencies(manifest, dependencies),
         scripts,
         devDependencies,
-    });
+    }, bunRuntimePolicy);
 }
 export function isManagedPackageContractCurrent(manifest, devtoolsVersion) {
     if (!hasCurrentBunRuntimePolicy(manifest)) {
@@ -132,15 +133,6 @@ async function readPackageManifest(targetDirectory) {
         throw error;
     }
 }
-function applyBunRuntimePolicy(manifest) {
-    const devDependencies = toRecord(manifest.devDependencies);
-    devDependencies[BUN_TYPES_PACKAGE_NAME] = bunRuntimePolicy.typesRange;
-    return {
-        ...manifest,
-        packageManager: bunRuntimePolicy.packageManager,
-        devDependencies,
-    };
-}
 function hasCurrentBunRuntimePolicy(manifest) {
     const devDependencies = toRecord(manifest.devDependencies);
     return (manifest.packageManager === bunRuntimePolicy.packageManager &&

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

@@ -18,4 +18,4 @@ jobs:
       github.actor == 'renovate[bot]' &&
       github.event.pull_request.head.repo.full_name == github.repository &&
       startsWith(github.event.pull_request.head.ref, 'renovate/')
-    uses: ankhorage/renovate/.github/workflows/changeset.yml@b7305e8f17f9b07238f6b827bbc9f866fd498a0f
+    uses: ankhorage/renovate/.github/workflows/changeset.yml@7d4a5104b94e763ca5be34919f4fcfbb12efd526

package/dist/tools/workflows/index.js

@@ -1,7 +1,5 @@
-import { readFile } from 'node:fs/promises';
 import { bunRuntimePolicy, nodeRuntimePolicy } from '../../policy/bunRuntimePolicy.js';
-const BUN_VERSION_TOKEN = '__ANKH_BUN_VERSION__';
-const NODE_VERSION_TOKEN = '__ANKH_NODE_VERSION__';
+import { renderWorkflowAsync } from './renderWorkflowAsync.js';
 export const workflowManagedFiles = [
     createWorkflowDefinition('.github/workflows/ci.yml', './files/ci.yml'),
     createWorkflowDefinition('.github/workflows/release.yml', './files/release.yml'),
@@ -11,11 +9,9 @@ function createWorkflowDefinition(relativePath, sourcePath) {
     const sourceUrl = new URL(sourcePath, import.meta.url);
     return {
         relativePath,
-        render: async () => {
-            const template = await readFile(sourceUrl, 'utf8');
-            return template
-                .replaceAll(BUN_VERSION_TOKEN, bunRuntimePolicy.version)
-                .replaceAll(NODE_VERSION_TOKEN, nodeRuntimePolicy.setupVersion);
-        },
+        render: async () => await renderWorkflowAsync(sourceUrl, {
+            bunVersion: bunRuntimePolicy.version,
+            nodeVersion: nodeRuntimePolicy.setupVersion,
+        }),
     };
 }

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

@@ -0,0 +1,4 @@
+export declare function renderWorkflowAsync(sourceUrl: URL, policy: {
+    readonly bunVersion: string;
+    readonly nodeVersion: string;
+}): Promise<string>;

package/dist/tools/workflows/renderWorkflowAsync.js

@@ -0,0 +1,9 @@
+import { readFile } from 'node:fs/promises';
+export async function renderWorkflowAsync(sourceUrl, policy) {
+    const template = await readFile(sourceUrl, 'utf8');
+    return template
+        .replaceAll(BUN_VERSION_TOKEN, policy.bunVersion)
+        .replaceAll(NODE_VERSION_TOKEN, policy.nodeVersion);
+}
+const BUN_VERSION_TOKEN = '__ANKH_BUN_VERSION__';
+const NODE_VERSION_TOKEN = '__ANKH_NODE_VERSION__';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/devtools",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "description": "Shared development tools and repository standards for Ankhorage",
   "license": "MIT",
   "homepage": "https://github.com/ankhorage/devtools#readme",
@@ -86,7 +86,7 @@
     "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",
+    "knip:check": "knip",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix --max-warnings=0",
     "format": "prettier --write .",
@@ -99,7 +99,7 @@
     "version-packages": "changeset version"
   },
   "dependencies": {
-    "@ankhorage/utility": "^0.1.1",
+    "@ankhorage/utility": "^0.2.0",
     "@eslint/compat": "^2.1.0",
     "@eslint/js": "^10.0.1",
     "eslint": "^10.7.0",
@@ -117,8 +117,8 @@
     "typescript-eslint": "^8.24.0"
   },
   "devDependencies": {
-    "@ankhorage/ankh": "^0.4.0",
-    "@ankhorage/doctor": "0.3.0",
+    "@ankhorage/ankh": "^0.8.2",
+    "@ankhorage/doctor": "0.10.1",
     "@changesets/cli": "^2.30.0",
     "@types/bun": "^1.3.14",
     "@types/node": "^25.2.3",