@astryxdesign/cli 0.6.3-canary.d0d49a4 → 0.6.3-canary.db4e378
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 +86 -72
- package/api/build/build.doc.mjs +3 -3
- package/api/build/build.test.mjs +14 -3
- package/api/build/build.type.d.mts +35 -1
- package/api/build/build.type.mjs +24 -3
- package/api/build/help/help.d.mts +8 -5
- package/api/build/help/help.mjs +56 -6
- package/api/component/component.doc.mjs +12 -3
- package/api/component/component.mjs +31 -2
- package/api/component/component.test.mjs +38 -0
- package/api/component/component.type.d.mts +16 -5
- package/api/component/component.type.mjs +13 -5
- package/api/component/detail/blocks/blocks.d.mts +2 -1
- package/api/component/detail/blocks/blocks.mjs +4 -3
- package/api/component/list/list.d.mts +0 -5
- package/api/component/list/list.mjs +37 -9
- package/api/discover/discover.doc.mjs +1 -1
- package/api/gap-report/gap-report.doc.mjs +7 -4
- package/api/init/init.doc.mjs +4 -0
- package/api/init/init.test.mjs +41 -1
- package/api/init/remove/remove.mjs +1 -1
- package/api/init/run/run.mjs +20 -10
- package/api/integration/add-contribution.component-names.test.mjs +120 -0
- package/api/integration/add-contribution.mjs +11 -0
- package/api/integration/add-contribution.test.mjs +80 -0
- package/api/integration/integrationAdd.doc.mjs +7 -4
- package/api/integration/integrationAddComponent.doc.mjs +1 -1
- package/api/integration/validate-integration.mjs +2 -0
- package/api/integration/validate-integration.test.mjs +91 -0
- package/api/integration/validateIntegration.doc.mjs +1 -1
- package/api/json/envelope-types.test.mjs +76 -0
- package/api/json/parseResponse.doc.mjs +2 -2
- package/api/layout/expand/expand.mjs +7 -5
- package/api/layout/expand/expand.path-safety.test.mjs +53 -0
- package/api/layout/grammar/grammar.mjs +2 -1
- package/api/layout/layoutExpand.doc.mjs +1 -1
- package/api/search/search-return-type.test.mjs +54 -0
- package/api/search/search.d.mts +2 -9
- package/api/search/search.doc.mjs +5 -1
- package/api/search/search.mjs +10 -3
- package/api/search/search.test.mjs +34 -0
- package/api/swizzle/copy/copy.mjs +28 -11
- package/api/swizzle/swizzle.doc.mjs +1 -1
- package/api/template/copy/copy.mjs +17 -23
- package/api/template/copy/copy.test.mjs +17 -0
- package/api/template/template.doc.mjs +2 -1
- package/api/theme/add/add.binary.test.mjs +91 -0
- package/api/theme/add/add.mjs +20 -3
- package/api/theme/add/add.staging.test.mjs +66 -0
- package/api/theme/build/build.mjs +114 -37
- package/api/theme/build/build.public-component-vars.test.mjs +1 -1
- package/api/theme/build/build.receipt-doc.test.mjs +111 -0
- package/api/theme/build/font-warning.mjs +3 -3
- package/api/theme/build/font-warning.test.mjs +5 -2
- package/api/theme/palette/generate/generate.mjs +7 -2
- package/api/theme/palette/generate/generate.test.mjs +96 -0
- package/api/theme/palette/generate/generator.mjs +8 -1
- package/api/theme/palette/generate/generator.test.mjs +10 -0
- package/api/theme/template/template.mjs +11 -2
- package/api/theme/template/template.test.mjs +15 -0
- package/api/theme/themeBuild.doc.mjs +7 -4
- package/api/theme/themeTemplate.doc.mjs +4 -1
- package/api/upgrade/_adapter.mjs +27 -4
- package/api/upgrade/list/list.mjs +2 -1
- package/api/upgrade/list/list.test.mjs +73 -0
- package/api/upgrade/status/status.mjs +2 -2
- package/api/upgrade/upgrade.doc.mjs +2 -1
- package/api/upgrade/upgrade.type.d.mts +4 -0
- package/api/upgrade/upgrade.type.mjs +1 -0
- package/assets/codemods/term-log.mjs +32 -8
- package/assets/codemods/term-log.test.mjs +19 -1
- package/assets/codemods/transform-prop.mjs +109 -0
- package/assets/codemods/transform-prop.test.mjs +95 -0
- package/assets/codemods/transforms/v0.0.14/__tests__/rename-status-variants.test.mjs +86 -165
- package/assets/codemods/transforms/v0.0.14/rename-status-variants.mjs +72 -210
- package/assets/codemods/transforms/v0.1.8/__tests__/rename-avatar-size-scale.test.mjs +83 -115
- package/assets/codemods/transforms/v0.1.8/rename-avatar-size-scale.mjs +57 -186
- package/assets/codemods/transforms/v0.6.0/__tests__/next-codemods.test.mjs +47 -0
- package/assets/codemods/transforms/v0.6.0/rename-resizable-pixel-bounds.mjs +57 -10
- package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaInlineRail.doc.mjs +14 -0
- package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaInlineRail.tsx +61 -0
- package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaOverscrollChaining.doc.mjs +14 -0
- package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaOverscrollChaining.tsx +126 -0
- package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaShowcase.doc.mjs +15 -0
- package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaShowcase.tsx +86 -0
- package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyGroupHeaders.doc.mjs +14 -0
- package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyGroupHeaders.tsx +99 -0
- package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyPassthrough.doc.mjs +14 -0
- package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyPassthrough.tsx +122 -0
- package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaTwoAxisBoard.doc.mjs +14 -0
- package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaTwoAxisBoard.tsx +95 -0
- package/assets/templates/pages/table-tree/page.tsx +1704 -0
- package/assets/templates/pages/table-tree/template.doc.mjs +12 -0
- package/authoring/config/config.doc.mjs +1 -1
- package/authoring/config/debug-composition.test.mjs +92 -0
- package/authoring/config/type.ts +15 -3
- package/clients/cli/command-load-failure.test.mjs +83 -0
- package/clients/cli/commands/blog.mjs +23 -8
- package/clients/cli/commands/blog.test.mjs +42 -1
- package/clients/cli/commands/build-theme.ascii-output.test.mjs +161 -0
- package/clients/cli/commands/build-theme.flag-docs.test.mjs +110 -0
- package/clients/cli/commands/build-theme.mjs +5 -5
- package/clients/cli/commands/build-theme.path-safety.test.mjs +86 -1
- package/clients/cli/commands/build-theme.variants.test.mjs +76 -0
- package/clients/cli/commands/build.doc.mjs +4 -1
- package/clients/cli/commands/build.exit-codes-doc.test.mjs +50 -0
- package/clients/cli/commands/build.mjs +32 -47
- package/clients/cli/commands/build.playbook.test.mjs +75 -0
- package/clients/cli/commands/build.text-fields.test.mjs +40 -0
- package/clients/cli/commands/component/index.mjs +2 -7
- package/clients/cli/commands/component-package.test.mjs +46 -0
- package/clients/cli/commands/component-resolution.test.mjs +21 -0
- package/clients/cli/commands/component.test.mjs +19 -0
- package/clients/cli/commands/detail-levels.test.mjs +2 -2
- package/clients/cli/commands/discover.broken-integration.test.mjs +48 -0
- package/clients/cli/commands/discover.components-flag.test.mjs +97 -0
- package/clients/cli/commands/discover.doc.mjs +4 -2
- package/clients/cli/commands/discover.mjs +3 -3
- package/clients/cli/commands/discover.text-projection.test.mjs +103 -0
- package/clients/cli/commands/doctor-integration.package-json.test.mjs +53 -0
- package/clients/cli/commands/doctor.mjs +6 -16
- package/clients/cli/commands/doctor.test.mjs +42 -0
- package/clients/cli/commands/gap-report.doc.mjs +16 -5
- package/clients/cli/commands/gap-report.test.mjs +72 -0
- package/clients/cli/commands/hook/index.mjs +7 -17
- package/clients/cli/commands/hook.text-projection.test.mjs +45 -0
- package/clients/cli/commands/init.doc.mjs +19 -8
- package/clients/cli/commands/init.flag-help.test.mjs +153 -0
- package/clients/cli/commands/integration-add.controls.test.mjs +132 -0
- package/clients/cli/commands/integration-add.doc.mjs +21 -5
- package/clients/cli/commands/interactive-guard.test.mjs +101 -24
- package/clients/cli/commands/json-contract.test.mjs +33 -0
- package/clients/cli/commands/layout-check.doc.mjs +14 -3
- package/clients/cli/commands/layout-expand.doc.mjs +21 -4
- package/clients/cli/commands/layout.doc.mjs +2 -2
- package/clients/cli/commands/layout.mjs +21 -9
- package/clients/cli/commands/layout.path-help.test.mjs +33 -0
- package/clients/cli/commands/layout.stdin-cap.test.mjs +47 -0
- package/clients/cli/commands/layout.text-fields.test.mjs +39 -0
- package/clients/cli/commands/no-prompt-wording.test.mjs +94 -0
- package/clients/cli/commands/search.doc.mjs +6 -3
- package/clients/cli/commands/search.mjs +17 -7
- package/clients/cli/commands/search.test.mjs +75 -0
- package/clients/cli/commands/swizzle.doc.mjs +2 -1
- package/clients/cli/commands/swizzle.path-safety.test.mjs +42 -0
- package/clients/cli/commands/template.doc.mjs +28 -6
- package/clients/cli/commands/template.flag-help.test.mjs +117 -0
- package/clients/cli/commands/template.path-help.test.mjs +40 -0
- package/clients/cli/commands/theme-add.doc.mjs +2 -1
- package/clients/cli/commands/theme-build.doc.mjs +7 -6
- package/clients/cli/commands/theme-palette-generate.test.mjs +19 -0
- package/clients/cli/commands/theme-template.behavior.test.mjs +12 -0
- package/clients/cli/commands/theme-template.doc.mjs +1 -1
- package/clients/cli/commands/upgrade.ascii-output.test.mjs +87 -0
- package/clients/cli/commands/upgrade.doc.mjs +17 -6
- package/clients/cli/commands/upgrade.flag-help.test.mjs +188 -0
- package/clients/cli/commands/upgrade.hook-output.test.mjs +88 -0
- package/clients/cli/index.mjs +13 -30
- package/clients/cli/latest-version-env.test.mjs +50 -0
- package/clients/cli/lib/cli-error.test.mjs +7 -0
- package/clients/cli/lib/component-format.mjs +9 -9
- package/clients/cli/lib/component-format.test.mjs +1 -1
- package/clients/cli/lib/define-command.mjs +32 -6
- package/clients/cli/lib/doc-text-ascii.test.mjs +82 -0
- package/clients/cli/lib/exit-codes.test.mjs +97 -0
- package/clients/cli/lib/hook-format.mjs +5 -5
- package/clients/cli/lib/json-shim.mjs +38 -2
- package/clients/cli/lib/json-shim.test.mjs +83 -0
- package/clients/cli/lib/manifest.d.ts +2 -0
- package/clients/cli/lib/manifest.mjs +22 -0
- package/clients/cli/lib/manifest.test.mjs +17 -0
- package/foundation/agent-docs/agent-docs.d.mts +4 -0
- package/foundation/agent-docs/agent-docs.mjs +69 -3
- package/foundation/agent-docs/agent-docs.path-safety.test.mjs +266 -4
- package/foundation/config/integration-debug.test.mjs +28 -3
- package/foundation/config/project.mjs +123 -9
- package/foundation/config/project.test.mjs +126 -0
- package/foundation/discovery/template-adapter.d.mts +14 -5
- package/foundation/discovery/template-adapter.fixture-refs.test.mjs +248 -0
- package/foundation/discovery/template-adapter.integration-isolation.test.mjs +94 -0
- package/foundation/discovery/template-adapter.mjs +292 -25
- package/foundation/discovery/theming-targets.test.mjs +4 -0
- package/foundation/fs/module-loader.d.mts +1 -0
- package/foundation/fs/module-loader.mjs +50 -1
- package/foundation/fs/module-loader.stdout.test.mjs +332 -0
- package/foundation/fs/path-safety.d.mts +3 -2
- package/foundation/fs/path-safety.mjs +49 -19
- package/foundation/fs/path-safety.test.mjs +50 -0
- package/foundation/fs/publish-file-hardlink-unavailable.test.mjs +129 -94
- package/foundation/integrations/autolink.mjs +6 -1
- package/foundation/response/base.d.ts +8 -4
- package/foundation/response/error-codes.doc.mjs +1 -2
- package/foundation/response/error-codes.mjs +1 -1
- package/foundation/response/error-codes.test.mjs +83 -0
- package/foundation/response/json-contract.test.mjs +11 -0
- package/foundation/response/json.d.mts +4 -2
- package/foundation/response/json.mjs +8 -10
- package/foundation/response/response-types.doc.mjs +10 -10
- package/foundation/response/response-types.doc.test.mjs +158 -0
- package/foundation/xle/expand.d.mts +2 -0
- package/foundation/xle/expand.mjs +3 -2
- package/foundation/xle/expand.test.mjs +54 -0
- package/package.json +9 -9
- package/clients/cli/lib/update-check.mjs +0 -83
- package/clients/cli/lib/update-check.test.mjs +0 -137
- package/clients/cli/update-hint-commands.test.mjs +0 -54
|
@@ -29,6 +29,9 @@
|
|
|
29
29
|
* 4. Routing unknown-subcommand attempts through the same error
|
|
30
30
|
* envelope path (so `astryx bogus-cmd --json` gets exit 1 + envelope
|
|
31
31
|
* instead of exit 0 + help envelope).
|
|
32
|
+
* 5. Emitting an error envelope, not the help envelope, when Commander
|
|
33
|
+
* shows help because the invocation failed (`help <unknown>`, or a
|
|
34
|
+
* command group with no subcommand), which exits 1.
|
|
32
35
|
*
|
|
33
36
|
* Non-JSON behavior is preserved exactly: every code path that printed
|
|
34
37
|
* to stderr before still prints to stderr. Commander writes its
|
|
@@ -117,6 +120,35 @@ export function buildHelpEnvelope(cmd) {
|
|
|
117
120
|
};
|
|
118
121
|
}
|
|
119
122
|
|
|
123
|
+
/**
|
|
124
|
+
* The error envelope for help Commander shows because the invocation failed
|
|
125
|
+
* (it then exits 1): `help <name>` for an unknown name on the root, or a
|
|
126
|
+
* command group run without a subcommand.
|
|
127
|
+
*
|
|
128
|
+
* @param {import('commander').Command} cmd the command whose help was shown
|
|
129
|
+
* @returns {ReturnType<typeof toErrorEnvelope>}
|
|
130
|
+
*/
|
|
131
|
+
export function buildHelpErrorEnvelope(cmd) {
|
|
132
|
+
const available = cmd.commands
|
|
133
|
+
.filter(s => !(/** @type {any} */ (s))._hidden && s.name() !== 'help')
|
|
134
|
+
.map(s => s.name());
|
|
135
|
+
if (!cmd.parent) {
|
|
136
|
+
// Commander dispatches `help <name>` with ['help', <name>, ...] in args.
|
|
137
|
+
const requested = cmd.args[1];
|
|
138
|
+
return toErrorEnvelope(
|
|
139
|
+
requested ? `unknown command '${requested}'` : 'unknown command',
|
|
140
|
+
available.map(name => ({name, reason: 'available command'})),
|
|
141
|
+
ERROR_CODES.ERR_UNKNOWN_COMMAND,
|
|
142
|
+
);
|
|
143
|
+
}
|
|
144
|
+
const group = fullNameOf(cmd);
|
|
145
|
+
return toErrorEnvelope(
|
|
146
|
+
`'${group}' needs a subcommand`,
|
|
147
|
+
available.map(name => ({name: `${group} ${name}`, reason: 'available subcommand'})),
|
|
148
|
+
ERROR_CODES.ERR_MISSING_ARGUMENT,
|
|
149
|
+
);
|
|
150
|
+
}
|
|
151
|
+
|
|
120
152
|
/**
|
|
121
153
|
* Emit a JSON error envelope to stdout (the JSON contract uses stdout
|
|
122
154
|
* for both success and error).
|
|
@@ -310,7 +342,9 @@ function patchOutputHelp(cmd) {
|
|
|
310
342
|
if (jsonActive()) {
|
|
311
343
|
if (!process.__xdsJsonHandled) {
|
|
312
344
|
process.__xdsJsonHandled = true;
|
|
313
|
-
const env =
|
|
345
|
+
const env = contextOptions?.error
|
|
346
|
+
? buildHelpErrorEnvelope(cmd)
|
|
347
|
+
: buildHelpEnvelope(cmd);
|
|
314
348
|
process.stdout.write(`${JSON.stringify(env, null, 2)}\n`);
|
|
315
349
|
}
|
|
316
350
|
return;
|
|
@@ -334,7 +368,9 @@ function patchPrototype(CommandCtor) {
|
|
|
334
368
|
if (jsonActive()) {
|
|
335
369
|
if (!process.__xdsJsonHandled) {
|
|
336
370
|
process.__xdsJsonHandled = true;
|
|
337
|
-
const env =
|
|
371
|
+
const env = contextOptions?.error
|
|
372
|
+
? buildHelpErrorEnvelope(this)
|
|
373
|
+
: buildHelpEnvelope(this);
|
|
338
374
|
process.stdout.write(`${JSON.stringify(env, null, 2)}\n`);
|
|
339
375
|
}
|
|
340
376
|
return;
|
|
@@ -20,7 +20,12 @@
|
|
|
20
20
|
*/
|
|
21
21
|
|
|
22
22
|
import {describe, it, expect} from 'vitest';
|
|
23
|
+
import {spawnSync} from 'node:child_process';
|
|
24
|
+
import {fileURLToPath} from 'node:url';
|
|
25
|
+
import {Command} from 'commander';
|
|
23
26
|
import {runCli} from '../../../test-utils/run-cli.mjs';
|
|
27
|
+
import {installJsonShim} from './json-shim.mjs';
|
|
28
|
+
import {setJsonMode} from '../../../foundation/response/json.mjs';
|
|
24
29
|
|
|
25
30
|
function parseJson(stdout) {
|
|
26
31
|
return JSON.parse(stdout);
|
|
@@ -207,3 +212,81 @@ describe('--json shim: stdout discipline under --json', () => {
|
|
|
207
212
|
}
|
|
208
213
|
});
|
|
209
214
|
});
|
|
215
|
+
|
|
216
|
+
describe('--json shim: help shown for a failed invocation is an error envelope', () => {
|
|
217
|
+
it('astryx help bogus --json emits ERR_UNKNOWN_COMMAND, exit 1', async () => {
|
|
218
|
+
const {status, stdout, stderr} = await runCli(['help', 'bogus', '--json']);
|
|
219
|
+
expect(status).toBe(1);
|
|
220
|
+
expect(stderr).toBe('');
|
|
221
|
+
const parsed = parseJson(stdout);
|
|
222
|
+
expect(parsed).not.toHaveProperty('type');
|
|
223
|
+
expect(parsed.apiVersion).toBe(1);
|
|
224
|
+
expect(parsed.code).toBe('ERR_UNKNOWN_COMMAND');
|
|
225
|
+
expect(parsed.error).toMatch(/bogus/);
|
|
226
|
+
});
|
|
227
|
+
|
|
228
|
+
it('astryx layout --json (group, no subcommand) emits ERR_MISSING_ARGUMENT, exit 1', async () => {
|
|
229
|
+
const {status, stdout, stderr} = await runCli(['layout', '--json']);
|
|
230
|
+
expect(status).toBe(1);
|
|
231
|
+
expect(stderr).toBe('');
|
|
232
|
+
const parsed = parseJson(stdout);
|
|
233
|
+
expect(parsed).not.toHaveProperty('type');
|
|
234
|
+
expect(parsed.code).toBe('ERR_MISSING_ARGUMENT');
|
|
235
|
+
expect(parsed.suggestions.map((s) => s.name)).toContain('layout expand');
|
|
236
|
+
});
|
|
237
|
+
|
|
238
|
+
it('astryx layout (no --json) still prints help to stderr, exit 1', async () => {
|
|
239
|
+
const {status, stdout, stderr} = await runCli(['layout']);
|
|
240
|
+
expect(status).toBe(1);
|
|
241
|
+
expect(stdout).toBe('');
|
|
242
|
+
expect(stderr).toMatch(/Usage: astryx layout/);
|
|
243
|
+
});
|
|
244
|
+
|
|
245
|
+
it('the real binary emits the same envelope for help bogus --json', () => {
|
|
246
|
+
// One program per process, so the root's own outputHelp patch is used here.
|
|
247
|
+
const bin = fileURLToPath(new URL('../bin/astryx.mjs', import.meta.url));
|
|
248
|
+
const res = spawnSync(process.execPath, [bin, 'help', 'bogus', '--json'], {
|
|
249
|
+
encoding: 'utf-8',
|
|
250
|
+
timeout: 20_000,
|
|
251
|
+
});
|
|
252
|
+
expect(res.status).toBe(1);
|
|
253
|
+
expect(res.stderr).toBe('');
|
|
254
|
+
const parsed = parseJson(res.stdout);
|
|
255
|
+
expect(parsed).not.toHaveProperty('type');
|
|
256
|
+
expect(parsed.code).toBe('ERR_UNKNOWN_COMMAND');
|
|
257
|
+
});
|
|
258
|
+
|
|
259
|
+
it('a group added after install gets the same error envelope', () => {
|
|
260
|
+
const program = new Command('astryx');
|
|
261
|
+
installJsonShim(program);
|
|
262
|
+
// Added later, so only the prototype-level patch covers its outputHelp.
|
|
263
|
+
const late = new Command('late');
|
|
264
|
+
late.command('child');
|
|
265
|
+
program.addCommand(late);
|
|
266
|
+
/** @type {string[]} */
|
|
267
|
+
const writes = [];
|
|
268
|
+
const origWrite = process.stdout.write;
|
|
269
|
+
// @ts-expect-error - test-only capture
|
|
270
|
+
process.stdout.write = (chunk) => writes.push(String(chunk)) > 0;
|
|
271
|
+
setJsonMode(true);
|
|
272
|
+
delete process.__xdsJsonHandled;
|
|
273
|
+
try {
|
|
274
|
+
late.outputHelp({error: true});
|
|
275
|
+
} finally {
|
|
276
|
+
process.stdout.write = origWrite;
|
|
277
|
+
setJsonMode(false);
|
|
278
|
+
delete process.__xdsJsonHandled;
|
|
279
|
+
}
|
|
280
|
+
const parsed = parseJson(writes.join(''));
|
|
281
|
+
expect(parsed.code).toBe('ERR_MISSING_ARGUMENT');
|
|
282
|
+
expect(parsed.suggestions).toEqual([{name: 'late child', reason: 'available subcommand'}]);
|
|
283
|
+
});
|
|
284
|
+
|
|
285
|
+
it('astryx help layout --json still emits the help envelope, exit 0', async () => {
|
|
286
|
+
const {status, stdout} = await runCli(['help', 'layout', '--json']);
|
|
287
|
+
expect(status).toBe(0);
|
|
288
|
+
const parsed = parseJson(stdout);
|
|
289
|
+
expect(parsed.type).toBe('help');
|
|
290
|
+
expect(parsed.data.command).toBe('astryx layout');
|
|
291
|
+
});
|
|
292
|
+
});
|
|
@@ -48,6 +48,8 @@ export interface ManifestCommand {
|
|
|
48
48
|
responseTypes?: string[];
|
|
49
49
|
/** Example invocations. */
|
|
50
50
|
examples?: string[];
|
|
51
|
+
/** Documented exit codes: the process exit status and when it occurs. */
|
|
52
|
+
exitCodes?: {code: number; when: string}[];
|
|
51
53
|
/** Nested subcommands (e.g. `theme build` under `theme`). */
|
|
52
54
|
subcommands?: ManifestCommand[];
|
|
53
55
|
}
|
|
@@ -35,6 +35,8 @@
|
|
|
35
35
|
*/
|
|
36
36
|
|
|
37
37
|
import {API_VERSION} from '../../../foundation/response/json.mjs';
|
|
38
|
+
import {commandDocsOf} from './define-command.mjs';
|
|
39
|
+
import {doc as manifestDoc} from '../commands/manifest.doc.mjs';
|
|
38
40
|
|
|
39
41
|
/**
|
|
40
42
|
* Response `type` discriminators each fully-qualified command can emit in
|
|
@@ -237,6 +239,18 @@ function fullName(cmd, root) {
|
|
|
237
239
|
return parts.join(' ');
|
|
238
240
|
}
|
|
239
241
|
|
|
242
|
+
/**
|
|
243
|
+
* The docs a command was built from. `manifest` is registered by hand in
|
|
244
|
+
* index.mjs, so its CommandDoc is read here.
|
|
245
|
+
* @param {import('commander').Command} cmd
|
|
246
|
+
* @param {string} name
|
|
247
|
+
*/
|
|
248
|
+
function docsOf(cmd, name) {
|
|
249
|
+
return (
|
|
250
|
+
commandDocsOf(cmd) ?? (name === 'manifest' ? {doc: manifestDoc} : undefined)
|
|
251
|
+
);
|
|
252
|
+
}
|
|
253
|
+
|
|
240
254
|
/**
|
|
241
255
|
* Recursively describe a Commander command and its subcommands.
|
|
242
256
|
*
|
|
@@ -252,6 +266,8 @@ function describeCommand(cmd, root, jsonSupported) {
|
|
|
252
266
|
// `_hidden` is a Commander internal not present on its public types.
|
|
253
267
|
if (!name || /** @type {any} */ (cmd)._hidden || name === 'help') return null;
|
|
254
268
|
|
|
269
|
+
const docs = docsOf(cmd, name);
|
|
270
|
+
|
|
255
271
|
const subcommands = /** @type {object[]} */ (
|
|
256
272
|
(cmd.commands || [])
|
|
257
273
|
.map(sub => describeCommand(sub, root, jsonSupported))
|
|
@@ -284,6 +300,12 @@ function describeCommand(cmd, root, jsonSupported) {
|
|
|
284
300
|
|
|
285
301
|
if (EXAMPLES[name]) entry.examples = [...EXAMPLES[name]];
|
|
286
302
|
|
|
303
|
+
const exitCodes = (docs?.doc.exitCodes ?? []).map(({code, when}) => ({
|
|
304
|
+
code,
|
|
305
|
+
when,
|
|
306
|
+
}));
|
|
307
|
+
if (exitCodes.length > 0) entry.exitCodes = exitCodes;
|
|
308
|
+
|
|
287
309
|
// Sort subcommands by name for a stable, agent-facing contract — the same
|
|
288
310
|
// guarantee the top-level command list makes. Otherwise Commander
|
|
289
311
|
// registration order leaks into the manifest and a pure reorder of
|
|
@@ -196,3 +196,20 @@ describe('manifest: e2e', () => {
|
|
|
196
196
|
.toContain('component.list');
|
|
197
197
|
});
|
|
198
198
|
});
|
|
199
|
+
|
|
200
|
+
describe('manifest: text projection', () => {
|
|
201
|
+
it('astryx manifest (text) uses the JSON entry keys as its field names', async () => {
|
|
202
|
+
const text = await runCli(['manifest']);
|
|
203
|
+
expect(text.status).toBe(0);
|
|
204
|
+
const json = JSON.parse((await runCli(['manifest', '--json'])).stdout);
|
|
205
|
+
const jsonKeys = new Set(json.data.commands.flatMap((c) => Object.keys(c)));
|
|
206
|
+
const textKeys = new Set(
|
|
207
|
+
text.stdout
|
|
208
|
+
.split('\n')
|
|
209
|
+
.map((line) => /^([A-Za-z]+):\s/.exec(line)?.[1])
|
|
210
|
+
.filter(Boolean),
|
|
211
|
+
);
|
|
212
|
+
expect(textKeys).toContain('name');
|
|
213
|
+
for (const key of textKeys) expect(jsonKeys).toContain(key);
|
|
214
|
+
});
|
|
215
|
+
});
|
|
@@ -182,6 +182,8 @@ export function removeXdsBlock(filePath: string, { deleteIfEmpty }?: {
|
|
|
182
182
|
/**
|
|
183
183
|
* Remove Astryx section from all known agent doc files.
|
|
184
184
|
* @param {string} targetDir
|
|
185
|
+
* @throws {PathSafetyError} `ERR_PATH_TRAVERSAL` when a file it would change
|
|
186
|
+
* resolves outside `targetDir`; nothing is changed.
|
|
185
187
|
*/
|
|
186
188
|
export function removeAgentDocs(targetDir: string): void;
|
|
187
189
|
/**
|
|
@@ -208,6 +210,8 @@ export function removeAgentDocs(targetDir: string): void;
|
|
|
208
210
|
* @param {string} [options.renderedBlock] - Fully rendered expected block. Init
|
|
209
211
|
* and upgrade pass one shared block to every target.
|
|
210
212
|
* @returns {string[]} List of files written
|
|
213
|
+
* @throws {import('../fs/path-safety.mjs').PathSafetyError} when a file it would
|
|
214
|
+
* write resolves outside `targetDir`; nothing is written.
|
|
211
215
|
*/
|
|
212
216
|
export function installAgentDocs(targetDir: string, { zh, lang, agent, paths, onlyReplace, topics, renderedBlock, }?: {
|
|
213
217
|
zh?: boolean | undefined;
|
|
@@ -22,11 +22,12 @@
|
|
|
22
22
|
import * as fs from 'node:fs';
|
|
23
23
|
import * as path from 'node:path';
|
|
24
24
|
import {findCoreDir, CLI_ROOT} from '../fs/paths.mjs';
|
|
25
|
-
import {assertWithin} from '../fs/path-safety.mjs';
|
|
25
|
+
import {assertWithin, PathSafetyError} from '../fs/path-safety.mjs';
|
|
26
26
|
import {getCliInvocation} from '../env/package-manager.mjs';
|
|
27
27
|
import {discoverComponents} from '../discovery/component-discovery.mjs';
|
|
28
28
|
import {Project} from '../config/project.mjs';
|
|
29
29
|
import {humanLog} from '../response/json.mjs';
|
|
30
|
+
import {ERROR_CODES} from '../response/error-codes.mjs';
|
|
30
31
|
import {
|
|
31
32
|
AGENTS_MD,
|
|
32
33
|
CLAUDE_MD,
|
|
@@ -705,12 +706,65 @@ export function removeXdsBlock(filePath, {deleteIfEmpty = false} = {}) {
|
|
|
705
706
|
return true;
|
|
706
707
|
}
|
|
707
708
|
|
|
709
|
+
/**
|
|
710
|
+
* Whether an agent-doc file already carries a managed-block marker.
|
|
711
|
+
* @param {string} filePath
|
|
712
|
+
* @returns {boolean}
|
|
713
|
+
*/
|
|
714
|
+
function hasManagedMarker(filePath) {
|
|
715
|
+
try {
|
|
716
|
+
const content = fs.readFileSync(filePath, 'utf-8');
|
|
717
|
+
return content.includes(MARKER_START) || content.includes(LEGACY_MARKER_START);
|
|
718
|
+
} catch {
|
|
719
|
+
return false;
|
|
720
|
+
}
|
|
721
|
+
}
|
|
722
|
+
|
|
723
|
+
/**
|
|
724
|
+
* Whether `removeXdsBlock` would change `filePath`: it holds one well-formed
|
|
725
|
+
* managed block.
|
|
726
|
+
* @param {string} filePath
|
|
727
|
+
* @returns {boolean}
|
|
728
|
+
*/
|
|
729
|
+
function hasRemovableBlock(filePath) {
|
|
730
|
+
try {
|
|
731
|
+
return findManagedBlock(fs.readFileSync(filePath, 'utf-8')) != null;
|
|
732
|
+
} catch {
|
|
733
|
+
return false;
|
|
734
|
+
}
|
|
735
|
+
}
|
|
736
|
+
|
|
737
|
+
/**
|
|
738
|
+
* Every file a run writes must resolve inside `targetDir`, symlinks
|
|
739
|
+
* included. Checked for the whole write set before the first write, so an
|
|
740
|
+
* escape writes nothing.
|
|
741
|
+
* @param {string} targetDir
|
|
742
|
+
* @param {Iterable<string>} relPaths
|
|
743
|
+
*/
|
|
744
|
+
function assertTargetsWithin(targetDir, relPaths) {
|
|
745
|
+
for (const p of relPaths) {
|
|
746
|
+
assertWithin(p, targetDir, {label: 'agent docs path'});
|
|
747
|
+
}
|
|
748
|
+
}
|
|
749
|
+
|
|
708
750
|
/**
|
|
709
751
|
* Remove Astryx section from all known agent doc files.
|
|
710
752
|
* @param {string} targetDir
|
|
753
|
+
* @throws {PathSafetyError} `ERR_PATH_TRAVERSAL` when a file it would change
|
|
754
|
+
* resolves outside `targetDir`; nothing is changed.
|
|
711
755
|
*/
|
|
712
756
|
export function removeAgentDocs(targetDir) {
|
|
713
757
|
const allPaths = discoverAgentDocs(targetDir);
|
|
758
|
+
try {
|
|
759
|
+
assertTargetsWithin(
|
|
760
|
+
targetDir,
|
|
761
|
+
allPaths.filter(p => hasRemovableBlock(path.join(targetDir, p))),
|
|
762
|
+
);
|
|
763
|
+
} catch (err) {
|
|
764
|
+
// The code reaches the error envelope as is, so it must be registered.
|
|
765
|
+
if (!(err instanceof PathSafetyError)) throw err;
|
|
766
|
+
throw new PathSafetyError(err.message, ERROR_CODES.ERR_PATH_TRAVERSAL);
|
|
767
|
+
}
|
|
714
768
|
|
|
715
769
|
for (const p of allPaths) {
|
|
716
770
|
const filePath = path.join(targetDir, p);
|
|
@@ -718,9 +772,9 @@ export function removeAgentDocs(targetDir) {
|
|
|
718
772
|
const deleteIfEmpty = p === AGENTS_MD || p === CLAUDE_DIR_MD;
|
|
719
773
|
if (removeXdsBlock(filePath, {deleteIfEmpty})) {
|
|
720
774
|
if (!fs.existsSync(filePath)) {
|
|
721
|
-
humanLog(
|
|
775
|
+
humanLog(`[ok] Removed empty ${p}`);
|
|
722
776
|
} else {
|
|
723
|
-
humanLog(
|
|
777
|
+
humanLog(`[ok] Removed design system section from ${p}`);
|
|
724
778
|
}
|
|
725
779
|
}
|
|
726
780
|
}
|
|
@@ -750,6 +804,8 @@ export function removeAgentDocs(targetDir) {
|
|
|
750
804
|
* @param {string} [options.renderedBlock] - Fully rendered expected block. Init
|
|
751
805
|
* and upgrade pass one shared block to every target.
|
|
752
806
|
* @returns {string[]} List of files written
|
|
807
|
+
* @throws {import('../fs/path-safety.mjs').PathSafetyError} when a file it would
|
|
808
|
+
* write resolves outside `targetDir`; nothing is written.
|
|
753
809
|
*/
|
|
754
810
|
export function installAgentDocs(
|
|
755
811
|
targetDir,
|
|
@@ -806,6 +862,7 @@ export function installAgentDocs(
|
|
|
806
862
|
// Agent preset
|
|
807
863
|
if (agent) {
|
|
808
864
|
const {inject, create} = resolveAgentPaths(targetDir, agent);
|
|
865
|
+
assertTargetsWithin(targetDir, [...inject, ...create]);
|
|
809
866
|
for (const p of inject) {
|
|
810
867
|
injectXdsBlock(path.join(targetDir, p), compressedIndex);
|
|
811
868
|
written.push(p);
|
|
@@ -833,6 +890,14 @@ export function installAgentDocs(
|
|
|
833
890
|
if (existing.length > 0) {
|
|
834
891
|
const wrappers = discoverAgentDocWrappers(targetDir, existing);
|
|
835
892
|
const targets = existing.filter(p => !wrappers.has(p));
|
|
893
|
+
// A refresh skips unmarked files and a wrapper is only written when it
|
|
894
|
+
// carries a block, so only the files this run writes are checked.
|
|
895
|
+
/** @param {string} p */
|
|
896
|
+
const marked = p => hasManagedMarker(path.join(targetDir, p));
|
|
897
|
+
assertTargetsWithin(targetDir, [
|
|
898
|
+
...targets.filter(p => !onlyReplace || marked(p)),
|
|
899
|
+
...[...wrappers].filter(marked),
|
|
900
|
+
]);
|
|
836
901
|
|
|
837
902
|
for (const p of targets) {
|
|
838
903
|
const didWrite = injectXdsBlock(path.join(targetDir, p), compressedIndex, {onlyReplace});
|
|
@@ -860,6 +925,7 @@ export function installAgentDocs(
|
|
|
860
925
|
if (onlyReplace) return written;
|
|
861
926
|
|
|
862
927
|
const defaultPath = AGENTS_MD;
|
|
928
|
+
assertTargetsWithin(targetDir, [defaultPath]);
|
|
863
929
|
injectXdsBlock(path.join(targetDir, defaultPath), compressedIndex, {
|
|
864
930
|
createIfMissing: true,
|
|
865
931
|
header: `# AGENTS.md\n\nProject-specific guidance for AI coding agents.`,
|