@ankhorage/devtools 1.20.0 → 1.21.0

package/README.md

@@ -3,7 +3,7 @@
 
 # @ankhorage/devtools
 
-![license: MIT](././paradox/badges/license.svg) ![npm: v1.20.0](././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.21.0](././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
 
@@ -199,10 +199,12 @@ The canonical workflow, VS Code, and skill files are packaged with `@ankhorage/d
 
 ## Managed agent instructions
 
-`ankh devtools agents sync` owns the repository-root `AGENTS.md`. The shared instructions are intentionally small and stable. The target repository's package name and description are rendered from `package.json`; the remaining content defines the unconditional current-architecture policy, directs structural work to the managed project-structure skill, and requires the canonical build, type, lint, Knip, Changeset, and formatting commands before pull request creation.
+`ankh devtools agents sync` owns the repository-root `AGENTS.md` plus `CLAUDE.md` and `GEMINI.md` as symbolic links to that canonical file. The shared instructions are intentionally small and stable. The target repository's package name and description are rendered from `package.json`; the remaining content defines the unconditional current-architecture policy, directs structural work to the managed project-structure skill, and requires the canonical build, type, lint, Knip, Changeset, and formatting commands before pull request creation.
 
 Only the current Ankhorage architecture is supported. Managed instructions reject deprecated APIs, compatibility aliases, shims, dual old/new paths, historical-state fallbacks, and migrations whose sole purpose is obsolete state. A canonical cross-package change requires affected repositories to update to the latest released public API.
 
+Every Devtools-managed repository is standalone: its own checkout must be sufficient to install, build, test, and use it with declared dependencies and explicit configuration. Published packages are additionally consumer-agnostic and reusable outside Ankhorage. Sibling repositories/source imports, unpublished workspace/file/link coupling, hidden organization-local state, and hard assumptions about a consuming app, infrastructure, hosting provider, web server, container runtime, or deployment topology are architecture debt rather than supported exceptions.
+
 ## Managed repository skills
 
 `ankh devtools skills sync` owns the complete `.agents/skills/ankhorage-coding-rules/`, `.agents/skills/hexagonal-architecture/`, and `.agents/skills/ankhorage-project-structure/` trees from the immutable copies shipped in the Devtools release. It creates `.agents/` when missing, replaces stale files in those managed skills, and preserves every unrelated skill directory. The project-structure skill requires both the coding-rules and hexagonal-architecture skills before structural work can continue.

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

@@ -1,6 +1,12 @@
 export declare const agentsManagedFiles: readonly [{
     readonly relativePath: "AGENTS.md";
     readonly render: typeof renderAgentsFile;
+}, {
+    readonly relativePath: "CLAUDE.md";
+    readonly symlinkTarget: "AGENTS.md";
+}, {
+    readonly relativePath: "GEMINI.md";
+    readonly symlinkTarget: "AGENTS.md";
 }];
 /*** Render mandatory repository instructions from the target package identity. */
 declare function renderAgentsFile(targetDirectory: string): Promise<string>;

package/dist/tools/agents/index.js

@@ -5,6 +5,14 @@ export const agentsManagedFiles = [
         relativePath: 'AGENTS.md',
         render: renderAgentsFile,
     },
+    {
+        relativePath: 'CLAUDE.md',
+        symlinkTarget: 'AGENTS.md',
+    },
+    {
+        relativePath: 'GEMINI.md',
+        symlinkTarget: 'AGENTS.md',
+    },
 ];
 /*** Render mandatory repository instructions from the target package identity. */
 async function renderAgentsFile(targetDirectory) {
@@ -13,6 +21,7 @@ async function renderAgentsFile(targetDirectory) {
     const description = readNonEmptyString(manifest.description) ?? 'No package description is declared.';
     const sections = [
         renderCurrentArchitectureInstructions(),
+        renderStandaloneRepositoryInstructions(),
         renderRequiredRepositoryInstructions(),
         renderDocumentationInstructions(),
         renderPullRequestInstructions(),
@@ -45,6 +54,26 @@ 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.
 
+`;
+}
+/*** Render the mandatory standalone repository and package contract. */
+function renderStandaloneRepositoryInstructions() {
+    return `## Standalone contract
+
+Every repository managed by \`@ankhorage/devtools\` is standalone. It must be independently
+installable, buildable, testable, and usable from its own checkout using only declared dependencies
+and explicit configuration. It must not require sibling repositories, sibling source imports,
+\`workspace:\`, \`file:\`, or \`link:\` dependencies to unpublished packages, hidden
+organization-local state, or assumptions about a specific consuming application, infrastructure,
+hosting provider, web server, container runtime, or deployment topology.
+
+Published packages are additionally consumer-agnostic and reusable outside Ankhorage.
+Environment- or provider-specific behavior belongs behind explicit configuration and adapters,
+never in the package core.
+
+If an existing repository violates this contract, treat that as architecture debt to remove, not
+as an exception to preserve.
+
 `;
 }
 /*** Render contextual repository skill-selection requirements. */

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

@@ -5,6 +5,7 @@ export interface ManagedFileDefinition {
     readonly sourceUrl?: URL;
     readonly contents?: string;
     readonly render?: ManagedFileRenderer;
+    readonly symlinkTarget?: string;
     readonly mode?: ManagedFileMode;
     readonly isApplicable?: (targetDirectory: string) => Promise<boolean> | boolean;
 }
@@ -18,8 +19,11 @@ export interface ManagedFileSyncResult {
     readonly relativePath: string;
     readonly action: ManagedFileSyncAction;
 }
+/*** Resolve and validate the repository directory targeted by a managed-files operation. */
 export declare function resolveManagedTargetDirectory(cwd: string, requestedPath: string | undefined): Promise<string>;
+/*** Inspect managed files and symbolic links without mutating repository state. */
 export declare function inspectManagedFiles(targetDirectory: string, definitions: readonly ManagedFileDefinition[]): Promise<readonly ManagedFileStatus[]>;
+/*** Synchronize managed files and symbolic links to their canonical definitions. */
 export declare function syncManagedFiles(targetDirectory: string, definitions: readonly ManagedFileDefinition[], options: {
     readonly dryRun: boolean;
 }): Promise<readonly ManagedFileSyncResult[]>;

package/dist/tools/shared/managedFiles.js

@@ -1,5 +1,6 @@
-import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { lstat, mkdir, readFile, readlink, rm, stat, symlink, writeFile } from 'node:fs/promises';
 import { dirname, resolve } from 'node:path';
+/*** Resolve and validate the repository directory targeted by a managed-files operation. */
 export async function resolveManagedTargetDirectory(cwd, requestedPath) {
     const targetDirectory = resolve(cwd, requestedPath ?? '.');
     let targetStats;
@@ -14,46 +15,62 @@ export async function resolveManagedTargetDirectory(cwd, requestedPath) {
     }
     return targetDirectory;
 }
+/*** Inspect managed files and symbolic links without mutating repository state. */
 export async function inspectManagedFiles(targetDirectory, definitions) {
-    const statuses = await Promise.all(definitions.map(async (definition) => {
-        const targetPath = resolve(targetDirectory, definition.relativePath);
-        const isApplicable = await (definition.isApplicable?.(targetDirectory) ?? true);
-        try {
-            const targetContents = await readFile(targetPath, 'utf8');
-            if (!isApplicable) {
-                return { relativePath: definition.relativePath, state: 'obsolete' };
-            }
-            if ((definition.mode ?? 'replace') === 'create-only') {
-                return { relativePath: definition.relativePath, state: 'current' };
-            }
-            const canonicalContents = await readCanonicalContents(definition, targetDirectory);
-            return {
-                relativePath: definition.relativePath,
-                state: targetContents === canonicalContents ? 'current' : 'outdated',
-            };
-        }
-        catch (error) {
-            if (isMissingFileError(error)) {
-                return isApplicable
-                    ? { relativePath: definition.relativePath, state: 'missing' }
-                    : undefined;
-            }
-            throw new Error(`Failed to inspect managed file: ${targetPath}`, { cause: error });
-        }
-    }));
+    const statuses = await Promise.all(definitions.map((definition) => inspectManagedFileAsync(targetDirectory, definition)));
     return statuses.filter((status) => status !== undefined);
 }
+/*** Synchronize managed files and symbolic links to their canonical definitions. */
 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) {
-        const result = await syncManagedFile(targetDirectory, status, definitionsByPath, options);
-        results.push(result);
+        results.push(await syncManagedFileAsync(targetDirectory, status, definitionsByPath, options));
     }
     return results;
 }
-async function syncManagedFile(targetDirectory, status, definitionsByPath, options) {
+/*** Inspect one managed artifact against its file or symbolic-link definition. */
+async function inspectManagedFileAsync(targetDirectory, definition) {
+    assertSingleContentSource(definition);
+    const targetPath = resolve(targetDirectory, definition.relativePath);
+    const isApplicable = await (definition.isApplicable?.(targetDirectory) ?? true);
+    try {
+        const targetStats = await lstat(targetPath);
+        if (!isApplicable) {
+            return { relativePath: definition.relativePath, state: 'obsolete' };
+        }
+        if ((definition.mode ?? 'replace') === 'create-only') {
+            return { relativePath: definition.relativePath, state: 'current' };
+        }
+        const current = definition.symlinkTarget === undefined
+            ? await isCurrentFileAsync(targetPath, targetStats.isSymbolicLink(), definition, targetDirectory)
+            : await isCurrentSymlinkAsync(targetPath, targetStats.isSymbolicLink(), definition.symlinkTarget);
+        return {
+            relativePath: definition.relativePath,
+            state: current ? 'current' : 'outdated',
+        };
+    }
+    catch (error) {
+        if (isMissingFileError(error)) {
+            return isApplicable ? { relativePath: definition.relativePath, state: 'missing' } : undefined;
+        }
+        throw new Error(`Failed to inspect managed file: ${targetPath}`, { cause: error });
+    }
+}
+/*** Compare one regular managed file with its canonical rendered contents. */
+async function isCurrentFileAsync(targetPath, isSymbolicLink, definition, targetDirectory) {
+    if (isSymbolicLink)
+        return false;
+    return ((await readFile(targetPath, 'utf8')) ===
+        (await readCanonicalContents(definition, targetDirectory)));
+}
+/*** Compare one managed symbolic link with its canonical relative target. */
+async function isCurrentSymlinkAsync(targetPath, isSymbolicLink, symlinkTarget) {
+    return isSymbolicLink && (await readlink(targetPath)) === symlinkTarget;
+}
+/*** Apply one managed artifact status to the target repository. */
+async function syncManagedFileAsync(targetDirectory, status, definitionsByPath, options) {
     if (status.state === 'current') {
         return { relativePath: status.relativePath, action: 'unchanged' };
     }
@@ -63,7 +80,7 @@ async function syncManagedFile(targetDirectory, status, definitionsByPath, optio
     }
     if (status.state === 'obsolete') {
         if (!options.dryRun) {
-            await rm(resolve(targetDirectory, definition.relativePath));
+            await rm(resolve(targetDirectory, definition.relativePath), { force: true, recursive: true });
         }
         return {
             relativePath: status.relativePath,
@@ -78,12 +95,41 @@ async function syncManagedFile(targetDirectory, status, definitionsByPath, optio
     }
     const targetPath = resolve(targetDirectory, definition.relativePath);
     await mkdir(dirname(targetPath), { recursive: true });
-    await writeFile(targetPath, await readCanonicalContents(definition, targetDirectory), 'utf8');
+    const canonicalContents = definition.symlinkTarget === undefined
+        ? await readCanonicalContents(definition, targetDirectory)
+        : undefined;
+    await prepareManagedTargetAsync(targetPath, definition);
+    await writeManagedArtifactAsync(targetPath, definition, canonicalContents);
     return {
         relativePath: status.relativePath,
         action: status.state === 'missing' ? 'created' : 'updated',
     };
 }
+/*** Remove an existing artifact only when writing through it would violate the target type. */
+async function prepareManagedTargetAsync(targetPath, definition) {
+    try {
+        const targetStats = await lstat(targetPath);
+        if (definition.symlinkTarget !== undefined || targetStats.isSymbolicLink()) {
+            await rm(targetPath, { force: true, recursive: true });
+        }
+    }
+    catch (error) {
+        if (!isMissingFileError(error))
+            throw error;
+    }
+}
+/*** Write either a canonical regular file or a canonical symbolic link. */
+async function writeManagedArtifactAsync(targetPath, definition, canonicalContents) {
+    if (definition.symlinkTarget !== undefined) {
+        await symlink(definition.symlinkTarget, targetPath);
+        return;
+    }
+    if (canonicalContents === undefined) {
+        throw new Error(`Missing canonical file contents for ${definition.relativePath}.`);
+    }
+    await writeFile(targetPath, canonicalContents, 'utf8');
+}
+/*** Resolve canonical contents for one regular managed file definition. */
 async function readCanonicalContents(definition, targetDirectory) {
     assertSingleContentSource(definition);
     if (definition.sourceUrl !== undefined) {
@@ -95,17 +141,25 @@ async function readCanonicalContents(definition, targetDirectory) {
     if (definition.render !== undefined) {
         return await definition.render(targetDirectory);
     }
-    throw new Error(`Managed file has no content source: ${definition.relativePath}`);
+    throw new Error(`Managed file does not contain regular-file content: ${definition.relativePath}`);
 }
+/*** Require every managed artifact to define exactly one canonical source. */
 function assertSingleContentSource(definition) {
-    const sourceCount = [definition.sourceUrl, definition.contents, definition.render].filter((value) => value !== undefined).length;
+    const sourceCount = [
+        definition.sourceUrl,
+        definition.contents,
+        definition.render,
+        definition.symlinkTarget,
+    ].filter((value) => value !== undefined).length;
     if (sourceCount !== 1) {
         throw new Error(`Managed file must define exactly one content source: ${definition.relativePath}`);
     }
 }
+/*** Check whether an unknown failure means the target path does not exist. */
 function isMissingFileError(error) {
     return isNodeError(error) && error.code === 'ENOENT';
 }
+/*** Check whether an unknown failure carries a Node.js error code. */
 function isNodeError(error) {
     return error instanceof Error && 'code' in error;
 }

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

@@ -83,6 +83,19 @@ jobs:
             echo "No test script found; skipping."
           fi
 
+      - name: Run standalone contract
+        run: |
+          if node -e "const p=require('./package.json'); const required=p.private!==true&&p.publishConfig?.access==='public'; process.exit(required||p.scripts?.['test:standalone']?0:1)"; then
+            if node -e "const p=require('./package.json'); process.exit(p.scripts?.['test:standalone']?0:1)"; then
+              bun run test:standalone
+            else
+              echo "::error title=Standalone contract test required::Public packages must define test:standalone."
+              exit 1
+            fi
+          else
+            echo "No standalone owner test required; skipping."
+          fi
+
       - name: Run typecheck
         run: |
           if node -e "const p=require('./package.json'); process.exit(p.scripts?.typecheck ? 0 : 1)"; then

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

@@ -76,6 +76,18 @@ jobs:
             echo "No build script found; skipping."
           fi
 
+      - name: Validate standalone release contract
+        run: |
+          BUN_INSTALL_CACHE_DIR="${RUNNER_TEMP}/doctor-cache" bunx @ankhorage/doctor@__ANKH_DOCTOR_VERSION__ validate .
+          if node -e "const p=require('./package.json'); const required=p.private!==true&&p.publishConfig?.access==='public'; process.exit(required||p.scripts?.['test:standalone']?0:1)"; then
+            if node -e "const p=require('./package.json'); process.exit(p.scripts?.['test:standalone']?0:1)"; then
+              bun run test:standalone
+            else
+              echo "::error title=Standalone contract test required::Public packages must define test:standalone."
+              exit 1
+            fi
+          fi
+
       - name: Version packages directly on main
         id: release
         if: hashFiles('.changeset/config.json') != ''
@@ -148,6 +160,31 @@ jobs:
             echo "release_sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
           fi
 
+      - name: Verify standalone packed install
+        if: steps.release.outputs.versioned == 'true'
+        run: |
+          set -euo pipefail
+          bun install --frozen-lockfile --ignore-scripts
+          if node -e "const p=require('./package.json'); process.exit(p.scripts?.build?0:1)"; then
+            bun run build
+          fi
+          if node -e "const p=require('./package.json'); process.exit(p.scripts?.['test:standalone']?0:1)"; then
+            bun run test:standalone
+          fi
+          pack_dir="$(mktemp -d "${RUNNER_TEMP}/standalone-pack.XXXXXX")"
+          install_dir="$(mktemp -d "${RUNNER_TEMP}/standalone-install.XXXXXX")"
+          npm pack --ignore-scripts --pack-destination "$pack_dir" >/dev/null
+          artifact="$(find "$pack_dir" -maxdepth 1 -type f -name '*.tgz' -print -quit)"
+          if [ -z "$artifact" ]; then
+            echo "::error title=Standalone pack failed::npm pack did not produce a package artifact."
+            exit 1
+          fi
+          printf '{"name":"standalone-consumer","private":true,"version":"0.0.0"}\n' > "$install_dir/package.json"
+          (
+            cd "$install_dir"
+            bun add "$artifact" --ignore-scripts
+          )
+
       - name: Publish unpublished packages
         if: hashFiles('.changeset/config.json') != ''
         run: |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/devtools",
-  "version": "1.20.0",
+  "version": "1.21.0",
   "description": "Shared tooling, repository automation, runtime policies, and agent standards for Ankhorage TypeScript projects",
   "license": "MIT",
   "homepage": "https://github.com/ankhorage/devtools#readme",
@@ -121,7 +121,8 @@
     "changeset": "bun src/cli/bin/changeset.ts",
     "changeset:status": "bun src/cli/bin/changeset.ts status --since=origin/main",
     "version-packages": "bun src/cli/bin/changeset.ts version",
-    "check-types": "bun x tsc --noEmit -p tsconfig.test.json"
+    "check-types": "bun x tsc --noEmit -p tsconfig.test.json",
+    "test:standalone": "bun test src/tools/agents/index.test.ts src/tools/shared/managedFiles.test.ts"
   },
   "dependencies": {
     "@ankhorage/apm": "^0.8.10",