@ankhorage/devtools 1.5.2 → 1.6.1

package/README.md

@@ -154,7 +154,7 @@ 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
+- package changes are followed by `bun install` after all managed files have been written, keeping installed dependencies and `bun.lock` synchronized without invalidating the running sync
 - current artifacts are left untouched
 - unrelated files and package fields are preserved
 - repeated sync produces only `unchanged` results
@@ -232,7 +232,7 @@ Use `eslint.local.config.mjs` for narrow repository-specific flat-config overrid
 
 ## Prettier
 
-`ankh devtools prettier sync` owns `.prettierrc.js` and emits the correct ESM or CommonJS delegate based on the repository's `package.json` module type.
+`ankh devtools prettier sync` owns `.prettierrc.js`, emits the correct ESM or CommonJS wrapper based on the repository's `package.json` module type, and creates `prettier.local.config.js` once for narrow repository-specific options.
 
 The consumer delegates formatting policy to:
 
@@ -240,6 +240,8 @@ The consumer delegates formatting policy to:
 @ankhorage/devtools/prettier
 ```
 
+The wrapper merges shared and local `overrides` in that order. On first synchronization, an existing non-canonical `.prettierrc.js` is preserved as `prettier.local.config.js`; former shared-only Devtools delegates become an empty local config. Later synchronization never overwrites the local file.
+
 ## Knip
 
 `ankh devtools knip sync` bootstraps `knip.config.ts` with:

package/dist/cli/runRepositoryCommand.js

@@ -52,20 +52,22 @@ async function runStatus(scope, targetDirectory, devtoolsVersion, context) {
 }
 async function runSync(scope, targetDirectory, devtoolsVersion, dryRun, context) {
     const results = [];
+    let packageDependenciesChanged = false;
     if (scope === 'all' || scope === 'package') {
         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));
-            }
-        }
+        packageDependenciesChanged = packageResult.action !== 'unchanged';
     }
     results.push(...(await syncManagedFiles(targetDirectory, getManagedFiles(scope), { dryRun })));
+    if (packageDependenciesChanged) {
+        if (dryRun) {
+            results.push(planBunDependencySync(targetDirectory));
+        }
+        else {
+            const syncDependencies = context.syncDependencies ?? syncBunDependencies;
+            results.push(await syncDependencies(targetDirectory));
+        }
+    }
     writeSyncOutput(results, context);
     return { exitCode: 0 };
 }

package/dist/policy/bunRuntimePolicy.d.ts

@@ -1,11 +1,23 @@
 /**
- * Canonical Bun runtime policy for Ankhorage repositories.
+ * Canonical runtime/tooling policies for Ankhorage repositories.
  *
- * Import this from `@ankhorage/devtools/policy` when another package needs to inspect
- * the managed Bun version without defining an independent version authority.
+ * 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";
     readonly version: "1.3.14";
 };
+/**
+ * Canonical Node LTS baseline for Node-based Ankhorage tooling and CI execution.
+ *
+ * Bun remains the repository package manager/primary command runtime where configured;
+ * this policy makes Node-based tooling deterministic instead of inheriting the ambient
+ * Node version from a CI runner image.
+ */
+export declare const nodeRuntimePolicy: {
+    readonly engineRange: "24.x";
+    readonly major: 24;
+    readonly setupVersion: "24";
+};

package/dist/policy/bunRuntimePolicy.js

@@ -1,11 +1,23 @@
 /**
- * Canonical Bun runtime policy for Ankhorage repositories.
+ * Canonical runtime/tooling policies for Ankhorage repositories.
  *
- * Import this from `@ankhorage/devtools/policy` when another package needs to inspect
- * the managed Bun version without defining an independent version authority.
+ * 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 const bunRuntimePolicy = {
     packageManager: 'bun@1.3.14',
     typesRange: '^1.3.14',
     version: '1.3.14',
 };
+/**
+ * Canonical Node LTS baseline for Node-based Ankhorage tooling and CI execution.
+ *
+ * Bun remains the repository package manager/primary command runtime where configured;
+ * this policy makes Node-based tooling deterministic instead of inheriting the ambient
+ * Node version from a CI runner image.
+ */
+export const nodeRuntimePolicy = {
+    engineRange: '24.x',
+    major: 24,
+    setupVersion: '24',
+};

package/dist/tools/prettier/managed.d.ts

@@ -1,6 +1,11 @@
 export declare const prettierManagedFiles: readonly [{
+    readonly relativePath: "prettier.local.config.js";
+    readonly render: typeof renderInitialLocalConfig;
+    readonly mode: "create-only";
+}, {
     readonly relativePath: ".prettierrc.js";
     readonly render: typeof renderPrettierConfig;
 }];
 declare function renderPrettierConfig(targetDirectory: string): Promise<string>;
+declare function renderInitialLocalConfig(targetDirectory: string): Promise<string>;
 export {};

package/dist/tools/prettier/managed.js

@@ -1,10 +1,37 @@
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
-const ESM_CONFIG = `export { default } from '@ankhorage/devtools/prettier';
+const ESM_CONFIG = `import sharedConfig from '@ankhorage/devtools/prettier';
+import localConfig from './prettier.local.config.js';
+
+export default {
+  ...sharedConfig,
+  ...localConfig,
+  overrides: [...(sharedConfig.overrides ?? []), ...(localConfig.overrides ?? [])],
+};
 `;
-const COMMONJS_CONFIG = `module.exports = require('@ankhorage/devtools/prettier');
+const COMMONJS_CONFIG = `const sharedConfig = require('@ankhorage/devtools/prettier');
+const localConfig = require('./prettier.local.config.js');
+
+module.exports = {
+  ...sharedConfig,
+  ...localConfig,
+  overrides: [...(sharedConfig.overrides ?? []), ...(localConfig.overrides ?? [])],
+};
+`;
+const EMPTY_ESM_LOCAL_CONFIG = `export default {};
+`;
+const EMPTY_COMMONJS_LOCAL_CONFIG = `module.exports = {};
+`;
+const LEGACY_ESM_CONFIG = `export { default } from '@ankhorage/devtools/prettier';
+`;
+const LEGACY_COMMONJS_CONFIG = `module.exports = require('@ankhorage/devtools/prettier');
 `;
 export const prettierManagedFiles = [
+    {
+        relativePath: 'prettier.local.config.js',
+        render: renderInitialLocalConfig,
+        mode: 'create-only',
+    },
     {
         relativePath: '.prettierrc.js',
         render: renderPrettierConfig,
@@ -13,6 +40,19 @@ export const prettierManagedFiles = [
 async function renderPrettierConfig(targetDirectory) {
     return (await readPackageType(targetDirectory)) === 'module' ? ESM_CONFIG : COMMONJS_CONFIG;
 }
+async function renderInitialLocalConfig(targetDirectory) {
+    const isModule = (await readPackageType(targetDirectory)) === 'module';
+    try {
+        const existingConfig = await readFile(resolve(targetDirectory, '.prettierrc.js'), 'utf8');
+        if (!isSharedOnlyConfig(existingConfig))
+            return existingConfig;
+    }
+    catch (error) {
+        if (!isNodeError(error) || error.code !== 'ENOENT')
+            throw error;
+    }
+    return isModule ? EMPTY_ESM_LOCAL_CONFIG : EMPTY_COMMONJS_LOCAL_CONFIG;
+}
 async function readPackageType(targetDirectory) {
     try {
         const contents = await readFile(resolve(targetDirectory, 'package.json'), 'utf8');
@@ -29,6 +69,9 @@ async function readPackageType(targetDirectory) {
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+function isSharedOnlyConfig(value) {
+    return [ESM_CONFIG, COMMONJS_CONFIG, LEGACY_ESM_CONFIG, LEGACY_COMMONJS_CONFIG].includes(value);
+}
 function isNodeError(error) {
     return error instanceof Error && 'code' in error;
 }

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

@@ -24,6 +24,11 @@ jobs:
         with:
           bun-version: '__ANKH_BUN_VERSION__'
 
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '__ANKH_NODE_VERSION__'
+
       - name: Install dependencies
         run: bun install --frozen-lockfile
 

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

@@ -32,7 +32,7 @@ jobs:
       - name: Setup Node for npm publishing
         uses: actions/setup-node@v4
         with:
-          node-version: 24
+          node-version: '__ANKH_NODE_VERSION__'
           registry-url: https://registry.npmjs.org
 
       - name: Update npm

package/dist/tools/workflows/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/devtools",
-  "version": "1.5.2",
+  "version": "1.6.1",
   "description": "Shared development tools and repository standards for Ankhorage",
   "license": "MIT",
   "homepage": "https://github.com/ankhorage/devtools#readme",