@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.
Files changed (206) hide show
  1. package/README.md +86 -72
  2. package/api/build/build.doc.mjs +3 -3
  3. package/api/build/build.test.mjs +14 -3
  4. package/api/build/build.type.d.mts +35 -1
  5. package/api/build/build.type.mjs +24 -3
  6. package/api/build/help/help.d.mts +8 -5
  7. package/api/build/help/help.mjs +56 -6
  8. package/api/component/component.doc.mjs +12 -3
  9. package/api/component/component.mjs +31 -2
  10. package/api/component/component.test.mjs +38 -0
  11. package/api/component/component.type.d.mts +16 -5
  12. package/api/component/component.type.mjs +13 -5
  13. package/api/component/detail/blocks/blocks.d.mts +2 -1
  14. package/api/component/detail/blocks/blocks.mjs +4 -3
  15. package/api/component/list/list.d.mts +0 -5
  16. package/api/component/list/list.mjs +37 -9
  17. package/api/discover/discover.doc.mjs +1 -1
  18. package/api/gap-report/gap-report.doc.mjs +7 -4
  19. package/api/init/init.doc.mjs +4 -0
  20. package/api/init/init.test.mjs +41 -1
  21. package/api/init/remove/remove.mjs +1 -1
  22. package/api/init/run/run.mjs +20 -10
  23. package/api/integration/add-contribution.component-names.test.mjs +120 -0
  24. package/api/integration/add-contribution.mjs +11 -0
  25. package/api/integration/add-contribution.test.mjs +80 -0
  26. package/api/integration/integrationAdd.doc.mjs +7 -4
  27. package/api/integration/integrationAddComponent.doc.mjs +1 -1
  28. package/api/integration/validate-integration.mjs +2 -0
  29. package/api/integration/validate-integration.test.mjs +91 -0
  30. package/api/integration/validateIntegration.doc.mjs +1 -1
  31. package/api/json/envelope-types.test.mjs +76 -0
  32. package/api/json/parseResponse.doc.mjs +2 -2
  33. package/api/layout/expand/expand.mjs +7 -5
  34. package/api/layout/expand/expand.path-safety.test.mjs +53 -0
  35. package/api/layout/grammar/grammar.mjs +2 -1
  36. package/api/layout/layoutExpand.doc.mjs +1 -1
  37. package/api/search/search-return-type.test.mjs +54 -0
  38. package/api/search/search.d.mts +2 -9
  39. package/api/search/search.doc.mjs +5 -1
  40. package/api/search/search.mjs +10 -3
  41. package/api/search/search.test.mjs +34 -0
  42. package/api/swizzle/copy/copy.mjs +28 -11
  43. package/api/swizzle/swizzle.doc.mjs +1 -1
  44. package/api/template/copy/copy.mjs +17 -23
  45. package/api/template/copy/copy.test.mjs +17 -0
  46. package/api/template/template.doc.mjs +2 -1
  47. package/api/theme/add/add.binary.test.mjs +91 -0
  48. package/api/theme/add/add.mjs +20 -3
  49. package/api/theme/add/add.staging.test.mjs +66 -0
  50. package/api/theme/build/build.mjs +114 -37
  51. package/api/theme/build/build.public-component-vars.test.mjs +1 -1
  52. package/api/theme/build/build.receipt-doc.test.mjs +111 -0
  53. package/api/theme/build/font-warning.mjs +3 -3
  54. package/api/theme/build/font-warning.test.mjs +5 -2
  55. package/api/theme/palette/generate/generate.mjs +7 -2
  56. package/api/theme/palette/generate/generate.test.mjs +96 -0
  57. package/api/theme/palette/generate/generator.mjs +8 -1
  58. package/api/theme/palette/generate/generator.test.mjs +10 -0
  59. package/api/theme/template/template.mjs +11 -2
  60. package/api/theme/template/template.test.mjs +15 -0
  61. package/api/theme/themeBuild.doc.mjs +7 -4
  62. package/api/theme/themeTemplate.doc.mjs +4 -1
  63. package/api/upgrade/_adapter.mjs +27 -4
  64. package/api/upgrade/list/list.mjs +2 -1
  65. package/api/upgrade/list/list.test.mjs +73 -0
  66. package/api/upgrade/status/status.mjs +2 -2
  67. package/api/upgrade/upgrade.doc.mjs +2 -1
  68. package/api/upgrade/upgrade.type.d.mts +4 -0
  69. package/api/upgrade/upgrade.type.mjs +1 -0
  70. package/assets/codemods/term-log.mjs +32 -8
  71. package/assets/codemods/term-log.test.mjs +19 -1
  72. package/assets/codemods/transform-prop.mjs +109 -0
  73. package/assets/codemods/transform-prop.test.mjs +95 -0
  74. package/assets/codemods/transforms/v0.0.14/__tests__/rename-status-variants.test.mjs +86 -165
  75. package/assets/codemods/transforms/v0.0.14/rename-status-variants.mjs +72 -210
  76. package/assets/codemods/transforms/v0.1.8/__tests__/rename-avatar-size-scale.test.mjs +83 -115
  77. package/assets/codemods/transforms/v0.1.8/rename-avatar-size-scale.mjs +57 -186
  78. package/assets/codemods/transforms/v0.6.0/__tests__/next-codemods.test.mjs +47 -0
  79. package/assets/codemods/transforms/v0.6.0/rename-resizable-pixel-bounds.mjs +57 -10
  80. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaInlineRail.doc.mjs +14 -0
  81. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaInlineRail.tsx +61 -0
  82. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaOverscrollChaining.doc.mjs +14 -0
  83. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaOverscrollChaining.tsx +126 -0
  84. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaShowcase.doc.mjs +15 -0
  85. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaShowcase.tsx +86 -0
  86. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyGroupHeaders.doc.mjs +14 -0
  87. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyGroupHeaders.tsx +99 -0
  88. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyPassthrough.doc.mjs +14 -0
  89. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyPassthrough.tsx +122 -0
  90. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaTwoAxisBoard.doc.mjs +14 -0
  91. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaTwoAxisBoard.tsx +95 -0
  92. package/assets/templates/pages/table-tree/page.tsx +1704 -0
  93. package/assets/templates/pages/table-tree/template.doc.mjs +12 -0
  94. package/authoring/config/config.doc.mjs +1 -1
  95. package/authoring/config/debug-composition.test.mjs +92 -0
  96. package/authoring/config/type.ts +15 -3
  97. package/clients/cli/command-load-failure.test.mjs +83 -0
  98. package/clients/cli/commands/blog.mjs +23 -8
  99. package/clients/cli/commands/blog.test.mjs +42 -1
  100. package/clients/cli/commands/build-theme.ascii-output.test.mjs +161 -0
  101. package/clients/cli/commands/build-theme.flag-docs.test.mjs +110 -0
  102. package/clients/cli/commands/build-theme.mjs +5 -5
  103. package/clients/cli/commands/build-theme.path-safety.test.mjs +86 -1
  104. package/clients/cli/commands/build-theme.variants.test.mjs +76 -0
  105. package/clients/cli/commands/build.doc.mjs +4 -1
  106. package/clients/cli/commands/build.exit-codes-doc.test.mjs +50 -0
  107. package/clients/cli/commands/build.mjs +32 -47
  108. package/clients/cli/commands/build.playbook.test.mjs +75 -0
  109. package/clients/cli/commands/build.text-fields.test.mjs +40 -0
  110. package/clients/cli/commands/component/index.mjs +2 -7
  111. package/clients/cli/commands/component-package.test.mjs +46 -0
  112. package/clients/cli/commands/component-resolution.test.mjs +21 -0
  113. package/clients/cli/commands/component.test.mjs +19 -0
  114. package/clients/cli/commands/detail-levels.test.mjs +2 -2
  115. package/clients/cli/commands/discover.broken-integration.test.mjs +48 -0
  116. package/clients/cli/commands/discover.components-flag.test.mjs +97 -0
  117. package/clients/cli/commands/discover.doc.mjs +4 -2
  118. package/clients/cli/commands/discover.mjs +3 -3
  119. package/clients/cli/commands/discover.text-projection.test.mjs +103 -0
  120. package/clients/cli/commands/doctor-integration.package-json.test.mjs +53 -0
  121. package/clients/cli/commands/doctor.mjs +6 -16
  122. package/clients/cli/commands/doctor.test.mjs +42 -0
  123. package/clients/cli/commands/gap-report.doc.mjs +16 -5
  124. package/clients/cli/commands/gap-report.test.mjs +72 -0
  125. package/clients/cli/commands/hook/index.mjs +7 -17
  126. package/clients/cli/commands/hook.text-projection.test.mjs +45 -0
  127. package/clients/cli/commands/init.doc.mjs +19 -8
  128. package/clients/cli/commands/init.flag-help.test.mjs +153 -0
  129. package/clients/cli/commands/integration-add.controls.test.mjs +132 -0
  130. package/clients/cli/commands/integration-add.doc.mjs +21 -5
  131. package/clients/cli/commands/interactive-guard.test.mjs +101 -24
  132. package/clients/cli/commands/json-contract.test.mjs +33 -0
  133. package/clients/cli/commands/layout-check.doc.mjs +14 -3
  134. package/clients/cli/commands/layout-expand.doc.mjs +21 -4
  135. package/clients/cli/commands/layout.doc.mjs +2 -2
  136. package/clients/cli/commands/layout.mjs +21 -9
  137. package/clients/cli/commands/layout.path-help.test.mjs +33 -0
  138. package/clients/cli/commands/layout.stdin-cap.test.mjs +47 -0
  139. package/clients/cli/commands/layout.text-fields.test.mjs +39 -0
  140. package/clients/cli/commands/no-prompt-wording.test.mjs +94 -0
  141. package/clients/cli/commands/search.doc.mjs +6 -3
  142. package/clients/cli/commands/search.mjs +17 -7
  143. package/clients/cli/commands/search.test.mjs +75 -0
  144. package/clients/cli/commands/swizzle.doc.mjs +2 -1
  145. package/clients/cli/commands/swizzle.path-safety.test.mjs +42 -0
  146. package/clients/cli/commands/template.doc.mjs +28 -6
  147. package/clients/cli/commands/template.flag-help.test.mjs +117 -0
  148. package/clients/cli/commands/template.path-help.test.mjs +40 -0
  149. package/clients/cli/commands/theme-add.doc.mjs +2 -1
  150. package/clients/cli/commands/theme-build.doc.mjs +7 -6
  151. package/clients/cli/commands/theme-palette-generate.test.mjs +19 -0
  152. package/clients/cli/commands/theme-template.behavior.test.mjs +12 -0
  153. package/clients/cli/commands/theme-template.doc.mjs +1 -1
  154. package/clients/cli/commands/upgrade.ascii-output.test.mjs +87 -0
  155. package/clients/cli/commands/upgrade.doc.mjs +17 -6
  156. package/clients/cli/commands/upgrade.flag-help.test.mjs +188 -0
  157. package/clients/cli/commands/upgrade.hook-output.test.mjs +88 -0
  158. package/clients/cli/index.mjs +13 -30
  159. package/clients/cli/latest-version-env.test.mjs +50 -0
  160. package/clients/cli/lib/cli-error.test.mjs +7 -0
  161. package/clients/cli/lib/component-format.mjs +9 -9
  162. package/clients/cli/lib/component-format.test.mjs +1 -1
  163. package/clients/cli/lib/define-command.mjs +32 -6
  164. package/clients/cli/lib/doc-text-ascii.test.mjs +82 -0
  165. package/clients/cli/lib/exit-codes.test.mjs +97 -0
  166. package/clients/cli/lib/hook-format.mjs +5 -5
  167. package/clients/cli/lib/json-shim.mjs +38 -2
  168. package/clients/cli/lib/json-shim.test.mjs +83 -0
  169. package/clients/cli/lib/manifest.d.ts +2 -0
  170. package/clients/cli/lib/manifest.mjs +22 -0
  171. package/clients/cli/lib/manifest.test.mjs +17 -0
  172. package/foundation/agent-docs/agent-docs.d.mts +4 -0
  173. package/foundation/agent-docs/agent-docs.mjs +69 -3
  174. package/foundation/agent-docs/agent-docs.path-safety.test.mjs +266 -4
  175. package/foundation/config/integration-debug.test.mjs +28 -3
  176. package/foundation/config/project.mjs +123 -9
  177. package/foundation/config/project.test.mjs +126 -0
  178. package/foundation/discovery/template-adapter.d.mts +14 -5
  179. package/foundation/discovery/template-adapter.fixture-refs.test.mjs +248 -0
  180. package/foundation/discovery/template-adapter.integration-isolation.test.mjs +94 -0
  181. package/foundation/discovery/template-adapter.mjs +292 -25
  182. package/foundation/discovery/theming-targets.test.mjs +4 -0
  183. package/foundation/fs/module-loader.d.mts +1 -0
  184. package/foundation/fs/module-loader.mjs +50 -1
  185. package/foundation/fs/module-loader.stdout.test.mjs +332 -0
  186. package/foundation/fs/path-safety.d.mts +3 -2
  187. package/foundation/fs/path-safety.mjs +49 -19
  188. package/foundation/fs/path-safety.test.mjs +50 -0
  189. package/foundation/fs/publish-file-hardlink-unavailable.test.mjs +129 -94
  190. package/foundation/integrations/autolink.mjs +6 -1
  191. package/foundation/response/base.d.ts +8 -4
  192. package/foundation/response/error-codes.doc.mjs +1 -2
  193. package/foundation/response/error-codes.mjs +1 -1
  194. package/foundation/response/error-codes.test.mjs +83 -0
  195. package/foundation/response/json-contract.test.mjs +11 -0
  196. package/foundation/response/json.d.mts +4 -2
  197. package/foundation/response/json.mjs +8 -10
  198. package/foundation/response/response-types.doc.mjs +10 -10
  199. package/foundation/response/response-types.doc.test.mjs +158 -0
  200. package/foundation/xle/expand.d.mts +2 -0
  201. package/foundation/xle/expand.mjs +3 -2
  202. package/foundation/xle/expand.test.mjs +54 -0
  203. package/package.json +9 -9
  204. package/clients/cli/lib/update-check.mjs +0 -83
  205. package/clients/cli/lib/update-check.test.mjs +0 -137
  206. package/clients/cli/update-hint-commands.test.mjs +0 -54
@@ -1,107 +1,142 @@
1
1
  // Copyright (c) Meta Platforms, Inc. and affiliates.
2
2
 
3
3
  /**
4
- * @file Optional integration proof for filesystems that reject hard links.
5
- * Set ASTRYX_HARDLINK_UNAVAILABLE_TEST_ROOT to a writable directory on such a
6
- * filesystem to exercise the real fallback end to end.
4
+ * @file Integration proof for filesystems that reject hard links.
5
+ *
6
+ * A module mock makes `fs.linkSync` fail the way those filesystems do (EPERM,
7
+ * or EXDEV across devices), so `applyWrites` publishes through the
8
+ * exclusive-copy fallback on every run. Private tests use injected seams, not
9
+ * environment variables (AST-017 FR14, DEC-5); the last case holds the
10
+ * publish-file module and its proofs to that.
7
11
  */
8
12
 
9
- import {describe, it, expect, beforeEach, afterEach} from 'vitest';
10
- import * as fs from 'node:fs';
13
+ import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
11
14
  import * as path from 'node:path';
12
- import {applyWrites} from '../../api/integration/add-helpers.mjs';
13
-
14
- const testRoot = process.env.ASTRYX_HARDLINK_UNAVAILABLE_TEST_ROOT ?? null;
15
-
16
- describe.skipIf(!testRoot)(
17
- 'hard-link-unavailable filesystem integration proof',
18
- () => {
19
- let testDir;
20
-
21
- beforeEach(() => {
22
- testDir = fs.mkdtempSync(path.join(testRoot, '.astryx-publish-proof-'));
15
+ import * as os from 'node:os';
16
+ import {fileURLToPath} from 'node:url';
17
+ import jscodeshift from 'jscodeshift';
18
+
19
+ vi.mock('node:fs', async importOriginal => {
20
+ const actual = await importOriginal();
21
+ return {
22
+ ...actual,
23
+ linkSync: vi.fn(() => {
24
+ throw Object.assign(new Error('EPERM: operation not permitted, link'), {code: 'EPERM'});
25
+ }),
26
+ copyFileSync: vi.fn(actual.copyFileSync),
27
+ };
28
+ });
29
+
30
+ const {applyWrites} = await import('../../api/integration/add-helpers.mjs');
31
+ const fs = await import('node:fs');
32
+
33
+ describe.each(['EPERM', 'EXDEV'])('hard links fail with %s', code => {
34
+ let testDir;
35
+
36
+ beforeEach(() => {
37
+ vi.clearAllMocks();
38
+ vi.mocked(fs.linkSync).mockImplementation(() => {
39
+ throw Object.assign(new Error(`${code}: cannot link`), {code});
23
40
  });
24
-
25
- afterEach(() => {
26
- fs.rmSync(testDir, {recursive: true, force: true});
27
- });
28
-
29
- it('confirms the configured filesystem rejects hard links', () => {
30
- const source = path.join(testDir, '.tmp-source');
31
- const destination = path.join(testDir, '.tmp-destination');
32
- fs.writeFileSync(source, 'link-test');
33
-
34
- expect(() => fs.linkSync(source, destination)).toThrow(
35
- expect.objectContaining({code: expect.stringMatching(/^(EPERM|EXDEV)$/)}),
41
+ testDir = fs.mkdtempSync(path.join(os.tmpdir(), '.astryx-publish-proof-'));
42
+ });
43
+
44
+ afterEach(() => {
45
+ fs.rmSync(testDir, {recursive: true, force: true});
46
+ });
47
+
48
+ it('applyWrites creates files through the exclusive-copy fallback', () => {
49
+ const plans = [
50
+ {
51
+ path: path.join(testDir, 'MyComponent.tsx'),
52
+ contents: '// MyComponent\nexport default function MyComponent() {}\n',
53
+ createOnly: true,
54
+ },
55
+ {
56
+ path: path.join(testDir, 'MyComponent.test.tsx'),
57
+ contents: '// test\nimport MyComponent from "./MyComponent";\n',
58
+ createOnly: true,
59
+ },
60
+ ];
61
+
62
+ const rollback = applyWrites(plans);
63
+ expect(typeof rollback).toBe('function');
64
+ expect(fs.readFileSync(plans[0].path, 'utf-8')).toContain('MyComponent');
65
+ expect(fs.readFileSync(plans[1].path, 'utf-8')).toContain('test');
66
+ expect(fs.linkSync).toHaveBeenCalledTimes(plans.length);
67
+ for (const plan of plans) {
68
+ expect(fs.copyFileSync).toHaveBeenCalledWith(
69
+ expect.any(String),
70
+ plan.path,
71
+ fs.constants.COPYFILE_EXCL,
36
72
  );
37
- });
73
+ }
74
+ });
38
75
 
39
- it('applyWrites creates files through the fallback', () => {
40
- const plans = [
41
- {
42
- path: path.join(testDir, 'MyComponent.tsx'),
43
- contents: '// MyComponent\nexport default function MyComponent() {}\n',
44
- createOnly: true,
45
- },
46
- {
47
- path: path.join(testDir, 'MyComponent.test.tsx'),
48
- contents: '// test\nimport MyComponent from "./MyComponent";\n',
49
- createOnly: true,
50
- },
51
- ];
52
-
53
- const rollback = applyWrites(plans);
54
- expect(typeof rollback).toBe('function');
55
- expect(fs.readFileSync(plans[0].path, 'utf-8')).toContain('MyComponent');
56
- expect(fs.readFileSync(plans[1].path, 'utf-8')).toContain('test');
57
- });
58
-
59
- it('applyWrites preserves no-clobber behavior', () => {
60
- const target = path.join(testDir, 'existing.tsx');
61
- fs.writeFileSync(target, '// original\n');
62
-
63
- expect(() =>
64
- applyWrites([
65
- {
66
- path: target,
67
- contents: '// replacement\n',
68
- createOnly: true,
69
- },
70
- ]),
71
- ).toThrow(/overwrite|exists/i);
72
- expect(fs.readFileSync(target, 'utf-8')).toBe('// original\n');
73
- });
76
+ it('applyWrites preserves no-clobber behavior', () => {
77
+ const target = path.join(testDir, 'existing.tsx');
78
+ fs.writeFileSync(target, '// original\n');
74
79
 
75
- it('applyWrites rolls back partial publication', () => {
76
- const good = path.join(testDir, 'good.tsx');
77
- const bad = path.join(testDir, 'bad.tsx');
78
- fs.writeFileSync(bad, '// preexisting\n');
79
-
80
- expect(() =>
81
- applyWrites([
82
- {path: good, contents: '// good file\n', createOnly: true},
83
- {path: bad, contents: '// replacement\n', createOnly: true},
84
- ]),
85
- ).toThrow();
86
- expect(fs.existsSync(good)).toBe(false);
87
- expect(fs.readFileSync(bad, 'utf-8')).toBe('// preexisting\n');
88
- });
89
-
90
- it('applyWrites keeps compare-and-swap replacement behavior', () => {
91
- const target = path.join(testDir, 'config.json');
92
- const original = '{"version": 1}\n';
93
- fs.writeFileSync(target, original);
94
-
95
- const rollback = applyWrites([
80
+ expect(() =>
81
+ applyWrites([
96
82
  {
97
83
  path: target,
98
- contents: '{"version": 2}\n',
99
- createOnly: false,
100
- expectedOriginal: Buffer.from(original),
84
+ contents: '// replacement\n',
85
+ createOnly: true,
101
86
  },
102
- ]);
103
- expect(typeof rollback).toBe('function');
104
- expect(fs.readFileSync(target, 'utf-8')).toBe('{"version": 2}\n');
105
- });
106
- },
107
- );
87
+ ]),
88
+ ).toThrow(/overwrite|exists/i);
89
+ expect(fs.readFileSync(target, 'utf-8')).toBe('// original\n');
90
+ });
91
+
92
+ it('applyWrites rolls back partial publication', () => {
93
+ const good = path.join(testDir, 'good.tsx');
94
+ const bad = path.join(testDir, 'bad.tsx');
95
+ fs.writeFileSync(bad, '// preexisting\n');
96
+
97
+ expect(() =>
98
+ applyWrites([
99
+ {path: good, contents: '// good file\n', createOnly: true},
100
+ {path: bad, contents: '// replacement\n', createOnly: true},
101
+ ]),
102
+ ).toThrow();
103
+ expect(fs.existsSync(good)).toBe(false);
104
+ expect(fs.readFileSync(bad, 'utf-8')).toBe('// preexisting\n');
105
+ });
106
+
107
+ it('applyWrites keeps compare-and-swap replacement behavior', () => {
108
+ const target = path.join(testDir, 'config.json');
109
+ const original = '{"version": 1}\n';
110
+ fs.writeFileSync(target, original);
111
+
112
+ const rollback = applyWrites([
113
+ {
114
+ path: target,
115
+ contents: '{"version": 2}\n',
116
+ createOnly: false,
117
+ expectedOriginal: Buffer.from(original),
118
+ },
119
+ ]);
120
+ expect(typeof rollback).toBe('function');
121
+ expect(fs.readFileSync(target, 'utf-8')).toBe('{"version": 2}\n');
122
+ });
123
+ });
124
+
125
+ describe('private test seams', () => {
126
+ it('no publish-file module or proof reads process.env', () => {
127
+ const self = fileURLToPath(import.meta.url);
128
+ const dir = path.dirname(self);
129
+ const files = fs.readdirSync(dir).filter(name => /^publish-file.*\.mjs$/.test(name));
130
+ const j = jscodeshift.withParser('babylon');
131
+ const reads = files.flatMap(name =>
132
+ j(fs.readFileSync(path.join(dir, name), 'utf8'))
133
+ .find(j.MemberExpression, {object: {name: 'process'}})
134
+ .filter(p => (p.node.computed ? p.node.property.value : p.node.property.name) === 'env')
135
+ .nodes()
136
+ .map(node => `${name}:${node.loc?.start.line}`),
137
+ );
138
+
139
+ expect(files).toEqual(expect.arrayContaining(['publish-file.mjs', path.basename(self)]));
140
+ expect(reads).toEqual([]);
141
+ });
142
+ });
@@ -229,7 +229,12 @@ export async function autolinkIntegrations({
229
229
  fresh = false,
230
230
  }) {
231
231
  const candidates = findAutolinkCandidates(projectDir, {
232
- exclude: loaded.map(integration => integration.__packageDir),
232
+ // A configured entry that never resolved to a directory has none to exclude.
233
+ exclude: loaded.flatMap(integration =>
234
+ typeof integration.__packageDir === 'string'
235
+ ? [integration.__packageDir]
236
+ : [],
237
+ ),
233
238
  });
234
239
 
235
240
  /** @type {import('./integrations.mjs').LoadedIntegration[]} */
@@ -29,6 +29,8 @@ export interface Suggestion {
29
29
  * human-readable `error` string, which changes freely.
30
30
  */
31
31
  export interface CLIError {
32
+ /** Version of the JSON envelope contract, as on the success envelope. */
33
+ apiVersion: number;
32
34
  error: string;
33
35
  code: ErrorCode;
34
36
  suggestions?: Suggestion[];
@@ -36,13 +38,15 @@ export interface CLIError {
36
38
 
37
39
  /** Returned by the fallback hook for commands without --json support. */
38
40
  export interface CLIUnsupportedError {
41
+ apiVersion: number;
39
42
  error: `JSON output is not supported for the '${string}' command`;
40
43
  code: ErrorCode;
41
44
  }
42
45
 
43
46
  /**
44
- * A success response envelope: a `type` discriminator, its `data` payload, and
45
- * an optional `meta` sidecar (emitted as a sibling of `data`, never merged in).
47
+ * A success response: a `type` discriminator, its `data` payload, and an
48
+ * optional `meta` sidecar (emitted as a sibling of `data`, never merged in).
49
+ * `--json` prints it with `apiVersion` added (see `parseResponse`).
46
50
  *
47
51
  * Structural by design — there is no central union of every response `type`.
48
52
  * A specific command narrows `data` via its own return type.
@@ -75,7 +79,7 @@ export function jsonError(
75
79
  /** Parse raw CLI output (string or object) into a typed result. */
76
80
  export function parseResponse(
77
81
  raw: unknown,
78
- ): CLIResponse | CLIError | CLIUnsupportedError;
82
+ ): (CLIResponse & {apiVersion: number}) | CLIError | CLIUnsupportedError;
79
83
 
80
84
  /** Type guard: returns true if result is an error. */
81
85
  export function isError(
@@ -90,7 +94,7 @@ export function isError(
90
94
  export function assertResponse<T extends string>(
91
95
  raw: unknown,
92
96
  type: T,
93
- ): CLIResponse & {type: T};
97
+ ): CLIResponse & {apiVersion: number; type: T};
94
98
 
95
99
  declare global {
96
100
  namespace NodeJS {
@@ -187,8 +187,7 @@ export const doc = {
187
187
  },
188
188
  {
189
189
  value: 'ERR_FILE_EXISTS',
190
- description:
191
- 'Refused to overwrite an existing file in non-interactive mode.',
190
+ description: 'Refused to overwrite an existing file.',
192
191
  },
193
192
  {
194
193
  value: 'ERR_PATH_TRAVERSAL',
@@ -177,7 +177,7 @@ export const ERROR_CODES = Object.freeze({
177
177
  // ── Filesystem ───────────────────────────────────────────────────
178
178
  /** A required input file did not exist. */
179
179
  ERR_FILE_NOT_FOUND: 'ERR_FILE_NOT_FOUND',
180
- /** Refused to overwrite an existing file in non-interactive mode. */
180
+ /** Refused to overwrite an existing file. */
181
181
  ERR_FILE_EXISTS: 'ERR_FILE_EXISTS',
182
182
  /** A path escaped its allowed root, or a name contained traversal markers. */
183
183
  ERR_PATH_TRAVERSAL: 'ERR_PATH_TRAVERSAL',
@@ -15,6 +15,9 @@
15
15
  */
16
16
 
17
17
  import {describe, it, expect} from 'vitest';
18
+ import * as fs from 'node:fs';
19
+ import * as os from 'node:os';
20
+ import * as path from 'node:path';
18
21
  import {ERROR_CODES, isErrorCode, allErrorCodes} from './error-codes.mjs';
19
22
  import {runCli} from '../../test-utils/run-cli.mjs';
20
23
 
@@ -75,6 +78,68 @@ describe('error-codes taxonomy', () => {
75
78
  });
76
79
  });
77
80
 
81
+ describe('error codes: shipped set', () => {
82
+ // Every code a release has published. INV3: a shipped code is never removed
83
+ // or respelled. Add a code here once it ships; never delete an entry.
84
+ const SHIPPED = [
85
+ 'ERR_AMBIGUOUS_COMPONENT',
86
+ 'ERR_AMBIGUOUS_TEMPLATE',
87
+ 'ERR_AMBIGUOUS_THEME',
88
+ 'ERR_CODEMOD_FAILED',
89
+ 'ERR_CORE_INCOMPATIBLE',
90
+ 'ERR_CORE_NOT_FOUND',
91
+ 'ERR_DEP_MISSING',
92
+ 'ERR_FETCH_FAILED',
93
+ 'ERR_FILE_EXISTS',
94
+ 'ERR_FILE_NOT_FOUND',
95
+ 'ERR_GH_CLI',
96
+ 'ERR_INTEGRATION_EXPORT_CONFLICT',
97
+ 'ERR_INTEGRATION_ROOT_CONFLICT',
98
+ 'ERR_INVALID_ARGUMENT',
99
+ 'ERR_INVALID_DETAIL',
100
+ 'ERR_INVALID_DOC',
101
+ 'ERR_INVALID_LANG',
102
+ 'ERR_INVALID_OPTION',
103
+ 'ERR_INVALID_VERSION',
104
+ 'ERR_LAYOUT_INVALID',
105
+ 'ERR_LAYOUT_PARSE',
106
+ 'ERR_MISSING_ARGUMENT',
107
+ 'ERR_NODE_VERSION',
108
+ 'ERR_NOT_FOUND',
109
+ 'ERR_NO_DOC',
110
+ 'ERR_NO_SHOWCASE',
111
+ 'ERR_NO_SOURCE',
112
+ 'ERR_PALETTE_GENERATION',
113
+ 'ERR_PATH_TRAVERSAL',
114
+ 'ERR_SIGNAL_TERMINATED',
115
+ 'ERR_THEME_INVALID',
116
+ 'ERR_THEME_LOAD',
117
+ 'ERR_UNCLASSIFIED_EXIT',
118
+ 'ERR_UNKNOWN',
119
+ 'ERR_UNKNOWN_AGENT',
120
+ 'ERR_UNKNOWN_CATEGORY',
121
+ 'ERR_UNKNOWN_CODEMOD',
122
+ 'ERR_UNKNOWN_COMMAND',
123
+ 'ERR_UNKNOWN_COMPONENT',
124
+ 'ERR_UNKNOWN_FEATURE',
125
+ 'ERR_UNKNOWN_HOOK',
126
+ 'ERR_UNKNOWN_PACKAGE',
127
+ 'ERR_UNKNOWN_POST',
128
+ 'ERR_UNKNOWN_SECTION',
129
+ 'ERR_UNKNOWN_SUBCOMMAND',
130
+ 'ERR_UNKNOWN_TEMPLATE',
131
+ 'ERR_UNKNOWN_THEME',
132
+ 'ERR_UNKNOWN_TOPIC',
133
+ 'ERR_VERSION_DETECT',
134
+ 'ERR_WRITE_FAILED',
135
+ ];
136
+
137
+ it('still carries every shipped code, spelled the same', () => {
138
+ const missing = SHIPPED.filter(code => !isErrorCode(code) || ERROR_CODES[code] !== code);
139
+ expect(missing, 'shipped codes removed or respelled').toEqual([]);
140
+ });
141
+ });
142
+
78
143
  describe('error codes: end-to-end JSON envelopes', () => {
79
144
  const cases = [
80
145
  {name: 'unknown component', args: ['component', 'Bogus', '--json'], code: 'ERR_UNKNOWN_COMPONENT'},
@@ -104,6 +169,24 @@ describe('error codes: end-to-end JSON envelopes', () => {
104
169
  });
105
170
  }
106
171
 
172
+ it('a filesystem failure carries a registered code, never the Node errno', async () => {
173
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-errno-'));
174
+ try {
175
+ // A file where the target directory should be: mkdir fails with ENOTDIR.
176
+ fs.writeFileSync(path.join(dir, 'blocker'), 'x');
177
+ const {status, stdout} = await runCli(
178
+ ['template', 'dashboard', 'blocker/out', '--json'],
179
+ {cwd: dir},
180
+ );
181
+ expect(status).toBe(1);
182
+ const env = envelope(stdout);
183
+ expect(env.error).toMatch(/ENOTDIR/);
184
+ expect(isErrorCode(env.code)).toBe(true);
185
+ } finally {
186
+ fs.rmSync(dir, {recursive: true, force: true});
187
+ }
188
+ });
189
+
107
190
  it('every error envelope carries a code (even unmatched paths fall back to ERR_UNKNOWN)', async () => {
108
191
  const {stdout} = await runCli(['component', 'Bogus', '--json']);
109
192
  const env = envelope(stdout);
@@ -112,6 +112,17 @@ describe('json envelope shape', () => {
112
112
  });
113
113
  });
114
114
 
115
+ it('toErrorEnvelope never emits an unregistered code', () => {
116
+ // A Node system error carries `code: 'EACCES'`; that is not an Astryx code.
117
+ const sysErr = Object.assign(new Error('EACCES: permission denied'), {
118
+ code: 'EACCES',
119
+ });
120
+ expect(toErrorEnvelope(sysErr).code).toBe('ERR_UNKNOWN');
121
+ expect(toErrorEnvelope('boom', undefined, 'ENOENT').code).toBe('ERR_UNKNOWN');
122
+ const docErr = Object.assign(new Error('no doc'), {code: 'ERR_NO_DOC'});
123
+ expect(toErrorEnvelope(docErr, undefined, 'ENOENT').code).toBe('ERR_NO_DOC');
124
+ });
125
+
115
126
  it('toErrorEnvelope includes suggestions when present', () => {
116
127
  const env = toErrorEnvelope('x', [{name: 'Button', reason: 'close match'}]);
117
128
  expect(env.suggestions).toEqual([{name: 'Button', reason: 'close match'}]);
@@ -50,8 +50,10 @@ export function jsonOut(response: {
50
50
  *
51
51
  * The `code` is resolved in priority order: an explicit `code` argument,
52
52
  * then a `code` property carried on a thrown Error/AstryxError, then the
53
- * generic `ERR_UNKNOWN` fallback. It always appears on the envelope so
54
- * consumers can branch on it unconditionally.
53
+ * generic `ERR_UNKNOWN` fallback. Only a registered code (error-codes.mjs) is
54
+ * taken from either source, so a Node system error's `ENOENT` never reaches
55
+ * the envelope. It always appears on the envelope so consumers can branch on
56
+ * it unconditionally.
55
57
  *
56
58
  * @param {unknown} err
57
59
  * @param {import('./base').Suggestion[]} [suggestions]
@@ -28,7 +28,7 @@
28
28
  * Version of the JSON envelope contract. Bump on breaking shape changes so
29
29
  * consumers can negotiate. Exposed on every envelope as `apiVersion`.
30
30
  */
31
- import {ERROR_CODES} from './error-codes.mjs';
31
+ import {ERROR_CODES, isErrorCode} from './error-codes.mjs';
32
32
  import {recordEnvelope, setOutcome} from '../debug/index.mjs';
33
33
 
34
34
  export const API_VERSION = 1;
@@ -118,8 +118,10 @@ export function jsonOut(response) {
118
118
  *
119
119
  * The `code` is resolved in priority order: an explicit `code` argument,
120
120
  * then a `code` property carried on a thrown Error/AstryxError, then the
121
- * generic `ERR_UNKNOWN` fallback. It always appears on the envelope so
122
- * consumers can branch on it unconditionally.
121
+ * generic `ERR_UNKNOWN` fallback. Only a registered code (error-codes.mjs) is
122
+ * taken from either source, so a Node system error's `ENOENT` never reaches
123
+ * the envelope. It always appears on the envelope so consumers can branch on
124
+ * it unconditionally.
123
125
  *
124
126
  * @param {unknown} err
125
127
  * @param {import('./base').Suggestion[]} [suggestions]
@@ -130,13 +132,9 @@ export function jsonOut(response) {
130
132
  export function toErrorEnvelope(err, suggestions, code) {
131
133
  const message =
132
134
  err instanceof Error ? err.message : typeof err === 'string' ? err : String(err);
133
- const resolvedCode =
134
- code ||
135
- (err && typeof err === 'object' &&
136
- typeof (/** @type {any} */ (err).code) === 'string'
137
- ? /** @type {any} */ (err).code
138
- : undefined) ||
139
- ERROR_CODES.ERR_UNKNOWN;
135
+ const carried =
136
+ err && typeof err === 'object' ? /** @type {any} */ (err).code : undefined;
137
+ const resolvedCode = [code, carried].find(isErrorCode) ?? ERROR_CODES.ERR_UNKNOWN;
140
138
  /** @type {any} */
141
139
  const env = {apiVersion: API_VERSION, error: message, code: resolvedCode};
142
140
  if (Array.isArray(suggestions) && suggestions.length) env.suggestions = suggestions;
@@ -36,7 +36,7 @@ export const doc = {
36
36
  {
37
37
  value: 'component.detail',
38
38
  description:
39
- "One component's authored ComponentDoc plus ownership metadata (owner package, import specifier, and whether source is available).",
39
+ "One component's authored ComponentDoc plus ownership fields (package, the owner; import, the specifier; sourceAvailable, whether source exists) and parentDoc (present when the component is documented inside another component's doc, naming that doc).",
40
40
  },
41
41
  {
42
42
  value: 'component.detail.props',
@@ -71,7 +71,7 @@ export const doc = {
71
71
  {
72
72
  value: 'docs.index',
73
73
  description:
74
- "One topic's section index (--index): each section's key, title, and one-line summary.",
74
+ "One topic's section index (--index): the topic's name, title, and description, plus sections, each {id, title, summary} (pass the id as the section argument; summary is the section's one-line summary).",
75
75
  },
76
76
  {
77
77
  value: 'docs.detail.section',
@@ -116,19 +116,19 @@ export const doc = {
116
116
  {
117
117
  value: 'search',
118
118
  description:
119
- 'The echoed query, `matchCount` (how many candidates matched in total, before `limit`), plus a ranked SearchResultEntry[] bounded by `limit` (domain, name, score, reason, description, follow-up command, and import path where relevant).',
119
+ 'The echoed query, `matchCount` (total matches, before `limit`), and results, a ranked SearchResultEntry[] bounded by `limit`: each {domain, name, score, reason, description, command}, plus import (components, hooks), title (docs), or displayName and kind (templates).',
120
120
  },
121
121
 
122
122
  // build
123
123
  {
124
124
  value: 'build.help',
125
125
  description:
126
- 'A marker (`playbook: true`) that the renderer expands into the how-to-build-a-page workflow; emitted when no query is given.',
126
+ 'The how-to-build-a-page playbook, emitted when no query is given: `playbook: true`, a title, the ordered steps (title, commands, optional returns), the on-system rules, and related lookups. Commands are bare subcommands for the caller to render with its own invocation.',
127
127
  },
128
128
  {
129
129
  value: 'build.kit',
130
130
  description:
131
- 'The grouped composition kit: echoed query, hasResults/matchCount/directMatch fields (matchCount is the total matched, never a cap read back), the closest page templates, drop-in block patterns, idea-specific components/hooks, and the always-on frame + foundation component-name arrays.',
131
+ 'The composition kit: echoed query, hasResults, matchCount (total matched, never a cap), directMatch, pages (closest templates), blocks (drop-in patterns) and domain (idea components/hooks) as SearchResultEntry[], frame and foundation name arrays, and hint {reason, commands} when thin.',
132
132
  },
133
133
 
134
134
  // swizzle
@@ -151,7 +151,7 @@ export const doc = {
151
151
  {
152
152
  value: 'gap-report.file',
153
153
  description:
154
- 'An aggregate receipt with overall status, the selected package and issues URL, ordered per-handler deliveries, and filedCount/routedOnlyCount totals.',
154
+ 'An aggregate receipt: overall status, the selected package, issuesUrl (or null), deliveries in handler order, each {handlerType: project | integration | fallback, handler, audience, status, url, message}, and filedCount/routedOnlyCount totals.',
155
155
  },
156
156
 
157
157
  // template
@@ -198,7 +198,7 @@ export const doc = {
198
198
  {
199
199
  value: 'theme.build',
200
200
  description:
201
- 'A theme build receipt: name, token- and component-override counts, output size, the written outputs {css, js, dts, and variantsDts when applicable}, and any validation warnings.',
201
+ 'A theme build receipt: name, tokenCount and componentCount (override counts), sizeKB, the written outputs {css, js, dts, and variantsDts when applicable}, warnings (defects to fix), and notices (advisories about a correct theme, such as a named font it does not load).',
202
202
  },
203
203
  {
204
204
  value: 'theme.build.check',
@@ -228,7 +228,7 @@ export const doc = {
228
228
  {
229
229
  value: 'theme.targets',
230
230
  description:
231
- 'The whole themeable surface: the echoed filter, the component count, and one entry per theming target — {key, className, component, props, states}, where props and states are its legal override keys.',
231
+ 'The whole themeable surface: the echoed filter, componentCount, and targets, one per theming target — {key, className, component, props, states, deprecatedFor?}, where props and states are its legal override keys and deprecatedFor names the canonical replacement key.',
232
232
  },
233
233
  {
234
234
  value: 'theme.palette.generate',
@@ -257,7 +257,7 @@ export const doc = {
257
257
  {
258
258
  value: 'manifest',
259
259
  description:
260
- 'The self-describing CLI capability manifest: name, version, apiVersion, global options, the command tree (args, options, json flag, response types, examples), the jsonSupported allowlist, and the flat responseTypes index.',
260
+ 'The CLI capability manifest: name, version, apiVersion, description, globalOptions, commands (each name, description, arguments, options, json, aliases?, responseTypes?, examples?, exitCodes? as [{code, when}], subcommands?), jsonSupported, and the flat responseTypes index.',
261
261
  },
262
262
 
263
263
  // doctor
@@ -276,7 +276,7 @@ export const doc = {
276
276
  {
277
277
  value: 'integration.pack-check',
278
278
  description:
279
- 'The packed-package check: package identity, tarball facts, local and packed contribution inventories, and issues.',
279
+ 'The packed-package check: name, version, packable, tarball {filename, fileCount, size, unpackedSize} or null, inventory {manifest, roots [{kind, path, expectedFiles, missingFiles, complete}], expectedFiles, packedFiles}, contributions {local, packed}, each null or {themes [{slug, exportName}], components, templates [{id, type, name}], codemods [{version, id}], docs, agentDocsAppend}, and issues [{code, severity, message}].',
280
280
  },
281
281
  {
282
282
  value: 'integration.validate',