@ankhorage/devtools 2.2.2 → 2.3.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -3,7 +3,7 @@
3
3
 
4
4
  # @ankhorage/devtools
5
5
 
6
- ![license: MIT](././paradox/badges/license.svg) ![npm: v2.2.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) ![paradox: warnings](././paradox/badges/docs.svg)
6
+ ![license: MIT](././paradox/badges/license.svg) ![npm: v2.3.5](././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) ![paradox: warnings](././paradox/badges/docs.svg)
7
7
 
8
8
  Shared tooling, repository automation, and agent standards for Ankhorage TypeScript projects
9
9
 
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env node
2
+ export {};
@@ -0,0 +1,17 @@
1
+ #!/usr/bin/env node
2
+ import { findDevtoolsCommandByPath } from '../commands.js';
3
+ import { runRepositoryCommand } from '../runRepositoryCommand.js';
4
+ const [scope, operation, ...argv] = process.argv.slice(2);
5
+ const command = findDevtoolsCommandByPath([scope, operation]);
6
+ if (command?.kind !== 'repository') {
7
+ console.error('Usage: ankhorage-repository <scope> <sync|status> [directory] [--dry-run]');
8
+ process.exitCode = 1;
9
+ }
10
+ else {
11
+ const result = await runRepositoryCommand(command, argv, {
12
+ cwd: process.cwd(),
13
+ writeStdout: (text) => process.stdout.write(text),
14
+ writeStderr: (text) => process.stderr.write(text),
15
+ });
16
+ process.exitCode = result.exitCode;
17
+ }
@@ -17,8 +17,8 @@ export async function inspectPackedApmReleaseCandidateAsync(targetDirectory, opt
17
17
  const temporaryRoot = await mkdtemp(resolve(tmpdir(), 'ankh-apm-release-'));
18
18
  try {
19
19
  const archive = resolve(temporaryRoot, 'candidate.tgz');
20
- const packageRoot = resolve(temporaryRoot, 'package');
21
20
  await packCandidateAsync(root, temporaryRoot, archive);
21
+ const packageRoot = await realpath(resolve(temporaryRoot, 'package'));
22
22
  const candidate = await readPackedCandidateAsync(packageRoot, archive);
23
23
  const result = await validatePackedCandidateAsync(candidate, packageRoot, root, options);
24
24
  if (!result.valid || options.artifactPath === undefined)
@@ -22,6 +22,7 @@ import { readFile, writeFile } from 'node:fs/promises';
22
22
  import { resolve } from 'node:path';
23
23
  import { REPOSITORY_RULE_METADATA } from '@ankhorage/rules-repository';
24
24
  import { applyBunRuntimePolicy } from '../../policy/applyBunRuntimePolicy.js';
25
+ import { resolvePackageCapabilitiesAsync } from './resolvePackageCapabilitiesAsync.js';
25
26
  const PACKAGE_PATH = 'package.json';
26
27
  const DEVTOOLS_PACKAGE_NAME = '@ankhorage/devtools';
27
28
  const BUN_TYPES_PACKAGE_NAME = '@types/bun';
@@ -57,7 +58,7 @@ export async function inspectPackageManifest(targetDirectory, devtoolsVersion) {
57
58
  }
58
59
  return {
59
60
  relativePath: PACKAGE_PATH,
60
- state: isManagedPackageContractCurrent(snapshot.manifest, devtoolsVersion, snapshot.changesetsConfigExists)
61
+ state: (await isManagedPackageContractCurrentAsync(snapshot.manifest, devtoolsVersion, snapshot.changesetsConfigExists, targetDirectory))
61
62
  ? 'current'
62
63
  : 'outdated',
63
64
  };
@@ -66,7 +67,7 @@ export async function inspectPackageManifest(targetDirectory, devtoolsVersion) {
66
67
  export async function syncPackageManifest(targetDirectory, devtoolsVersion, options) {
67
68
  const snapshot = await readPackageManifest(targetDirectory);
68
69
  if (snapshot.exists &&
69
- isManagedPackageContractCurrent(snapshot.manifest, devtoolsVersion, snapshot.changesetsConfigExists)) {
70
+ (await isManagedPackageContractCurrentAsync(snapshot.manifest, devtoolsVersion, snapshot.changesetsConfigExists, targetDirectory))) {
70
71
  return { relativePath: PACKAGE_PATH, action: 'unchanged' };
71
72
  }
72
73
  if (options.dryRun) {
@@ -75,7 +76,11 @@ export async function syncPackageManifest(targetDirectory, devtoolsVersion, opti
75
76
  action: snapshot.exists ? 'would-update' : 'would-create',
76
77
  };
77
78
  }
78
- const updatedManifest = applyManagedPackageContract(snapshot.manifest, devtoolsVersion, snapshot.changesetsConfigExists);
79
+ let updatedManifest = applyManagedPackageContract(snapshot.manifest, devtoolsVersion, snapshot.changesetsConfigExists);
80
+ const capabilities = await resolvePackageCapabilitiesAsync(targetDirectory, snapshot.manifest);
81
+ if (capabilities !== undefined) {
82
+ updatedManifest = applyManagedPackageCapabilities(updatedManifest, capabilities);
83
+ }
79
84
  await writeFile(resolve(targetDirectory, PACKAGE_PATH), serializePackageManifest(updatedManifest), 'utf8');
80
85
  return {
81
86
  relativePath: PACKAGE_PATH,
@@ -106,6 +111,11 @@ export function applyManagedPackageContract(manifest, devtoolsVersion, changeset
106
111
  devDependencies,
107
112
  });
108
113
  }
114
+ /*** Apply a canonical capability catalog without replacing authored Ankh metadata. */
115
+ function applyManagedPackageCapabilities(manifest, capabilities) {
116
+ const ankh = toRecord(manifest.ankh);
117
+ return { ...manifest, ankh: { ...ankh, capabilities } };
118
+ }
109
119
  /*** Check whether the Devtools-owned package manifest fields match current policy. */
110
120
  export function isManagedPackageContractCurrent(manifest, devtoolsVersion, changesetsConfigExists = false) {
111
121
  if (!hasCurrentBunRuntimePolicy(manifest)) {
@@ -125,6 +135,15 @@ export function isManagedPackageContractCurrent(manifest, devtoolsVersion, chang
125
135
  hasCurrentChangesetsScripts(scripts, changesetsEnabled) &&
126
136
  hasCurrentDevtoolsDependencyPlacement(dependencies, devDependencies, devtoolsVersion));
127
137
  }
138
+ /*** Check managed package policy and materialized capability metadata without writing files. */
139
+ async function isManagedPackageContractCurrentAsync(manifest, devtoolsVersion, changesetsConfigExists, targetDirectory) {
140
+ const capabilities = await resolvePackageCapabilitiesAsync(targetDirectory, manifest);
141
+ if (!isManagedPackageContractCurrent(manifest, devtoolsVersion, changesetsConfigExists)) {
142
+ return false;
143
+ }
144
+ return (capabilities === undefined ||
145
+ JSON.stringify(toRecord(manifest.ankh).capabilities) === JSON.stringify(capabilities));
146
+ }
128
147
  /*** Read the current Devtools package version used for consumer synchronization. */
129
148
  export function readCurrentDevtoolsVersion() {
130
149
  const parsed = JSON.parse(readFileSync(new URL('../../../package.json', import.meta.url), 'utf8'));
@@ -0,0 +1,3 @@
1
+ import { type Capability } from '@ankhorage/contracts/capabilities';
2
+ /*** Resolve, validate, and normalize one opted-in package's canonical capability catalog. */
3
+ export declare function resolvePackageCapabilitiesAsync(targetDirectory: string, manifest: Readonly<Record<string, unknown>>): Promise<readonly Capability[] | undefined>;
@@ -0,0 +1,59 @@
1
+ /*** Materialize the trusted canonical capability surface for one package checkout. */
2
+ import { access } from 'node:fs/promises';
3
+ import { resolve } from 'node:path';
4
+ import { pathToFileURL } from 'node:url';
5
+ import { isCapability, normalizeCapability, } from '@ankhorage/contracts/capabilities';
6
+ const CAPABILITIES_SOURCE_PATH = 'src/capabilities/index.ts';
7
+ /*** Resolve, validate, and normalize one opted-in package's canonical capability catalog. */
8
+ export async function resolvePackageCapabilitiesAsync(targetDirectory, manifest) {
9
+ const sourcePath = resolve(targetDirectory, CAPABILITIES_SOURCE_PATH);
10
+ try {
11
+ await access(sourcePath);
12
+ }
13
+ catch (error) {
14
+ if (isNodeError(error) && error.code === 'ENOENT') {
15
+ if (!hasCapabilityMetadata(manifest))
16
+ return undefined;
17
+ throw new Error(`package.json ankh.capabilities requires the canonical ${CAPABILITIES_SOURCE_PATH} capability surface.`, { cause: error });
18
+ }
19
+ throw error;
20
+ }
21
+ if (!isRecord(manifest.ankh)) {
22
+ throw new Error(`${CAPABILITIES_SOURCE_PATH} requires package.json ankh discovery metadata for publication.`);
23
+ }
24
+ const source = await import(pathToFileURL(sourcePath).href);
25
+ const catalog = isRecord(source) ? source.CAPABILITIES : undefined;
26
+ if (!Array.isArray(catalog)) {
27
+ throw new Error(`${CAPABILITIES_SOURCE_PATH} must export CAPABILITIES as an array.`);
28
+ }
29
+ const capabilities = catalog.map((capability, index) => {
30
+ if (!isCapability(capability)) {
31
+ throw new Error(`${CAPABILITIES_SOURCE_PATH} CAPABILITIES[${index}] is not a valid Capability.`);
32
+ }
33
+ return normalizeCapability(capability);
34
+ });
35
+ assertUniqueCapabilityIds(capabilities);
36
+ return capabilities;
37
+ }
38
+ /*** Check whether a manifest declares published capability discovery metadata. */
39
+ function hasCapabilityMetadata(manifest) {
40
+ return isRecord(manifest.ankh) && Object.hasOwn(manifest.ankh, 'capabilities');
41
+ }
42
+ /*** Reject duplicate identifiers before serializing a catalog into static package metadata. */
43
+ function assertUniqueCapabilityIds(capabilities) {
44
+ const ids = new Set();
45
+ for (const capability of capabilities) {
46
+ if (ids.has(capability.id)) {
47
+ throw new Error(`Duplicate capability id "${capability.id}" in ${CAPABILITIES_SOURCE_PATH}.`);
48
+ }
49
+ ids.add(capability.id);
50
+ }
51
+ }
52
+ /*** Narrow an unknown value to a JSON object. */
53
+ function isRecord(value) {
54
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
55
+ }
56
+ /*** Narrow an unknown error to a Node error carrying an error code. */
57
+ function isNodeError(error) {
58
+ return error instanceof Error && 'code' in error;
59
+ }
@@ -77,6 +77,20 @@ jobs:
77
77
  echo "No build script found; skipping."
78
78
  fi
79
79
 
80
+ - name: Synchronize package capability metadata
81
+ run: |
82
+ if node -e "const p=require('./package.json'); process.exit(p.ankh === undefined ? 1 : 0)"; then
83
+ if node -e "const p=require('./package.json'); process.exit(p.name === '@ankhorage/devtools' ? 0 : 1)"; then
84
+ bun ./dist/cli/bin/repository.js package sync .
85
+ bun ./dist/cli/bin/repository.js package status .
86
+ else
87
+ bunx --bun --no-install ankhorage-repository package sync .
88
+ bunx --bun --no-install ankhorage-repository package status .
89
+ fi
90
+ else
91
+ echo "No Ankh package metadata found; skipping capability materialization."
92
+ fi
93
+
80
94
  - name: Validate release contract
81
95
  run: |
82
96
  if node -e "const p=require('./package.json'); process.exit(p.name === '@ankhorage/doctor' ? 0 : 1)"; then
@@ -255,6 +269,32 @@ jobs:
255
269
  }
256
270
  const output = records.sort();
257
271
  process.stdout.write(output.length === 0 ? '' : `${output.join('\n')}\n`);
272
+ NODE
273
+
274
+ PACKAGE_NAME="$package_name" node --input-type=module - <<'NODE'
275
+ import { readFileSync } from 'node:fs';
276
+ import { createRequire } from 'node:module';
277
+ import { join } from 'node:path';
278
+ import { pathToFileURL } from 'node:url';
279
+ const name = process.env.PACKAGE_NAME;
280
+ const packageDir = join(process.cwd(), 'node_modules', ...name.split('/'));
281
+ const manifest = JSON.parse(readFileSync(join(packageDir, 'package.json'), 'utf8'));
282
+ if (
283
+ !manifest.ankh ||
284
+ typeof manifest.ankh !== 'object' ||
285
+ !Object.hasOwn(manifest.ankh, 'capabilities')
286
+ ) process.exit(0);
287
+ const requireFromPackage = createRequire(join(packageDir, 'package.json'));
288
+ const contractsPath = requireFromPackage.resolve('@ankhorage/contracts/capabilities');
289
+ const { areCapabilitiesEqual, isCapability, normalizeCapability } = await import(pathToFileURL(contractsPath).href);
290
+ const { CAPABILITIES } = await import(`${name}/capabilities`);
291
+ const metadata = manifest.ankh.capabilities;
292
+ if (!Array.isArray(CAPABILITIES) || !Array.isArray(metadata) ||
293
+ !CAPABILITIES.every(isCapability) || !metadata.every(isCapability) ||
294
+ CAPABILITIES.length !== metadata.length ||
295
+ !CAPABILITIES.every((capability, index) => areCapabilitiesEqual(normalizeCapability(capability), metadata[index]))) {
296
+ throw new Error('Packed package.json ankh.capabilities must exactly match the public CAPABILITIES catalog.');
297
+ }
258
298
  NODE
259
299
 
260
300
  while IFS='|' read -r loader specifier; do
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ankhorage/devtools",
3
- "version": "2.2.2",
3
+ "version": "2.3.5",
4
4
  "description": "Shared tooling, repository automation, and agent standards for Ankhorage TypeScript projects",
5
5
  "license": "MIT",
6
6
  "homepage": "https://github.com/ankhorage/devtools#readme",
@@ -431,7 +431,8 @@
431
431
  "ankhorage-knip": "./dist/cli/bin/knip.js",
432
432
  "ankhorage-prettier": "./dist/cli/bin/prettier.js",
433
433
  "ankhorage-apm-release": "./dist/cli/bin/apm-release.js",
434
- "ankhorage-structure": "./dist/cli/bin/structure.js"
434
+ "ankhorage-structure": "./dist/cli/bin/structure.js",
435
+ "ankhorage-repository": "./dist/cli/bin/repository.js"
435
436
  },
436
437
  "exports": {
437
438
  "./cli": {
@@ -490,7 +491,7 @@
490
491
  },
491
492
  "dependencies": {
492
493
  "@ankhorage/apm": "^0.8.14",
493
- "@ankhorage/contracts": "^24.1.0",
494
+ "@ankhorage/contracts": "^24.2.1",
494
495
  "@ankhorage/project-detector": "^0.3.4",
495
496
  "@ankhorage/rules-repository": "^0.2.0",
496
497
  "@ankhorage/utility": "^0.5.5",
@@ -514,9 +515,9 @@
514
515
  "typescript-eslint": "^8.71.1"
515
516
  },
516
517
  "devDependencies": {
517
- "@ankhorage/paradox": "^0.2.28",
518
- "@ankhorage/ankh": "^0.12.0",
519
- "@ankhorage/doctor": "0.13.1",
518
+ "@ankhorage/paradox": "^0.3.1",
519
+ "@ankhorage/ankh": "^0.12.2",
520
+ "@ankhorage/doctor": "0.14.2",
520
521
  "@techstark/opencv-js": "^5.0.0-release.1",
521
522
  "@types/bun": "^1.4.2",
522
523
  "@types/node": "^26.6.4",