@ankhorage/devtools 1.15.0 → 1.15.2

package/README.md

@@ -3,7 +3,7 @@
 
 # @ankhorage/devtools
 
-![license: MIT](././paradox/badges/license.svg) ![npm: v1.14.8](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: checked](././paradox/badges/tests.svg) ![docs: paradox](././paradox/badges/docs.svg)
+![license: MIT](././paradox/badges/license.svg) ![npm: v1.15.2](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: checked](././paradox/badges/tests.svg) ![docs: paradox](././paradox/badges/docs.svg)
 
 Shared tooling, repository automation, runtime policies, and agent standards for Ankhorage TypeScript projects
 
@@ -440,6 +440,7 @@ Never declare an unpublished owner version. Project migration recovery is owned
 package's declared handlers; passing this release gate does not execute migrations against user
 projects, deploy production services, or prove compatibility with shipped native binaries.
 
+
 ## CLI
 
 Run and synchronize the shared development toolchain through the Ankh CLI.

package/dist/cli/runRepositoryCommand.js

@@ -1,5 +1,6 @@
 import { agentsManagedFiles } from '../tools/agents/index.js';
 import { eslintManagedFiles } from '../tools/eslint/managed.js';
+import { gitignoreManagedFiles } from '../tools/gitignore/index.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';
@@ -90,7 +91,7 @@ function getManagedFiles(scope) {
         workflows: workflowManagedFiles,
     };
     if (scope === 'all') {
-        return Object.values(definitionsByScope).flat();
+        return [...Object.values(definitionsByScope).flat(), ...gitignoreManagedFiles];
     }
     if (scope === 'package') {
         return [];

package/dist/tools/agents/index.js

@@ -11,6 +11,13 @@ async function renderAgentsFile(targetDirectory) {
     const manifest = await readPackageManifest(targetDirectory);
     const packageName = readNonEmptyString(manifest.name) ?? 'Package name not declared';
     const description = readNonEmptyString(manifest.description) ?? 'No package description is declared.';
+    const sections = [
+        renderCurrentArchitectureInstructions(),
+        renderRequiredRepositoryInstructions(),
+        renderDocumentationInstructions(),
+        renderPullRequestInstructions(),
+        renderSkillScriptInstructions(),
+    ].join('');
     return `# AGENTS.md
 
 <!-- This file is managed by @ankhorage/devtools. -->
@@ -21,7 +28,11 @@ Package: \`${escapeInlineCode(packageName)}\`
 
 ${description}
 
-## Current architecture only
+${sections}`;
+}
+/*** Render the current-architecture policy shared by every managed repository. */
+function renderCurrentArchitectureInstructions() {
+    return `## Current architecture only
 
 Only the current Ankhorage architecture is valid. Do not add or retain deprecated APIs,
 compatibility aliases, shims, dual old/new paths, historical-state fallbacks, or migrations whose
@@ -34,27 +45,47 @@ published public APIs and declared dependencies, never sibling source files.
 Current-runtime error handling and canonical database or infrastructure migrations remain valid
 when they support states that the current architecture can intentionally produce.
 
-## Required repository instructions
+`;
+}
+/*** Render contextual repository skill-selection requirements. */
+function renderRequiredRepositoryInstructions() {
+    return `## Required repository instructions
 
 Before changing any file, read this \`AGENTS.md\` completely and inspect \`.agents/skills/\`.
-For every change, load and follow both baseline repository skills before making changes:
+Treat skill selection as a mandatory precondition to editing, then follow every selected skill
+through validation and delivery.
+
+- Load \`.agents/skills/ankhorage-coding-rules/SKILL.md\` for implementation, refactoring, testing,
+  review, or pull-request delivery work.
+- Load \`.agents/skills/ankhorage-project-structure/SKILL.md\` when the task changes or reviews
+  directory ownership, package boundaries, public entrypoints, cross-repository ownership, type or
+  utility placement, or source architecture.
+- Load every additional repository-local skill whose description or requirements match the task,
+  including skills required by any selected skill. These rules define mandatory minimums, not an
+  allow-list; do not skip a useful relevant skill merely because it is not named here.
+
+Do not load unrelated skills merely because they are installed. If the task scope expands, inspect
+\`.agents/skills/\` again and load the newly relevant skills before continuing. Do not substitute
+remembered, globally installed, or generic guidance for the repository-local versions.
 
-1. \`.agents/skills/ankhorage-coding-rules/SKILL.md\`
-2. \`.agents/skills/ankhorage-project-structure/SKILL.md\`
-
-Load and follow every additional repository-local skill relevant to the task, including skills
-required by either baseline skill. Continue to follow these instructions and skills through
-validation and delivery; do not substitute remembered, globally installed, or generic guidance for
-the repository-local versions.
-
-## Documentation
+`;
+}
+/*** Render the release-owned generated documentation policy. */
+function renderDocumentationInstructions() {
+    return `## Documentation
 
-\`README.md\` and the \`paradox/\` documentation tree are generated by \`@ankhorage/paradox\`.
-Never edit generated documentation directly. Update the owning Paradox \`/*** ... */\` comments in
-\`src\`, including \`@readme\` tags where the content belongs in the README, then run \`bun docs\`
-and commit the regenerated artifacts.
+\`README.md\` and the configured Paradox output are generated release artifacts. Never edit them
+manually, and do not regenerate or commit them in ordinary feature pull requests. Update the owning
+Paradox \`/*** ... */\` comments in \`src\` and leading \`@usage\` comments in real
+\`examples/<example>/...\` source files, plus any repository-owned manual documentation outside the
+generated output. The managed release workflow runs \`bun run docs\` after the package version bump
+and commits the regenerated artifacts in the release commit.
 
-## Pull requests
+`;
+}
+/*** Render canonical pull-request validation commands. */
+function renderPullRequestInstructions() {
+    return `## Pull requests
 
 Before creating a pull request, run all of these commands in this order and resolve every failure:
 
@@ -67,13 +98,18 @@ bun run changeset
 bun run format
 \`\`\`
 
-## Skill scripts
+`;
+}
+/*** Render the repository rule for executable Agent Skill scripts. */
+function renderSkillScriptInstructions() {
+    return `## Skill scripts
 
 Scripts inside an Agent Skill must always be TypeScript files with the \`.ts\` extension.
 JavaScript skill scripts using \`.js\`, \`.mjs\`, or \`.cjs\` are not allowed. Run TypeScript
 skill scripts with Bun.
 `;
 }
+/*** Read the target package manifest used to personalize managed repository instructions. */
 async function readPackageManifest(targetDirectory) {
     try {
         const contents = await readFile(resolve(targetDirectory, 'package.json'), 'utf8');
@@ -90,15 +126,19 @@ async function readPackageManifest(targetDirectory) {
         throw error;
     }
 }
+/*** Escape inline-code delimiters before interpolating repository metadata into Markdown. */
 function escapeInlineCode(value) {
     return value.replaceAll('`', '\\`');
 }
+/*** Check whether an unknown failure carries a Node.js error code. */
 function isNodeError(error) {
     return error instanceof Error && 'code' in error;
 }
+/*** Check whether an unknown value is a plain record-shaped object. */
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+/*** Read and trim a non-empty string value from package metadata. */
 function readNonEmptyString(value) {
     return typeof value === 'string' && value.trim() !== '' ? value.trim() : null;
 }

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

@@ -0,0 +1,10 @@
+export declare const gitignoreManagedFiles: readonly [{
+    readonly relativePath: ".gitignore";
+    readonly render: typeof renderGitignore;
+    readonly isApplicable: typeof isGitignorePresent;
+}];
+/*** Preserve repository-owned ignore rules while keeping documentation directories trackable. */
+declare function renderGitignore(targetDirectory: string): Promise<string>;
+/*** Report whether a repository already owns a `.gitignore` file that can be normalized. */
+declare function isGitignorePresent(targetDirectory: string): Promise<boolean>;
+export {};

package/dist/tools/gitignore/index.js

@@ -0,0 +1,43 @@
+import { access, readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+const TRACKED_DOCUMENTATION_PATTERNS = new Set([
+    'docs',
+    'docs/',
+    '/docs',
+    '/docs/',
+    'paradox',
+    'paradox/',
+    '/paradox',
+    '/paradox/',
+]);
+export const gitignoreManagedFiles = [
+    {
+        relativePath: '.gitignore',
+        render: renderGitignore,
+        isApplicable: isGitignorePresent,
+    },
+];
+/*** Preserve repository-owned ignore rules while keeping documentation directories trackable. */
+async function renderGitignore(targetDirectory) {
+    const contents = await readFile(resolve(targetDirectory, '.gitignore'), 'utf8');
+    return contents
+        .split('\n')
+        .filter((line) => !TRACKED_DOCUMENTATION_PATTERNS.has(line.trim()))
+        .join('\n');
+}
+/*** Report whether a repository already owns a `.gitignore` file that can be normalized. */
+async function isGitignorePresent(targetDirectory) {
+    try {
+        await access(resolve(targetDirectory, '.gitignore'));
+        return true;
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+/*** Check whether an unknown failure carries a Node.js error code. */
+function isNodeError(error) {
+    return error instanceof Error && 'code' in error;
+}

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

@@ -1,3 +1,4 @@
+/*** Defines the Prettier files and ignore policy managed for consuming repositories. */
 export declare const prettierManagedFiles: readonly [{
     readonly relativePath: "prettier.local.config.js";
     readonly render: typeof renderInitialLocalConfig;
@@ -5,7 +6,14 @@ export declare const prettierManagedFiles: readonly [{
 }, {
     readonly relativePath: ".prettierrc.js";
     readonly render: typeof renderPrettierConfig;
+}, {
+    readonly relativePath: ".prettierignore";
+    readonly render: typeof renderPrettierIgnore;
 }];
+/*** Renders the shared Prettier wrapper for the target package module type. */
 declare function renderPrettierConfig(targetDirectory: string): Promise<string>;
+/*** Preserves an existing repository Prettier config as its initial local extension. */
 declare function renderInitialLocalConfig(targetDirectory: string): Promise<string>;
+/*** Preserves repository-owned ignore entries while appending required generated-artifact ignores. */
+declare function renderPrettierIgnore(targetDirectory: string): Promise<string>;
 export {};

package/dist/tools/prettier/managed.js

@@ -26,6 +26,8 @@ const LEGACY_ESM_CONFIG = `export { default } from '@ankhorage/devtools/prettier
 `;
 const LEGACY_COMMONJS_CONFIG = `module.exports = require('@ankhorage/devtools/prettier');
 `;
+const REQUIRED_PRETTIER_IGNORE_ENTRIES = ['node_modules', 'dist', 'README.md', 'paradox/'];
+/*** Defines the Prettier files and ignore policy managed for consuming repositories. */
 export const prettierManagedFiles = [
     {
         relativePath: 'prettier.local.config.js',
@@ -36,10 +38,16 @@ export const prettierManagedFiles = [
         relativePath: '.prettierrc.js',
         render: renderPrettierConfig,
     },
+    {
+        relativePath: '.prettierignore',
+        render: renderPrettierIgnore,
+    },
 ];
+/*** Renders the shared Prettier wrapper for the target package module type. */
 async function renderPrettierConfig(targetDirectory) {
     return (await readPackageType(targetDirectory)) === 'module' ? ESM_CONFIG : COMMONJS_CONFIG;
 }
+/*** Preserves an existing repository Prettier config as its initial local extension. */
 async function renderInitialLocalConfig(targetDirectory) {
     const isModule = (await readPackageType(targetDirectory)) === 'module';
     try {
@@ -53,6 +61,25 @@ async function renderInitialLocalConfig(targetDirectory) {
     }
     return isModule ? EMPTY_ESM_LOCAL_CONFIG : EMPTY_COMMONJS_LOCAL_CONFIG;
 }
+/*** Preserves repository-owned ignore entries while appending required generated-artifact ignores. */
+async function renderPrettierIgnore(targetDirectory) {
+    const existing = await readFile(resolve(targetDirectory, '.prettierignore'), 'utf8').catch((error) => {
+        if (isNodeError(error) && error.code === 'ENOENT')
+            return '';
+        throw error;
+    });
+    const existingEntries = new Set(existing
+        .split(/\r?\n/u)
+        .map((line) => line.trim())
+        .filter((line) => line !== '' && !line.startsWith('#')));
+    const missingEntries = REQUIRED_PRETTIER_IGNORE_ENTRIES.filter((entry) => !existingEntries.has(entry));
+    if (missingEntries.length === 0) {
+        return existing.endsWith('\n') ? existing : `${existing}\n`;
+    }
+    const prefix = existing === '' ? '' : existing.endsWith('\n') ? existing : `${existing}\n`;
+    return `${prefix}${missingEntries.join('\n')}\n`;
+}
+/*** Reads whether the target package uses ESM or CommonJS package semantics. */
 async function readPackageType(targetDirectory) {
     try {
         const contents = await readFile(resolve(targetDirectory, 'package.json'), 'utf8');
@@ -66,12 +93,15 @@ async function readPackageType(targetDirectory) {
         throw error;
     }
 }
+/*** Narrows an unknown JSON value to a non-array record. */
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+/*** Identifies Prettier wrappers that contain no repository-owned configuration. */
 function isSharedOnlyConfig(value) {
     return [ESM_CONFIG, COMMONJS_CONFIG, LEGACY_ESM_CONFIG, LEGACY_COMMONJS_CONFIG].includes(value);
 }
+/*** Narrows an unknown error to a Node error carrying an error code. */
 function isNodeError(error) {
     return error instanceof Error && 'code' in error;
 }

package/dist/tools/skills/assets/ankhorage-coding-rules/SKILL.md

@@ -45,6 +45,31 @@ exceptions or replaced by generic preferences from this skill.
 - Keep one canonical implementation. Do not add compatibility aliases, dual paths, historical-state
   fallbacks, or sibling-source imports.
 
+## Comments and Paradox documentation
+
+- Give every named production function under `src` a concise Paradox `/*** ... */` comment,
+  including exported functions and internal named helpers. Inline callbacks are exempt.
+- Use ordinary inline comments when they explain non-obvious intent, invariants, constraints, or the
+  reason behind a decision. Do not narrate self-explanatory code or duplicate what names and types
+  already express.
+- Paradox documentation metadata belongs only inside `/*** ... */` comments. Use only supported
+  Paradox tags: `@readme`, `@config`, `@example`, and `@usage`. Do not use JSDoc-only tags such as
+  `@param` or `@returns` as Paradox metadata.
+- Add a supported Paradox tag only when it changes or usefully enriches generated documentation;
+  plain function descriptions do not need tags.
+- README usage documentation must come from a real repository-root `examples/<example>/...` source
+  file. Put `@usage` in that example file's leading `/*** ... */` comment so Paradox promotes the
+  runnable example into the README Usage section. Do not create dedicated `readme-usage`,
+  `usage-readme`, `readmeUsage`, or equivalent source modules whose only purpose is feeding README
+  usage text.
+- Update documentation sources in the pull request, including repository-owned manual documentation
+  outside the configured generated output. Never hand-edit generated README or Paradox artifacts.
+- Generated documentation is release-owned. Ordinary feature pull requests must not regenerate or
+  commit `README.md` or the configured Paradox output. The managed release workflow runs
+  `bun run docs` after the package version bump and commits the result in the release commit.
+- Run `bun run docs` locally only when the task explicitly changes or validates Paradox generation;
+  do not commit that generated diff from an ordinary feature pull request.
+
 ## Testing
 
 - Test observable behavior at the owning boundary. Keep tests deterministic and independent of
@@ -60,15 +85,6 @@ exceptions or replaced by generic preferences from this skill.
   full reruns without a substantive code or configuration change, stop cycling, inspect logs and
   artifacts, and report the blocker.
 
-## Paradox documentation
-
-- Give every named production function under `src` a concise Paradox `/*** ... */` description,
-  including internal helpers. Inline callbacks are exempt.
-- Add `@param`, `@returns`, `@example`, or `@readme` to public APIs only when the tag adds useful
-  information.
-- Update documentation sources and regenerate tracked Paradox output. Never hand-edit generated
-  README or Paradox artifacts.
-
 ## Public API and release quality
 
 - Export public symbols intentionally from canonical entrypoints and exercise those exports in
@@ -77,7 +93,8 @@ exceptions or replaced by generic preferences from this skill.
   public API changes.
 - Justify new dependencies and keep generated artifacts, lockfiles, and package metadata aligned
   with the repository's owning workflows.
-- Review the final diff, then run the applicable build, lint, test, typecheck, Knip, format, docs,
-  changeset-status, and packaging checks.
+- Review the final diff, then run the applicable build, lint, test, typecheck, Knip, format,
+  changeset-status, and packaging checks. Run documentation generation only when explicitly needed
+  to validate documentation tooling behavior.
 - Report the exact commands run and any omissions or failures. Do not imply a fully green handoff
   when a required check did not run or pass.

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

@@ -78,6 +78,14 @@ jobs:
           fi
           after_version="$(node -p "require('./package.json').version")"
 
+          if [ "$before_version" != "$after_version" ]; then
+            if node -e "const p=require('./package.json'); process.exit(p.scripts?.docs ? 0 : 1)"; then
+              bun run docs
+            else
+              echo "No docs script found; skipping."
+            fi
+          fi
+
           if git diff --quiet; then
             echo "versioned=false" >> "$GITHUB_OUTPUT"
             exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/devtools",
-  "version": "1.15.0",
+  "version": "1.15.2",
   "description": "Shared tooling, repository automation, runtime policies, and agent standards for Ankhorage TypeScript projects",
   "license": "MIT",
   "homepage": "https://github.com/ankhorage/devtools#readme",
@@ -49,14 +49,15 @@
     "renovateSyncProtocol": 1
   },
   "keywords": [
-    "typescript",
+    "ankhorage",
+    "developer-tools",
     "eslint",
-    "prettier",
-    "knip",
     "github-actions",
-    "vscode",
+    "knip",
+    "prettier",
     "repository-sync",
-    "developer-tools"
+    "typescript",
+    "vscode"
   ],
   "bin": {
     "ankhorage-changeset": "./dist/cli/bin/changeset.js",