@atelier-ui/create-workspace 0.2.43 → 0.3.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/CHANGELOG.md +59 -11
- package/package.json +1 -1
- package/src/generators/preset/files/claude/agents/component-review.md +53 -0
- package/src/generators/preset/files/claude/commands/verify.md +24 -0
- package/src/generators/preset/files/claude/hooks/format-edited.sh +77 -0
- package/src/generators/preset/files/claude/skills/atelier-component/SKILL.md +84 -0
- package/src/generators/preset/files/storybook/angular/atl-button.stories.ts.template +48 -1
- package/src/generators/preset/files/storybook/react/atl-button.stories.tsx +56 -1
- package/src/generators/preset/files/storybook/vue/atl-button.stories.ts.template +57 -2
- package/src/generators/preset/files/testing/angular/atl-button.spec.ts.template +27 -0
- package/src/generators/preset/files/testing/angular/test-setup.ts.template +6 -0
- package/src/generators/preset/files/testing/angular/vitest.unit.config.ts.template +36 -0
- package/src/generators/preset/files/testing/react/atl-button.spec.tsx +22 -0
- package/src/generators/preset/files/testing/react/test-setup.ts.template +1 -0
- package/src/generators/preset/files/testing/react/vitest.unit.config.ts.template +42 -0
- package/src/generators/preset/files/testing/vue/atl-button.spec.ts.template +25 -0
- package/src/generators/preset/files/testing/vue/test-setup.ts.template +1 -0
- package/src/generators/preset/files/testing/vue/vitest.unit.config.ts.template +50 -0
- package/src/generators/preset/preset.js +762 -359
- package/src/generators/preset/preset.js.map +1 -1
- package/src/generators/preset/schema.d.ts +2 -1
- package/src/generators/preset/schema.json +18 -3
|
@@ -10,6 +10,28 @@ const node_path_1 = require("node:path");
|
|
|
10
10
|
function readTemplate(relativePath) {
|
|
11
11
|
return (0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, 'files', relativePath), 'utf-8');
|
|
12
12
|
}
|
|
13
|
+
// All five packages this monorepo publishes (angular, react, vue,
|
|
14
|
+
// create-workspace, create-atelier-ui-workspace) release in lockstep from
|
|
15
|
+
// nx.json's `libraries` release group — they always carry the same version.
|
|
16
|
+
// So rather than pinning @atelier-ui/<framework> to `latest` (which drifts
|
|
17
|
+
// out from under a workshop the moment a newer version ships, and can't be
|
|
18
|
+
// reproduced later), the preset pins it to ITS OWN version: this package's
|
|
19
|
+
// package.json, one level above `src/generators/preset` from this file.
|
|
20
|
+
// Verified to resolve identically from both places this file runs as:
|
|
21
|
+
// `libs/create-workspace/src/generators/preset/preset.ts` under jest
|
|
22
|
+
// (ts-jest preserves the real on-disk __dirname), and the published
|
|
23
|
+
// `dist/libs/create-workspace/src/generators/preset/preset.js` (the
|
|
24
|
+
// `@nx/js:tsc` build mirrors the same src-relative depth under dist/, and
|
|
25
|
+
// its default `generatePackageJson` behaviour writes a package.json at
|
|
26
|
+
// dist/libs/create-workspace — confirmed against this repo's own dist/ output).
|
|
27
|
+
function readOwnVersion() {
|
|
28
|
+
const pkgPath = (0, node_path_1.join)(__dirname, '../../../package.json');
|
|
29
|
+
const pkg = JSON.parse((0, node_fs_1.readFileSync)(pkgPath, 'utf-8'));
|
|
30
|
+
if (!pkg.version) {
|
|
31
|
+
throw new Error(`Cannot read a "version" field from ${pkgPath}`);
|
|
32
|
+
}
|
|
33
|
+
return pkg.version;
|
|
34
|
+
}
|
|
13
35
|
const SITE_URL = 'https://atelier.pieper.io';
|
|
14
36
|
// Pinned to the exact version this monorepo runs (root package.json
|
|
15
37
|
// devDependencies) — the workshop needs the same Storybook every attendee's
|
|
@@ -52,6 +74,48 @@ function storybookTemplateName(framework, base) {
|
|
|
52
74
|
function storybookOutputExt(framework) {
|
|
53
75
|
return framework === 'react' ? 'tsx' : 'ts';
|
|
54
76
|
}
|
|
77
|
+
// S5's own template lookup, mirroring storybookTemplateName()'s `.template`
|
|
78
|
+
// dodge above: `vitest.unit.config.ts` and `test-setup.ts` contain no JSX on
|
|
79
|
+
// any framework, so both always need the suffix; `atl-button.spec` follows
|
|
80
|
+
// the same per-framework extension as the example story (`.tsx` on react,
|
|
81
|
+
// `.ts.template` elsewhere).
|
|
82
|
+
function testingTemplateName(framework, base) {
|
|
83
|
+
if (base === 'atl-button.spec') {
|
|
84
|
+
const ext = framework === 'react' ? 'tsx' : 'ts.template';
|
|
85
|
+
return `testing/${framework}/atl-button.spec.${ext}`;
|
|
86
|
+
}
|
|
87
|
+
return `testing/${framework}/${base}.ts.template`;
|
|
88
|
+
}
|
|
89
|
+
// The workspace's own component skill (`.claude/skills/atelier-component/`)
|
|
90
|
+
// ships as a static `files/` template — its instructions don't vary by
|
|
91
|
+
// framework except for two names: the app directory (`workshop-<fw>`) and
|
|
92
|
+
// the `@atelier-ui/<fw>` package/framework name. Rather than rewrite it as a
|
|
93
|
+
// JS template string (like CLAUDE.md/README.md below, which vary in far more
|
|
94
|
+
// places), it stays a template file with those two spots marked
|
|
95
|
+
// `<app>`/`<framework>`, substituted here at generate time.
|
|
96
|
+
//
|
|
97
|
+
// `<app>` and `<framework>` (angle-bracket-wrapped) were chosen as the
|
|
98
|
+
// substitution tokens deliberately, over inventing a new one: the skill's own
|
|
99
|
+
// prose already uses the BARE words "app" and "framework" as ordinary
|
|
100
|
+
// English (e.g. "one app (`workshop-<framework>`), one framework, ..." and "
|
|
101
|
+
// ... two-way bindings ... for this framework"), so a substitution key of the
|
|
102
|
+
// bare word would have corrupted those sentences. The angle-bracket form is
|
|
103
|
+
// the one substring that appears ONLY at the seven spots meant to be filled
|
|
104
|
+
// in (four `<app>`, three `<framework>`) — verified against the shipped
|
|
105
|
+
// file, not assumed — and is
|
|
106
|
+
// distinct from the file's other bracketed placeholder, `<name>` (a
|
|
107
|
+
// component name, e.g. in `<name>.contract.ts`), which stays generic prose
|
|
108
|
+
// for the reader and must NOT be substituted.
|
|
109
|
+
function renderAtelierComponentSkill(appName, framework) {
|
|
110
|
+
// `.split(token).join(value)` rather than `String.prototype.replaceAll`:
|
|
111
|
+
// this package's tsconfig targets a lib below ES2021, where `replaceAll`
|
|
112
|
+
// doesn't type-check.
|
|
113
|
+
return readTemplate('claude/skills/atelier-component/SKILL.md')
|
|
114
|
+
.split('<app>')
|
|
115
|
+
.join(appName)
|
|
116
|
+
.split('<framework>')
|
|
117
|
+
.join(framework);
|
|
118
|
+
}
|
|
55
119
|
// Splices `block` (one or more object literals, as raw source text, starting
|
|
56
120
|
// with a leading comma) into the flat ESLint config a framework's own
|
|
57
121
|
// application generator (@nx/angular, @nx/react, @nx/vue — all invoked with
|
|
@@ -90,13 +154,13 @@ function appendToFlatEslintConfig(tree, path, block, imports = []) {
|
|
|
90
154
|
content.slice(closeIndex));
|
|
91
155
|
}
|
|
92
156
|
// Ported CSS-discipline stylelint rules (ADR-0130): assembles the scaffold's
|
|
93
|
-
// own stylelint.config.mjs — one override block
|
|
157
|
+
// own stylelint.config.mjs — the one override block for the scaffold's single
|
|
94
158
|
// `workshop-<fw>/src` tree, mirroring this repo's own stylelint.config.mjs
|
|
95
159
|
// (which does the same per libs/{angular,react,vue}). Built as a template
|
|
96
|
-
// string here rather than a static files/ template, because
|
|
97
|
-
//
|
|
98
|
-
//
|
|
99
|
-
//
|
|
160
|
+
// string here rather than a static files/ template, because the app-relative
|
|
161
|
+
// paths it names depend on which framework was selected — the same reason
|
|
162
|
+
// CLAUDE.md/README.md below are assembled from `framework`, not copied
|
|
163
|
+
// verbatim.
|
|
100
164
|
//
|
|
101
165
|
// Only three of the four shipped rules are wired: `atelier/no-primitive-token`
|
|
102
166
|
// polices reaching past the semantic token tier into a primitive ramp (e.g.
|
|
@@ -113,12 +177,10 @@ function appendToFlatEslintConfig(tree, path, block, imports = []) {
|
|
|
113
177
|
// and the staleness scan those two options drive never runs (documented in
|
|
114
178
|
// each rule's own header in tools/stylelint-rules/) — passing them here would
|
|
115
179
|
// configure a scan that can never find anything.
|
|
116
|
-
function buildStylelintConfig(
|
|
117
|
-
const
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
const tokensCss = `${appName}/src/styles/tokens.css`;
|
|
121
|
-
return ` {
|
|
180
|
+
function buildStylelintConfig(framework) {
|
|
181
|
+
const appName = `workshop-${framework}`;
|
|
182
|
+
const tokensCss = `${appName}/src/styles/tokens.css`;
|
|
183
|
+
const overrides = ` {
|
|
122
184
|
files: ['${appName}/src/**/*.css'],
|
|
123
185
|
rules: {
|
|
124
186
|
'atelier/no-raw-color-literal': true,
|
|
@@ -126,8 +188,6 @@ function buildStylelintConfig(frameworks) {
|
|
|
126
188
|
'atelier/no-token-bypass': [true, { tokenFile: '${tokensCss}' }],
|
|
127
189
|
},
|
|
128
190
|
},`;
|
|
129
|
-
})
|
|
130
|
-
.join('\n');
|
|
131
191
|
return `// This workspace's own CSS-discipline rules only ('tools/stylelint-rules/')
|
|
132
192
|
// — ported from the parent Atelier monorepo (ADR-0130). No
|
|
133
193
|
// stylelint-config-standard or any other base config: stylelint 16+ ships no
|
|
@@ -143,7 +203,7 @@ function buildStylelintConfig(frameworks) {
|
|
|
143
203
|
// typo'd or undeclared --ui-* token, and a literal that duplicates a token's
|
|
144
204
|
// value instead of binding to it.
|
|
145
205
|
//
|
|
146
|
-
// tokens.css itself is EXCLUDED from
|
|
206
|
+
// tokens.css itself is EXCLUDED from the app's stylelint target (via
|
|
147
207
|
// --ignore-pattern in the app's project.json, not an exemption here): it is
|
|
148
208
|
// the one file that legitimately spells out raw color/dimension literals as
|
|
149
209
|
// token DEFINITIONS — the opposite of what these rules police in a file that
|
|
@@ -241,10 +301,25 @@ const PLAYWRIGHT_VERSION = '^1.36.0';
|
|
|
241
301
|
const VITE_PLUGIN_REACT_VERSION = '6.1.1';
|
|
242
302
|
const VITE_PLUGIN_VUE_VERSION = '^6.0.5';
|
|
243
303
|
const ANALOGJS_VITE_PLUGIN_ANGULAR_VERSION = '2.7.1';
|
|
244
|
-
//
|
|
245
|
-
// matchers
|
|
246
|
-
//
|
|
304
|
+
// Imported by Vue's browser-mode vitest.setup.ts.template (custom jest-dom
|
|
305
|
+
// matchers, mirroring libs/vue/.storybook/vitest.setup.ts exactly) AND, since
|
|
306
|
+
// S5, by every framework's own src/test-setup.ts (the jsdom unit-test
|
|
307
|
+
// runner's setup file) — the same custom matchers there too.
|
|
247
308
|
const TESTING_LIBRARY_JEST_DOM_VERSION = '^6.9.1';
|
|
309
|
+
// S5 — the unit test runner (`nx test`, jsdom, separate from the browser-mode
|
|
310
|
+
// story tests above): each framework's own Testing Library, `jsdom` itself
|
|
311
|
+
// (Vitest doesn't bundle a DOM implementation — `environment: 'jsdom'` needs
|
|
312
|
+
// the package installed), and Angular's `@analogjs/vitest-angular` (the
|
|
313
|
+
// TestBed setup helpers `libs/angular/src/test-setup.ts` uses, mirrored here
|
|
314
|
+
// per the same file). Versions copied verbatim from this monorepo's own root
|
|
315
|
+
// package.json, like the vitest/browser-mode constants above.
|
|
316
|
+
const TESTING_LIBRARY_ANGULAR_VERSION = '^19.2.1';
|
|
317
|
+
const TESTING_LIBRARY_REACT_VERSION = '^16.3.2';
|
|
318
|
+
const TESTING_LIBRARY_VUE_VERSION = '^8.1.0';
|
|
319
|
+
const JSDOM_VERSION = '^27.1.0';
|
|
320
|
+
// Same pin as ANALOGJS_VITE_PLUGIN_ANGULAR_VERSION above — both packages are
|
|
321
|
+
// released in lockstep by @analogjs.
|
|
322
|
+
const ANALOGJS_VITEST_ANGULAR_VERSION = '2.7.1';
|
|
248
323
|
// The Vue eslint.config.mjs addition above (see the appendToFlatEslintConfig
|
|
249
324
|
// call in the vue branch) imports this directly. @nx/eslint's own root config
|
|
250
325
|
// setup already adds it unconditionally regardless of framework or of
|
|
@@ -417,12 +492,11 @@ function installSkills(tree, skillsEnabled) {
|
|
|
417
492
|
}
|
|
418
493
|
function presetGenerator(tree, options) {
|
|
419
494
|
return tslib_1.__awaiter(this, void 0, void 0, function* () {
|
|
420
|
-
var _a, _b, _c, _d, _e;
|
|
421
|
-
const
|
|
422
|
-
.split(',')
|
|
423
|
-
.map((f) => f.trim())
|
|
424
|
-
.filter(Boolean);
|
|
495
|
+
var _a, _b, _c, _d, _e, _f;
|
|
496
|
+
const framework = (_a = options.framework) !== null && _a !== void 0 ? _a : 'angular';
|
|
425
497
|
const skillsEnabled = (_b = options.skills) !== null && _b !== void 0 ? _b : true;
|
|
498
|
+
// Pinned, not `latest` — see readOwnVersion()'s comment.
|
|
499
|
+
const componentPackageVersion = readOwnVersion();
|
|
426
500
|
const deps = {};
|
|
427
501
|
// Every scaffolded workspace gets a local Storybook — not behind a flag
|
|
428
502
|
// (2026-09-10 owner decision, tasks/todo.md "Storybook + the storybookjs/mcp
|
|
@@ -436,277 +510,302 @@ function presetGenerator(tree, options) {
|
|
|
436
510
|
'@storybook/addon-a11y': STORYBOOK_VERSION,
|
|
437
511
|
'@storybook/addon-docs': STORYBOOK_VERSION,
|
|
438
512
|
// Browser-mode Storybook tests (owner correction 2026-09-10 to ADR-0123) —
|
|
439
|
-
//
|
|
440
|
-
// framework-specific Vite plugin is added conditionally,
|
|
441
|
-
//
|
|
442
|
-
// bring its own in.
|
|
513
|
+
// written unconditionally, independent of which framework is selected; the
|
|
514
|
+
// framework-specific Vite plugin is added conditionally, further below,
|
|
515
|
+
// once the app generator has had a chance to bring its own in.
|
|
443
516
|
'@storybook/addon-vitest': STORYBOOK_VERSION,
|
|
444
517
|
vitest: VITEST_VERSION,
|
|
445
518
|
'@vitest/browser-playwright': VITEST_BROWSER_PLAYWRIGHT_VERSION,
|
|
446
519
|
playwright: PLAYWRIGHT_VERSION,
|
|
447
520
|
};
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
'@angular-eslint/template/no-positive-tabindex': 'error',
|
|
508
|
-
},
|
|
521
|
+
const appName = `workshop-${framework}`;
|
|
522
|
+
if (framework === 'angular') {
|
|
523
|
+
console.log(`\n◇ Generating Angular workshop app…`);
|
|
524
|
+
// NX_VERSION is the version of the nx running this generator, which is the
|
|
525
|
+
// one create-nx-workspace installed into the workspace. Pinning to it is not
|
|
526
|
+
// tidiness: nx ships core and plugins as one release and they reach across
|
|
527
|
+
// the package boundary, so a plugin one patch ahead of core throws at load.
|
|
528
|
+
// `@nx/eslint@23.1.2` calls `combineGlobPatterns` from `@nx/devkit/internal`,
|
|
529
|
+
// which `@nx/devkit@23.1.1` does not export — measured, and it broke CI the
|
|
530
|
+
// day 23.1.2 was published.
|
|
531
|
+
//
|
|
532
|
+
// This is also why `@nx/angular` is an OPTIONAL peer of this package. npm
|
|
533
|
+
// auto-installs a required peer, and `>=22.0.0` resolves to whatever is
|
|
534
|
+
// latest — measured: it installed @nx/angular 23.1.2 into a workspace whose
|
|
535
|
+
// nx was 23.1.1, dragging @nx/eslint 23.1.2 with it, before this generator
|
|
536
|
+
// ever ran. Optional peers are not auto-installed, so the first thing that
|
|
537
|
+
// installs it is the line below, at the version that matches.
|
|
538
|
+
yield (0, devkit_1.ensurePackage)('@nx/angular', devkit_1.NX_VERSION);
|
|
539
|
+
const { applicationGenerator: angularAppGenerator, } = require('@nx/angular/generators');
|
|
540
|
+
yield angularAppGenerator(tree, {
|
|
541
|
+
name: appName,
|
|
542
|
+
directory: appName,
|
|
543
|
+
style: 'css',
|
|
544
|
+
routing: true,
|
|
545
|
+
standalone: true,
|
|
546
|
+
ssr: false,
|
|
547
|
+
skipTests: true,
|
|
548
|
+
e2eTestRunner: 'none',
|
|
549
|
+
skipFormat: true,
|
|
550
|
+
// Without this, the generator's own linter choice defaults to
|
|
551
|
+
// `normalizeLinterOption`'s non-interactive fallback: follow an
|
|
552
|
+
// eslint setup already detected in the tree, or `'none'` if there is
|
|
553
|
+
// none yet. A single-framework Angular scaffold (the common,
|
|
554
|
+
// documented case — ADR-0084) starts from a genuinely empty tree, so
|
|
555
|
+
// that fallback silently produced ZERO eslint.config.mjs and no
|
|
556
|
+
// eslint devDependency at all — verified by running the real
|
|
557
|
+
// generator against an empty workspace with this line omitted.
|
|
558
|
+
// React and Vue below already pass this explicitly; Angular didn't,
|
|
559
|
+
// which was the actual defect, not merely a posture gap.
|
|
560
|
+
linter: 'eslint',
|
|
561
|
+
});
|
|
562
|
+
deps['@atelier-ui/angular'] = componentPackageVersion;
|
|
563
|
+
// `flat/angular-template` above (written into workshop-angular's own
|
|
564
|
+
// eslint.config.mjs by the application generator, confirmed by a real
|
|
565
|
+
// run) already carries angular-eslint's `templateAccessibility` preset
|
|
566
|
+
// — see libs/angular/eslint.config.mjs's comment for the 11 rules that
|
|
567
|
+
// covers. This one isn't part of that preset (not `:accessibility:`
|
|
568
|
+
// tagged in angular-eslint's README): WCAG 2.4.3, positive tabindex
|
|
569
|
+
// fights natural DOM tab order. Same addition libs/angular's own config
|
|
570
|
+
// makes on top of the identical preset.
|
|
571
|
+
appendToFlatEslintConfig(tree, `${appName}/eslint.config.mjs`, `,
|
|
572
|
+
{
|
|
573
|
+
// Not covered by \`flat/angular-template\` above (angular-eslint's own
|
|
574
|
+
// \`templateAccessibility\` preset only) — WCAG 2.4.3, positive tabindex
|
|
575
|
+
// fights natural DOM tab order. Mirrors libs/angular/eslint.config.mjs's
|
|
576
|
+
// identical addition on top of the same preset.
|
|
577
|
+
files: ['**/*.html'],
|
|
578
|
+
rules: {
|
|
579
|
+
'@angular-eslint/template/no-positive-tabindex': 'error',
|
|
509
580
|
},
|
|
581
|
+
},
|
|
510
582
|
`);
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
|
|
598
|
-
|
|
599
|
-
},
|
|
583
|
+
}
|
|
584
|
+
if (framework === 'react') {
|
|
585
|
+
console.log(`\n◇ Generating React workshop app…`);
|
|
586
|
+
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
|
587
|
+
const { applicationGenerator: reactAppGenerator } = yield (0, devkit_1.ensurePackage)('@nx/react', devkit_1.NX_VERSION);
|
|
588
|
+
yield reactAppGenerator(tree, {
|
|
589
|
+
name: appName,
|
|
590
|
+
directory: appName,
|
|
591
|
+
style: 'css',
|
|
592
|
+
routing: true,
|
|
593
|
+
bundler: 'vite',
|
|
594
|
+
linter: 'eslint',
|
|
595
|
+
unitTestRunner: 'none',
|
|
596
|
+
e2eTestRunner: 'none',
|
|
597
|
+
skipFormat: true,
|
|
598
|
+
});
|
|
599
|
+
deps['@atelier-ui/react'] = componentPackageVersion;
|
|
600
|
+
// Deliberately nothing added here. `flat/react` above (written into
|
|
601
|
+
// workshop-react's own eslint.config.mjs by the application generator,
|
|
602
|
+
// confirmed by a real run) already carries jsx-a11y's full 18-rule
|
|
603
|
+
// active set — the same rule set libs/react/eslint.config.mjs relies on
|
|
604
|
+
// without adding anything of its own either.
|
|
605
|
+
}
|
|
606
|
+
if (framework === 'vue') {
|
|
607
|
+
console.log(`\n◇ Generating Vue workshop app…`);
|
|
608
|
+
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
|
609
|
+
const { applicationGenerator: vueAppGenerator } = yield (0, devkit_1.ensurePackage)('@nx/vue', devkit_1.NX_VERSION);
|
|
610
|
+
yield vueAppGenerator(tree, {
|
|
611
|
+
name: appName,
|
|
612
|
+
directory: appName,
|
|
613
|
+
style: 'css',
|
|
614
|
+
routing: true,
|
|
615
|
+
linter: 'eslint',
|
|
616
|
+
unitTestRunner: 'none',
|
|
617
|
+
e2eTestRunner: 'none',
|
|
618
|
+
skipFormat: true,
|
|
619
|
+
});
|
|
620
|
+
deps['@atelier-ui/vue'] = componentPackageVersion;
|
|
621
|
+
// @nx/vue's own application generator (confirmed by a real run against
|
|
622
|
+
// an in-memory Tree, packed from the exact pinned version — @nx/vue is
|
|
623
|
+
// an optional peer, not installed in this workspace) DOES match `.vue`
|
|
624
|
+
// files and wire vue-eslint-parser + typescript-eslint's parser for
|
|
625
|
+
// them via `parserOptions.parser` — the gap this generator's own
|
|
626
|
+
// libs/vue/eslint.config.mjs once had (`.vue` files matched by no
|
|
627
|
+
// config at all) does not exist in the scaffold. What IS missing,
|
|
628
|
+
// mirrored below from libs/vue/eslint.config.mjs:
|
|
629
|
+
//
|
|
630
|
+
// 1. `eslint-config-prettier` after eslint-plugin-vue's rules, scoped
|
|
631
|
+
// to `.vue` — without it, eslint-plugin-vue's layout/whitespace
|
|
632
|
+
// rules (max-attributes-per-line, html-self-closing, …) fight
|
|
633
|
+
// Prettier. eslint-config-prettier is already an unconditional
|
|
634
|
+
// devDependency here (added by @nx/eslint's own root config setup,
|
|
635
|
+
// confirmed by the same run), independent of whether `prettier`
|
|
636
|
+
// itself is installed — the defensive add near the end of
|
|
637
|
+
// presetGenerator below is a safety net for that, not the primary
|
|
638
|
+
// source.
|
|
639
|
+
// 2. `vue/no-unused-properties` — not part of any eslint-plugin-vue
|
|
640
|
+
// preset, opted in explicitly.
|
|
641
|
+
//
|
|
642
|
+
// Deliberately NOT mirrored: libs/vue/eslint.config.mjs also re-scopes
|
|
643
|
+
// eslint-plugin-vue's `flat/recommended` essential/strongly-recommended
|
|
644
|
+
// /recommended blocks to `**/*.vue` (verified here too: those blocks
|
|
645
|
+
// carry no `files` restriction in the installed eslint-plugin-vue, so
|
|
646
|
+
// @nx/vue's own `...vue.configs['flat/recommended']` spread — which
|
|
647
|
+
// this generator does not rewrite, only append to — applies Vue-only
|
|
648
|
+
// rules to every .ts/.js file in the app as well). Doing the same here
|
|
649
|
+
// would mean rewriting a block the application generator wrote, not
|
|
650
|
+
// appending to it, which is the one thing this helper is built to
|
|
651
|
+
// avoid; the practical exposure in a fresh single-app scaffold is low
|
|
652
|
+
// (no .spec.ts/.stories.ts test-double files exist yet at this point in
|
|
653
|
+
// the generator, and @nx/vue already turns off the rule most likely to
|
|
654
|
+
// misfire on plain .ts — vue/multi-word-component-names — project-wide
|
|
655
|
+
// on its own). Recorded here rather than silently left unmentioned.
|
|
656
|
+
appendToFlatEslintConfig(tree, `${appName}/eslint.config.mjs`, `,
|
|
657
|
+
{
|
|
658
|
+
// eslint-plugin-vue's flat/recommended (spread above by @nx/vue's own
|
|
659
|
+
// application generator) ships layout/whitespace rules that fight
|
|
660
|
+
// Prettier — same gap libs/vue/eslint.config.mjs closes.
|
|
661
|
+
files: ['**/*.vue'],
|
|
662
|
+
rules: eslintConfigPrettier.rules,
|
|
663
|
+
},
|
|
664
|
+
{
|
|
665
|
+
// Not part of any eslint-plugin-vue preset — opted in explicitly, same as
|
|
666
|
+
// libs/vue/eslint.config.mjs: catches a declared prop nothing in the
|
|
667
|
+
// component reads.
|
|
668
|
+
files: ['**/*.vue'],
|
|
669
|
+
rules: {
|
|
670
|
+
'vue/no-unused-properties': ['error', { groups: ['props'] }],
|
|
600
671
|
},
|
|
672
|
+
},
|
|
601
673
|
`, [`import eslintConfigPrettier from 'eslint-config-prettier';`]);
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
|
|
616
|
-
|
|
617
|
-
|
|
618
|
-
|
|
619
|
-
|
|
620
|
-
|
|
621
|
-
|
|
622
|
-
|
|
623
|
-
|
|
624
|
-
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
|
|
635
|
-
|
|
636
|
-
|
|
637
|
-
|
|
638
|
-
|
|
639
|
-
|
|
640
|
-
|
|
641
|
-
|
|
642
|
-
|
|
643
|
-
|
|
644
|
-
|
|
645
|
-
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
|
|
650
|
-
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
|
|
654
|
-
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
|
|
665
|
-
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
|
|
673
|
-
|
|
674
|
-
|
|
675
|
-
|
|
676
|
-
|
|
677
|
-
|
|
678
|
-
|
|
679
|
-
|
|
680
|
-
|
|
681
|
-
|
|
682
|
-
|
|
683
|
-
|
|
684
|
-
|
|
685
|
-
|
|
686
|
-
|
|
687
|
-
|
|
688
|
-
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
//
|
|
692
|
-
|
|
693
|
-
|
|
694
|
-
|
|
695
|
-
|
|
696
|
-
|
|
697
|
-
|
|
698
|
-
//
|
|
699
|
-
//
|
|
700
|
-
//
|
|
701
|
-
//
|
|
702
|
-
//
|
|
703
|
-
//
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
|
|
674
|
+
}
|
|
675
|
+
// Copy design tokens into the scaffolded app so attendees can edit them
|
|
676
|
+
// directly. They're not imported from the @atelier-ui/<fw> npm package
|
|
677
|
+
// because (a) those published packages don't ship tokens.css, and (b) a
|
|
678
|
+
// workshop attendee editing colors in node_modules is a bad experience.
|
|
679
|
+
tree.write(`${appName}/src/styles/tokens.css`, readTemplate('styles/tokens.css'));
|
|
680
|
+
// Prepend the tokens import to the app's global stylesheet
|
|
681
|
+
const stylesPath = `${appName}/src/styles.css`;
|
|
682
|
+
const existing = tree.exists(stylesPath)
|
|
683
|
+
? ((_c = tree.read(stylesPath, 'utf-8')) !== null && _c !== void 0 ? _c : '')
|
|
684
|
+
: '';
|
|
685
|
+
tree.write(stylesPath, `@import './styles/tokens.css';\n\n${existing}`);
|
|
686
|
+
// Storybook config: mirrors libs/{angular,react,vue}/.storybook/main.ts
|
|
687
|
+
// minus staticDirs, the BUILD_STORYBOOK viteFinal block (hosted-path-only),
|
|
688
|
+
// and @storybook/addon-designs (no Figma handoff doc to link from here).
|
|
689
|
+
// @storybook/addon-vitest DOES ship (owner correction 2026-09-10 to
|
|
690
|
+
// ADR-0123's original "no test runner" call).
|
|
691
|
+
tree.write(`${appName}/.storybook/main.ts`, readTemplate(storybookTemplateName(framework, 'main.ts')));
|
|
692
|
+
tree.write(`${appName}/.storybook/preview.${storybookOutputExt(framework)}`, readTemplate(storybookTemplateName(framework, 'preview')));
|
|
693
|
+
if (framework === 'angular') {
|
|
694
|
+
// The only framework that needs its own Storybook-scoped tsconfig — see
|
|
695
|
+
// libs/angular/.storybook/tsconfig.json, which this mirrors against the
|
|
696
|
+
// tsconfig.json the Angular application generator actually writes (both
|
|
697
|
+
// shapes verified: `files: []`, `include: []`, `references` to app/spec).
|
|
698
|
+
tree.write(`${appName}/.storybook/tsconfig.json`, readTemplate('storybook/angular/tsconfig.json'));
|
|
699
|
+
}
|
|
700
|
+
// One example story per app: small on purpose — it exists so Storybook
|
|
701
|
+
// isn't empty and the attendee has a working pattern to copy, not as a
|
|
702
|
+
// second component showcase.
|
|
703
|
+
tree.write(`${appName}/src/atl-button.stories.${storybookOutputExt(framework)}`, readTemplate(storybookTemplateName(framework, 'atl-button.stories')));
|
|
704
|
+
// Browser-mode Storybook tests (owner correction 2026-09-10 to ADR-0123 —
|
|
705
|
+
// storybook-test / check:stories ship with the scaffold after all).
|
|
706
|
+
// `vitest.config.ts` is always plain `.ts`, never `.tsx` — see
|
|
707
|
+
// storybookTemplateName()'s comment. The literal filename matters:
|
|
708
|
+
// @storybook/addon-vitest's `test-run` tool walks up from a story's
|
|
709
|
+
// .storybook directory looking for the nearest vitest/vite config by
|
|
710
|
+
// this standard name.
|
|
711
|
+
tree.write(`${appName}/vitest.config.ts`, readTemplate(storybookTemplateName(framework, 'vitest.config')));
|
|
712
|
+
tree.write(`${appName}/.storybook/vitest.setup.ts`, readTemplate(storybookTemplateName(framework, 'vitest.setup')));
|
|
713
|
+
// S5 — the unit test runner: a second, unmarked Vitest config
|
|
714
|
+
// (`vitest.unit.config.ts`, never `vitest.config.ts` — see that file's own
|
|
715
|
+
// comment above and testingTemplateName()'s) so a composable, a service, a
|
|
716
|
+
// helper, or a form-validation rule gets a fast, jsdom-based `nx test` —
|
|
717
|
+
// not just the browser-mode story tests above. One example unit test per
|
|
718
|
+
// app, same purpose as atl-button.stories.*: the pattern that gets copied.
|
|
719
|
+
tree.write(`${appName}/vitest.unit.config.ts`, readTemplate(testingTemplateName(framework, 'vitest.unit.config')));
|
|
720
|
+
tree.write(`${appName}/src/test-setup.ts`, readTemplate(testingTemplateName(framework, 'test-setup')));
|
|
721
|
+
tree.write(`${appName}/src/atl-button.spec.${storybookOutputExt(framework)}`, readTemplate(testingTemplateName(framework, 'atl-button.spec')));
|
|
722
|
+
// The application generator (@nx/{angular,react,vue}:application, above)
|
|
723
|
+
// guarantees `${appName}/project.json` exists at this point — updateJson
|
|
724
|
+
// reads it first and throws `Cannot find ${path}` if it doesn't, which is
|
|
725
|
+
// exactly the loud failure we want: a workshop app with a Storybook config
|
|
726
|
+
// directory but no way to start it is worse than a generator that stops.
|
|
727
|
+
// Always 6006 — the workshop scaffolds exactly one app, so there is no
|
|
728
|
+
// second framework's Storybook to offset a port against.
|
|
729
|
+
const storybookPort = 6006;
|
|
730
|
+
(0, devkit_1.updateJson)(tree, `${appName}/project.json`, (config) => {
|
|
731
|
+
var _a;
|
|
732
|
+
(_a = config.targets) !== null && _a !== void 0 ? _a : (config.targets = {});
|
|
733
|
+
config.targets['storybook'] = {
|
|
734
|
+
executor: 'nx:run-commands',
|
|
735
|
+
options: {
|
|
736
|
+
command: `npx storybook dev --config-dir ${appName}/.storybook --port ${storybookPort}`,
|
|
737
|
+
},
|
|
738
|
+
};
|
|
739
|
+
config.targets['build-storybook'] = {
|
|
740
|
+
executor: 'nx:run-commands',
|
|
741
|
+
outputs: [`{workspaceRoot}/dist/storybook/${appName}`],
|
|
742
|
+
options: {
|
|
743
|
+
command: `npx storybook build --config-dir ${appName}/.storybook --output-dir dist/storybook/${appName}`,
|
|
744
|
+
},
|
|
745
|
+
};
|
|
746
|
+
// Mirrors libs/{angular,react,vue}/project.json's own "storybook-test"
|
|
747
|
+
// target exactly, modulo the config filename (vitest.config.ts here,
|
|
748
|
+
// vitest.storybook.config.ts there — see storybookTemplateName()'s
|
|
749
|
+
// comment on why the scaffold uses the standard name instead).
|
|
750
|
+
config.targets['storybook-test'] = {
|
|
751
|
+
executor: 'nx:run-commands',
|
|
752
|
+
options: {
|
|
753
|
+
command: 'npx vitest run --config vitest.config.ts',
|
|
754
|
+
cwd: appName,
|
|
755
|
+
},
|
|
756
|
+
};
|
|
757
|
+
// Ported CSS-discipline rules (ADR-0130): a sibling target, not folded
|
|
758
|
+
// into `lint` — same reasoning as this repo's own libs/{fw}/project.json
|
|
759
|
+
// (lint is inferred by @nx/eslint/plugin per project; overriding it to
|
|
760
|
+
// also shell out would re-implement what inference gives for free).
|
|
761
|
+
// --ignore-pattern excludes this app's own tokens.css from the run: it
|
|
762
|
+
// is a token DEFINITION file, the one place these rules' raw literals
|
|
763
|
+
// are supposed to live, not a file that reads/consumes tokens.
|
|
764
|
+
config.targets['stylelint'] = {
|
|
765
|
+
executor: 'nx:run-commands',
|
|
766
|
+
options: {
|
|
767
|
+
command: `stylelint '${appName}/src/**/*.css' --ignore-pattern '${appName}/src/styles/tokens.css' --config stylelint.config.mjs`,
|
|
768
|
+
},
|
|
769
|
+
};
|
|
770
|
+
// S5 — the unit test runner. Mirrors "storybook-test" above exactly
|
|
771
|
+
// (nx:run-commands + cwd), just pointed at vitest.unit.config.ts instead.
|
|
772
|
+
// This REPLACES whatever "test" target the framework's own application
|
|
773
|
+
// generator wrote: React/Vue write none (unitTestRunner: 'none'); Angular
|
|
774
|
+
// writes its own native `@angular/build:unit-test` wiring regardless of
|
|
775
|
+
// skipTests (confirmed against the real generator — skipTests only skips
|
|
776
|
+
// generating example spec files, not the target). This workspace instead
|
|
777
|
+
// mirrors libs/angular's own proven setup — @analogjs/vitest-angular +
|
|
778
|
+
// a vite.config-style file — the same way on all three frameworks, so
|
|
779
|
+
// `nx test` behaves identically across the workshop regardless of which
|
|
780
|
+
// one was chosen.
|
|
781
|
+
config.targets['test'] = {
|
|
782
|
+
executor: 'nx:run-commands',
|
|
783
|
+
options: {
|
|
784
|
+
command: 'npx vitest run --config vitest.unit.config.ts',
|
|
785
|
+
cwd: appName,
|
|
786
|
+
},
|
|
787
|
+
};
|
|
788
|
+
return config;
|
|
789
|
+
});
|
|
790
|
+
storybookDevDeps[STORYBOOK_FRAMEWORK_PACKAGE[framework]] = STORYBOOK_VERSION;
|
|
791
|
+
// @storybook/react-vite and @storybook/vue3-vite each carry their
|
|
792
|
+
// non-vite renderer counterpart as a plain (non-peer) `dependency`, not
|
|
793
|
+
// something npm/pnpm is told the app needs directly — but the story and
|
|
794
|
+
// preview templates import straight from '@storybook/react' /
|
|
795
|
+
// '@storybook/vue3' for the `Meta`/`StoryObj`/`Preview` types. That
|
|
796
|
+
// resolves today only because npm hoists it; pnpm's stricter, non-hoisted
|
|
797
|
+
// layout would leave the import unresolved. Angular has no matching case:
|
|
798
|
+
// '@storybook/angular-vite' has no such counterpart to hoist, and the
|
|
799
|
+
// angular templates import their types from '@storybook/angular-vite'
|
|
800
|
+
// itself (see files/storybook/angular/*.template) — adding
|
|
801
|
+
// '@storybook/angular' back here would reintroduce exactly the ERESOLVE
|
|
802
|
+
// this generator now avoids (its peer on @angular-devkit/build-angular is
|
|
803
|
+
// not satisfiable by a freshly scaffolded Angular 22 app).
|
|
804
|
+
if (framework === 'react') {
|
|
805
|
+
storybookDevDeps['@storybook/react'] = STORYBOOK_VERSION;
|
|
806
|
+
}
|
|
807
|
+
if (framework === 'vue') {
|
|
808
|
+
storybookDevDeps['@storybook/vue3'] = STORYBOOK_VERSION;
|
|
710
809
|
}
|
|
711
810
|
// ─── Prettier (formatting enforcement) ───────────────────────────────────
|
|
712
811
|
// Measured 2026-09-12 (tasks/todo.md, "A. Formatting enforcement"): a
|
|
@@ -721,7 +820,7 @@ function presetGenerator(tree, options) {
|
|
|
721
820
|
(0, devkit_1.writeJson)(tree, '.prettierrc', { singleQuote: true });
|
|
722
821
|
// ─── Stylelint (ported CSS-discipline rules, ADR-0130) ───────────────────
|
|
723
822
|
console.log(`\n◇ Wiring stylelint (ported CSS-discipline rules)…`);
|
|
724
|
-
tree.write('stylelint.config.mjs', buildStylelintConfig(
|
|
823
|
+
tree.write('stylelint.config.mjs', buildStylelintConfig(framework));
|
|
725
824
|
// Six files, byte-identical to the canonical copies in tools/stylelint-rules/
|
|
726
825
|
// (kept that way by this repo's own sync-preflight.mjs) — see
|
|
727
826
|
// buildStylelintConfig's comment above for why no-primitive-token.js ships
|
|
@@ -736,13 +835,13 @@ function presetGenerator(tree, options) {
|
|
|
736
835
|
]) {
|
|
737
836
|
tree.write(`tools/stylelint-rules/${ruleFile}`, readTemplate(`tools/stylelint-rules/${ruleFile}`));
|
|
738
837
|
}
|
|
739
|
-
// The config and the rule files above both live outside
|
|
740
|
-
// reads them (the
|
|
741
|
-
//
|
|
742
|
-
//
|
|
838
|
+
// The config and the rule files above both live outside the project that
|
|
839
|
+
// reads them (the app's own `stylelint` target added above) — exactly the
|
|
840
|
+
// cache trap ADR-0130 proved twice in this repo's own nx.json. Mirrors this
|
|
841
|
+
// repo's own targetDefaults.stylelint, minus
|
|
743
842
|
// `tools/scripts/lib/allowlists.js` (the scaffold ships no such file — see
|
|
744
843
|
// buildStylelintConfig's comment on why neither wired rule is given
|
|
745
|
-
// `allowlistsFile`). The application
|
|
844
|
+
// `allowlistsFile`). The application generator above is guaranteed to
|
|
746
845
|
// have already written nx.json (create-nx-workspace writes it before any
|
|
747
846
|
// preset runs), so `updateJson` here is safe the same way the package.json
|
|
748
847
|
// update below is.
|
|
@@ -756,28 +855,24 @@ function presetGenerator(tree, options) {
|
|
|
756
855
|
'^default',
|
|
757
856
|
'{workspaceRoot}/stylelint.config.mjs',
|
|
758
857
|
'{workspaceRoot}/tools/stylelint-rules/**/*',
|
|
759
|
-
|
|
858
|
+
`{workspaceRoot}/${appName}/src/styles/tokens.css`,
|
|
760
859
|
{ externalDependencies: ['stylelint'] },
|
|
761
860
|
],
|
|
762
861
|
};
|
|
763
862
|
return config;
|
|
764
863
|
});
|
|
765
864
|
// ─── The contract loop (ADR-0121 S4) ─────────────────────────────────────
|
|
766
|
-
//
|
|
767
|
-
//
|
|
768
|
-
// precedent frameworks[0] already sets elsewhere in this generator (the
|
|
769
|
-
// README's "Getting started" nx serve command).
|
|
770
|
-
const primaryFramework = frameworks[0];
|
|
771
|
-
const primaryApp = `workshop-${primaryFramework}`;
|
|
865
|
+
// contracts.config.json names the workshop's one framework and app —
|
|
866
|
+
// `framework`/`appName`, already established above.
|
|
772
867
|
console.log(`\n◇ Writing the contract loop (check:contracts, the example AtlButton contract, the Figma snapshot projection)…`);
|
|
773
868
|
// .ts.template, not .ts — see the comment on storybookTemplateName() above:
|
|
774
869
|
// a literal `.ts` file under files/ is compiled away by this package's own
|
|
775
870
|
// tsconfig.lib.json (`include: ["src/**/*.ts"]`) and never reaches dist/
|
|
776
871
|
// under a name readTemplate() can find at runtime. The OUTPUT filenames
|
|
777
872
|
// below stay plain `.ts` — only the template source needs the suffix.
|
|
778
|
-
tree.write(`${
|
|
779
|
-
tree.write(`${
|
|
780
|
-
tree.write(`${
|
|
873
|
+
tree.write(`${appName}/src/contracts/types.ts`, readTemplate('contracts/types.ts.template'));
|
|
874
|
+
tree.write(`${appName}/src/contracts/README.md`, readTemplate('contracts/README.md'));
|
|
875
|
+
tree.write(`${appName}/src/contracts/button.contract.ts`, readTemplate('contracts/button.contract.ts.template'));
|
|
781
876
|
tree.write('tools/scripts/check-contracts.mjs', readTemplate('tools/scripts/check-contracts.mjs'));
|
|
782
877
|
tree.write('tools/scripts/lib/ts-eval.js', readTemplate('tools/scripts/lib/ts-eval.js'));
|
|
783
878
|
tree.write('tools/scripts/lib/docgen.mjs', readTemplate('tools/scripts/lib/docgen.mjs'));
|
|
@@ -788,47 +883,117 @@ function presetGenerator(tree, options) {
|
|
|
788
883
|
// figma:snapshot themselves.
|
|
789
884
|
tree.write('tools/figma/snapshot.json', readTemplate('figma/snapshot.json'));
|
|
790
885
|
(0, devkit_1.writeJson)(tree, 'contracts.config.json', {
|
|
791
|
-
framework
|
|
792
|
-
contracts: `${
|
|
793
|
-
stories: [`${
|
|
886
|
+
framework,
|
|
887
|
+
contracts: `${appName}/src/contracts`,
|
|
888
|
+
stories: [`${appName}/src`],
|
|
794
889
|
snapshot: 'tools/figma/snapshot.json',
|
|
795
890
|
});
|
|
796
891
|
console.log(`\n◇ Writing project files (CLAUDE.md, README, .mcp.json)…`);
|
|
797
892
|
// Write CLAUDE.md with framework-specific guidance
|
|
798
|
-
|
|
799
|
-
|
|
800
|
-
|
|
801
|
-
return `### Angular (\`@atelier-ui/angular\`)
|
|
893
|
+
let frameworkSection = '';
|
|
894
|
+
if (framework === 'angular') {
|
|
895
|
+
frameworkSection = `### Angular (\`@atelier-ui/angular\`)
|
|
802
896
|
- Selectors: \`atl-button\`, \`atl-input\`, \`atl-dialog\`, …
|
|
803
897
|
- Import: \`import { AtlButton } from '@atelier-ui/angular';\`
|
|
804
898
|
- Add to \`@Component({ imports: [AtlButton] })\`
|
|
805
899
|
- Form controls implement Signal Forms (\`FormValueControl\` / \`FormCheckboxControl\`)`;
|
|
806
|
-
|
|
807
|
-
|
|
808
|
-
|
|
900
|
+
}
|
|
901
|
+
else if (framework === 'react') {
|
|
902
|
+
frameworkSection = `### React (\`@atelier-ui/react\`)
|
|
809
903
|
- Elements: \`<AtlButton>\`, \`<AtlInput>\`, \`<AtlDialog>\`, …
|
|
810
904
|
- Import: \`import { AtlButton } from '@atelier-ui/react';\`
|
|
811
905
|
- Event handlers follow \`onXxx\` / \`onXxxChange\` convention
|
|
812
906
|
- Toast: use \`useAtlToast()\` hook inside \`<AtlToastProvider>\``;
|
|
813
|
-
|
|
814
|
-
|
|
815
|
-
|
|
907
|
+
}
|
|
908
|
+
else if (framework === 'vue') {
|
|
909
|
+
frameworkSection = `### Vue (\`@atelier-ui/vue\`)
|
|
816
910
|
- Elements: \`<AtlButton>\`, \`<AtlInput>\`, \`<AtlDialog>\`, …
|
|
817
911
|
- Import: \`import { AtlButton } from '@atelier-ui/vue';\`
|
|
818
912
|
- Two-way binding: \`v-model\` and \`v-model:value\` where applicable
|
|
819
913
|
- Toast: use \`useAtlToast()\` composable`;
|
|
820
|
-
|
|
821
|
-
|
|
822
|
-
|
|
823
|
-
|
|
824
|
-
|
|
825
|
-
|
|
914
|
+
}
|
|
915
|
+
// Idioms for the ONE framework this workspace scaffolds (tasks/todo.md's
|
|
916
|
+
// "S3 — the workspace is set up for Claude Code" — a later plan than, and
|
|
917
|
+
// unrelated to, the S1-S4 labels elsewhere in this file, which are this
|
|
918
|
+
// package's own now-shipped Storybook/skills slices) — three to
|
|
919
|
+
// four bullets, not an essay; each names the thing an attendee coming from
|
|
920
|
+
// a different framework (or an agent trained on generic examples) is most
|
|
921
|
+
// likely to get wrong on day one.
|
|
922
|
+
let frameworkIdiomsSection = '';
|
|
923
|
+
if (framework === 'angular') {
|
|
924
|
+
frameworkIdiomsSection = `- Prefer signals (\`signal\`, \`computed\`, \`linkedSignal\`) over manual state
|
|
925
|
+
bookkeeping — this workspace runs **zoneless** (no Zone.js), so change
|
|
926
|
+
detection reacts to signal writes, not to arbitrary async callbacks.
|
|
927
|
+
- Use the built-in control-flow syntax (\`@if\`, \`@for\`, \`@switch\`) in
|
|
928
|
+
templates, not the legacy \`*ngIf\`/\`*ngFor\` structural directives.
|
|
929
|
+
- Use \`inject()\` for dependency injection in fields and functions instead of
|
|
930
|
+
constructor-parameter injection.
|
|
931
|
+
- Form controls implement Signal Forms (\`FormValueControl\` /
|
|
932
|
+
\`FormCheckboxControl\`, not \`ReactiveFormsModule\`) — see Component Libraries
|
|
933
|
+
above.`;
|
|
934
|
+
}
|
|
935
|
+
else if (framework === 'react') {
|
|
936
|
+
frameworkIdiomsSection = `- Follow the Rules of Hooks: only call hooks at the top level of a component
|
|
937
|
+
or custom hook, never inside a condition, loop, or nested function.
|
|
938
|
+
- This is a **Vite SPA, not an RSC app** — there are no Server Components, no
|
|
939
|
+
\`"use client"\` directives, and no server actions; everything renders
|
|
940
|
+
client-side.
|
|
941
|
+
- Keep \`useEffect\` dependency arrays honest — a missing dependency is a bug
|
|
942
|
+
to fix, not a lint rule to silence.
|
|
943
|
+
- Event handlers on Atelier components follow the \`onXxx\` / \`onXxxChange\`
|
|
944
|
+
convention (see Component Libraries above) — match it in your own composed
|
|
945
|
+
components too.`;
|
|
946
|
+
}
|
|
947
|
+
else if (framework === 'vue') {
|
|
948
|
+
frameworkIdiomsSection = `- Use \`<script setup>\` with the Composition API — no Options API (\`data()\`,
|
|
949
|
+
\`methods\`, …) in new components.
|
|
950
|
+
- Use \`defineModel()\` for two-way-bound props instead of hand-rolling a
|
|
951
|
+
\`modelValue\` prop plus \`emit('update:modelValue')\`.
|
|
952
|
+
- Prefer \`ref\`/\`reactive\` + \`computed\` over ad-hoc mutable state.
|
|
953
|
+
- Two-way binding on Atelier components follows \`v-model\` / \`v-model:value\`
|
|
954
|
+
(see Component Libraries above) — mirror that convention in your own
|
|
955
|
+
composed components.`;
|
|
956
|
+
}
|
|
957
|
+
const mcpSection = `### \`storybook-${framework}\` MCP
|
|
826
958
|
Before using any component:
|
|
827
959
|
1. Call \`docs-list\` to get valid component IDs
|
|
828
960
|
2. Call \`docs-show\` with the ID — never invent props
|
|
829
961
|
3. Call \`docs-show-story\` for a specific variant
|
|
830
|
-
4. Do not use a component that is not in the docs
|
|
831
|
-
|
|
962
|
+
4. Do not use a component that is not in the docs
|
|
963
|
+
|
|
964
|
+
### \`uianatomy\` MCP
|
|
965
|
+
Canonical component anatomy, axes, slots, transitions, motion, tokens, events, and
|
|
966
|
+
cross-framework/library divergences. Reach for it when a Storybook doc leaves a
|
|
967
|
+
prop's shape, an interaction, or a cross-library convention ambiguous.`;
|
|
968
|
+
const angularCliMcpSection = framework === 'angular'
|
|
969
|
+
? `
|
|
970
|
+
|
|
971
|
+
### \`angular-cli\` MCP
|
|
972
|
+
Angular CLI best practices, API search, and docs lookups — prefer it over guessing
|
|
973
|
+
at \`ng\` flags or Angular API shape from memory.`
|
|
974
|
+
: '';
|
|
975
|
+
const versionsSection = `## Versions
|
|
976
|
+
|
|
977
|
+
\`@atelier-ui/${framework}\` is pinned to \`${componentPackageVersion}\` — the version
|
|
978
|
+
this workspace was scaffolded with — so the workshop is reproducible: every attendee
|
|
979
|
+
gets the same component behavior, not whatever \`latest\` happens to resolve to that
|
|
980
|
+
morning. Move it deliberately when you want a newer release:
|
|
981
|
+
|
|
982
|
+
\`\`\`bash
|
|
983
|
+
npm install @atelier-ui/${framework}@latest
|
|
984
|
+
\`\`\`
|
|
985
|
+
`;
|
|
986
|
+
// S5a — the generated \`figma:snapshot\` npm script names the attendee's own
|
|
987
|
+
// Figma file key when the CLI collected one (see the \`options.figmaFile\`
|
|
988
|
+
// branch on \`pkg.scripts['figma:snapshot']\` further below); otherwise it
|
|
989
|
+
// keeps today's literal \`<YOUR_FIGMA_FILE_KEY>\` placeholder. This sentence
|
|
990
|
+
// has to agree with whichever branch that assignment takes, or CLAUDE.md
|
|
991
|
+
// would tell the reader to edit a placeholder that was never written.
|
|
992
|
+
const figmaSnapshotRefreshInstruction = options.figmaFile
|
|
993
|
+
? `\`figma:snapshot\` is already pointed at \`${options.figmaFile}\`; change it if you
|
|
994
|
+
duplicate the file again`
|
|
995
|
+
: `edit the \`--file\` placeholder in \`package.json\`'s \`figma:snapshot\` script to
|
|
996
|
+
your own Figma file key`;
|
|
832
997
|
tree.write('CLAUDE.md', `# Atelier Workshop
|
|
833
998
|
|
|
834
999
|
This workspace uses Atelier for all UI components.
|
|
@@ -838,11 +1003,17 @@ Full API reference: ${SITE_URL}/llms-full.txt
|
|
|
838
1003
|
|
|
839
1004
|
The servers are pre-configured in \`.mcp.json\` and connect automatically.
|
|
840
1005
|
|
|
841
|
-
${mcpSection}
|
|
1006
|
+
${mcpSection}${angularCliMcpSection}
|
|
842
1007
|
|
|
843
1008
|
## Component Libraries
|
|
844
1009
|
|
|
845
|
-
${
|
|
1010
|
+
${frameworkSection}
|
|
1011
|
+
|
|
1012
|
+
${versionsSection}
|
|
1013
|
+
|
|
1014
|
+
## Framework Idioms
|
|
1015
|
+
|
|
1016
|
+
${frameworkIdiomsSection}
|
|
846
1017
|
|
|
847
1018
|
## Composition Patterns
|
|
848
1019
|
|
|
@@ -861,7 +1032,7 @@ hardcoded hex values or pixel sizes — always reference a token.
|
|
|
861
1032
|
Key tokens:
|
|
862
1033
|
- Colors: --ui-color-primary, --ui-color-text, --ui-color-surface-raised, --ui-color-border
|
|
863
1034
|
- Spacing: --ui-spacing-4 (1rem), --ui-spacing-6 (1.5rem), --ui-spacing-8 (2rem)
|
|
864
|
-
- Radius: --ui-radius-sm (0.
|
|
1035
|
+
- Radius: --ui-radius-sm (0.5rem), --ui-radius-md (0.625rem), --ui-radius-lg (0.875rem)
|
|
865
1036
|
|
|
866
1037
|
## Rules
|
|
867
1038
|
- Prefer component props over custom CSS
|
|
@@ -878,15 +1049,15 @@ scaffold itself is already Prettier-clean — \`check:format\` passes right afte
|
|
|
878
1049
|
|
|
879
1050
|
## Apps
|
|
880
1051
|
|
|
881
|
-
|
|
1052
|
+
- \`${appName}\` — run with \`npx nx serve ${appName}\`
|
|
882
1053
|
|
|
883
1054
|
## Storybook
|
|
884
1055
|
|
|
885
|
-
|
|
1056
|
+
The app has its own local Storybook:
|
|
886
1057
|
|
|
887
|
-
|
|
1058
|
+
- \`${appName}\` — \`npx nx storybook ${appName}\` — http://localhost:6006
|
|
888
1059
|
|
|
889
|
-
Build a static Storybook (CI, hosting) with \`npx nx build-storybook
|
|
1060
|
+
Build a static Storybook (CI, hosting) with \`npx nx build-storybook ${appName}\`.
|
|
890
1061
|
|
|
891
1062
|
Every story is also a browser-mode test (\`@storybook/addon-vitest\`). One-time setup
|
|
892
1063
|
after \`npm install\`:
|
|
@@ -903,6 +1074,13 @@ npm run check:stories
|
|
|
903
1074
|
|
|
904
1075
|
## Agent Skills
|
|
905
1076
|
|
|
1077
|
+
This workspace also ships \`atelier-component\` (\`.claude/skills/atelier-component/SKILL.md\`)
|
|
1078
|
+
unconditionally — this generator writes it straight to disk as part of scaffolding, with no
|
|
1079
|
+
network fetch and no \`skills: false\` opt-out, unlike the four skills below. It runs the
|
|
1080
|
+
Figma → contract → stories → checks loop scoped to what this workspace can actually check —
|
|
1081
|
+
see the skill itself, or ask Claude Code to use it, for the loop and \`check:contracts\`'s
|
|
1082
|
+
finding codes.
|
|
1083
|
+
|
|
906
1084
|
${skillsEnabled
|
|
907
1085
|
? `The scaffold attempted to install four \`storybookjs/mcp\` skills for Claude
|
|
908
1086
|
Code (\`.claude/skills/\`) during setup — a failed clone (offline, unreachable
|
|
@@ -953,9 +1131,19 @@ ${SKILLS_ADD_COMMAND_FOR_HUMANS}
|
|
|
953
1131
|
\`\`\`
|
|
954
1132
|
`}
|
|
955
1133
|
|
|
1134
|
+
## API Design Principles
|
|
1135
|
+
|
|
1136
|
+
Every component in \`@atelier-ui/${framework}\` follows one set of API-design rules —
|
|
1137
|
+
predictable naming across components, narrow literal-union types instead of \`string\`,
|
|
1138
|
+
composition over configuration, and a sensible default for every prop — so a model that
|
|
1139
|
+
has generated code for one component can infer the shape of the next. When you design
|
|
1140
|
+
the API of your own component, these are the rules the library itself follows:
|
|
1141
|
+
|
|
1142
|
+
- Guide: ${SITE_URL}/design-principles
|
|
1143
|
+
|
|
956
1144
|
## The Contract Loop
|
|
957
1145
|
|
|
958
|
-
A contract (\`${
|
|
1146
|
+
A contract (\`${appName}/src/contracts/<name>.contract.ts\`) is the one hand-authored
|
|
959
1147
|
spec file per component: the Figma master's node id, plus intentional Figma ↔ code
|
|
960
1148
|
mismatches (\`figmaOnly\`, \`codeOnly\`, \`axisMap\`) — never props, defaults, or
|
|
961
1149
|
descriptions; those live in the component's own types/JSDoc and its stories.
|
|
@@ -975,13 +1163,12 @@ offline — no browser, no Storybook build — and reports one line per finding:
|
|
|
975
1163
|
that renders it)
|
|
976
1164
|
|
|
977
1165
|
Refresh \`tools/figma/snapshot.json\` from the real master with the Figma Desktop Bridge
|
|
978
|
-
connected:
|
|
979
|
-
your own Figma file key, then run \`npm run figma:snapshot\`.
|
|
1166
|
+
connected: ${figmaSnapshotRefreshInstruction}, then run \`npm run figma:snapshot\`.
|
|
980
1167
|
|
|
981
1168
|
\`check:contracts\` proves shape and story coverage; \`npm run check:stories\` (every story,
|
|
982
1169
|
rendered headless in Chromium via \`@storybook/addon-vitest\`, with axe) proves rendering
|
|
983
1170
|
and accessibility. It does so for components whose source lives in this workspace. For
|
|
984
|
-
components imported from \`@atelier-ui/${
|
|
1171
|
+
components imported from \`@atelier-ui/${framework}\` — the example \`AtlButton\`
|
|
985
1172
|
included — the check recognises that the import resolves into \`node_modules\` and skips
|
|
986
1173
|
docgen for it — the same rule in every framework — so it has nothing to compare and
|
|
987
1174
|
reports only \`[NO-STORY-META]\`; their prop tables come from the hosted
|
|
@@ -989,6 +1176,22 @@ Storybook MCP (\`docs-show\`) instead. A green \`check:contracts\` on the exampl
|
|
|
989
1176
|
therefore proves the wiring, not the example. Run \`npx playwright install chromium\`
|
|
990
1177
|
once after \`npm install\` — see Storybook below.
|
|
991
1178
|
|
|
1179
|
+
## Definition of Done
|
|
1180
|
+
|
|
1181
|
+
A change here is done when all five of these pass:
|
|
1182
|
+
|
|
1183
|
+
- \`npm run check:format\` — Prettier
|
|
1184
|
+
- \`npm run check:stylelint\` — the ported CSS-discipline rules
|
|
1185
|
+
- \`npm run check:contracts\` — contract ↔ docgen ↔ Figma-snapshot parity
|
|
1186
|
+
- \`npm run check:unit\` — jsdom unit tests (components, composables, helpers)
|
|
1187
|
+
- \`npm run check:stories\` — every story, rendered in Chromium, axe-checked
|
|
1188
|
+
|
|
1189
|
+
**A gate's result is its exit code.** Run it as
|
|
1190
|
+
\`<command> > /tmp/x.log 2>&1; echo $?\` and read the log afterwards — never pipe
|
|
1191
|
+
a gate into \`head\` or \`grep\`. The pipe's own exit status is always \`0\`, which
|
|
1192
|
+
silently turns a failing gate into a passing one. \`/verify\` runs all five and
|
|
1193
|
+
reports each exit code (\`.claude/commands/verify.md\`).
|
|
1194
|
+
|
|
992
1195
|
## Troubleshooting
|
|
993
1196
|
|
|
994
1197
|
Run the preflight self-check to verify your environment:
|
|
@@ -1021,7 +1224,7 @@ file exports). The Desktop Bridge covers creation and inspection without a token
|
|
|
1021
1224
|
// The contract loop's own devDependencies (ADR-0121 S4): the MCP SDK
|
|
1022
1225
|
// figma-snapshot-contracts.mjs imports directly, always; `typescript` only
|
|
1023
1226
|
// when the framework application generator (above) didn't already add it —
|
|
1024
|
-
// read from the tree's package.json as it stands right now, after
|
|
1227
|
+
// read from the tree's package.json as it stands right now, after the
|
|
1025
1228
|
// framework's generator has run and before this generator's own writes
|
|
1026
1229
|
// below it.
|
|
1027
1230
|
const pkgSoFar = (0, devkit_1.readJson)(tree, 'package.json');
|
|
@@ -1034,31 +1237,57 @@ file exports). The Desktop Bridge covers creation and inspection without a token
|
|
|
1034
1237
|
contractLoopDevDeps.typescript = TYPESCRIPT_VERSION;
|
|
1035
1238
|
}
|
|
1036
1239
|
// Browser-mode Storybook tests (owner correction 2026-09-10 to ADR-0123):
|
|
1037
|
-
//
|
|
1240
|
+
// the selected framework needs its own Vite plugin for the vitest browser
|
|
1038
1241
|
// pipeline, added only when the framework's own application generator
|
|
1039
1242
|
// (above) didn't already bring it in. React and Vue's vite-based app
|
|
1040
1243
|
// generators typically already do; Angular's esbuild-based one never does.
|
|
1041
1244
|
const viteFrameworkDevDeps = {};
|
|
1042
|
-
if (
|
|
1245
|
+
if (framework === 'react' && !existingDeps['@vitejs/plugin-react']) {
|
|
1043
1246
|
viteFrameworkDevDeps['@vitejs/plugin-react'] = VITE_PLUGIN_REACT_VERSION;
|
|
1044
1247
|
}
|
|
1045
|
-
if (
|
|
1248
|
+
if (framework === 'vue' && !existingDeps['@vitejs/plugin-vue']) {
|
|
1046
1249
|
viteFrameworkDevDeps['@vitejs/plugin-vue'] = VITE_PLUGIN_VUE_VERSION;
|
|
1047
1250
|
}
|
|
1048
|
-
if (
|
|
1251
|
+
if (framework === 'angular' &&
|
|
1049
1252
|
!existingDeps['@analogjs/vite-plugin-angular']) {
|
|
1050
1253
|
viteFrameworkDevDeps['@analogjs/vite-plugin-angular'] =
|
|
1051
1254
|
ANALOGJS_VITE_PLUGIN_ANGULAR_VERSION;
|
|
1052
1255
|
}
|
|
1053
|
-
|
|
1054
|
-
|
|
1256
|
+
// Generalized for S5 (was Vue-only, for its browser-mode vitest.setup.ts):
|
|
1257
|
+
// every framework's own src/test-setup.ts now imports this too.
|
|
1258
|
+
if (!existingDeps['@testing-library/jest-dom']) {
|
|
1055
1259
|
viteFrameworkDevDeps['@testing-library/jest-dom'] =
|
|
1056
1260
|
TESTING_LIBRARY_JEST_DOM_VERSION;
|
|
1057
1261
|
}
|
|
1058
|
-
if (
|
|
1262
|
+
if (framework === 'vue' && !existingDeps['eslint-config-prettier']) {
|
|
1059
1263
|
viteFrameworkDevDeps['eslint-config-prettier'] =
|
|
1060
1264
|
ESLINT_CONFIG_PRETTIER_VERSION;
|
|
1061
1265
|
}
|
|
1266
|
+
// S5 — the unit test runner: each framework's own Testing Library, plus
|
|
1267
|
+
// `jsdom` itself (Vitest's `environment: 'jsdom'` needs the package
|
|
1268
|
+
// installed — it isn't bundled), added only when not already present.
|
|
1269
|
+
// Measured against the real application generators: Angular's own
|
|
1270
|
+
// (`addVitestAngular`, its native @angular/build:unit-test wiring, present
|
|
1271
|
+
// regardless of `skipTests`) already adds both `jsdom` and `vitest`; none
|
|
1272
|
+
// of the three adds a Testing Library package or `@analogjs/vitest-angular`.
|
|
1273
|
+
const unitTestDevDeps = {};
|
|
1274
|
+
if (!existingDeps.jsdom) {
|
|
1275
|
+
unitTestDevDeps.jsdom = JSDOM_VERSION;
|
|
1276
|
+
}
|
|
1277
|
+
if (framework === 'angular' && !existingDeps['@testing-library/angular']) {
|
|
1278
|
+
unitTestDevDeps['@testing-library/angular'] =
|
|
1279
|
+
TESTING_LIBRARY_ANGULAR_VERSION;
|
|
1280
|
+
}
|
|
1281
|
+
if (framework === 'react' && !existingDeps['@testing-library/react']) {
|
|
1282
|
+
unitTestDevDeps['@testing-library/react'] = TESTING_LIBRARY_REACT_VERSION;
|
|
1283
|
+
}
|
|
1284
|
+
if (framework === 'vue' && !existingDeps['@testing-library/vue']) {
|
|
1285
|
+
unitTestDevDeps['@testing-library/vue'] = TESTING_LIBRARY_VUE_VERSION;
|
|
1286
|
+
}
|
|
1287
|
+
if (framework === 'angular' && !existingDeps['@analogjs/vitest-angular']) {
|
|
1288
|
+
unitTestDevDeps['@analogjs/vitest-angular'] =
|
|
1289
|
+
ANALOGJS_VITEST_ANGULAR_VERSION;
|
|
1290
|
+
}
|
|
1062
1291
|
// Ported CSS-discipline rules (ADR-0130). No postcss-html: that's only
|
|
1063
1292
|
// needed to lint .astro files, and the scaffold has none.
|
|
1064
1293
|
const stylelintDevDeps = {
|
|
@@ -1070,10 +1299,10 @@ file exports). The Desktop Bridge covers creation and inspection without a token
|
|
|
1070
1299
|
prettier: PRETTIER_VERSION,
|
|
1071
1300
|
};
|
|
1072
1301
|
// Install selected @atelier-ui/* packages (dependencies) and Storybook +
|
|
1073
|
-
// the contract loop's own tools + the vitest browser-mode tooling +
|
|
1074
|
-
//
|
|
1075
|
-
// constants above)
|
|
1076
|
-
const installTask = (0, devkit_1.addDependenciesToPackageJson)(tree, deps, Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, storybookDevDeps), contractLoopDevDeps), viteFrameworkDevDeps), stylelintDevDeps), prettierDevDeps));
|
|
1302
|
+
// the contract loop's own tools + the vitest browser-mode tooling + the
|
|
1303
|
+
// unit test runner's own tooling (S5) + stylelint + prettier
|
|
1304
|
+
// (devDependencies, exact pins — see the *_VERSION constants above)
|
|
1305
|
+
const installTask = (0, devkit_1.addDependenciesToPackageJson)(tree, deps, Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, storybookDevDeps), contractLoopDevDeps), viteFrameworkDevDeps), unitTestDevDeps), stylelintDevDeps), prettierDevDeps));
|
|
1077
1306
|
// Remove the preset package itself — create-nx-workspace adds it automatically
|
|
1078
1307
|
// but it's a build-time tool and should not be in the workspace's dependencies
|
|
1079
1308
|
const removePresetTask = (0, devkit_1.removeDependenciesFromPackageJson)(tree, ['@atelier-ui/create-workspace'], []);
|
|
@@ -1087,21 +1316,30 @@ file exports). The Desktop Bridge covers creation and inspection without a token
|
|
|
1087
1316
|
var _a;
|
|
1088
1317
|
pkg.scripts = (_a = pkg.scripts) !== null && _a !== void 0 ? _a : {};
|
|
1089
1318
|
pkg.scripts.preflight = 'node tools/scripts/preflight.mjs';
|
|
1090
|
-
// The contract loop (ADR-0121 S4). `figma:snapshot`
|
|
1091
|
-
//
|
|
1092
|
-
//
|
|
1093
|
-
//
|
|
1094
|
-
//
|
|
1095
|
-
//
|
|
1319
|
+
// The contract loop (ADR-0121 S4). `figma:snapshot` names the attendee's
|
|
1320
|
+
// own Figma file key (schema option `figmaFile`, S5a) when the caller
|
|
1321
|
+
// supplied one — QMnDD8uZQPldPrlCwZZ58T is THIS repo's own file, never a
|
|
1322
|
+
// default here. Most direct-preset callers have no key to hand, so
|
|
1323
|
+
// without one it ships with the same literal placeholder as before;
|
|
1324
|
+
// CLAUDE.md's "The Contract Loop" section (figmaSnapshotRefreshInstruction
|
|
1325
|
+
// above) spells out how to fill it in either way.
|
|
1096
1326
|
pkg.scripts['check:contracts'] = 'node tools/scripts/check-contracts.mjs';
|
|
1097
|
-
pkg.scripts['figma:snapshot'] =
|
|
1098
|
-
|
|
1327
|
+
pkg.scripts['figma:snapshot'] = options.figmaFile
|
|
1328
|
+
? `node tools/scripts/figma-snapshot-contracts.mjs --file ${options.figmaFile}`
|
|
1329
|
+
: 'node tools/scripts/figma-snapshot-contracts.mjs --file <YOUR_FIGMA_FILE_KEY>';
|
|
1099
1330
|
// Browser-mode Storybook tests (owner correction 2026-09-10 to ADR-0123).
|
|
1100
1331
|
// Identical to the monorepo's own root package.json script.
|
|
1101
1332
|
pkg.scripts['check:stories'] = 'nx run-many -t storybook-test --parallel=1';
|
|
1102
1333
|
// Ported CSS-discipline rules (ADR-0130). Identical to the monorepo's own
|
|
1103
1334
|
// root package.json script.
|
|
1104
1335
|
pkg.scripts['check:stylelint'] = 'nx run-many -t stylelint';
|
|
1336
|
+
// S5 — the unit test runner: jsdom-based tests for anything that is not
|
|
1337
|
+
// itself a story (a component's own logic, a service, a helper, a
|
|
1338
|
+
// form-validation rule). A sibling check, not folded into check:stories
|
|
1339
|
+
// (which proves rendering + a11y in a real browser) — this scaffold
|
|
1340
|
+
// deliberately has no check:all umbrella, so this is one more named
|
|
1341
|
+
// check, not a chain.
|
|
1342
|
+
pkg.scripts['check:unit'] = 'nx run-many -t test';
|
|
1105
1343
|
// Formatting enforcement. Deliberately this monorepo's own
|
|
1106
1344
|
// `prettier --write .` / `prettier --check .` shape, not `nx format:*` —
|
|
1107
1345
|
// measured 2026-09-12 against a real generated workspace, two distinct
|
|
@@ -1133,18 +1371,35 @@ file exports). The Desktop Bridge covers creation and inspection without a token
|
|
|
1133
1371
|
pkg.scripts['check:format'] = 'prettier --check .';
|
|
1134
1372
|
return pkg;
|
|
1135
1373
|
});
|
|
1136
|
-
// Write .mcp.json with MCP servers for selected
|
|
1374
|
+
// Write .mcp.json with MCP servers for the selected framework
|
|
1137
1375
|
const mcpServers = {
|
|
1138
1376
|
'nx-mcp': {
|
|
1139
1377
|
type: 'stdio',
|
|
1140
1378
|
command: 'npx',
|
|
1141
1379
|
args: ['nx', 'mcp'],
|
|
1142
1380
|
},
|
|
1143
|
-
|
|
1144
|
-
for (const framework of frameworks) {
|
|
1145
|
-
mcpServers[`storybook-${framework}`] = {
|
|
1381
|
+
[`storybook-${framework}`]: {
|
|
1146
1382
|
type: 'http',
|
|
1147
1383
|
url: `${SITE_URL}/storybook-${framework}/mcp`,
|
|
1384
|
+
},
|
|
1385
|
+
// Canonical component anatomy, axes, slots, transitions, motion, tokens,
|
|
1386
|
+
// events, and cross-library divergences — copied verbatim from this
|
|
1387
|
+
// monorepo's own root .mcp.json, where it is wired unconditionally.
|
|
1388
|
+
uianatomy: {
|
|
1389
|
+
type: 'http',
|
|
1390
|
+
url: 'https://uianatomy.dev/mcp',
|
|
1391
|
+
},
|
|
1392
|
+
};
|
|
1393
|
+
if (framework === 'angular') {
|
|
1394
|
+
// Angular CLI best practices, API search, and examples — copied verbatim
|
|
1395
|
+
// from this monorepo's own root .mcp.json. That file wires it
|
|
1396
|
+
// unconditionally because the monorepo itself always has an Angular app;
|
|
1397
|
+
// a single-framework workshop only needs it when Angular is the one
|
|
1398
|
+
// chosen.
|
|
1399
|
+
mcpServers['angular-cli'] = {
|
|
1400
|
+
type: 'stdio',
|
|
1401
|
+
command: 'npx',
|
|
1402
|
+
args: ['-y', '@angular/cli', 'mcp'],
|
|
1148
1403
|
};
|
|
1149
1404
|
}
|
|
1150
1405
|
if (options.figmaMcp) {
|
|
@@ -1165,14 +1420,20 @@ file exports). The Desktop Bridge covers creation and inspection without a token
|
|
|
1165
1420
|
|
|
1166
1421
|
## Apps
|
|
1167
1422
|
|
|
1168
|
-
|
|
1423
|
+
- \`${appName}\` — \`@atelier-ui/${framework}\`
|
|
1424
|
+
|
|
1425
|
+
## Versions
|
|
1426
|
+
|
|
1427
|
+
\`@atelier-ui/${framework}\` is pinned to \`${componentPackageVersion}\` for reproducibility —
|
|
1428
|
+
not \`latest\`, so the workshop behaves the same for everyone. Upgrade deliberately:
|
|
1429
|
+
\`npm install @atelier-ui/${framework}@latest\`.
|
|
1169
1430
|
|
|
1170
1431
|
## Getting started
|
|
1171
1432
|
|
|
1172
1433
|
\`\`\`bash
|
|
1173
1434
|
npm install
|
|
1174
1435
|
npx playwright install chromium # one-time — needed by npm run check:stories
|
|
1175
|
-
npx nx serve
|
|
1436
|
+
npx nx serve ${appName}
|
|
1176
1437
|
\`\`\`
|
|
1177
1438
|
|
|
1178
1439
|
## Formatting
|
|
@@ -1183,7 +1444,7 @@ Prettier-clean out of the box — \`check:format\` passes right after \`npm inst
|
|
|
1183
1444
|
|
|
1184
1445
|
## Storybook
|
|
1185
1446
|
|
|
1186
|
-
|
|
1447
|
+
- \`${appName}\` — \`npx nx storybook ${appName}\` — http://localhost:6006
|
|
1187
1448
|
|
|
1188
1449
|
Every story is also a browser-mode test — run them all headless in Chromium with
|
|
1189
1450
|
\`npm run check:stories\`.
|
|
@@ -1214,6 +1475,148 @@ ${SKILLS_ADD_COMMAND_FOR_HUMANS}
|
|
|
1214
1475
|
Claude Code MCP servers are pre-configured in \`.mcp.json\`.
|
|
1215
1476
|
Browse components at ${SITE_URL}
|
|
1216
1477
|
`);
|
|
1478
|
+
// ─── Claude Code project setup ────────────────────────────────────────────
|
|
1479
|
+
// tasks/todo.md's "S3 — the workspace is set up for Claude Code" — a later,
|
|
1480
|
+
// unrelated plan from the S1-S4 labels elsewhere in this file (those mark
|
|
1481
|
+
// this package's own now-shipped Storybook/skills slices, a different
|
|
1482
|
+
// roadmap that reused the same S-numbers first).
|
|
1483
|
+
//
|
|
1484
|
+
// Everything above this point already writes CLAUDE.md, .mcp.json, and
|
|
1485
|
+
// (installSkills, further below) four storybookjs/mcp skills under
|
|
1486
|
+
// .claude/skills/ — but nothing else under .claude/, so every session in a
|
|
1487
|
+
// generated workspace re-asked permission for `npx nx …` / `npm run …` and
|
|
1488
|
+
// had to approve each MCP server by hand. This section closes that gap:
|
|
1489
|
+
// a checked-in settings.json (nothing personal in it — see below), a
|
|
1490
|
+
// formatting hook, a /verify entry point, a read-only review subagent, and
|
|
1491
|
+
// the .gitignore line the personal settings.local.json overlay needs.
|
|
1492
|
+
console.log(`\n◇ Wiring Claude Code project setup (settings, hooks, /verify, component-review)…`);
|
|
1493
|
+
// settings.json is CHECKED IN (unlike settings.local.json below), so it
|
|
1494
|
+
// carries only shared, non-personal defaults — the same bar CLAUDE.md and
|
|
1495
|
+
// .mcp.json already meet.
|
|
1496
|
+
(0, devkit_1.writeJson)(tree, '.claude/settings.json', {
|
|
1497
|
+
$schema: 'https://json.schemastore.org/claude-code-settings.json',
|
|
1498
|
+
// Every server the preset just wrote into .mcp.json (nx-mcp,
|
|
1499
|
+
// storybook-${framework}, uianatomy, angular-cli when Angular,
|
|
1500
|
+
// figma-console when requested) connects on session start instead of
|
|
1501
|
+
// needing individual first-use approval.
|
|
1502
|
+
enableAllProjectMcpServers: true,
|
|
1503
|
+
permissions: {
|
|
1504
|
+
allow: [
|
|
1505
|
+
// The Nx CLI — `npx nx serve/storybook/build-storybook <app>`, all
|
|
1506
|
+
// named in the CLAUDE.md this preset writes above.
|
|
1507
|
+
'Bash(npx nx *)',
|
|
1508
|
+
// The eight npm scripts this preset writes to package.json
|
|
1509
|
+
// (preflight, check:contracts, figma:snapshot, check:unit,
|
|
1510
|
+
// check:stories, check:stylelint, format, check:format) — one
|
|
1511
|
+
// wildcard entry rather than eight separate ones, since this
|
|
1512
|
+
// workspace's package.json carries exactly this fixed,
|
|
1513
|
+
// generator-written script set (a workshop attendee adding a script
|
|
1514
|
+
// of their own opts into this same allowance by definition, having
|
|
1515
|
+
// already edited package.json by hand).
|
|
1516
|
+
'Bash(npm run *)',
|
|
1517
|
+
// The Storybook CLI itself — `dev`/`build` only, the two
|
|
1518
|
+
// subcommands CLAUDE.md/README actually tell an attendee to run.
|
|
1519
|
+
// Deliberately NOT a bare `Bash(npx storybook *)`: this repo's own
|
|
1520
|
+
// AGENTS.md warns against running `storybook automigrate`/`upgrade`
|
|
1521
|
+
// against the pinned 10.6.0 setup (it silently proposes bumping
|
|
1522
|
+
// addon-mcp to `latest` and rewriting every main.ts) — a blanket
|
|
1523
|
+
// wildcard here would auto-approve exactly that.
|
|
1524
|
+
'Bash(npx storybook dev *)',
|
|
1525
|
+
'Bash(npx storybook build *)',
|
|
1526
|
+
// The one-time browser install `check:stories` needs (CLAUDE.md's
|
|
1527
|
+
// "Storybook" section).
|
|
1528
|
+
'Bash(npx playwright install *)',
|
|
1529
|
+
// Read-only inspection — never something that writes to the repo or
|
|
1530
|
+
// reaches the network.
|
|
1531
|
+
'Bash(git status)',
|
|
1532
|
+
'Bash(git diff *)',
|
|
1533
|
+
'Bash(git log *)',
|
|
1534
|
+
],
|
|
1535
|
+
ask: [
|
|
1536
|
+
// `Bash(npx nx *)` above pre-approves every `nx` subcommand, `migrate`
|
|
1537
|
+
// included — the wildcard sits right after the subcommand position,
|
|
1538
|
+
// the exact placement the CLI's own settings validator warns matches
|
|
1539
|
+
// "any options inserted at that position" without a prompt. `nx
|
|
1540
|
+
// migrate` is the same hazard class as the Storybook
|
|
1541
|
+
// `automigrate`/`upgrade` commands excluded two entries above: it
|
|
1542
|
+
// rewrites package.json, fetches migration scripts from the npm
|
|
1543
|
+
// registry, and then runs them. Two entries (bare and with args)
|
|
1544
|
+
// rather than one wildcard, so a bare `npx nx migrate` (no version
|
|
1545
|
+
// argument) can't slip through a trailing-space gap in the wildcard
|
|
1546
|
+
// form. A narrower `ask` rule wins over a broader matching `allow`
|
|
1547
|
+
// entry — verified empirically against the installed 2.1.269 CLI, not
|
|
1548
|
+
// assumed: the same command matching both a `Bash(echo *)` allow rule
|
|
1549
|
+
// and an exact-match `ask` rule was routed to a permission prompt
|
|
1550
|
+
// (denied when prompts are disabled); with the `ask` rule removed the
|
|
1551
|
+
// identical command ran under the `allow` rule alone. So this narrows
|
|
1552
|
+
// just `migrate` back to asking for confirmation every time, without
|
|
1553
|
+
// blocking it outright and without touching the `npx nx *` wildcard
|
|
1554
|
+
// itself.
|
|
1555
|
+
'Bash(npx nx migrate)',
|
|
1556
|
+
'Bash(npx nx migrate *)',
|
|
1557
|
+
],
|
|
1558
|
+
},
|
|
1559
|
+
hooks: {
|
|
1560
|
+
// Formats whatever Edit/Write just touched. `matcher` is a regex over
|
|
1561
|
+
// the tool name, not a glob — `Edit|Write` is the alternation, not two
|
|
1562
|
+
// separate matchers.
|
|
1563
|
+
PostToolUse: [
|
|
1564
|
+
{
|
|
1565
|
+
matcher: 'Edit|Write',
|
|
1566
|
+
hooks: [
|
|
1567
|
+
{
|
|
1568
|
+
type: 'command',
|
|
1569
|
+
// `bash "$CLAUDE_PROJECT_DIR/…"`, not a direct executable
|
|
1570
|
+
// invocation: the Tree API that wrote this script (below)
|
|
1571
|
+
// cannot set an executable bit.
|
|
1572
|
+
command: 'bash "$CLAUDE_PROJECT_DIR/.claude/hooks/format-edited.sh"',
|
|
1573
|
+
},
|
|
1574
|
+
],
|
|
1575
|
+
},
|
|
1576
|
+
],
|
|
1577
|
+
},
|
|
1578
|
+
});
|
|
1579
|
+
// Static — the hook's formatting logic doesn't depend on which framework
|
|
1580
|
+
// was selected, so (unlike CLAUDE.md/README above) this is a files/
|
|
1581
|
+
// template rather than an assembled string.
|
|
1582
|
+
tree.write('.claude/hooks/format-edited.sh', readTemplate('claude/hooks/format-edited.sh'));
|
|
1583
|
+
// `.claude/commands/verify.md`, not a `.claude/skills/verify/SKILL.md`:
|
|
1584
|
+
// both are invocable as `/verify` (the installed 2.1.269 CLI treats a
|
|
1585
|
+
// commands/*.md file as a "slash-command skill" internally, and `--bare`'s
|
|
1586
|
+
// own help text says "Skills still resolve via /skill-name" — so either
|
|
1587
|
+
// mechanism reaches the same entry point). A command file is the
|
|
1588
|
+
// narrower, more honest fit for what this actually is: a fixed action a
|
|
1589
|
+
// person explicitly triggers, with nothing for the model to decide about
|
|
1590
|
+
// *whether* to invoke it — the thing SKILL.md's richer description-driven
|
|
1591
|
+
// auto-triggering and multi-file bundling exist for. Four fixed npm
|
|
1592
|
+
// scripts and "read the exit code" is exactly the shape commands/*.md is
|
|
1593
|
+
// for.
|
|
1594
|
+
tree.write('.claude/commands/verify.md', readTemplate('claude/commands/verify.md'));
|
|
1595
|
+
// Read-only review subagent (Read/Grep/Glob/Bash only — no Edit/Write), so
|
|
1596
|
+
// it can inspect and even run a gate for corroboration but never fix what
|
|
1597
|
+
// it finds. Static, like the hook and the command above: the checklist
|
|
1598
|
+
// (contract / stories / a11y) is the same shape regardless of framework,
|
|
1599
|
+
// and the agent discovers the one scaffolded app itself via Glob.
|
|
1600
|
+
tree.write('.claude/agents/component-review.md', readTemplate('claude/agents/component-review.md'));
|
|
1601
|
+
// The workspace's own component skill — written unconditionally (no
|
|
1602
|
+
// network, no `skills` opt-out), unlike the four storybookjs/mcp skills
|
|
1603
|
+
// installSkills fetches further below. See renderAtelierComponentSkill's
|
|
1604
|
+
// comment above for the `<app>`/`<framework>` substitution it performs, and
|
|
1605
|
+
// CLAUDE.md's "Agent Skills" section (built above) for why this one is
|
|
1606
|
+
// called out separately from those four.
|
|
1607
|
+
tree.write('.claude/skills/atelier-component/SKILL.md', renderAtelierComponentSkill(appName, framework));
|
|
1608
|
+
// .gitignore: create-nx-workspace already writes this file (before any
|
|
1609
|
+
// preset runs) with its own standard ignores (node_modules, dist, .nx, …)
|
|
1610
|
+
// — appended to, never overwritten, so a future create-nx-workspace
|
|
1611
|
+
// version's own ignores survive. `.claude/settings.local.json` is where
|
|
1612
|
+
// Claude Code records an attendee's own permission approvals; it must
|
|
1613
|
+
// never be committed, unlike the shared `.claude/settings.json` written
|
|
1614
|
+
// above.
|
|
1615
|
+
const existingGitignore = tree.exists('.gitignore')
|
|
1616
|
+
? ((_f = tree.read('.gitignore', 'utf-8')) !== null && _f !== void 0 ? _f : '')
|
|
1617
|
+
: '';
|
|
1618
|
+
const gitignoreBase = existingGitignore.replace(/\n+$/, '');
|
|
1619
|
+
tree.write('.gitignore', `${gitignoreBase}${gitignoreBase ? '\n\n' : ''}# Claude Code — personal overrides, never shared\n.claude/settings.local.json\n`);
|
|
1217
1620
|
console.log(`\n◇ Formatting files…`);
|
|
1218
1621
|
yield (0, devkit_1.formatFiles)(tree);
|
|
1219
1622
|
// Wrap installTask + removePresetTask so the (multi-second, otherwise silent)
|