@ankhorage/devtools 1.3.4 → 1.4.0

package/README.md

@@ -9,6 +9,7 @@ Shared development tools and repository standards for Ankhorage TypeScript proje
 ```text
 src/
 ├── cli/
+├── policy/
 └── tools/
     ├── eslint/
     ├── prettier/
@@ -18,14 +19,15 @@ src/
     └── vscode/
 ```
 
+- `policy`: shared repository runtime policy, including the canonical Bun version
 - `eslint`: shared flat ESLint configuration, automatic project profiles, and the bundled ESLint runner
 - `prettier`: shared Prettier configuration and the bundled Prettier runner
 - `knip`: shared Knip configuration helpers and the bundled Knip runner
-- `package`: merge-aware synchronization of the shared `package.json` tooling contract
+- `package`: merge-aware synchronization of the shared `package.json` tooling and Bun runtime contract
 - `workflows`: canonical `.github/workflows/ci.yml` and `release.yml`
 - `vscode`: canonical `.vscode/settings.json` and `extensions.json`
 
-The package owns the supported ESLint, TypeScript ESLint, Prettier, Knip, security, React, React Hooks, React Native, import/sort, unused-import, and formatting-plugin versions used by consuming repositories.
+The package owns the supported ESLint, TypeScript ESLint, Prettier, Knip, security, React, React Hooks, React Native, import/sort, unused-import, and formatting-plugin versions used by consuming repositories. It also owns the Bun runtime version used by Ankhorage repository metadata and managed workflows.
 
 ## Bootstrap
 
@@ -34,7 +36,6 @@ For a repository that does not yet depend on the shared toolchain:
 ```bash
 bun add -D @ankhorage/devtools
 bunx @ankhorage/ankh devtools sync .
-bun install
 ```
 
 After the first install, the normal workflow is:
@@ -45,7 +46,9 @@ ankh devtools sync
 
 The target path is optional and defaults to the current working directory.
 
-Synchronization ensures `@ankhorage/devtools` is declared using the version of the provider performing the sync, installs the standard package scripts, and removes direct devDependencies for tools/plugins owned by devtools. Unrelated package metadata, dependencies, and scripts are preserved.
+Synchronization ensures `@ankhorage/devtools` is declared using the version of the provider performing the sync, installs the standard package scripts, applies the managed Bun runtime policy, and removes direct devDependencies for tools/plugins owned by devtools. When package metadata changes, sync runs `bun install` so installed dependencies and `bun.lock` match the synchronized manifest. Unrelated package metadata, dependencies, and scripts are preserved.
+
+`devtools sync` does not upgrade the globally installed Bun executable. The managed version applies to repository metadata, Bun types, and GitHub workflows.
 
 ## Ankh provider
 
@@ -150,6 +153,8 @@ Synchronization is deterministic and idempotent:
 
 - missing managed artifacts are created
 - outdated centrally owned artifacts are updated
+- the managed Bun runtime version is applied consistently to package metadata and workflows
+- package changes are followed by `bun install`, keeping installed dependencies and `bun.lock` synchronized
 - current artifacts are left untouched
 - unrelated files and package fields are preserved
 - repeated sync produces only `unchanged` results
@@ -247,20 +252,36 @@ export default createKnipConfig();
 
 `knip.config.ts` is create-only after bootstrap so repositories can retain narrow local entries, projects, ignores, binaries, dependencies, or switch to `createKnipMonorepoConfig()` without synchronization overwriting those extensions.
 
+## Managed Bun runtime policy
+
+The canonical Bun policy is defined once in devtools and consumed by both package and workflow synchronization. The current policy is:
+
+```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.
+
 ## Managed package contract
 
 `ankh devtools package sync` merge-updates `package.json` rather than replacing it.
 
 It owns:
 
-- the `@ankhorage/devtools` devDependency version range
+- the `@ankhorage/devtools` dependency version range
+- `packageManager` according to the managed Bun runtime policy
+- the `@types/bun` development dependency according to the managed Bun runtime policy
 - `lint`
 - `lint:fix`
 - `format`
 - `format:check`
 - `knip`
 
-It also removes direct devDependencies for tools and ESLint plugins already provided by `@ankhorage/devtools`. Unrelated scripts, dependencies, metadata, and repository-specific configuration remain unchanged.
+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.
+
+When this managed package contract changes, synchronization runs `bun install`. This updates installed dependencies and `bun.lock` before sync completes. It also removes direct devDependencies for tools and ESLint plugins already provided by `@ankhorage/devtools`. Unrelated scripts, dependencies, metadata, and repository-specific configuration remain unchanged.
 
 ## Managed GitHub Actions workflows
 
@@ -271,7 +292,7 @@ It also removes direct devDependencies for tools and ESLint plugins already prov
 .github/workflows/release.yml
 ```
 
-The CI workflow installs the pinned Bun version with the frozen lockfile, builds before repository-provider validation, runs `bunx @ankhorage/ankh doctor validate .`, and conditionally runs lint, formatting, Knip, tests, typecheck, and Changesets checks.
+Both workflows render their `bun-version` from the same managed Bun runtime policy used for `package.json`. The CI workflow installs that Bun version with the frozen lockfile, builds before repository-provider validation, runs `bunx @ankhorage/ankh doctor validate .`, and conditionally runs lint, formatting, Knip, tests, typecheck, and Changesets checks.
 
 ## Managed VS Code configuration
 

package/dist/cli/runRepositoryCommand.d.ts

@@ -1,6 +1,8 @@
+import { type ManagedFileSyncResult } from '../tools/shared/managedFiles.js';
 import type { DevtoolsRepositoryCommandDefinition } from './commands.js';
 export interface DevtoolsRepositoryCommandContext {
     readonly cwd: string;
+    readonly syncDependencies?: (targetDirectory: string) => Promise<ManagedFileSyncResult>;
     writeStdout(text: string): void;
     writeStderr(text: string): void;
 }

package/dist/cli/runRepositoryCommand.js

@@ -1,6 +1,7 @@
 import { eslintManagedFiles } from '../tools/eslint/managed.js';
 import { knipManagedFiles } from '../tools/knip/managed.js';
 import { inspectPackageManifest, readCurrentDevtoolsVersion, syncPackageManifest, } from '../tools/package/index.js';
+import { planBunDependencySync, syncBunDependencies, } from '../tools/package/syncBunDependencies.js';
 import { prettierManagedFiles } from '../tools/prettier/managed.js';
 import { inspectManagedFiles, resolveManagedTargetDirectory, syncManagedFiles, } from '../tools/shared/managedFiles.js';
 import { vscodeManagedFiles } from '../tools/vscode/index.js';
@@ -52,7 +53,17 @@ async function runStatus(scope, targetDirectory, devtoolsVersion, context) {
 async function runSync(scope, targetDirectory, devtoolsVersion, dryRun, context) {
     const results = [];
     if (scope === 'all' || scope === 'package') {
-        results.push(await syncPackageManifest(targetDirectory, devtoolsVersion, { dryRun }));
+        const packageResult = await syncPackageManifest(targetDirectory, devtoolsVersion, { dryRun });
+        results.push(packageResult);
+        if (packageResult.action !== 'unchanged') {
+            if (dryRun) {
+                results.push(planBunDependencySync(targetDirectory));
+            }
+            else {
+                const syncDependencies = context.syncDependencies ?? syncBunDependencies;
+                results.push(await syncDependencies(targetDirectory));
+            }
+        }
     }
     results.push(...(await syncManagedFiles(targetDirectory, getManagedFiles(scope), { dryRun })));
     writeSyncOutput(results, context);

package/dist/policy/bunRuntimePolicy.d.ts

@@ -0,0 +1,5 @@
+export declare const bunRuntimePolicy: {
+    readonly packageManager: "bun@1.3.14";
+    readonly typesRange: "^1.3.14";
+    readonly version: "1.3.14";
+};

package/dist/policy/bunRuntimePolicy.js

@@ -0,0 +1,5 @@
+export const bunRuntimePolicy = {
+    packageManager: 'bun@1.3.14',
+    typesRange: '^1.3.14',
+    version: '1.3.14',
+};

package/dist/tools/package/index.js

@@ -8,21 +8,23 @@
  * `format`, `format:check`, and `knip` scripts are written.
  * Unrelated manifest fields, scripts, dependencies, and metadata are preserved.
  *
+ * The Bun runtime policy is shared by every repository, including devtools itself. Devtools skips
+ * only its consumer dependency/script normalization so it never attempts to install itself.
+ *
  * Status compares only the fields owned by this contract, so unrelated repository customization
  * does not count as drift. `--dry-run` reports whether `package.json` would be created or updated
  * without writing it, and repeated synchronization is idempotent.
  *
- * The devtools package itself is excluded from the consumer contract to avoid rewriting its own
- * manifest.
- *
  * @readme
  */
 import { readFileSync } from 'node:fs';
 import { readFile, writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
+import { bunRuntimePolicy } from '../../policy/bunRuntimePolicy.js';
 const PACKAGE_PATH = 'package.json';
 const DEVTOOLS_PACKAGE_NAME = '@ankhorage/devtools';
 const ANKH_PACKAGE_NAME = '@ankhorage/ankh';
+const BUN_TYPES_PACKAGE_NAME = '@types/bun';
 const STANDARD_SCRIPTS = {
     lint: 'ankhorage-eslint . --max-warnings=0',
     'lint:fix': 'ankhorage-eslint . --fix --max-warnings=0',
@@ -78,20 +80,23 @@ export async function syncPackageManifest(targetDirectory, devtoolsVersion, opti
 }
 export function applyManagedPackageContract(manifest, devtoolsVersion) {
     if (manifest.name === DEVTOOLS_PACKAGE_NAME) {
-        return manifest;
+        return applyBunRuntimePolicy(manifest);
     }
     const scripts = { ...toRecord(manifest.scripts), ...STANDARD_SCRIPTS };
     const devDependencies = removeOwnedDependencies(toRecord(manifest.devDependencies));
     const dependencies = toRecord(manifest.dependencies);
     applyDevtoolsDependencyPlacement(manifest, dependencies, devDependencies, devtoolsVersion);
-    return {
+    return applyBunRuntimePolicy({
         ...manifest,
         ...normalizedDependencies(manifest, dependencies),
         scripts,
         devDependencies,
-    };
+    });
 }
 export function isManagedPackageContractCurrent(manifest, devtoolsVersion) {
+    if (!hasCurrentBunRuntimePolicy(manifest)) {
+        return false;
+    }
     if (manifest.name === DEVTOOLS_PACKAGE_NAME) {
         return true;
     }
@@ -125,6 +130,20 @@ 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 &&
+        devDependencies[BUN_TYPES_PACKAGE_NAME] === bunRuntimePolicy.typesRange);
+}
 function applyDevtoolsDependencyPlacement(manifest, dependencies, devDependencies, devtoolsVersion) {
     const versionRange = `^${devtoolsVersion}`;
     if (manifest.name === ANKH_PACKAGE_NAME) {

package/dist/tools/package/syncBunDependencies.d.ts

@@ -0,0 +1,3 @@
+import type { ManagedFileSyncResult } from '../shared/managedFiles.js';
+export declare function planBunDependencySync(targetDirectory: string): ManagedFileSyncResult;
+export declare function syncBunDependencies(targetDirectory: string): Promise<ManagedFileSyncResult>;

package/dist/tools/package/syncBunDependencies.js

@@ -0,0 +1,30 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+export function planBunDependencySync(targetDirectory) {
+    return {
+        relativePath: 'bun.lock',
+        action: existsSync(resolve(targetDirectory, 'bun.lock')) ? 'would-update' : 'would-create',
+    };
+}
+export async function syncBunDependencies(targetDirectory) {
+    const existed = existsSync(resolve(targetDirectory, 'bun.lock'));
+    await runBunInstall(targetDirectory);
+    return {
+        relativePath: 'bun.lock',
+        action: existed ? 'updated' : 'created',
+    };
+}
+async function runBunInstall(targetDirectory) {
+    await new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn('bun', ['install'], { cwd: targetDirectory, stdio: 'inherit' });
+        child.once('error', rejectPromise);
+        child.once('exit', (code) => {
+            if (code === 0) {
+                resolvePromise();
+                return;
+            }
+            rejectPromise(new Error(`bun install exited with code ${code ?? 'unknown'}.`));
+        });
+    });
+}

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

@@ -22,7 +22,7 @@ jobs:
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2
         with:
-          bun-version: '1.3.13'
+          bun-version: '__ANKH_BUN_VERSION__'
 
       - name: Install dependencies
         run: bun install --frozen-lockfile

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

@@ -27,7 +27,7 @@ jobs:
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2
         with:
-          bun-version: '1.3.13'
+          bun-version: '__ANKH_BUN_VERSION__'
 
       - name: Setup Node for npm publishing
         uses: actions/setup-node@v4

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

@@ -1,7 +1,2 @@
-export declare const workflowManagedFiles: readonly [{
-    readonly relativePath: ".github/workflows/ci.yml";
-    readonly sourceUrl: URL;
-}, {
-    readonly relativePath: ".github/workflows/release.yml";
-    readonly sourceUrl: URL;
-}];
+import type { ManagedFileDefinition } from '../shared/managedFiles.js';
+export declare const workflowManagedFiles: readonly [ManagedFileDefinition, ManagedFileDefinition];

package/dist/tools/workflows/index.js

@@ -1,10 +1,17 @@
+import { readFile } from 'node:fs/promises';
+import { bunRuntimePolicy } from '../../policy/bunRuntimePolicy.js';
+const BUN_VERSION_TOKEN = '__ANKH_BUN_VERSION__';
 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),
-    },
+    createWorkflowDefinition('.github/workflows/ci.yml', './files/ci.yml'),
+    createWorkflowDefinition('.github/workflows/release.yml', './files/release.yml'),
 ];
+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);
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/devtools",
-  "version": "1.3.4",
+  "version": "1.4.0",
   "description": "Shared development tools and repository standards for Ankhorage",
   "license": "MIT",
   "homepage": "https://github.com/ankhorage/devtools#readme",
@@ -116,9 +116,9 @@
     "@ankhorage/ankh": "^0.4.0",
     "@ankhorage/doctor": "0.3.0",
     "@changesets/cli": "^2.30.0",
-    "@types/bun": "^1.3.13",
+    "@types/bun": "^1.3.14",
     "@types/node": "^25.2.3",
     "typescript": "^5.9.3"
   },
-  "packageManager": "bun@1.3.13"
+  "packageManager": "bun@1.3.14"
 }