@ankhorage/devtools 2.6.0 → 2.7.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
@@ -3,7 +3,7 @@
3
3
 
4
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.7.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
8
  Shared tooling, repository automation, and agent standards for Ankhorage TypeScript projects
9
9
 
@@ -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,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,246 @@
1
+ import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
2
+ import { dirname, join, resolve } from 'node:path';
3
+ import { evaluateRepositoryMetadataPreflight, REPOSITORY_RULE_METADATA, } from '@ankhorage/rules-repository';
4
+ import { isRecord } from '@ankhorage/utility/object';
5
+ /*** Initialize or inspect authored repository metadata without turning it into an enforcement gate. */
6
+ export async function runRepositoryMetadataCommandAsync(operation, argv, context) {
7
+ try {
8
+ const input = parseMetadataArguments(argv, operation === 'init');
9
+ const targetDirectory = resolve(context.cwd, input.targetPath ?? '.');
10
+ await assertDirectoryAsync(targetDirectory);
11
+ const fact = await readMetadataFactAsync(targetDirectory);
12
+ if (operation === 'init' && !fact.exists) {
13
+ const result = await initializeMetadataAsync(targetDirectory, fact.path, input.dryRun);
14
+ context.writeStdout(`${result} ${fact.path}\n`);
15
+ }
16
+ const status = await readMetadataFactAsync(targetDirectory);
17
+ const evaluation = evaluateRepositoryMetadataPreflight({
18
+ cliCommands: [],
19
+ imports: [],
20
+ metadata: { ...status, eligibility: 'applicable', managed: true },
21
+ packageJson: { dependencies: [], exports: [], fields: {}, scripts: {} },
22
+ paths: [],
23
+ workflowBunVersions: {},
24
+ });
25
+ const tasks = authoredTasks(status.document);
26
+ writeMetadataStatus(evaluation.findings, tasks, status.path, context);
27
+ return { exitCode: evaluation.findings.length === 0 && tasks.length === 0 ? 0 : 1 };
28
+ }
29
+ catch (error) {
30
+ context.writeStderr(`${getErrorMessage(error)}\n`);
31
+ return { exitCode: 1 };
32
+ }
33
+ }
34
+ /*** Parse deterministic metadata command arguments without consulting network or ambient configuration. */
35
+ function parseMetadataArguments(argv, allowDryRun) {
36
+ let dryRun = false;
37
+ let targetPath;
38
+ for (const argument of argv) {
39
+ if (argument === '--dry-run') {
40
+ if (!allowDryRun)
41
+ throw new Error('--dry-run is only valid for metadata init.');
42
+ dryRun = true;
43
+ }
44
+ else if (argument.startsWith('-')) {
45
+ throw new Error(`Unknown option: ${argument}`);
46
+ }
47
+ else if (targetPath === undefined) {
48
+ targetPath = argument;
49
+ }
50
+ else {
51
+ throw new Error('Only one target path may be provided.');
52
+ }
53
+ }
54
+ return { dryRun, targetPath };
55
+ }
56
+ /*** Require a local directory before any metadata inspection or initialization. */
57
+ async function assertDirectoryAsync(targetDirectory) {
58
+ await access(targetDirectory);
59
+ }
60
+ /*** Discover the profile-owned metadata location and parse only structurally recognizable JSON. */
61
+ async function readMetadataFactAsync(targetDirectory) {
62
+ const profile = (await pathExistsAsync(join(targetDirectory, 'src'))) ? 'source' : 'non-source';
63
+ const path = profile === 'source'
64
+ ? REPOSITORY_RULE_METADATA.metadata.profiles.source.canonicalPath
65
+ : REPOSITORY_RULE_METADATA.metadata.profiles.nonSource.canonicalPath;
66
+ const metadataPath = join(targetDirectory, path);
67
+ if (!(await pathExistsAsync(metadataPath)))
68
+ return { document: undefined, exists: false, path, profile };
69
+ return {
70
+ document: parseRepositoryMetadata(await readFile(metadataPath, 'utf8')),
71
+ exists: true,
72
+ path,
73
+ profile,
74
+ };
75
+ }
76
+ /*** Create an intentionally incomplete authored template only when metadata is absent. */
77
+ async function initializeMetadataAsync(targetDirectory, relativePath, dryRun) {
78
+ const destination = join(targetDirectory, relativePath);
79
+ if (dryRun)
80
+ return '+';
81
+ await mkdir(dirname(destination), { recursive: true });
82
+ await writeFile(destination, `${JSON.stringify(await metadataTemplateAsync(targetDirectory), null, 2)}\n`);
83
+ return '+';
84
+ }
85
+ /*** Build a template from only independently verifiable local repository facts. */
86
+ async function metadataTemplateAsync(targetDirectory) {
87
+ const manifest = await readManifestAsync(targetDirectory);
88
+ return {
89
+ schemaVersion: 1,
90
+ title: typeof manifest.name === 'string' ? manifest.name : '',
91
+ summary: '',
92
+ purpose: '',
93
+ };
94
+ }
95
+ /*** Read package metadata defensively; absence never fabricates author-owned content. */
96
+ async function readManifestAsync(targetDirectory) {
97
+ const manifestPath = join(targetDirectory, 'package.json');
98
+ if (!(await pathExistsAsync(manifestPath)))
99
+ return {};
100
+ const parsed = JSON.parse(await readFile(manifestPath, 'utf8'));
101
+ return isRecord(parsed) ? parsed : {};
102
+ }
103
+ /*** Decode a document enough for Rules to produce diagnostic findings without claiming semantic truth. */
104
+ function parseRepositoryMetadata(text) {
105
+ const parsed = JSON.parse(text);
106
+ if (!isRecord(parsed) || parsed.schemaVersion !== 1 || !isMetadataKind(parsed.kind))
107
+ return undefined;
108
+ if (typeof parsed.title !== 'string' ||
109
+ typeof parsed.summary !== 'string' ||
110
+ typeof parsed.purpose !== 'string') {
111
+ return undefined;
112
+ }
113
+ return {
114
+ schemaVersion: 1,
115
+ kind: parsed.kind,
116
+ title: parsed.title,
117
+ summary: parsed.summary,
118
+ purpose: parsed.purpose,
119
+ ...optionalMetadataFields(parsed),
120
+ };
121
+ }
122
+ /*** Preserve recognizable optional Contract fields so Rules can report their semantic findings. */
123
+ function optionalMetadataFields(metadata) {
124
+ return {
125
+ ...(typeof metadata.domain === 'string' ? { domain: metadata.domain } : {}),
126
+ ...optionalTextCollections(metadata),
127
+ ...optionalArchitectureField(metadata.architecture),
128
+ ...optionalImplementsField(metadata.implements),
129
+ ...optionalConstraintsField(metadata.constraints),
130
+ };
131
+ }
132
+ /*** Read optional authored text collections without widening untrusted JSON values. */
133
+ function optionalTextCollections(metadata) {
134
+ const responsibilities = readStringArray(metadata.responsibilities);
135
+ const boundaries = readStringArray(metadata.boundaries);
136
+ const audience = readStringArray(metadata.audience);
137
+ const useCases = readStringArray(metadata.useCases);
138
+ return {
139
+ ...(responsibilities === undefined ? {} : { responsibilities }),
140
+ ...(boundaries === undefined ? {} : { boundaries }),
141
+ ...(audience === undefined ? {} : { audience }),
142
+ ...(useCases === undefined ? {} : { useCases }),
143
+ };
144
+ }
145
+ /*** Read an optional architecture fact only when all recognized subfields are safely shaped. */
146
+ function optionalArchitectureField(value) {
147
+ if (!isRecord(value))
148
+ return {};
149
+ const architecture = {
150
+ ...(typeof value.role === 'string' ? { role: value.role } : {}),
151
+ ...(Array.isArray(value.invariants) &&
152
+ value.invariants.every((item) => typeof item === 'string')
153
+ ? { invariants: value.invariants }
154
+ : {}),
155
+ };
156
+ return Object.keys(architecture).length > 0 ? { architecture } : {};
157
+ }
158
+ /*** Read implementation references so their public-shape rules remain observable to authors. */
159
+ function optionalImplementsField(value) {
160
+ if (!Array.isArray(value))
161
+ return {};
162
+ const implementations = value.map(parseImplementationReference);
163
+ return implementations.every((implementation) => implementation !== undefined)
164
+ ? { implements: implementations }
165
+ : {};
166
+ }
167
+ /*** Decode one Contract-shaped implementation reference from authored JSON. */
168
+ function parseImplementationReference(value) {
169
+ if (!isRecord(value) || typeof value.packageName !== 'string')
170
+ return undefined;
171
+ if (value.subpath !== undefined && typeof value.subpath !== 'string')
172
+ return undefined;
173
+ if (value.interfaceId !== undefined && typeof value.interfaceId !== 'string')
174
+ return undefined;
175
+ return {
176
+ packageName: value.packageName,
177
+ ...(typeof value.subpath === 'string' ? { subpath: value.subpath } : {}),
178
+ ...(typeof value.interfaceId === 'string' ? { interfaceId: value.interfaceId } : {}),
179
+ };
180
+ }
181
+ /*** Read optional platform and operational constraints without accepting malformed child lists. */
182
+ function optionalConstraintsField(value) {
183
+ if (!isRecord(value))
184
+ return {};
185
+ const constraints = {
186
+ ...(readStringArray(value.platforms) === undefined
187
+ ? {}
188
+ : { platforms: readStringArray(value.platforms) }),
189
+ ...(readStringArray(value.configuration) === undefined
190
+ ? {}
191
+ : { configuration: readStringArray(value.configuration) }),
192
+ ...(readStringArray(value.security) === undefined
193
+ ? {}
194
+ : { security: readStringArray(value.security) }),
195
+ ...(readStringArray(value.limitations) === undefined
196
+ ? {}
197
+ : { limitations: readStringArray(value.limitations) }),
198
+ };
199
+ return Object.keys(constraints).length > 0 ? { constraints } : {};
200
+ }
201
+ /*** Read one Contract-compatible string-array shape from authored JSON. */
202
+ function readStringArray(value) {
203
+ return Array.isArray(value) && value.every((entry) => typeof entry === 'string')
204
+ ? value
205
+ : undefined;
206
+ }
207
+ /*** Recognize the portable Contract's closed metadata-kind vocabulary. */
208
+ function isMetadataKind(value) {
209
+ return (typeof value === 'string' &&
210
+ [
211
+ 'adapter',
212
+ 'application',
213
+ 'configuration',
214
+ 'contract',
215
+ 'infrastructure',
216
+ 'library',
217
+ 'tooling',
218
+ 'website',
219
+ ].includes(value));
220
+ }
221
+ /*** Identify human-authored fields that deliberately remain absent from the bootstrap template. */
222
+ function authoredTasks(document) {
223
+ if (document === undefined)
224
+ return ['create structurally valid repository metadata'];
225
+ return [
226
+ ...(document.summary.trim() === '' ? ['author summary'] : []),
227
+ ...(document.purpose.trim() === '' ? ['author purpose'] : []),
228
+ ];
229
+ }
230
+ /*** Render preflight findings and ownership tasks as deterministic actionable CLI output. */
231
+ function writeMetadataStatus(findings, tasks, path, context) {
232
+ for (const finding of findings)
233
+ context.writeStdout(`! ${finding.subjects[0]?.path ?? path} ${finding.message}\n`);
234
+ for (const task of tasks)
235
+ context.writeStdout(`? ${path} ${task}\n`);
236
+ if (findings.length === 0 && tasks.length === 0)
237
+ context.writeStdout(`✓ ${path} current\n`);
238
+ }
239
+ /*** Test one local path without shelling out or consulting external state. */
240
+ async function pathExistsAsync(path) {
241
+ return await access(path).then(() => true, () => false);
242
+ }
243
+ /*** Normalize any boundary error for the CLI adapter. */
244
+ function getErrorMessage(error) {
245
+ return error instanceof Error ? error.message : String(error);
246
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ankhorage/devtools",
3
- "version": "2.6.0",
3
+ "version": "2.7.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",
@@ -497,9 +527,9 @@
497
527
  "dependencies": {
498
528
  "@ankhorage/apm": "^0.8.15",
499
529
  "@ankhorage/capability": "^0.2.2",
500
- "@ankhorage/contracts": "^26.4.0",
530
+ "@ankhorage/contracts": "^26.11.0",
501
531
  "@ankhorage/project-detector": "^0.3.5",
502
- "@ankhorage/rules-repository": "0.2.3",
532
+ "@ankhorage/rules-repository": "^0.4.0",
503
533
  "@ankhorage/utility": "^0.5.5",
504
534
  "@changesets/cli": "^3.0.3",
505
535
  "@eslint/compat": "^2.1.1",