@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.
Files changed (22) hide show
  1. package/CHANGELOG.md +59 -11
  2. package/package.json +1 -1
  3. package/src/generators/preset/files/claude/agents/component-review.md +53 -0
  4. package/src/generators/preset/files/claude/commands/verify.md +24 -0
  5. package/src/generators/preset/files/claude/hooks/format-edited.sh +77 -0
  6. package/src/generators/preset/files/claude/skills/atelier-component/SKILL.md +84 -0
  7. package/src/generators/preset/files/storybook/angular/atl-button.stories.ts.template +48 -1
  8. package/src/generators/preset/files/storybook/react/atl-button.stories.tsx +56 -1
  9. package/src/generators/preset/files/storybook/vue/atl-button.stories.ts.template +57 -2
  10. package/src/generators/preset/files/testing/angular/atl-button.spec.ts.template +27 -0
  11. package/src/generators/preset/files/testing/angular/test-setup.ts.template +6 -0
  12. package/src/generators/preset/files/testing/angular/vitest.unit.config.ts.template +36 -0
  13. package/src/generators/preset/files/testing/react/atl-button.spec.tsx +22 -0
  14. package/src/generators/preset/files/testing/react/test-setup.ts.template +1 -0
  15. package/src/generators/preset/files/testing/react/vitest.unit.config.ts.template +42 -0
  16. package/src/generators/preset/files/testing/vue/atl-button.spec.ts.template +25 -0
  17. package/src/generators/preset/files/testing/vue/test-setup.ts.template +1 -0
  18. package/src/generators/preset/files/testing/vue/vitest.unit.config.ts.template +50 -0
  19. package/src/generators/preset/preset.js +762 -359
  20. package/src/generators/preset/preset.js.map +1 -1
  21. package/src/generators/preset/schema.d.ts +2 -1
  22. 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 per selected framework's own
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 both the block
97
- // count and the app-relative paths it names depend on which frameworks were
98
- // selected — the same reason CLAUDE.md/README.md below are assembled from
99
- // `frameworks`, not copied verbatim.
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(frameworks) {
117
- const overrides = frameworks
118
- .map((framework) => {
119
- const appName = `workshop-${framework}`;
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 every framework's stylelint target (via
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
- // Only Vue's vitest.setup.ts.template imports this (custom jest-dom
245
- // matchers), mirroring libs/vue/.storybook/vitest.setup.ts exactly — React
246
- // and Angular's setup files don't use it.
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 frameworks = ((_a = options.frameworks) !== null && _a !== void 0 ? _a : 'angular')
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
- // shared regardless of how many frameworks are selected; the
440
- // framework-specific Vite plugin is added conditionally, after the
441
- // frameworks loop below, once every app generator has had a chance to
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
- for (const framework of frameworks) {
449
- const appName = `workshop-${framework}`;
450
- if (framework === 'angular') {
451
- console.log(`\n◇ Generating Angular workshop app…`);
452
- // NX_VERSION is the version of the nx running this generator, which is the
453
- // one create-nx-workspace installed into the workspace. Pinning to it is not
454
- // tidiness: nx ships core and plugins as one release and they reach across
455
- // the package boundary, so a plugin one patch ahead of core throws at load.
456
- // `@nx/eslint@23.1.2` calls `combineGlobPatterns` from `@nx/devkit/internal`,
457
- // which `@nx/devkit@23.1.1` does not export — measured, and it broke CI the
458
- // day 23.1.2 was published.
459
- //
460
- // This is also why `@nx/angular` is an OPTIONAL peer of this package. npm
461
- // auto-installs a required peer, and `>=22.0.0` resolves to whatever is
462
- // latest — measured: it installed @nx/angular 23.1.2 into a workspace whose
463
- // nx was 23.1.1, dragging @nx/eslint 23.1.2 with it, before this generator
464
- // ever ran. Optional peers are not auto-installed, so the first thing that
465
- // installs it is the line below, at the version that matches.
466
- yield (0, devkit_1.ensurePackage)('@nx/angular', devkit_1.NX_VERSION);
467
- const { applicationGenerator: angularAppGenerator, } = require('@nx/angular/generators');
468
- yield angularAppGenerator(tree, {
469
- name: appName,
470
- directory: appName,
471
- style: 'css',
472
- routing: true,
473
- standalone: true,
474
- ssr: false,
475
- skipTests: true,
476
- e2eTestRunner: 'none',
477
- skipFormat: true,
478
- // Without this, the generator's own linter choice defaults to
479
- // `normalizeLinterOption`'s non-interactive fallback: follow an
480
- // eslint setup already detected in the tree, or `'none'` if there is
481
- // none yet. A single-framework Angular scaffold (the common,
482
- // documented case — ADR-0084) starts from a genuinely empty tree, so
483
- // that fallback silently produced ZERO eslint.config.mjs and no
484
- // eslint devDependency at all — verified by running the real
485
- // generator against an empty workspace with this line omitted.
486
- // React and Vue below already pass this explicitly; Angular didn't,
487
- // which was the actual defect, not merely a posture gap.
488
- linter: 'eslint',
489
- });
490
- deps['@atelier-ui/angular'] = 'latest';
491
- // `flat/angular-template` above (written into workshop-angular's own
492
- // eslint.config.mjs by the application generator, confirmed by a real
493
- // run) already carries angular-eslint's `templateAccessibility` preset
494
- // — see libs/angular/eslint.config.mjs's comment for the 11 rules that
495
- // covers. This one isn't part of that preset (not `:accessibility:`
496
- // tagged in angular-eslint's README): WCAG 2.4.3, positive tabindex
497
- // fights natural DOM tab order. Same addition libs/angular's own config
498
- // makes on top of the identical preset.
499
- appendToFlatEslintConfig(tree, `${appName}/eslint.config.mjs`, `,
500
- {
501
- // Not covered by \`flat/angular-template\` above (angular-eslint's own
502
- // \`templateAccessibility\` preset only) — WCAG 2.4.3, positive tabindex
503
- // fights natural DOM tab order. Mirrors libs/angular/eslint.config.mjs's
504
- // identical addition on top of the same preset.
505
- files: ['**/*.html'],
506
- rules: {
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
- if (framework === 'react') {
513
- console.log(`\n◇ Generating React workshop app…`);
514
- // eslint-disable-next-line @typescript-eslint/no-explicit-any
515
- const { applicationGenerator: reactAppGenerator } = yield (0, devkit_1.ensurePackage)('@nx/react', devkit_1.NX_VERSION);
516
- yield reactAppGenerator(tree, {
517
- name: appName,
518
- directory: appName,
519
- style: 'css',
520
- routing: true,
521
- bundler: 'vite',
522
- linter: 'eslint',
523
- unitTestRunner: 'none',
524
- e2eTestRunner: 'none',
525
- skipFormat: true,
526
- });
527
- deps['@atelier-ui/react'] = 'latest';
528
- // Deliberately nothing added here. `flat/react` above (written into
529
- // workshop-react's own eslint.config.mjs by the application generator,
530
- // confirmed by a real run) already carries jsx-a11y's full 18-rule
531
- // active set — the same rule set libs/react/eslint.config.mjs relies on
532
- // without adding anything of its own either.
533
- }
534
- if (framework === 'vue') {
535
- console.log(`\n◇ Generating Vue workshop app…`);
536
- // eslint-disable-next-line @typescript-eslint/no-explicit-any
537
- const { applicationGenerator: vueAppGenerator } = yield (0, devkit_1.ensurePackage)('@nx/vue', devkit_1.NX_VERSION);
538
- yield vueAppGenerator(tree, {
539
- name: appName,
540
- directory: appName,
541
- style: 'css',
542
- routing: true,
543
- linter: 'eslint',
544
- unitTestRunner: 'none',
545
- e2eTestRunner: 'none',
546
- skipFormat: true,
547
- });
548
- deps['@atelier-ui/vue'] = 'latest';
549
- // @nx/vue's own application generator (confirmed by a real run against
550
- // an in-memory Tree, packed from the exact pinned version — @nx/vue is
551
- // an optional peer, not installed in this workspace) DOES match `.vue`
552
- // files and wire vue-eslint-parser + typescript-eslint's parser for
553
- // them via `parserOptions.parser` — the gap this generator's own
554
- // libs/vue/eslint.config.mjs once had (`.vue` files matched by no
555
- // config at all) does not exist in the scaffold. What IS missing,
556
- // mirrored below from libs/vue/eslint.config.mjs:
557
- //
558
- // 1. `eslint-config-prettier` after eslint-plugin-vue's rules, scoped
559
- // to `.vue` — without it, eslint-plugin-vue's layout/whitespace
560
- // rules (max-attributes-per-line, html-self-closing, …) fight
561
- // Prettier. eslint-config-prettier is already an unconditional
562
- // devDependency here (added by @nx/eslint's own root config setup,
563
- // confirmed by the same run), independent of whether `prettier`
564
- // itself is installed — the defensive add near the end of
565
- // presetGenerator below is a safety net for that, not the primary
566
- // source.
567
- // 2. `vue/no-unused-properties` — not part of any eslint-plugin-vue
568
- // preset, opted in explicitly.
569
- //
570
- // Deliberately NOT mirrored: libs/vue/eslint.config.mjs also re-scopes
571
- // eslint-plugin-vue's `flat/recommended` essential/strongly-recommended
572
- // /recommended blocks to `**/*.vue` (verified here too: those blocks
573
- // carry no `files` restriction in the installed eslint-plugin-vue, so
574
- // @nx/vue's own `...vue.configs['flat/recommended']` spread — which
575
- // this generator does not rewrite, only append to — applies Vue-only
576
- // rules to every .ts/.js file in the app as well). Doing the same here
577
- // would mean rewriting a block the application generator wrote, not
578
- // appending to it, which is the one thing this helper is built to
579
- // avoid; the practical exposure in a fresh single-app scaffold is low
580
- // (no .spec.ts/.stories.ts test-double files exist yet at this point in
581
- // the generator, and @nx/vue already turns off the rule most likely to
582
- // misfire on plain .ts — vue/multi-word-component-names — project-wide
583
- // on its own). Recorded here rather than silently left unmentioned.
584
- appendToFlatEslintConfig(tree, `${appName}/eslint.config.mjs`, `,
585
- {
586
- // eslint-plugin-vue's flat/recommended (spread above by @nx/vue's own
587
- // application generator) ships layout/whitespace rules that fight
588
- // Prettier — same gap libs/vue/eslint.config.mjs closes.
589
- files: ['**/*.vue'],
590
- rules: eslintConfigPrettier.rules,
591
- },
592
- {
593
- // Not part of any eslint-plugin-vue preset — opted in explicitly, same as
594
- // libs/vue/eslint.config.mjs: catches a declared prop nothing in the
595
- // component reads.
596
- files: ['**/*.vue'],
597
- rules: {
598
- 'vue/no-unused-properties': ['error', { groups: ['props'] }],
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
- // Copy design tokens into the scaffolded app so attendees can edit them
604
- // directly. They're not imported from the @atelier-ui/<fw> npm package
605
- // because (a) those published packages don't ship tokens.css, and (b) a
606
- // workshop attendee editing colors in node_modules is a bad experience.
607
- tree.write(`${appName}/src/styles/tokens.css`, readTemplate('styles/tokens.css'));
608
- // Prepend the tokens import to the app's global stylesheet
609
- const stylesPath = `${appName}/src/styles.css`;
610
- const existing = tree.exists(stylesPath)
611
- ? ((_c = tree.read(stylesPath, 'utf-8')) !== null && _c !== void 0 ? _c : '')
612
- : '';
613
- tree.write(stylesPath, `@import './styles/tokens.css';\n\n${existing}`);
614
- // Storybook config: mirrors libs/{angular,react,vue}/.storybook/main.ts
615
- // minus staticDirs, the BUILD_STORYBOOK viteFinal block (hosted-path-only),
616
- // and @storybook/addon-designs (no Figma handoff doc to link from here).
617
- // @storybook/addon-vitest DOES ship (owner correction 2026-09-10 to
618
- // ADR-0123's original "no test runner" call).
619
- tree.write(`${appName}/.storybook/main.ts`, readTemplate(storybookTemplateName(framework, 'main.ts')));
620
- tree.write(`${appName}/.storybook/preview.${storybookOutputExt(framework)}`, readTemplate(storybookTemplateName(framework, 'preview')));
621
- if (framework === 'angular') {
622
- // The only framework that needs its own Storybook-scoped tsconfig — see
623
- // libs/angular/.storybook/tsconfig.json, which this mirrors against the
624
- // tsconfig.json the Angular application generator actually writes (both
625
- // shapes verified: `files: []`, `include: []`, `references` to app/spec).
626
- tree.write(`${appName}/.storybook/tsconfig.json`, readTemplate('storybook/angular/tsconfig.json'));
627
- }
628
- // One example story per app: small on purpose — it exists so Storybook
629
- // isn't empty and the attendee has a working pattern to copy, not as a
630
- // second component showcase.
631
- tree.write(`${appName}/src/atl-button.stories.${storybookOutputExt(framework)}`, readTemplate(storybookTemplateName(framework, 'atl-button.stories')));
632
- // Browser-mode Storybook tests (owner correction 2026-09-10 to ADR-0123 —
633
- // storybook-test / check:stories ship with the scaffold after all).
634
- // `vitest.config.ts` is always plain `.ts`, never `.tsx` — see
635
- // storybookTemplateName()'s comment. The literal filename matters:
636
- // @storybook/addon-vitest's `test-run` tool walks up from a story's
637
- // .storybook directory looking for the nearest vitest/vite config by
638
- // this standard name.
639
- tree.write(`${appName}/vitest.config.ts`, readTemplate(storybookTemplateName(framework, 'vitest.config')));
640
- tree.write(`${appName}/.storybook/vitest.setup.ts`, readTemplate(storybookTemplateName(framework, 'vitest.setup')));
641
- // The application generator (@nx/{angular,react,vue}:application, above)
642
- // guarantees `${appName}/project.json` exists at this point — updateJson
643
- // reads it first and throws `Cannot find ${path}` if it doesn't, which is
644
- // exactly the loud failure we want: a workshop app with a Storybook config
645
- // directory but no way to start it is worse than a generator that stops.
646
- const storybookPort = 6006 + frameworks.indexOf(framework);
647
- (0, devkit_1.updateJson)(tree, `${appName}/project.json`, (config) => {
648
- var _a;
649
- (_a = config.targets) !== null && _a !== void 0 ? _a : (config.targets = {});
650
- config.targets['storybook'] = {
651
- executor: 'nx:run-commands',
652
- options: {
653
- command: `npx storybook dev --config-dir ${appName}/.storybook --port ${storybookPort}`,
654
- },
655
- };
656
- config.targets['build-storybook'] = {
657
- executor: 'nx:run-commands',
658
- outputs: [`{workspaceRoot}/dist/storybook/${appName}`],
659
- options: {
660
- command: `npx storybook build --config-dir ${appName}/.storybook --output-dir dist/storybook/${appName}`,
661
- },
662
- };
663
- // Mirrors libs/{angular,react,vue}/project.json's own "storybook-test"
664
- // target exactly, modulo the config filename (vitest.config.ts here,
665
- // vitest.storybook.config.ts there — see storybookTemplateName()'s
666
- // comment on why the scaffold uses the standard name instead).
667
- config.targets['storybook-test'] = {
668
- executor: 'nx:run-commands',
669
- options: {
670
- command: 'npx vitest run --config vitest.config.ts',
671
- cwd: appName,
672
- },
673
- };
674
- // Ported CSS-discipline rules (ADR-0130): a sibling target, not folded
675
- // into `lint` — same reasoning as this repo's own libs/{fw}/project.json
676
- // (lint is inferred by @nx/eslint/plugin per project; overriding it to
677
- // also shell out would re-implement what inference gives for free).
678
- // --ignore-pattern excludes this app's own tokens.css from the run: it
679
- // is a token DEFINITION file, the one place these rules' raw literals
680
- // are supposed to live, not a file that reads/consumes tokens.
681
- config.targets['stylelint'] = {
682
- executor: 'nx:run-commands',
683
- options: {
684
- command: `stylelint '${appName}/src/**/*.css' --ignore-pattern '${appName}/src/styles/tokens.css' --config stylelint.config.mjs`,
685
- },
686
- };
687
- return config;
688
- });
689
- storybookDevDeps[STORYBOOK_FRAMEWORK_PACKAGE[framework]] =
690
- STORYBOOK_VERSION;
691
- // @storybook/react-vite and @storybook/vue3-vite each carry their
692
- // non-vite renderer counterpart as a plain (non-peer) `dependency`, not
693
- // something npm/pnpm is told the app needs directly — but the story and
694
- // preview templates import straight from '@storybook/react' /
695
- // '@storybook/vue3' for the `Meta`/`StoryObj`/`Preview` types. That
696
- // resolves today only because npm hoists it; pnpm's stricter, non-hoisted
697
- // layout would leave the import unresolved. Angular has no matching case:
698
- // '@storybook/angular-vite' has no such counterpart to hoist, and the
699
- // angular templates import their types from '@storybook/angular-vite'
700
- // itself (see files/storybook/angular/*.template) — adding
701
- // '@storybook/angular' back here would reintroduce exactly the ERESOLVE
702
- // this generator now avoids (its peer on @angular-devkit/build-angular is
703
- // not satisfiable by a freshly scaffolded Angular 22 app).
704
- if (framework === 'react') {
705
- storybookDevDeps['@storybook/react'] = STORYBOOK_VERSION;
706
- }
707
- if (framework === 'vue') {
708
- storybookDevDeps['@storybook/vue3'] = STORYBOOK_VERSION;
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(frameworks));
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 every project that
740
- // reads them (the per-app `stylelint` targets added in the loop above) —
741
- // exactly the cache trap ADR-0130 proved twice in this repo's own
742
- // nx.json. Mirrors this repo's own targetDefaults.stylelint, minus
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 generators above are guaranteed to
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
- ...frameworks.map((framework) => `{workspaceRoot}/workshop-${framework}/src/styles/tokens.css`),
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
- // Ships once, scoped to the FIRST selected framework — a contracts.config.json
767
- // names exactly one framework, the same "the workshop uses one framework"
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(`${primaryApp}/src/contracts/types.ts`, readTemplate('contracts/types.ts.template'));
779
- tree.write(`${primaryApp}/src/contracts/README.md`, readTemplate('contracts/README.md'));
780
- tree.write(`${primaryApp}/src/contracts/button.contract.ts`, readTemplate('contracts/button.contract.ts.template'));
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: primaryFramework,
792
- contracts: `${primaryApp}/src/contracts`,
793
- stories: [`${primaryApp}/src`],
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
- const frameworkSections = frameworks
799
- .map((f) => {
800
- if (f === 'angular') {
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
- if (f === 'react') {
808
- return `### React (\`@atelier-ui/react\`)
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
- if (f === 'vue') {
815
- return `### Vue (\`@atelier-ui/vue\`)
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
- return '';
822
- })
823
- .join('\n\n');
824
- const mcpSection = frameworks
825
- .map((f) => `### \`storybook-${f}\` MCP
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
- .join('\n\n');
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
- ${frameworkSections}
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.375rem), --ui-radius-md (0.5rem), --ui-radius-lg (0.75rem)
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
- ${frameworks.map((f) => `- \`workshop-${f}\` — run with \`npx nx serve workshop-${f}\``).join('\n')}
1052
+ - \`${appName}\` — run with \`npx nx serve ${appName}\`
882
1053
 
883
1054
  ## Storybook
884
1055
 
885
- Every app has its own local Storybook, started per framework:
1056
+ The app has its own local Storybook:
886
1057
 
887
- ${frameworks.map((f, i) => `- \`workshop-${f}\` — \`npx nx storybook workshop-${f}\` — http://localhost:${6006 + i}`).join('\n')}
1058
+ - \`${appName}\` — \`npx nx storybook ${appName}\` — http://localhost:6006
888
1059
 
889
- Build a static Storybook (CI, hosting) with \`npx nx build-storybook workshop-<fw>\`.
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 (\`${primaryApp}/src/contracts/<name>.contract.ts\`) is the one hand-authored
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: edit the \`--file\` placeholder in \`package.json\`'s \`figma:snapshot\` script to
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/${primaryFramework}\` — the example \`AtlButton\`
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 every
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
- // each selected framework needs its own Vite plugin for the vitest browser
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 (frameworks.includes('react') && !existingDeps['@vitejs/plugin-react']) {
1245
+ if (framework === 'react' && !existingDeps['@vitejs/plugin-react']) {
1043
1246
  viteFrameworkDevDeps['@vitejs/plugin-react'] = VITE_PLUGIN_REACT_VERSION;
1044
1247
  }
1045
- if (frameworks.includes('vue') && !existingDeps['@vitejs/plugin-vue']) {
1248
+ if (framework === 'vue' && !existingDeps['@vitejs/plugin-vue']) {
1046
1249
  viteFrameworkDevDeps['@vitejs/plugin-vue'] = VITE_PLUGIN_VUE_VERSION;
1047
1250
  }
1048
- if (frameworks.includes('angular') &&
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
- if (frameworks.includes('vue') &&
1054
- !existingDeps['@testing-library/jest-dom']) {
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 (frameworks.includes('vue') && !existingDeps['eslint-config-prettier']) {
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
- // stylelint + prettier (devDependencies, exact pins — see the *_VERSION
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` ships with a literal
1091
- // placeholder rather than the Atelier file key — this preset has no
1092
- // "which Figma file is yours" schema option (only the boolean
1093
- // `figmaMcp`), and QMnDD8uZQPldPrlCwZZ58T is THIS repo's own file, not
1094
- // the attendee's. CLAUDE.md's "The contract loop" section spells out how
1095
- // to fill it in.
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
- 'node tools/scripts/figma-snapshot-contracts.mjs --file <YOUR_FIGMA_FILE_KEY>';
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 frameworks
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
- ${frameworks.map((f) => `- \`workshop-${f}\` — \`@atelier-ui/${f}\``).join('\n')}
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 workshop-${frameworks[0]}
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
- ${frameworks.map((f, i) => `- \`workshop-${f}\` — \`npx nx storybook workshop-${f}\` — http://localhost:${6006 + i}`).join('\n')}
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)