@ankhorage/devtools 2.6.0 → 2.8.0

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
@@ -1,11 +1,13 @@
1
1
  <!-- markdownlint-disable MD013 MD033 -->
2
2
  <!-- This file is generated by Paradox. Do not edit manually. -->
3
3
 
4
- # @ankhorage/devtools
4
+ # Ankhorage Devtools
5
5
 
6
- ![license: MIT](././paradox/badges/license.svg) ![npm: v2.6.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: configured](././paradox/badges/tests.svg) ![paradox: warnings](././paradox/badges/docs.svg)
6
+ ![license: MIT](././paradox/badges/license.svg) ![npm: v2.8.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: configured](././paradox/badges/tests.svg) ![paradox: warnings](././paradox/badges/docs.svg)
7
7
 
8
- Shared tooling, repository automation, and agent standards for Ankhorage TypeScript projects
8
+ Owns shared repository automation, managed development tooling, workflows, and agent standards for Ankhorage TypeScript projects.
9
+
10
+ Keep standalone repositories aligned through released, reusable tooling instead of copied project-specific automation.
9
11
 
10
12
  ## Usage
11
13
 
@@ -35,16 +37,9 @@ export default createConfig({
35
37
 
36
38
  This package contains 1 additional example. See the generated documentation for the complete set.
37
39
 
38
- ## Generated documentation
40
+ ## Documentation
39
41
 
40
- - [Interactive documentation app](././paradox/index.html)
41
- - [Public API reference](././paradox/exports.md)
42
- - [Component registry](././paradox/components.md)
43
- - [Architecture overview](././paradox/diagrams/architecture-overview.mmd)
44
- - [Module relationships](././paradox/diagrams/module-relationships.mmd)
45
- - [Export graph](././paradox/diagrams/export-graph.mmd)
46
- - [createKnipConfig sequence](././paradox/diagrams/sequences/create-knip-config.mmd)
47
- - [createKnipMonorepoConfig sequence](././paradox/diagrams/sequences/create-knip-monorepo-config.mmd)
42
+ Open `./paradox/index.html` locally in your browser to browse the complete documentation.
48
43
 
49
44
  ## Public API
50
45
 
@@ -92,3 +87,14 @@ Source: `src/features/apm-release-validation/composition/validatePackedApmReleas
92
87
  Related symbols: `ApmReleaseValidationOptions`, `ApmReleaseValidationResult`
93
88
 
94
89
  </details>
90
+
91
+ ## Contributors
92
+
93
+ <!-- readme: contributors -start -->
94
+ <!-- readme: contributors -end -->
95
+
96
+ ## Donation
97
+
98
+ If this project is useful to you, you can support its continued development.
99
+
100
+ [Support @ankhorage](https://github.com/sponsors/ankhorage)
@@ -39,6 +39,26 @@ export declare const CAPABILITIES: readonly [{
39
39
  };
40
40
  readonly label: "Check structure evidence";
41
41
  readonly description: "Verify structural descriptor evidence is current.";
42
+ }, {
43
+ readonly id: "devtools.metadata.init";
44
+ readonly owner: "@ankhorage/devtools";
45
+ readonly access: readonly ["invoke"];
46
+ readonly binding: {
47
+ readonly kind: "action";
48
+ readonly bindableAs: readonly ["target"];
49
+ };
50
+ readonly label: "Initialize repository metadata";
51
+ readonly description: "Create only missing repository metadata templates.";
52
+ }, {
53
+ readonly id: "devtools.metadata.status";
54
+ readonly owner: "@ankhorage/devtools";
55
+ readonly access: readonly ["invoke"];
56
+ readonly binding: {
57
+ readonly kind: "action";
58
+ readonly bindableAs: readonly ["target"];
59
+ };
60
+ readonly label: "Check repository metadata";
61
+ readonly description: "Report advisory authored repository metadata status.";
42
62
  }, {
43
63
  readonly id: "devtools.changeset";
44
64
  readonly owner: "@ankhorage/devtools";
@@ -32,6 +32,22 @@ export const CAPABILITIES = [
32
32
  label: 'Check structure evidence',
33
33
  description: 'Verify structural descriptor evidence is current.',
34
34
  },
35
+ {
36
+ id: 'devtools.metadata.init',
37
+ owner: '@ankhorage/devtools',
38
+ access: ['invoke'],
39
+ binding: { kind: 'action', bindableAs: ['target'] },
40
+ label: 'Initialize repository metadata',
41
+ description: 'Create only missing repository metadata templates.',
42
+ },
43
+ {
44
+ id: 'devtools.metadata.status',
45
+ owner: '@ankhorage/devtools',
46
+ access: ['invoke'],
47
+ binding: { kind: 'action', bindableAs: ['target'] },
48
+ label: 'Check repository metadata',
49
+ description: 'Report advisory authored repository metadata status.',
50
+ },
35
51
  {
36
52
  id: 'devtools.changeset',
37
53
  owner: '@ankhorage/devtools',
@@ -0,0 +1,5 @@
1
+ import type { DevtoolsRepositoryCommandContext } from '../../../types/provider-command.js';
2
+ /*** Adapt the public metadata CLI command to the repository-metadata application boundary. */
3
+ export declare function runMetadataCommandAsync(operation: 'init' | 'status', argv: readonly string[], context: DevtoolsRepositoryCommandContext): Promise<{
4
+ readonly exitCode: number;
5
+ }>;
@@ -0,0 +1,5 @@
1
+ import { runRepositoryMetadataCommandAsync } from '../../../features/repository-metadata/application/runRepositoryMetadataCommandAsync.js';
2
+ /*** Adapt the public metadata CLI command to the repository-metadata application boundary. */
3
+ export async function runMetadataCommandAsync(operation, argv, context) {
4
+ return await runRepositoryMetadataCommandAsync(operation, argv, context);
5
+ }
@@ -26,7 +26,11 @@ interface DevtoolsStructureCommandDefinition extends DevtoolsCommandBase {
26
26
  readonly kind: 'structure';
27
27
  readonly operation: 'build' | 'check';
28
28
  }
29
- export type DevtoolsCommandDefinition = DevtoolsExternalCommandDefinition | DevtoolsRepositoryCommandDefinition | DevtoolsApmReleaseCommandDefinition | DevtoolsStructureCommandDefinition;
29
+ interface DevtoolsMetadataCommandDefinition extends DevtoolsCommandBase {
30
+ readonly kind: 'metadata';
31
+ readonly operation: 'init' | 'status';
32
+ }
33
+ export type DevtoolsCommandDefinition = DevtoolsExternalCommandDefinition | DevtoolsRepositoryCommandDefinition | DevtoolsApmReleaseCommandDefinition | DevtoolsStructureCommandDefinition | DevtoolsMetadataCommandDefinition;
30
34
  export declare function getDevtoolsCommands(): readonly DevtoolsCommandDefinition[];
31
35
  export declare function findDevtoolsCommandByPath(path: readonly string[]): DevtoolsCommandDefinition | null;
32
36
  export declare function getDevtoolsToolCommand(toolName: DevtoolsToolName): DevtoolsExternalCommandDefinition;
@@ -27,6 +27,20 @@ const DEVTOOLS_COMMANDS = [
27
27
  capability: 'devtools.structure.check',
28
28
  summary: 'Verify structural descriptor evidence is current.',
29
29
  },
30
+ {
31
+ kind: 'metadata',
32
+ operation: 'init',
33
+ path: ['metadata', 'init'],
34
+ capability: 'devtools.metadata.init',
35
+ summary: 'Create only missing repository metadata templates.',
36
+ },
37
+ {
38
+ kind: 'metadata',
39
+ operation: 'status',
40
+ path: ['metadata', 'status'],
41
+ capability: 'devtools.metadata.status',
42
+ summary: 'Report advisory authored repository metadata status.',
43
+ },
30
44
  externalCommand('changeset', 'devtools.changeset', 'Run the shared Changesets toolchain.', '@changesets/cli', 'changeset'),
31
45
  externalCommand('lint', 'devtools.lint', 'Run the shared ESLint toolchain.', 'eslint', 'eslint'),
32
46
  externalCommand('format', 'devtools.format', 'Run the shared Prettier toolchain.', 'prettier', 'prettier'),
@@ -42,6 +42,26 @@ declare const provider: {
42
42
  };
43
43
  readonly label: "Check structure evidence";
44
44
  readonly description: "Verify structural descriptor evidence is current.";
45
+ }, {
46
+ readonly id: "devtools.metadata.init";
47
+ readonly owner: "@ankhorage/devtools";
48
+ readonly access: readonly ["invoke"];
49
+ readonly binding: {
50
+ readonly kind: "action";
51
+ readonly bindableAs: readonly ["target"];
52
+ };
53
+ readonly label: "Initialize repository metadata";
54
+ readonly description: "Create only missing repository metadata templates.";
55
+ }, {
56
+ readonly id: "devtools.metadata.status";
57
+ readonly owner: "@ankhorage/devtools";
58
+ readonly access: readonly ["invoke"];
59
+ readonly binding: {
60
+ readonly kind: "action";
61
+ readonly bindableAs: readonly ["target"];
62
+ };
63
+ readonly label: "Check repository metadata";
64
+ readonly description: "Report advisory authored repository metadata status.";
45
65
  }, {
46
66
  readonly id: "devtools.changeset";
47
67
  readonly owner: "@ankhorage/devtools";
package/dist/cli/index.js CHANGED
@@ -8,6 +8,8 @@
8
8
  * `prettier`, `knip`, `package`, `workflows`, and `vscode` sync/status subcommands.
9
9
  * Owner packages can opt into deterministic structural metadata with
10
10
  * `ankh devtools structure build` and verify committed evidence with `ankh devtools structure check`.
11
+ * Repository metadata authoring is available through `ankh devtools metadata init` and
12
+ * `ankh devtools metadata status`; it is advisory and never enables Doctor enforcement.
11
13
  *
12
14
  * Sync commands accept an optional target directory and `--dry-run`. Aggregate sync is
13
15
  * deterministic and idempotent: canonical managed files and skill trees are created or updated,
@@ -1,5 +1,6 @@
1
1
  import { sync } from './commands/apm/sync.js';
2
2
  import { validate } from './commands/apm/validate.js';
3
+ import { runMetadataCommandAsync } from './commands/metadata/runMetadataCommandAsync.js';
3
4
  import { build } from './commands/structure/build.js';
4
5
  import { check } from './commands/structure/check.js';
5
6
  import { runExternalTool } from './runExternalTool.js';
@@ -11,6 +12,9 @@ export async function runProviderCommand(command, argv, context) {
11
12
  if (command.kind === 'structure') {
12
13
  return command.operation === 'build' ? build(argv, context) : check(argv, context);
13
14
  }
15
+ if (command.kind === 'metadata') {
16
+ return await runMetadataCommandAsync(command.operation, argv, context);
17
+ }
14
18
  if (command.kind === 'external') {
15
19
  return await runExternalTool(command, argv, {
16
20
  cwd: context.cwd,
@@ -0,0 +1,9 @@
1
+ import type { RepositoryMetadata } from '@ankhorage/contracts/metadata';
2
+ export interface RepositoryMetadataFact {
3
+ readonly document: RepositoryMetadata | undefined;
4
+ readonly exists: boolean;
5
+ readonly path: string;
6
+ readonly profile: 'non-source' | 'source';
7
+ }
8
+ /*** Read canonical repository metadata as inert JSON from the profile-owned local path. */
9
+ export declare function readRepositoryMetadataFactAsync(targetDirectory: string): Promise<RepositoryMetadataFact>;
@@ -0,0 +1,191 @@
1
+ import { access, readFile } from 'node:fs/promises';
2
+ import { join } from 'node:path';
3
+ import { REPOSITORY_RULE_METADATA } from '@ankhorage/rules-repository';
4
+ import { isRecord } from '@ankhorage/utility/object';
5
+ /*** Read canonical repository metadata as inert JSON from the profile-owned local path. */
6
+ export async function readRepositoryMetadataFactAsync(targetDirectory) {
7
+ const profile = (await pathExistsAsync(join(targetDirectory, 'src'))) ? 'source' : 'non-source';
8
+ const path = profile === 'source'
9
+ ? REPOSITORY_RULE_METADATA.metadata.profiles.source.canonicalPath
10
+ : REPOSITORY_RULE_METADATA.metadata.profiles.nonSource.canonicalPath;
11
+ const metadataPath = join(targetDirectory, path);
12
+ if (!(await pathExistsAsync(metadataPath))) {
13
+ return { document: undefined, exists: false, path, profile };
14
+ }
15
+ return {
16
+ document: parseRepositoryMetadata(await readFile(metadataPath, 'utf8')),
17
+ exists: true,
18
+ path,
19
+ profile,
20
+ };
21
+ }
22
+ /*** Decode a complete portable metadata document without executing repository-owned code. */
23
+ function parseRepositoryMetadata(text) {
24
+ const parsed = parseJsonDocument(text);
25
+ if (!isRecord(parsed) || parsed.schemaVersion !== 1 || !isMetadataKind(parsed.kind)) {
26
+ return undefined;
27
+ }
28
+ if (typeof parsed.title !== 'string' ||
29
+ typeof parsed.summary !== 'string' ||
30
+ typeof parsed.purpose !== 'string' ||
31
+ !hasValidOptionalFields(parsed)) {
32
+ return undefined;
33
+ }
34
+ return {
35
+ schemaVersion: 1,
36
+ kind: parsed.kind,
37
+ title: parsed.title,
38
+ summary: parsed.summary,
39
+ purpose: parsed.purpose,
40
+ ...optionalMetadataFields(parsed),
41
+ };
42
+ }
43
+ /*** Parse authored JSON without leaking parser-specific failures across the metadata boundary. */
44
+ function parseJsonDocument(text) {
45
+ try {
46
+ return JSON.parse(text);
47
+ }
48
+ catch {
49
+ return undefined;
50
+ }
51
+ }
52
+ /*** Reject malformed recognized fields instead of silently discarding authored facts. */
53
+ function hasValidOptionalFields(metadata) {
54
+ return ((metadata.domain === undefined || typeof metadata.domain === 'string') &&
55
+ hasOptionalStringArray(metadata.responsibilities) &&
56
+ hasOptionalStringArray(metadata.boundaries) &&
57
+ hasOptionalStringArray(metadata.audience) &&
58
+ hasOptionalStringArray(metadata.useCases) &&
59
+ hasValidArchitecture(metadata.architecture) &&
60
+ hasValidImplementations(metadata.implements) &&
61
+ hasValidConstraints(metadata.constraints));
62
+ }
63
+ /*** Preserve optional Contract fields after their complete shape has been verified. */
64
+ function optionalMetadataFields(metadata) {
65
+ return {
66
+ ...(typeof metadata.domain === 'string' ? { domain: metadata.domain } : {}),
67
+ ...optionalTextCollections(metadata),
68
+ ...optionalArchitectureField(metadata.architecture),
69
+ ...optionalImplementsField(metadata.implements),
70
+ ...optionalConstraintsField(metadata.constraints),
71
+ };
72
+ }
73
+ /*** Read optional authored text collections from a previously validated document. */
74
+ function optionalTextCollections(metadata) {
75
+ const responsibilities = readStringArray(metadata.responsibilities);
76
+ const boundaries = readStringArray(metadata.boundaries);
77
+ const audience = readStringArray(metadata.audience);
78
+ const useCases = readStringArray(metadata.useCases);
79
+ return {
80
+ ...(responsibilities === undefined ? {} : { responsibilities }),
81
+ ...(boundaries === undefined ? {} : { boundaries }),
82
+ ...(audience === undefined ? {} : { audience }),
83
+ ...(useCases === undefined ? {} : { useCases }),
84
+ };
85
+ }
86
+ /*** Read an optional architecture fact from a previously validated document. */
87
+ function optionalArchitectureField(value) {
88
+ if (!isRecord(value))
89
+ return {};
90
+ const invariants = readStringArray(value.invariants);
91
+ const architecture = {
92
+ ...(typeof value.role === 'string' ? { role: value.role } : {}),
93
+ ...(invariants === undefined ? {} : { invariants }),
94
+ };
95
+ return Object.keys(architecture).length > 0 ? { architecture } : {};
96
+ }
97
+ /*** Read implementation references from a previously validated document. */
98
+ function optionalImplementsField(value) {
99
+ if (!Array.isArray(value))
100
+ return {};
101
+ return {
102
+ implements: value.flatMap((reference) => {
103
+ const implementation = parseImplementationReference(reference);
104
+ return implementation === undefined ? [] : [implementation];
105
+ }),
106
+ };
107
+ }
108
+ /*** Decode one validated portable implementation reference. */
109
+ function parseImplementationReference(value) {
110
+ if (!isRecord(value) || typeof value.packageName !== 'string')
111
+ return undefined;
112
+ if (value.subpath !== undefined && typeof value.subpath !== 'string')
113
+ return undefined;
114
+ if (value.interfaceId !== undefined && typeof value.interfaceId !== 'string')
115
+ return undefined;
116
+ return {
117
+ packageName: value.packageName,
118
+ ...(typeof value.subpath === 'string' ? { subpath: value.subpath } : {}),
119
+ ...(typeof value.interfaceId === 'string' ? { interfaceId: value.interfaceId } : {}),
120
+ };
121
+ }
122
+ /*** Read optional operational constraints from a previously validated document. */
123
+ function optionalConstraintsField(value) {
124
+ if (!isRecord(value))
125
+ return {};
126
+ const constraints = {
127
+ ...(readStringArray(value.platforms) === undefined
128
+ ? {}
129
+ : { platforms: readStringArray(value.platforms) }),
130
+ ...(readStringArray(value.configuration) === undefined
131
+ ? {}
132
+ : { configuration: readStringArray(value.configuration) }),
133
+ ...(readStringArray(value.security) === undefined
134
+ ? {}
135
+ : { security: readStringArray(value.security) }),
136
+ ...(readStringArray(value.limitations) === undefined
137
+ ? {}
138
+ : { limitations: readStringArray(value.limitations) }),
139
+ };
140
+ return Object.keys(constraints).length > 0 ? { constraints } : {};
141
+ }
142
+ /*** Check whether an optional value is absent or a complete Contract-compatible string array. */
143
+ function hasOptionalStringArray(value) {
144
+ return value === undefined || readStringArray(value) !== undefined;
145
+ }
146
+ /*** Check an optional architecture field without accepting malformed child values. */
147
+ function hasValidArchitecture(value) {
148
+ return (value === undefined ||
149
+ (isRecord(value) &&
150
+ (value.role === undefined || typeof value.role === 'string') &&
151
+ hasOptionalStringArray(value.invariants)));
152
+ }
153
+ /*** Check optional implementation references without losing malformed entries. */
154
+ function hasValidImplementations(value) {
155
+ return (value === undefined ||
156
+ (Array.isArray(value) &&
157
+ value.every((reference) => parseImplementationReference(reference) !== undefined)));
158
+ }
159
+ /*** Check optional constraint fields without accepting malformed child values. */
160
+ function hasValidConstraints(value) {
161
+ return (value === undefined ||
162
+ (isRecord(value) &&
163
+ hasOptionalStringArray(value.platforms) &&
164
+ hasOptionalStringArray(value.configuration) &&
165
+ hasOptionalStringArray(value.security) &&
166
+ hasOptionalStringArray(value.limitations)));
167
+ }
168
+ /*** Read one Contract-compatible string-array shape from authored JSON. */
169
+ function readStringArray(value) {
170
+ return Array.isArray(value) && value.every((entry) => typeof entry === 'string')
171
+ ? value
172
+ : undefined;
173
+ }
174
+ /*** Recognize the portable Contract's closed metadata-kind vocabulary. */
175
+ function isMetadataKind(value) {
176
+ return (typeof value === 'string' &&
177
+ [
178
+ 'adapter',
179
+ 'application',
180
+ 'configuration',
181
+ 'contract',
182
+ 'infrastructure',
183
+ 'library',
184
+ 'tooling',
185
+ 'website',
186
+ ].includes(value));
187
+ }
188
+ /*** Test one local path without shelling out or consulting external state. */
189
+ async function pathExistsAsync(path) {
190
+ return await access(path).then(() => true, () => false);
191
+ }
@@ -0,0 +1,5 @@
1
+ import type { DevtoolsRepositoryCommandContext } from '../../../types/provider-command.js';
2
+ /*** Initialize or inspect authored repository metadata without turning it into an enforcement gate. */
3
+ export declare function runRepositoryMetadataCommandAsync(operation: 'init' | 'status', argv: readonly string[], context: DevtoolsRepositoryCommandContext): Promise<{
4
+ readonly exitCode: number;
5
+ }>;
@@ -0,0 +1,113 @@
1
+ import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
2
+ import { dirname, join, resolve } from 'node:path';
3
+ import { evaluateRepositoryMetadataPreflight } from '@ankhorage/rules-repository';
4
+ import { isRecord } from '@ankhorage/utility/object';
5
+ import { readRepositoryMetadataFactAsync } from './readRepositoryMetadataFactAsync.js';
6
+ /*** Initialize or inspect authored repository metadata without turning it into an enforcement gate. */
7
+ export async function runRepositoryMetadataCommandAsync(operation, argv, context) {
8
+ try {
9
+ const input = parseMetadataArguments(argv, operation === 'init');
10
+ const targetDirectory = resolve(context.cwd, input.targetPath ?? '.');
11
+ await assertDirectoryAsync(targetDirectory);
12
+ const fact = await readRepositoryMetadataFactAsync(targetDirectory);
13
+ if (operation === 'init' && !fact.exists) {
14
+ const result = await initializeMetadataAsync(targetDirectory, fact.path, input.dryRun);
15
+ context.writeStdout(`${result} ${fact.path}\n`);
16
+ }
17
+ const status = await readRepositoryMetadataFactAsync(targetDirectory);
18
+ const evaluation = evaluateRepositoryMetadataPreflight({
19
+ cliCommands: [],
20
+ imports: [],
21
+ metadata: { ...status, eligibility: 'applicable', managed: true },
22
+ packageJson: { dependencies: [], exports: [], fields: {}, scripts: {} },
23
+ paths: [],
24
+ workflowBunVersions: {},
25
+ });
26
+ const tasks = authoredTasks(status.document);
27
+ writeMetadataStatus(evaluation.findings, tasks, status.path, context);
28
+ return { exitCode: evaluation.findings.length === 0 && tasks.length === 0 ? 0 : 1 };
29
+ }
30
+ catch (error) {
31
+ context.writeStderr(`${getErrorMessage(error)}\n`);
32
+ return { exitCode: 1 };
33
+ }
34
+ }
35
+ /*** Parse deterministic metadata command arguments without consulting network or ambient configuration. */
36
+ function parseMetadataArguments(argv, allowDryRun) {
37
+ let dryRun = false;
38
+ let targetPath;
39
+ for (const argument of argv) {
40
+ if (argument === '--dry-run') {
41
+ if (!allowDryRun)
42
+ throw new Error('--dry-run is only valid for metadata init.');
43
+ dryRun = true;
44
+ }
45
+ else if (argument.startsWith('-')) {
46
+ throw new Error(`Unknown option: ${argument}`);
47
+ }
48
+ else if (targetPath === undefined) {
49
+ targetPath = argument;
50
+ }
51
+ else {
52
+ throw new Error('Only one target path may be provided.');
53
+ }
54
+ }
55
+ return { dryRun, targetPath };
56
+ }
57
+ /*** Require a local directory before any metadata inspection or initialization. */
58
+ async function assertDirectoryAsync(targetDirectory) {
59
+ await access(targetDirectory);
60
+ }
61
+ /*** Create an intentionally incomplete authored template only when metadata is absent. */
62
+ async function initializeMetadataAsync(targetDirectory, relativePath, dryRun) {
63
+ const destination = join(targetDirectory, relativePath);
64
+ if (dryRun)
65
+ return '+';
66
+ await mkdir(dirname(destination), { recursive: true });
67
+ await writeFile(destination, `${JSON.stringify(await metadataTemplateAsync(targetDirectory), null, 2)}\n`);
68
+ return '+';
69
+ }
70
+ /*** Build a template from only independently verifiable local repository facts. */
71
+ async function metadataTemplateAsync(targetDirectory) {
72
+ const manifest = await readManifestAsync(targetDirectory);
73
+ return {
74
+ schemaVersion: 1,
75
+ title: typeof manifest.name === 'string' ? manifest.name : '',
76
+ summary: '',
77
+ purpose: '',
78
+ };
79
+ }
80
+ /*** Read package metadata defensively; absence never fabricates author-owned content. */
81
+ async function readManifestAsync(targetDirectory) {
82
+ const manifestPath = join(targetDirectory, 'package.json');
83
+ if (!(await pathExistsAsync(manifestPath)))
84
+ return {};
85
+ const parsed = JSON.parse(await readFile(manifestPath, 'utf8'));
86
+ return isRecord(parsed) ? parsed : {};
87
+ }
88
+ /*** Identify human-authored fields that deliberately remain absent from the bootstrap template. */
89
+ function authoredTasks(document) {
90
+ if (document === undefined)
91
+ return ['create structurally valid repository metadata'];
92
+ return [
93
+ ...(document.summary.trim() === '' ? ['author summary'] : []),
94
+ ...(document.purpose.trim() === '' ? ['author purpose'] : []),
95
+ ];
96
+ }
97
+ /*** Render preflight findings and ownership tasks as deterministic actionable CLI output. */
98
+ function writeMetadataStatus(findings, tasks, path, context) {
99
+ for (const finding of findings)
100
+ context.writeStdout(`! ${finding.subjects[0]?.path ?? path} ${finding.message}\n`);
101
+ for (const task of tasks)
102
+ context.writeStdout(`? ${path} ${task}\n`);
103
+ if (findings.length === 0 && tasks.length === 0)
104
+ context.writeStdout(`✓ ${path} current\n`);
105
+ }
106
+ /*** Test one local path without shelling out or consulting external state. */
107
+ async function pathExistsAsync(path) {
108
+ return await access(path).then(() => true, () => false);
109
+ }
110
+ /*** Normalize any boundary error for the CLI adapter. */
111
+ function getErrorMessage(error) {
112
+ return error instanceof Error ? error.message : String(error);
113
+ }
@@ -1 +1,2 @@
1
- export declare function getReadmeDocumentationErrors(readmeContents: string): string[];
1
+ /*** Checks generated README markers using the title owned by repository metadata. */
2
+ export declare function getReadmeDocumentationErrors(readmeContents: string, expectedTitle: string): string[];
@@ -1,15 +1,15 @@
1
1
  const REQUIRED_README_SNIPPETS = [
2
2
  '<!-- This file is generated by Paradox. Do not edit manually. -->',
3
- '# @ankhorage/devtools',
4
3
  '## Usage',
5
4
  'ankh devtools --help',
6
5
  'Standalone package ESLint configuration',
7
6
  'export default createConfig({',
8
- '## Generated documentation',
7
+ '## Documentation',
9
8
  'paradox/index.html',
10
9
  ];
11
- export function getReadmeDocumentationErrors(readmeContents) {
12
- return REQUIRED_README_SNIPPETS.flatMap((snippet) => readmeContents.includes(snippet)
10
+ /*** Checks generated README markers using the title owned by repository metadata. */
11
+ export function getReadmeDocumentationErrors(readmeContents, expectedTitle) {
12
+ return [`# ${expectedTitle}`, ...REQUIRED_README_SNIPPETS].flatMap((snippet) => readmeContents.includes(snippet)
13
13
  ? []
14
14
  : [`README.md is missing required documentation snippet: ${snippet}`]);
15
15
  }
@@ -1,5 +1,6 @@
1
1
  import { readFile } from 'node:fs/promises';
2
2
  import { resolve } from 'node:path';
3
+ import { renderRepositorySectionsAsync } from './renderRepositorySectionsAsync.js';
3
4
  export const agentsManagedFiles = [
4
5
  {
5
6
  relativePath: 'AGENTS.md',
@@ -19,6 +20,10 @@ async function renderAgentsFile(targetDirectory) {
19
20
  const manifest = await readPackageManifest(targetDirectory);
20
21
  const packageName = readNonEmptyString(manifest.name) ?? 'Package name not declared';
21
22
  const description = readNonEmptyString(manifest.description) ?? 'No package description is declared.';
23
+ const repositorySections = await renderRepositorySectionsAsync(targetDirectory, {
24
+ description,
25
+ packageName,
26
+ });
22
27
  const sections = [
23
28
  renderCurrentArchitectureInstructions(),
24
29
  renderStandaloneRepositoryInstructions(),
@@ -31,12 +36,7 @@ async function renderAgentsFile(targetDirectory) {
31
36
 
32
37
  <!-- This file is managed by @ankhorage/devtools. -->
33
38
 
34
- ## Repository
35
-
36
- Package: \`${escapeInlineCode(packageName)}\`
37
-
38
- ${description}
39
-
39
+ ${repositorySections}
40
40
  ${sections}`;
41
41
  }
42
42
  /*** Render the current-architecture policy shared by every managed repository. */
@@ -159,10 +159,6 @@ async function readPackageManifest(targetDirectory) {
159
159
  throw error;
160
160
  }
161
161
  }
162
- /*** Escape inline-code delimiters before interpolating repository metadata into Markdown. */
163
- function escapeInlineCode(value) {
164
- return value.replaceAll('`', '\\`');
165
- }
166
162
  /*** Check whether an unknown failure carries a Node.js error code. */
167
163
  function isNodeError(error) {
168
164
  return error instanceof Error && 'code' in error;
@@ -0,0 +1,7 @@
1
+ interface RepositoryIdentity {
2
+ readonly description: string;
3
+ readonly packageName: string;
4
+ }
5
+ /*** Render curated repository scope when valid metadata exists, preserving the manifest fallback. */
6
+ export declare function renderRepositorySectionsAsync(targetDirectory: string, identity: RepositoryIdentity): Promise<string>;
7
+ export {};
@@ -0,0 +1,86 @@
1
+ import { evaluateRepositoryMetadataPreflight } from '@ankhorage/rules-repository';
2
+ import { readRepositoryMetadataFactAsync } from '../../features/repository-metadata/application/readRepositoryMetadataFactAsync.js';
3
+ /*** Render curated repository scope when valid metadata exists, preserving the manifest fallback. */
4
+ export async function renderRepositorySectionsAsync(targetDirectory, identity) {
5
+ const fact = await readRepositoryMetadataFactAsync(targetDirectory);
6
+ if (!fact.exists) {
7
+ return renderFallbackRepositorySection(identity);
8
+ }
9
+ const evaluation = evaluateRepositoryMetadataPreflight({
10
+ cliCommands: [],
11
+ imports: [],
12
+ metadata: { ...fact, eligibility: 'applicable', managed: true },
13
+ packageJson: { dependencies: [], exports: [], fields: {}, scripts: {} },
14
+ paths: [],
15
+ workflowBunVersions: {},
16
+ });
17
+ if (fact.document === undefined || evaluation.findings.length > 0) {
18
+ const messages = evaluation.findings.map(({ message }) => message).join('; ');
19
+ throw new Error(`Invalid repository metadata at ${fact.path}: ${messages || 'document does not match the published contract'}`);
20
+ }
21
+ return renderCuratedRepositorySections(identity.packageName, fact.document);
22
+ }
23
+ /*** Render the transition-safe package-manifest fallback when canonical metadata is absent. */
24
+ function renderFallbackRepositorySection(identity) {
25
+ return `## Repository
26
+
27
+ Package: \`${escapeInlineCode(identity.packageName)}\`
28
+
29
+ ${escapeMarkdownText(identity.description)}
30
+
31
+ `;
32
+ }
33
+ /*** Render authored purpose, ownership, boundaries, audience, and architectural invariants. */
34
+ function renderCuratedRepositorySections(packageName, metadata) {
35
+ const repositoryDetails = [
36
+ `Package: \`${escapeInlineCode(packageName)}\``,
37
+ `Title: ${escapeMarkdownText(metadata.title)}`,
38
+ escapeMarkdownText(metadata.summary),
39
+ `Purpose: ${escapeMarkdownText(metadata.purpose)}`,
40
+ renderList('Audience', metadata.audience),
41
+ ]
42
+ .filter((value) => value !== '')
43
+ .join('\n\n');
44
+ const scopeDetails = [
45
+ renderList('Responsibilities', metadata.responsibilities),
46
+ renderList('Boundaries', metadata.boundaries),
47
+ metadata.architecture?.role === undefined
48
+ ? ''
49
+ : `Architecture role: ${escapeMarkdownText(metadata.architecture.role)}`,
50
+ renderList('Architectural invariants', metadata.architecture?.invariants),
51
+ ]
52
+ .filter((value) => value !== '')
53
+ .join('\n\n');
54
+ return `## Repository
55
+
56
+ ${repositoryDetails}
57
+
58
+ ## Scope and boundaries
59
+
60
+ ${scopeDetails || 'No additional scope or architecture facts are declared.'}
61
+
62
+ `;
63
+ }
64
+ /*** Render one optional authored collection as a deterministic Markdown list. */
65
+ function renderList(title, values) {
66
+ if (values === undefined || values.length === 0)
67
+ return '';
68
+ return `${title}:
69
+
70
+ ${values.map((value) => `- ${escapeMarkdownText(value)}`).join('\n')}`;
71
+ }
72
+ /*** Escape inline-code delimiters and backslashes inside a managed Markdown code span. */
73
+ function escapeInlineCode(value) {
74
+ return normalizeText(value).replaceAll('\\', '\\\\').replaceAll('`', '\\`');
75
+ }
76
+ /*** Flatten authored prose and escape Markdown control characters before interpolation. */
77
+ function escapeMarkdownText(value) {
78
+ return [...normalizeText(value)]
79
+ .map((character) => (MARKDOWN_CONTROL_CHARACTERS.has(character) ? `\\${character}` : character))
80
+ .join('');
81
+ }
82
+ /*** Normalize authored prose to one managed Markdown line without changing its words. */
83
+ function normalizeText(value) {
84
+ return value.trim().replaceAll(/\s+/gu, ' ');
85
+ }
86
+ const MARKDOWN_CONTROL_CHARACTERS = new Set(['\\', '`', '*', '_', '[', ']', '<', '>']);
@@ -227,19 +227,24 @@ jobs:
227
227
  exit 1
228
228
  fi
229
229
 
230
- if [ -n "$tagged_sha" ]; then
230
+ if [ "$HIGHEST_PUBLISHED_VERSION" != "$current_version" ]; then
231
+ release_sha="$(git rev-parse HEAD)"
232
+ echo "Completing unpublished ${release_tag} from current main ${release_sha} without another version bump."
233
+ elif [ -n "$tagged_sha" ]; then
231
234
  echo "Release tag ${release_tag} already points to ${release_sha}; resuming idempotent finalization."
232
235
  else
233
236
  echo "Recovering canonical release commit $release_sha for version $current_version without another version bump."
234
237
  fi
235
238
 
236
- if ! git diff --quiet || ! git diff --cached --quiet || [ -n "$(git ls-files --others --exclude-standard)" ]; then
239
+ if [ "$HIGHEST_PUBLISHED_VERSION" = "$current_version" ] && (! git diff --quiet || ! git diff --cached --quiet || [ -n "$(git ls-files --others --exclude-standard)" ]); then
237
240
  git status --short
238
241
  echo "::error title=Release recovery requires a clean worktree::A release preparation step modified the checkout before recovery. Refusing to discard changes while switching to canonical release commit $release_sha."
239
242
  exit 1
240
243
  fi
241
244
 
242
- git checkout --detach "$release_sha"
245
+ if [ "$HIGHEST_PUBLISHED_VERSION" = "$current_version" ]; then
246
+ git checkout --detach "$release_sha"
247
+ fi
243
248
  echo "versioned=true" >> "$GITHUB_OUTPUT"
244
249
  echo "package_name=$(node -p "require('./package.json').name")" >> "$GITHUB_OUTPUT"
245
250
  echo "package_version=$current_version" >> "$GITHUB_OUTPUT"
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ankhorage/devtools",
3
- "version": "2.6.0",
3
+ "version": "2.8.0",
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",
@@ -79,6 +79,36 @@
79
79
  "label": "Check structure evidence",
80
80
  "description": "Verify structural descriptor evidence is current."
81
81
  },
82
+ {
83
+ "id": "devtools.metadata.init",
84
+ "owner": "@ankhorage/devtools",
85
+ "access": [
86
+ "invoke"
87
+ ],
88
+ "binding": {
89
+ "kind": "action",
90
+ "bindableAs": [
91
+ "target"
92
+ ]
93
+ },
94
+ "label": "Initialize repository metadata",
95
+ "description": "Create only missing repository metadata templates."
96
+ },
97
+ {
98
+ "id": "devtools.metadata.status",
99
+ "owner": "@ankhorage/devtools",
100
+ "access": [
101
+ "invoke"
102
+ ],
103
+ "binding": {
104
+ "kind": "action",
105
+ "bindableAs": [
106
+ "target"
107
+ ]
108
+ },
109
+ "label": "Check repository metadata",
110
+ "description": "Report advisory authored repository metadata status."
111
+ },
82
112
  {
83
113
  "id": "devtools.changeset",
84
114
  "owner": "@ankhorage/devtools",
@@ -496,16 +526,16 @@
496
526
  },
497
527
  "dependencies": {
498
528
  "@ankhorage/apm": "^0.8.15",
499
- "@ankhorage/capability": "^0.2.2",
500
- "@ankhorage/contracts": "^26.4.0",
501
- "@ankhorage/project-detector": "^0.3.5",
502
- "@ankhorage/rules-repository": "0.2.3",
529
+ "@ankhorage/capability": "^0.2.3",
530
+ "@ankhorage/contracts": "^26.11.1",
531
+ "@ankhorage/project-detector": "^0.3.6",
532
+ "@ankhorage/rules-repository": "^0.4.1",
503
533
  "@ankhorage/utility": "^0.5.5",
504
534
  "@changesets/cli": "^3.0.3",
505
535
  "@eslint/compat": "^2.1.1",
506
536
  "@eslint/js": "^10.0.1",
507
- "@next/eslint-plugin-next": "^16.4.5",
508
- "eslint": "^10.14.0",
537
+ "@next/eslint-plugin-next": "^16.4.6",
538
+ "eslint": "^10.15.0",
509
539
  "eslint-config-prettier": "^10.1.8",
510
540
  "eslint-plugin-import": "^2.32.0",
511
541
  "eslint-plugin-prettier": "^5.5.7",
@@ -515,15 +545,15 @@
515
545
  "eslint-plugin-security": "^4.2.1",
516
546
  "eslint-plugin-simple-import-sort": "^14.0.0",
517
547
  "eslint-plugin-unused-imports": "^4.4.1",
518
- "knip": "^6.44.1",
519
- "prettier": "^3.9.10",
548
+ "knip": "^6.45.1",
549
+ "prettier": "^3.10.1",
520
550
  "typescript": "~6.0.3",
521
- "typescript-eslint": "^8.72.1"
551
+ "typescript-eslint": "^8.72.2"
522
552
  },
523
553
  "devDependencies": {
524
- "@ankhorage/paradox": "^0.3.6",
525
- "@ankhorage/ankh": "^0.13.5",
526
- "@ankhorage/doctor": "0.14.35",
554
+ "@ankhorage/paradox": "^0.5.0",
555
+ "@ankhorage/ankh": "^0.13.7",
556
+ "@ankhorage/doctor": "0.14.36",
527
557
  "@techstark/opencv-js": "^5.0.0-release.1",
528
558
  "@types/bun": "^1.4.2",
529
559
  "@types/node": "^26.6.6",