@atelier-ui/create-workspace 0.2.42 → 0.2.44

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 (52) hide show
  1. package/CHANGELOG.md +50 -4
  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/contracts/README.md +29 -0
  8. package/src/generators/preset/files/contracts/button.contract.ts.template +20 -0
  9. package/src/generators/preset/files/contracts/types.ts.template +55 -0
  10. package/src/generators/preset/files/figma/snapshot.json +164 -0
  11. package/src/generators/preset/files/storybook/angular/atl-button.stories.ts.template +85 -0
  12. package/src/generators/preset/files/storybook/angular/main.ts.template +39 -0
  13. package/src/generators/preset/files/storybook/angular/preview.ts.template +30 -0
  14. package/src/generators/preset/files/storybook/angular/tsconfig.json +16 -0
  15. package/src/generators/preset/files/storybook/angular/vitest.config.ts.template +40 -0
  16. package/src/generators/preset/files/storybook/angular/vitest.setup.ts.template +14 -0
  17. package/src/generators/preset/files/storybook/react/atl-button.stories.tsx +86 -0
  18. package/src/generators/preset/files/storybook/react/main.ts.template +37 -0
  19. package/src/generators/preset/files/storybook/react/preview.tsx +29 -0
  20. package/src/generators/preset/files/storybook/react/vitest.config.ts.template +32 -0
  21. package/src/generators/preset/files/storybook/react/vitest.setup.ts.template +8 -0
  22. package/src/generators/preset/files/storybook/vue/atl-button.stories.ts.template +89 -0
  23. package/src/generators/preset/files/storybook/vue/main.ts.template +38 -0
  24. package/src/generators/preset/files/storybook/vue/preview.ts.template +29 -0
  25. package/src/generators/preset/files/storybook/vue/vitest.config.ts.template +32 -0
  26. package/src/generators/preset/files/storybook/vue/vitest.setup.ts.template +9 -0
  27. package/src/generators/preset/files/styles/tokens.css +59 -43
  28. package/src/generators/preset/files/testing/angular/atl-button.spec.ts.template +27 -0
  29. package/src/generators/preset/files/testing/angular/test-setup.ts.template +6 -0
  30. package/src/generators/preset/files/testing/angular/vitest.unit.config.ts.template +36 -0
  31. package/src/generators/preset/files/testing/react/atl-button.spec.tsx +22 -0
  32. package/src/generators/preset/files/testing/react/test-setup.ts.template +1 -0
  33. package/src/generators/preset/files/testing/react/vitest.unit.config.ts.template +21 -0
  34. package/src/generators/preset/files/testing/vue/atl-button.spec.ts.template +25 -0
  35. package/src/generators/preset/files/testing/vue/test-setup.ts.template +1 -0
  36. package/src/generators/preset/files/testing/vue/vitest.unit.config.ts.template +50 -0
  37. package/src/generators/preset/files/tools/scripts/check-contracts.mjs +1644 -0
  38. package/src/generators/preset/files/tools/scripts/figma-snapshot-contracts.mjs +370 -0
  39. package/src/generators/preset/files/tools/scripts/lib/docgen.mjs +573 -0
  40. package/src/generators/preset/files/tools/scripts/lib/ts-eval.js +126 -0
  41. package/src/generators/preset/files/tools/scripts/preflight.mjs +163 -31
  42. package/src/generators/preset/files/tools/stylelint-rules/index.js +21 -0
  43. package/src/generators/preset/files/tools/stylelint-rules/no-primitive-token.js +362 -0
  44. package/src/generators/preset/files/tools/stylelint-rules/no-raw-color-literal.js +154 -0
  45. package/src/generators/preset/files/tools/stylelint-rules/no-token-bypass.js +497 -0
  46. package/src/generators/preset/files/tools/stylelint-rules/no-undeclared-token.js +122 -0
  47. package/src/generators/preset/files/tools/stylelint-rules/utils.js +71 -0
  48. package/src/generators/preset/preset.d.ts +1 -0
  49. package/src/generators/preset/preset.js +1463 -110
  50. package/src/generators/preset/preset.js.map +1 -1
  51. package/src/generators/preset/schema.d.ts +3 -1
  52. package/src/generators/preset/schema.json +23 -3
@@ -1,134 +1,999 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.installSkills = installSkills;
3
4
  exports.presetGenerator = presetGenerator;
4
5
  const tslib_1 = require("tslib");
5
6
  const devkit_1 = require("@nx/devkit");
7
+ const node_child_process_1 = require("node:child_process");
6
8
  const node_fs_1 = require("node:fs");
7
9
  const node_path_1 = require("node:path");
8
10
  function readTemplate(relativePath) {
9
11
  return (0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, 'files', relativePath), 'utf-8');
10
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
+ }
11
35
  const SITE_URL = 'https://atelier.pieper.io';
36
+ // Pinned to the exact version this monorepo runs (root package.json
37
+ // devDependencies) — the workshop needs the same Storybook every attendee's
38
+ // neighbour has, not whatever `latest` resolves to on the day of the cohort.
39
+ const STORYBOOK_VERSION = '10.6.0';
40
+ // Storybook's `framework.name` package per scaffolded app, and the exact
41
+ // devDependency set each one needs beyond the common addons below.
42
+ const STORYBOOK_FRAMEWORK_PACKAGE = {
43
+ angular: '@storybook/angular-vite',
44
+ react: '@storybook/react-vite',
45
+ vue: '@storybook/vue3-vite',
46
+ };
47
+ // Templates that contain literal TypeScript source (not JSX) are suffixed
48
+ // `.template` in files/storybook/<fw>/ so that neither tsc nor the asset-copy
49
+ // glob touches them before this generator ships: tsconfig.lib.json's
50
+ // `include: ["src/**/*.ts"]` would otherwise compile them as part of this
51
+ // package's own build, and project.json's build `assets` glob
52
+ // (`**/!(*.ts)`) explicitly excludes `.ts` files from the verbatim asset
53
+ // copy — between the two, a template literally named `main.ts` would be
54
+ // transpiled away and never reach dist/ under a name this generator's
55
+ // `readTemplate()` can find at runtime. `.tsx` files (no literal `.ts`
56
+ // suffix) hit neither rule and are stored under their real name. Verified the
57
+ // hard way once already: `contracts/types.ts` and `contracts/button.contract.ts`
58
+ // (no `.template` suffix) threw `ENOENT` from inside a packed npm tarball —
59
+ // see sync-preflight.mjs's comment on those two entries.
60
+ function storybookTemplateName(framework, base) {
61
+ if (base === 'main.ts')
62
+ return `storybook/${framework}/main.ts.template`;
63
+ // vitest.config.ts and .storybook/vitest.setup.ts are always written out
64
+ // as plain `.ts` regardless of framework — unlike main.ts/preview/the
65
+ // example story, react does NOT get a `.tsx` variant for these (neither
66
+ // file contains JSX), so both need the `.template` dodge on every framework.
67
+ if (base === 'vitest.config' || base === 'vitest.setup')
68
+ return `storybook/${framework}/${base}.ts.template`;
69
+ const ext = framework === 'react' ? 'tsx' : 'ts.template';
70
+ return `storybook/${framework}/${base}.${ext}`;
71
+ }
72
+ // The destination filename written into the scaffolded workspace — a plain,
73
+ // correct `.ts`/`.tsx` extension regardless of the source template's name.
74
+ function storybookOutputExt(framework) {
75
+ return framework === 'react' ? 'tsx' : 'ts';
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
+ }
119
+ // Splices `block` (one or more object literals, as raw source text, starting
120
+ // with a leading comma) into the flat ESLint config a framework's own
121
+ // application generator (@nx/angular, @nx/react, @nx/vue — all invoked with
122
+ // `linter: 'eslint'` below) already wrote at `path`, immediately before the
123
+ // file's closing `];`, and prepends any `imports` the block needs.
124
+ //
125
+ // This is text surgery, not an AST rewrite, and that is deliberate: the
126
+ // generated file is Nx's, not ours, and a future Nx version reshaping it
127
+ // should not silently swallow this addition the way editing its AST in place
128
+ // might. `@nx/eslint`'s own flat-config codegen (confirmed by actually
129
+ // running the three application generators against an in-memory Tree —
130
+ // verified for this Nx version, not assumed) always emits a single
131
+ // `export default [ ... ];` as the file's last statement, so anchoring on the
132
+ // final `];` is stable across the Nx versions this generator supports.
133
+ // `formatFiles(tree)` at the end of presetGenerator reformats whatever this
134
+ // produces, so exact indentation here doesn't matter.
135
+ //
136
+ // Throws loudly if the file is missing or doesn't have that shape, rather
137
+ // than silently skipping the addition — same reasoning as the storybook
138
+ // targets' `updateJson` calls below: a workshop app whose ESLint config
139
+ // silently didn't get the framework's accessibility rule is worse than a
140
+ // generator that stops.
141
+ function appendToFlatEslintConfig(tree, path, block, imports = []) {
142
+ const content = tree.read(path, 'utf-8');
143
+ if (content === null) {
144
+ throw new Error(`Cannot find ${path} — expected the framework application generator to have already written a flat ESLint config there (this generator always passes linter: 'eslint').`);
145
+ }
146
+ const closeIndex = content.lastIndexOf('];');
147
+ if (closeIndex === -1) {
148
+ throw new Error(`${path} does not end with a flat-config array ("];") — the framework application generator's ESLint output may have changed shape; appendToFlatEslintConfig needs updating.`);
149
+ }
150
+ const importPrefix = imports.length ? `${imports.join('\n')}\n` : '';
151
+ tree.write(path, importPrefix +
152
+ content.slice(0, closeIndex) +
153
+ block +
154
+ content.slice(closeIndex));
155
+ }
156
+ // Ported CSS-discipline stylelint rules (ADR-0130): assembles the scaffold's
157
+ // own stylelint.config.mjs — the one override block for the scaffold's single
158
+ // `workshop-<fw>/src` tree, mirroring this repo's own stylelint.config.mjs
159
+ // (which does the same per libs/{angular,react,vue}). Built as a template
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.
164
+ //
165
+ // Only three of the four shipped rules are wired: `atelier/no-primitive-token`
166
+ // polices reaching past the semantic token tier into a primitive ramp (e.g.
167
+ // `--ui-color-teal-500`), which presupposes knowing that ramp exists — this
168
+ // workspace's own tokens.css has no such tiering to police. The file still
169
+ // ships (see the loop that writes tools/stylelint-rules/* below) because
170
+ // index.js requires all four rule files unconditionally, and a
171
+ // byte-identical index.js (kept in sync with the canonical copy by
172
+ // sync-preflight.mjs) is worth more than a scaffold-specific fork that drops
173
+ // one require().
174
+ //
175
+ // Neither wired rule is given `componentRoot` or `allowlistsFile`: this
176
+ // workspace ships no allowlists.js, so every exemption map defaults to empty
177
+ // and the staleness scan those two options drive never runs (documented in
178
+ // each rule's own header in tools/stylelint-rules/) — passing them here would
179
+ // configure a scan that can never find anything.
180
+ function buildStylelintConfig(framework) {
181
+ const appName = `workshop-${framework}`;
182
+ const tokensCss = `${appName}/src/styles/tokens.css`;
183
+ const overrides = ` {
184
+ files: ['${appName}/src/**/*.css'],
185
+ rules: {
186
+ 'atelier/no-raw-color-literal': true,
187
+ 'atelier/no-undeclared-token': [true, { tokenFiles: ['${tokensCss}'] }],
188
+ 'atelier/no-token-bypass': [true, { tokenFile: '${tokensCss}' }],
189
+ },
190
+ },`;
191
+ return `// This workspace's own CSS-discipline rules only ('tools/stylelint-rules/')
192
+ // — ported from the parent Atelier monorepo (ADR-0130). No
193
+ // stylelint-config-standard or any other base config: stylelint 16+ ships no
194
+ // built-in formatting/stylistic rules at all (split out to the separate,
195
+ // opt-in @stylistic plugin, which this workspace does not install), so there
196
+ // is nothing here that could fight Prettier.
197
+ //
198
+ // Three of the four shipped rules are wired below. atelier/no-primitive-token
199
+ // is NOT — it polices reaching past the semantic token tier into a primitive
200
+ // ramp, which presupposes knowing that ramp exists, and this workspace's own
201
+ // tokens.css has no such tiering. The three below catch what an attendee does
202
+ // by writing ordinary component CSS on day one: a raw color literal, a
203
+ // typo'd or undeclared --ui-* token, and a literal that duplicates a token's
204
+ // value instead of binding to it.
205
+ //
206
+ // tokens.css itself is EXCLUDED from the app's stylelint target (via
207
+ // --ignore-pattern in the app's project.json, not an exemption here): it is
208
+ // the one file that legitimately spells out raw color/dimension literals as
209
+ // token DEFINITIONS — the opposite of what these rules police in a file that
210
+ // CONSUMES tokens.
211
+ import atelier from './tools/stylelint-rules/index.js';
212
+
213
+ export default {
214
+ plugins: [atelier],
215
+ rules: {},
216
+ overrides: [
217
+ ${overrides}
218
+ ],
219
+ };
220
+ `;
221
+ }
222
+ // The four storybookjs/mcp skills this generator installs post-scaffold (S2).
223
+ // Pinned the same way ADR-0110 pins figma-console-mcp: a skill install is a
224
+ // remote pull of skill *text*, and an un-pinned CLI could silently change what
225
+ // gets written into an attendee's .claude/skills/ between one workshop and the
226
+ // next.
227
+ const SKILLS_CLI_VERSION = '1.5.25';
228
+ const SKILLS_ADD_ARGV = [
229
+ '-y',
230
+ `skills@${SKILLS_CLI_VERSION}`,
231
+ 'add',
232
+ 'storybookjs/mcp',
233
+ '--skill',
234
+ '*',
235
+ '--agent',
236
+ 'claude-code',
237
+ '--yes',
238
+ '--copy',
239
+ ];
240
+ // Kept in sync with SKILLS_ADD_ARGV by hand — this is the string shown to a
241
+ // human (the failure warning, CLAUDE.md, README.md), quoted the way a real
242
+ // shell needs it. It is unrelated to how SKILLS_ADD_ARGV itself reaches the
243
+ // child process below: on POSIX it goes straight to `spawn` as an argv array
244
+ // with no shell involved (so nothing there needs quoting at all), and on
245
+ // Windows it is re-quoted for cmd.exe by `quoteForCmdExe` — this constant
246
+ // exists only for the text a person reads and re-types by hand.
247
+ const SKILLS_ADD_COMMAND_FOR_HUMANS = `npx -y skills@${SKILLS_CLI_VERSION} add storybookjs/mcp --skill "*" --agent claude-code --yes --copy`;
248
+ // Bounds the CLI's own git clone (it reads this env var itself) so a bad
249
+ // conference network fails fast with a clear message instead of hanging.
250
+ const SKILLS_CLONE_TIMEOUT_MS = 60000;
251
+ // The contract loop (ADR-0121 S4): figma-snapshot-contracts.mjs imports the
252
+ // MCP SDK directly (the same client figma-snapshot.mjs uses), pinned to the
253
+ // exact version this monorepo runs (root package.json devDependencies) so
254
+ // the scaffold's copy behaves the same as the canonical script.
255
+ const MCP_SDK_VERSION = '^1.29.0';
256
+ // ts-eval.js (shared by check-contracts.mjs and figma-snapshot-contracts.mjs)
257
+ // needs `typescript` at runtime. Every framework's Nx application generator
258
+ // already adds it, so this is a safety net, not the primary source — see the
259
+ // conditional add near the end of presetGenerator, which only includes this
260
+ // constant in the devDependencies write when `typescript` isn't already
261
+ // present.
262
+ const TYPESCRIPT_VERSION = '6.0.3';
263
+ // Ported CSS-discipline stylelint rules (ADR-0130): pinned the same way
264
+ // STORYBOOK_VERSION above is — the exact version this monorepo actually
265
+ // runs, not the caret range root package.json declares (`^17.15.0`); the
266
+ // resolved, installed version (package-lock.json) is 17.15.0, and that's
267
+ // the one every attendee's neighbour should get too. No `postcss-html`
268
+ // devDependency: that's only needed to lint `.astro` files, and the
269
+ // scaffold has none.
270
+ const STYLELINT_VERSION = '17.15.0';
271
+ // Formatting enforcement (measured 2026-09-12 against a real workspace
272
+ // generated through this preset via a local verdaccio, per
273
+ // tasks/todo.md — not assumed from Nx's docs): a freshly `create-nx-workspace`'d
274
+ // tree declares no `prettier` devDependency and writes no `.prettierrc` — this
275
+ // monorepo's own ADR-0127 baseline ("configured and never enforced") does not
276
+ // even get as far as "configured" here, it has to be added from scratch. Root
277
+ // package.json's own declaration (`~3.9.6`) is already a tight tilde, not the
278
+ // wide caret range some of this file's other *_VERSION constants have to
279
+ // narrow — package-lock.json resolves it to the same 3.9.6, so there's no
280
+ // "declared vs. actually resolved" gap to reconcile.
281
+ const PRETTIER_VERSION = '~3.9.6';
282
+ // Browser-mode Storybook tests (owner correction, 2026-09-10, to ADR-0123's
283
+ // "no test runner" decision — see the dated correction on that record).
284
+ // Every scaffolded app gets its own vitest.config.ts + storybook-test target,
285
+ // mirroring libs/{angular,react,vue}/vitest.storybook.config.ts. Versions are
286
+ // copied verbatim from the monorepo's own root package.json — most are exact
287
+ // pins there; `vitest` and `@vitest/browser-playwright` are themselves caret
288
+ // ranges in root package.json, so they stay caret ranges here too, rather
289
+ // than inventing an exact pin root itself doesn't have.
290
+ const VITEST_VERSION = '^4.0.8';
291
+ const VITEST_BROWSER_PLAYWRIGHT_VERSION = '^4.1.0';
292
+ // @vitest/browser-playwright declares a PEER (not transitive) dependency on
293
+ // `playwright` itself (peerDependencies: { playwright: "*" }). Root
294
+ // package.json has no bare `playwright` entry — only `@playwright/test`
295
+ // (^1.36.0), whose own dependency on `playwright` satisfies the peer there
296
+ // via monorepo-wide hoisting. A standalone scaffold gets no such hoist, so
297
+ // the bare peer is pinned here directly, at the same range @playwright/test
298
+ // itself uses — there is no "exact version root package.json has" for the
299
+ // bare package to copy, since root never names it.
300
+ const PLAYWRIGHT_VERSION = '^1.36.0';
301
+ const VITE_PLUGIN_REACT_VERSION = '6.1.1';
302
+ const VITE_PLUGIN_VUE_VERSION = '^6.0.5';
303
+ const ANALOGJS_VITE_PLUGIN_ANGULAR_VERSION = '2.7.1';
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.
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';
323
+ // The Vue eslint.config.mjs addition above (see the appendToFlatEslintConfig
324
+ // call in the vue branch) imports this directly. @nx/eslint's own root config
325
+ // setup already adds it unconditionally regardless of framework or of
326
+ // whether `prettier` itself is installed (confirmed by running all three
327
+ // application generators against an empty Tree), so the conditional add near
328
+ // the end of presetGenerator below is a safety net, not the primary source —
329
+ // same reasoning as TYPESCRIPT_VERSION above. Version matches what that run
330
+ // installed.
331
+ const ESLINT_CONFIG_PRETTIER_VERSION = '^10.0.0';
332
+ // Hard kill for the whole child process — a backstop above the CLI's own
333
+ // clone timeout, covering the install/copy phase after the clone too.
334
+ const SKILLS_INSTALL_TIMEOUT_MS = 120000;
335
+ // `execFile` (and its promisified form) never actually spawns a shell — it
336
+ // forwards only a fixed allowlist of options to the underlying `spawn` call,
337
+ // and `stdio` is not on that list. Measured: `promisify(execFile)(...,
338
+ // { stdio: 'inherit' })` still resolves with the child's stdout captured in
339
+ // `result.stdout`, and nothing is written to this process's own stdout in
340
+ // the meantime — the attendee would see a silent multi-minute pause (the
341
+ // CLI's own clone can take that long over a bad conference network) and then
342
+ // either a success or failure with no progress in between. `spawn` (used
343
+ // below) genuinely honours `stdio: 'inherit'`, wiring the child's streams to
344
+ // this process's own so the CLI's progress reaches the terminal live.
345
+ //
346
+ // `process.platform` is read live inside `runSkillsAddCommand` (rather than
347
+ // cached in a module-level constant) so a test can stub it per-case without
348
+ // having to reset and re-import the module.
349
+ // `spawn`'s `shell: true` mode does not escape an `args` array for you — it
350
+ // just space-joins `[command, ...args]` before handing the result to the
351
+ // shell (this is exactly what Node's DEP0190 deprecation warns about:
352
+ // "Passing args to a child process with shell option true ... arguments are
353
+ // not escaped, only concatenated"). So this is not a general-purpose Windows
354
+ // command-line escaper — every token in SKILLS_ADD_ARGV is a fixed literal
355
+ // (a package specifier, a flag name, or the bare `*`) with no embedded quotes
356
+ // of its own, and wrapping a token in quotes whenever it contains whitespace
357
+ // or a metacharacter is sufficient for that fixed, known argv. `*`/`?` are
358
+ // included even though cmd.exe itself does not glob-expand them (unlike a
359
+ // POSIX shell, wildcard expansion on Windows is the invoked program's own
360
+ // job, not the shell's) — quoting them anyway is the belt-and-suspenders
361
+ // match for the POSIX side's guarantee, so `--skill "*"` reaches npx as a
362
+ // literal one-character string on both platforms by construction, not by
363
+ // relying on cmd.exe's particular behaviour.
364
+ function quoteForCmdExe(token) {
365
+ return /[\s"^&|<>()*?]/.test(token)
366
+ ? `"${token.replace(/"/g, '\\"')}"`
367
+ : token;
368
+ }
369
+ // Runs `npx <SKILLS_ADD_ARGV...>` with the child's stdio wired to this
370
+ // process's own, resolving on a clean exit and rejecting with a descriptive
371
+ // error otherwise (non-zero exit, the install timeout killing the child, or
372
+ // the child never starting at all) — installSkills' catch block below turns
373
+ // any of those into the same non-fatal warning.
374
+ function runSkillsAddCommand(cwd, env) {
375
+ return new Promise((resolve, reject) => {
376
+ const isWindows = process.platform === 'win32';
377
+ let settled = false;
378
+ // Set only by the Windows timeout backstop below — the `exit` handler
379
+ // needs it because a `taskkill /F` termination is not guaranteed to show
380
+ // up as a `signal` on the `exit` event the way POSIX's SIGTERM does.
381
+ let timedOut = false;
382
+ const settle = (fn) => {
383
+ if (settled)
384
+ return;
385
+ settled = true;
386
+ fn();
387
+ };
388
+ const spawnOptions = Object.assign({ cwd,
389
+ env, stdio: 'inherit' }, (isWindows
390
+ ? {}
391
+ : { timeout: SKILLS_INSTALL_TIMEOUT_MS, killSignal: 'SIGTERM' }));
392
+ const child = isWindows
393
+ ? // Windows can only execute a `.cmd` file (npx resolves to npx.cmd
394
+ // there) through cmd.exe, and Node no longer shells out to run one
395
+ // implicitly — a hardening in the Node 18.20 / 20.12 lines now
396
+ // requires the caller to opt in with `shell: true`, or the spawn
397
+ // never starts at all. That is exactly the platform `--copy` above
398
+ // was chosen for, so this path has to work. `shell: true` (rather
399
+ // than hardcoding the `npx.cmd` binary name) is enough on its own:
400
+ // once cmd.exe is in the loop it resolves the bare `npx` via its own
401
+ // PATHEXT lookup, the same as typing `npx` at a Windows prompt.
402
+ // Because `shell: true` does not escape an args array (see
403
+ // quoteForCmdExe above), the whole command line is built and quoted
404
+ // by hand instead of passing SKILLS_ADD_ARGV as a separate array.
405
+ (0, node_child_process_1.spawn)(['npx', ...SKILLS_ADD_ARGV].map(quoteForCmdExe).join(' '), Object.assign(Object.assign({}, spawnOptions), { shell: true }))
406
+ : // POSIX: no shell is spawned at all, so nothing is in a position to
407
+ // glob-expand the literal `*` in `--skill *` — `npx` is exec'd
408
+ // directly with SKILLS_ADD_ARGV as its argv.
409
+ (0, node_child_process_1.spawn)('npx', SKILLS_ADD_ARGV, spawnOptions);
410
+ // Windows-only backstop for SKILLS_INSTALL_TIMEOUT_MS. `spawn`'s own
411
+ // `timeout` + `killSignal` (used above for POSIX) only terminates the
412
+ // process `child` actually refers to — under `shell: true` that is
413
+ // cmd.exe, not `npx`. cmd.exe does not propagate termination to the
414
+ // `npx`/npm/git descendants it launched, so relying on the same option
415
+ // here would kill the shell while the clone it kicked off kept running
416
+ // in the background — orphaned, and still writing into the scaffolded
417
+ // workspace after this function had already rejected. `taskkill /T`
418
+ // kills the whole process tree rooted at cmd.exe's pid instead of just
419
+ // cmd.exe itself.
420
+ //
421
+ // UNVERIFIED ON WINDOWS: reasoned through from documented cmd.exe/
422
+ // taskkill behaviour, but there is no Windows machine or CI runner
423
+ // available in this environment to actually exercise it. Verify on a
424
+ // real Windows box before relying on it.
425
+ let windowsTimeoutHandle;
426
+ if (isWindows) {
427
+ windowsTimeoutHandle = setTimeout(() => {
428
+ if (settled)
429
+ return;
430
+ timedOut = true;
431
+ if (typeof child.pid === 'number') {
432
+ // `taskkill` is a stock Windows binary, so this should never itself
433
+ // fail to spawn — but an unhandled `error` event on a ChildProcess
434
+ // throws, and there is nothing more useful to do here than swallow
435
+ // it: the `exit` handler above has already been told (`timedOut`)
436
+ // and will reject with the real, readable timeout message either way.
437
+ (0, node_child_process_1.spawn)('taskkill', ['/pid', String(child.pid), '/T', '/F'], {
438
+ stdio: 'ignore',
439
+ }).on('error', () => undefined);
440
+ }
441
+ }, SKILLS_INSTALL_TIMEOUT_MS);
442
+ }
443
+ child.on('error', (error) => {
444
+ // The child never started (e.g. `npx` not found on PATH).
445
+ clearTimeout(windowsTimeoutHandle);
446
+ settle(() => reject(error));
447
+ });
448
+ child.on('exit', (code, signal) => {
449
+ clearTimeout(windowsTimeoutHandle);
450
+ if (signal || timedOut) {
451
+ settle(() => reject(new Error(`npx was killed${signal ? ` by ${signal}` : ''} before finishing — most likely the ` +
452
+ `${SKILLS_INSTALL_TIMEOUT_MS}ms install timeout on a slow or unreachable network`)));
453
+ return;
454
+ }
455
+ if (code !== 0) {
456
+ settle(() => reject(new Error(`npx exited with code ${code}`)));
457
+ return;
458
+ }
459
+ settle(resolve);
460
+ });
461
+ });
462
+ }
463
+ // Exported (rather than inlined into the returned post-generator task) so it
464
+ // can be exercised directly in tests without also invoking the real
465
+ // `npm install` that `installTask`/`removePresetTask` run when called.
466
+ function installSkills(tree, skillsEnabled) {
467
+ return tslib_1.__awaiter(this, void 0, void 0, function* () {
468
+ if (!skillsEnabled)
469
+ return;
470
+ console.log(`\n◇ Installing storybookjs/mcp skills (stories, storybook-init, storybook-setup, storybook-upgrade)…`);
471
+ try {
472
+ // Runs in the scaffolded workspace's real root: by the time the
473
+ // post-generator task calls this, Nx has already flushed the virtual Tree
474
+ // to disk (that's what lets installTask run a real `npm install`).
475
+ // `--copy` (not the CLI's default symlink farm) because an attendee on
476
+ // Windows without developer mode cannot create symlinks. `--agent
477
+ // claude-code` (not `--all`) so the scaffold doesn't also grow
478
+ // `.cursor/`, `.codex/`, etc.
479
+ const env = Object.assign(Object.assign({}, process.env), { DO_NOT_TRACK: '1', SKILLS_CLONE_TIMEOUT_MS: String(SKILLS_CLONE_TIMEOUT_MS) });
480
+ yield runSkillsAddCommand(tree.root, env);
481
+ }
482
+ catch (error) {
483
+ // Non-fatal by design: a scaffold that dies on this last step because a
484
+ // conference network can't reach GitHub is a ruined workshop morning; a
485
+ // workspace merely missing its skills is a nuisance the attendee (or
486
+ // facilitator) can fix with the command below.
487
+ console.warn(`\n⚠ Could not install the storybookjs/mcp skills automatically (${error instanceof Error ? error.message : String(error)}).`);
488
+ console.warn(` Run this by hand once you have network access:\n`);
489
+ console.warn(` ${SKILLS_ADD_COMMAND_FOR_HUMANS}\n`);
490
+ }
491
+ });
492
+ }
12
493
  function presetGenerator(tree, options) {
13
494
  return tslib_1.__awaiter(this, void 0, void 0, function* () {
14
- var _a, _b;
15
- const frameworks = ((_a = options.frameworks) !== null && _a !== void 0 ? _a : 'angular')
16
- .split(',')
17
- .map((f) => f.trim())
18
- .filter(Boolean);
495
+ var _a, _b, _c, _d, _e, _f;
496
+ const framework = (_a = options.framework) !== null && _a !== void 0 ? _a : 'angular';
497
+ const skillsEnabled = (_b = options.skills) !== null && _b !== void 0 ? _b : true;
498
+ // Pinned, not `latest` — see readOwnVersion()'s comment.
499
+ const componentPackageVersion = readOwnVersion();
19
500
  const deps = {};
20
- for (const framework of frameworks) {
21
- const appName = `workshop-${framework}`;
22
- if (framework === 'angular') {
23
- console.log(`\n◇ Generating Angular workshop app…`);
24
- // NX_VERSION is the version of the nx running this generator, which is the
25
- // one create-nx-workspace installed into the workspace. Pinning to it is not
26
- // tidiness: nx ships core and plugins as one release and they reach across
27
- // the package boundary, so a plugin one patch ahead of core throws at load.
28
- // `@nx/eslint@23.1.2` calls `combineGlobPatterns` from `@nx/devkit/internal`,
29
- // which `@nx/devkit@23.1.1` does not export — measured, and it broke CI the
30
- // day 23.1.2 was published.
31
- //
32
- // This is also why `@nx/angular` is an OPTIONAL peer of this package. npm
33
- // auto-installs a required peer, and `>=22.0.0` resolves to whatever is
34
- // latest — measured: it installed @nx/angular 23.1.2 into a workspace whose
35
- // nx was 23.1.1, dragging @nx/eslint 23.1.2 with it, before this generator
36
- // ever ran. Optional peers are not auto-installed, so the first thing that
37
- // installs it is the line below, at the version that matches.
38
- yield (0, devkit_1.ensurePackage)('@nx/angular', devkit_1.NX_VERSION);
39
- const { applicationGenerator: angularAppGenerator } = require('@nx/angular/generators');
40
- yield angularAppGenerator(tree, {
41
- name: appName,
42
- directory: appName,
43
- style: 'css',
44
- routing: true,
45
- standalone: true,
46
- ssr: false,
47
- skipTests: true,
48
- e2eTestRunner: 'none',
49
- skipFormat: true,
50
- });
51
- deps['@atelier-ui/angular'] = 'latest';
52
- }
53
- if (framework === 'react') {
54
- console.log(`\n◇ Generating React workshop app…`);
55
- // eslint-disable-next-line @typescript-eslint/no-explicit-any
56
- const { applicationGenerator: reactAppGenerator } = yield (0, devkit_1.ensurePackage)('@nx/react', devkit_1.NX_VERSION);
57
- yield reactAppGenerator(tree, {
58
- name: appName,
59
- directory: appName,
60
- style: 'css',
61
- routing: true,
62
- bundler: 'vite',
63
- linter: 'eslint',
64
- unitTestRunner: 'none',
65
- e2eTestRunner: 'none',
66
- skipFormat: true,
67
- });
68
- deps['@atelier-ui/react'] = 'latest';
69
- }
70
- if (framework === 'vue') {
71
- console.log(`\n◇ Generating Vue workshop app…`);
72
- // eslint-disable-next-line @typescript-eslint/no-explicit-any
73
- const { applicationGenerator: vueAppGenerator } = yield (0, devkit_1.ensurePackage)('@nx/vue', devkit_1.NX_VERSION);
74
- yield vueAppGenerator(tree, {
75
- name: appName,
76
- directory: appName,
77
- style: 'css',
78
- routing: true,
79
- linter: 'eslint',
80
- unitTestRunner: 'none',
81
- e2eTestRunner: 'none',
82
- skipFormat: true,
83
- });
84
- deps['@atelier-ui/vue'] = 'latest';
85
- }
86
- // Copy design tokens into the scaffolded app so attendees can edit them
87
- // directly. They're not imported from the @atelier-ui/<fw> npm package
88
- // because (a) those published packages don't ship tokens.css, and (b) a
89
- // workshop attendee editing colors in node_modules is a bad experience.
90
- tree.write(`${appName}/src/styles/tokens.css`, readTemplate('styles/tokens.css'));
91
- // Prepend the tokens import to the app's global stylesheet
92
- const stylesPath = `${appName}/src/styles.css`;
93
- const existing = tree.exists(stylesPath) ? ((_b = tree.read(stylesPath, 'utf-8')) !== null && _b !== void 0 ? _b : '') : '';
94
- tree.write(stylesPath, `@import './styles/tokens.css';\n\n${existing}`);
501
+ // Every scaffolded workspace gets a local Storybook — not behind a flag
502
+ // (2026-09-10 owner decision, tasks/todo.md "Storybook + the storybookjs/mcp
503
+ // skills in the scaffolded workspace"). It exists so the storybookjs/mcp
504
+ // skills installed below have a Storybook ≥ 10.5 with `@storybook/addon-mcp`
505
+ // to talk to; without it, the `stories` skill's own first move on any UI task
506
+ // would be to propose installing one.
507
+ const storybookDevDeps = {
508
+ storybook: STORYBOOK_VERSION,
509
+ '@storybook/addon-mcp': STORYBOOK_VERSION,
510
+ '@storybook/addon-a11y': STORYBOOK_VERSION,
511
+ '@storybook/addon-docs': STORYBOOK_VERSION,
512
+ // Browser-mode Storybook tests (owner correction 2026-09-10 to ADR-0123) —
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.
516
+ '@storybook/addon-vitest': STORYBOOK_VERSION,
517
+ vitest: VITEST_VERSION,
518
+ '@vitest/browser-playwright': VITEST_BROWSER_PLAYWRIGHT_VERSION,
519
+ playwright: PLAYWRIGHT_VERSION,
520
+ };
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',
580
+ },
581
+ },
582
+ `);
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'] }],
671
+ },
672
+ },
673
+ `, [`import eslintConfigPrettier from 'eslint-config-prettier';`]);
95
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;
809
+ }
810
+ // ─── Prettier (formatting enforcement) ───────────────────────────────────
811
+ // Measured 2026-09-12 (tasks/todo.md, "A. Formatting enforcement"): a
812
+ // fresh `create-nx-workspace` tree ships neither a `prettier`
813
+ // devDependency nor a `.prettierrc` — this is the ADR-0127 problem before
814
+ // even the "configured" half exists, so both are written here rather than
815
+ // assumed present. Content is byte-identical to this monorepo's own
816
+ // `.prettierrc` — no reason for a workshop attendee to start from a
817
+ // different formatting convention than the repo whose components they're
818
+ // consuming.
819
+ console.log(`\n◇ Wiring Prettier…`);
820
+ (0, devkit_1.writeJson)(tree, '.prettierrc', { singleQuote: true });
821
+ // ─── Stylelint (ported CSS-discipline rules, ADR-0130) ───────────────────
822
+ console.log(`\n◇ Wiring stylelint (ported CSS-discipline rules)…`);
823
+ tree.write('stylelint.config.mjs', buildStylelintConfig(framework));
824
+ // Six files, byte-identical to the canonical copies in tools/stylelint-rules/
825
+ // (kept that way by this repo's own sync-preflight.mjs) — see
826
+ // buildStylelintConfig's comment above for why no-primitive-token.js ships
827
+ // even though it's never wired into the config just written.
828
+ for (const ruleFile of [
829
+ 'index.js',
830
+ 'utils.js',
831
+ 'no-raw-color-literal.js',
832
+ 'no-undeclared-token.js',
833
+ 'no-primitive-token.js',
834
+ 'no-token-bypass.js',
835
+ ]) {
836
+ tree.write(`tools/stylelint-rules/${ruleFile}`, readTemplate(`tools/stylelint-rules/${ruleFile}`));
837
+ }
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
842
+ // `tools/scripts/lib/allowlists.js` (the scaffold ships no such file — see
843
+ // buildStylelintConfig's comment on why neither wired rule is given
844
+ // `allowlistsFile`). The application generator above is guaranteed to
845
+ // have already written nx.json (create-nx-workspace writes it before any
846
+ // preset runs), so `updateJson` here is safe the same way the package.json
847
+ // update below is.
848
+ (0, devkit_1.updateJson)(tree, 'nx.json', (config) => {
849
+ var _a;
850
+ (_a = config.targetDefaults) !== null && _a !== void 0 ? _a : (config.targetDefaults = {});
851
+ config.targetDefaults['stylelint'] = {
852
+ cache: true,
853
+ inputs: [
854
+ 'default',
855
+ '^default',
856
+ '{workspaceRoot}/stylelint.config.mjs',
857
+ '{workspaceRoot}/tools/stylelint-rules/**/*',
858
+ `{workspaceRoot}/${appName}/src/styles/tokens.css`,
859
+ { externalDependencies: ['stylelint'] },
860
+ ],
861
+ };
862
+ return config;
863
+ });
864
+ // ─── The contract loop (ADR-0121 S4) ─────────────────────────────────────
865
+ // contracts.config.json names the workshop's one framework and app —
866
+ // `framework`/`appName`, already established above.
867
+ console.log(`\n◇ Writing the contract loop (check:contracts, the example AtlButton contract, the Figma snapshot projection)…`);
868
+ // .ts.template, not .ts — see the comment on storybookTemplateName() above:
869
+ // a literal `.ts` file under files/ is compiled away by this package's own
870
+ // tsconfig.lib.json (`include: ["src/**/*.ts"]`) and never reaches dist/
871
+ // under a name readTemplate() can find at runtime. The OUTPUT filenames
872
+ // below stay plain `.ts` — only the template source needs the suffix.
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'));
876
+ tree.write('tools/scripts/check-contracts.mjs', readTemplate('tools/scripts/check-contracts.mjs'));
877
+ tree.write('tools/scripts/lib/ts-eval.js', readTemplate('tools/scripts/lib/ts-eval.js'));
878
+ tree.write('tools/scripts/lib/docgen.mjs', readTemplate('tools/scripts/lib/docgen.mjs'));
879
+ tree.write('tools/scripts/figma-snapshot-contracts.mjs', readTemplate('tools/scripts/figma-snapshot-contracts.mjs'));
880
+ // The AtlButton-only projection of this repo's own tools/figma/snapshot.json
881
+ // (gen-scaffold-snapshot.mjs) — gives check:contracts a Figma side for the
882
+ // example contract + story on day one, before the attendee ever runs
883
+ // figma:snapshot themselves.
884
+ tree.write('tools/figma/snapshot.json', readTemplate('figma/snapshot.json'));
885
+ (0, devkit_1.writeJson)(tree, 'contracts.config.json', {
886
+ framework,
887
+ contracts: `${appName}/src/contracts`,
888
+ stories: [`${appName}/src`],
889
+ snapshot: 'tools/figma/snapshot.json',
890
+ });
96
891
  console.log(`\n◇ Writing project files (CLAUDE.md, README, .mcp.json)…`);
97
892
  // Write CLAUDE.md with framework-specific guidance
98
- const frameworkSections = frameworks
99
- .map((f) => {
100
- if (f === 'angular') {
101
- return `### Angular (\`@atelier-ui/angular\`)
893
+ let frameworkSection = '';
894
+ if (framework === 'angular') {
895
+ frameworkSection = `### Angular (\`@atelier-ui/angular\`)
102
896
  - Selectors: \`atl-button\`, \`atl-input\`, \`atl-dialog\`, …
103
897
  - Import: \`import { AtlButton } from '@atelier-ui/angular';\`
104
898
  - Add to \`@Component({ imports: [AtlButton] })\`
105
899
  - Form controls implement Signal Forms (\`FormValueControl\` / \`FormCheckboxControl\`)`;
106
- }
107
- if (f === 'react') {
108
- return `### React (\`@atelier-ui/react\`)
900
+ }
901
+ else if (framework === 'react') {
902
+ frameworkSection = `### React (\`@atelier-ui/react\`)
109
903
  - Elements: \`<AtlButton>\`, \`<AtlInput>\`, \`<AtlDialog>\`, …
110
904
  - Import: \`import { AtlButton } from '@atelier-ui/react';\`
111
905
  - Event handlers follow \`onXxx\` / \`onXxxChange\` convention
112
906
  - Toast: use \`useAtlToast()\` hook inside \`<AtlToastProvider>\``;
113
- }
114
- if (f === 'vue') {
115
- return `### Vue (\`@atelier-ui/vue\`)
907
+ }
908
+ else if (framework === 'vue') {
909
+ frameworkSection = `### Vue (\`@atelier-ui/vue\`)
116
910
  - Elements: \`<AtlButton>\`, \`<AtlInput>\`, \`<AtlDialog>\`, …
117
911
  - Import: \`import { AtlButton } from '@atelier-ui/vue';\`
118
912
  - Two-way binding: \`v-model\` and \`v-model:value\` where applicable
119
913
  - Toast: use \`useAtlToast()\` composable`;
120
- }
121
- return '';
122
- })
123
- .join('\n\n');
124
- const mcpSection = frameworks
125
- .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
126
958
  Before using any component:
127
959
  1. Call \`docs-list\` to get valid component IDs
128
960
  2. Call \`docs-show\` with the ID — never invent props
129
961
  3. Call \`docs-show-story\` for a specific variant
130
- 4. Do not use a component that is not in the docs`)
131
- .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`;
132
997
  tree.write('CLAUDE.md', `# Atelier Workshop
133
998
 
134
999
  This workspace uses Atelier for all UI components.
@@ -138,11 +1003,17 @@ Full API reference: ${SITE_URL}/llms-full.txt
138
1003
 
139
1004
  The servers are pre-configured in \`.mcp.json\` and connect automatically.
140
1005
 
141
- ${mcpSection}
1006
+ ${mcpSection}${angularCliMcpSection}
142
1007
 
143
1008
  ## Component Libraries
144
1009
 
145
- ${frameworkSections}
1010
+ ${frameworkSection}
1011
+
1012
+ ${versionsSection}
1013
+
1014
+ ## Framework Idioms
1015
+
1016
+ ${frameworkIdiomsSection}
146
1017
 
147
1018
  ## Composition Patterns
148
1019
 
@@ -161,7 +1032,7 @@ hardcoded hex values or pixel sizes — always reference a token.
161
1032
  Key tokens:
162
1033
  - Colors: --ui-color-primary, --ui-color-text, --ui-color-surface-raised, --ui-color-border
163
1034
  - Spacing: --ui-spacing-4 (1rem), --ui-spacing-6 (1.5rem), --ui-spacing-8 (2rem)
164
- - 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)
165
1036
 
166
1037
  ## Rules
167
1038
  - Prefer component props over custom CSS
@@ -169,9 +1040,157 @@ Key tokens:
169
1040
  - Do not install other UI component libraries alongside Atelier
170
1041
  - Do not add inline hex colors or hardcoded spacing values
171
1042
 
1043
+ ## Formatting
1044
+
1045
+ Prettier is configured (\`.prettierrc\`, \`{ singleQuote: true }\`): \`npm run format\`
1046
+ (\`prettier --write .\`) and \`npm run check:format\` (\`prettier --check .\`). The
1047
+ scaffold itself is already Prettier-clean — \`check:format\` passes right after
1048
+ \`npm install\`, before you've written a line of your own.
1049
+
172
1050
  ## Apps
173
1051
 
174
- ${frameworks.map((f) => `- \`workshop-${f}\` — run with \`npx nx serve workshop-${f}\``).join('\n')}
1052
+ - \`${appName}\` — run with \`npx nx serve ${appName}\`
1053
+
1054
+ ## Storybook
1055
+
1056
+ The app has its own local Storybook:
1057
+
1058
+ - \`${appName}\` — \`npx nx storybook ${appName}\` — http://localhost:6006
1059
+
1060
+ Build a static Storybook (CI, hosting) with \`npx nx build-storybook ${appName}\`.
1061
+
1062
+ Every story is also a browser-mode test (\`@storybook/addon-vitest\`). One-time setup
1063
+ after \`npm install\`:
1064
+
1065
+ \`\`\`bash
1066
+ npx playwright install chromium
1067
+ \`\`\`
1068
+
1069
+ Then run every app's stories headless in Chromium with axe checks:
1070
+
1071
+ \`\`\`bash
1072
+ npm run check:stories
1073
+ \`\`\`
1074
+
1075
+ ## Agent Skills
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
+
1084
+ ${skillsEnabled
1085
+ ? `The scaffold attempted to install four \`storybookjs/mcp\` skills for Claude
1086
+ Code (\`.claude/skills/\`) during setup — a failed clone (offline, unreachable
1087
+ registry) does not stop the workspace from being created, so this file can't
1088
+ promise they actually landed. Check \`.claude/skills/\` for the four directories
1089
+ below; re-run the command further down if any are missing:
1090
+
1091
+ - **stories** — invoke first, before creating, editing, or deleting components, stories, styles, CSS, themes, colors, or design tokens
1092
+ - **storybook-init** — adding Storybook to a project that does not have it configured yet
1093
+ - **storybook-setup** — Storybook is installed and you want a working \`preview\` file and stories for real components
1094
+ - **storybook-upgrade** — Storybook exists but needs an upgrade
1095
+
1096
+ Re-run or update the install at any time:
1097
+
1098
+ \`\`\`bash
1099
+ ${SKILLS_ADD_COMMAND_FOR_HUMANS}
1100
+ \`\`\`
1101
+
1102
+ **Which MCP tools these skills can reach depends on \`.mcp.json\`, not just on the
1103
+ skills being present.** \`.mcp.json\` wires only the *hosted* Storybook MCP servers
1104
+ (\`storybook-<fw>\` → ${SITE_URL}/storybook-<fw>/mcp), which serve the \`docs\`
1105
+ toolset — \`docs-list\`, \`docs-show\`, \`docs-show-story\` all work out of the box.
1106
+ The skills' \`dev\`-toolset tools (\`stories-preview\`, \`get-storybook-story-instructions\`)
1107
+ instead come from \`@storybook/addon-mcp\` inside a *running local* Storybook
1108
+ (already configured in every app's \`.storybook/main.ts\`) — that local endpoint is
1109
+ deliberately not wired into \`.mcp.json\` by default, the same as this repo's own
1110
+ root \`.mcp.json\`, because a fixed \`localhost\` entry would fail to connect on
1111
+ every Claude Code session started without that Storybook already running. To use
1112
+ the \`dev\` toolset: start \`npx nx storybook workshop-<fw>\` (see Storybook below),
1113
+ then add this to \`.mcp.json\`'s \`mcpServers\` (only while that Storybook is up):
1114
+
1115
+ \`\`\`json
1116
+ "storybook-<fw>-local": {
1117
+ "type": "http",
1118
+ "url": "http://localhost:<port>/mcp"
1119
+ }
1120
+ \`\`\`
1121
+
1122
+ (\`<port>\` is the one listed for that app under Storybook below.) \`test-run\`
1123
+ works too, once that local Storybook is running — every story here IS a
1124
+ render + accessibility test (\`@storybook/addon-vitest\`, run offline via
1125
+ \`npm run check:stories\`; see "The Contract Loop" below).`
1126
+ : `Skipped for this workspace (\`skills: false\`). Install the four \`storybookjs/mcp\`
1127
+ skills for Claude Code by hand:
1128
+
1129
+ \`\`\`bash
1130
+ ${SKILLS_ADD_COMMAND_FOR_HUMANS}
1131
+ \`\`\`
1132
+ `}
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
+
1144
+ ## The Contract Loop
1145
+
1146
+ A contract (\`${appName}/src/contracts/<name>.contract.ts\`) is the one hand-authored
1147
+ spec file per component: the Figma master's node id, plus intentional Figma ↔ code
1148
+ mismatches (\`figmaOnly\`, \`codeOnly\`, \`axisMap\`) — never props, defaults, or
1149
+ descriptions; those live in the component's own types/JSDoc and its stories.
1150
+
1151
+ Order: read the Figma handoff → write the contract → write one story per variant and
1152
+ interaction state → \`npm run check:contracts\` → \`figma_check_design_parity\` in Storybook.
1153
+
1154
+ \`check:contracts\` joins the contract, the component's docgen, and \`tools/figma/snapshot.json\`
1155
+ offline — no browser, no Storybook build — and reports one line per finding:
1156
+ - \`[CONTRACT-MISSING]\` / \`[CONTRACT-NODE]\` — no contract file, or its node id disagrees
1157
+ - \`[AXIS]\` / \`[BOOLEAN]\` / \`[ENUM-UNDRAWN]\` — a Figma property has no matching code prop
1158
+ - \`[COVERAGE]\` / \`[COVERAGE-BOOL]\` — a variant value or boolean is never rendered by a story
1159
+ - \`[FIGMA-ONLY]\` / \`[STALE-EXEMPTION]\` / \`[UNMIRRORED]\` — an exemption is missing, stale, or unexplained
1160
+ - \`[NO-STORY-META]\` / \`[NO-MASTER]\` — a contract with nothing yet to check it against
1161
+ - \`[CONTRACT-IMPORT]\` — a story meta doesn't import its component's contract and set
1162
+ \`contract\` in \`parameters\` (a warning here, until this workspace ships a docs block
1163
+ that renders it)
1164
+
1165
+ Refresh \`tools/figma/snapshot.json\` from the real master with the Figma Desktop Bridge
1166
+ connected: ${figmaSnapshotRefreshInstruction}, then run \`npm run figma:snapshot\`.
1167
+
1168
+ \`check:contracts\` proves shape and story coverage; \`npm run check:stories\` (every story,
1169
+ rendered headless in Chromium via \`@storybook/addon-vitest\`, with axe) proves rendering
1170
+ and accessibility. It does so for components whose source lives in this workspace. For
1171
+ components imported from \`@atelier-ui/${framework}\` — the example \`AtlButton\`
1172
+ included — the check recognises that the import resolves into \`node_modules\` and skips
1173
+ docgen for it — the same rule in every framework — so it has nothing to compare and
1174
+ reports only \`[NO-STORY-META]\`; their prop tables come from the hosted
1175
+ Storybook MCP (\`docs-show\`) instead. A green \`check:contracts\` on the example story
1176
+ therefore proves the wiring, not the example. Run \`npx playwright install chromium\`
1177
+ once after \`npm install\` — see Storybook below.
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\`).
175
1194
 
176
1195
  ## Troubleshooting
177
1196
 
@@ -202,8 +1221,88 @@ file exports). The Desktop Bridge covers creation and inspection without a token
202
1221
  - MCP Playground (inspect tool responses): ${SITE_URL}/mcp
203
1222
  - CLAUDE.md template: ${SITE_URL}/claude-md
204
1223
  `);
205
- // Install selected @atelier-ui/* packages
206
- const installTask = (0, devkit_1.addDependenciesToPackageJson)(tree, deps, {});
1224
+ // The contract loop's own devDependencies (ADR-0121 S4): the MCP SDK
1225
+ // figma-snapshot-contracts.mjs imports directly, always; `typescript` only
1226
+ // when the framework application generator (above) didn't already add it —
1227
+ // read from the tree's package.json as it stands right now, after the
1228
+ // framework's generator has run and before this generator's own writes
1229
+ // below it.
1230
+ const pkgSoFar = (0, devkit_1.readJson)(tree, 'package.json');
1231
+ const existingDeps = Object.assign(Object.assign({}, ((_d = pkgSoFar.dependencies) !== null && _d !== void 0 ? _d : {})), ((_e = pkgSoFar.devDependencies) !== null && _e !== void 0 ? _e : {}));
1232
+ const hasTypescript = Boolean(existingDeps.typescript);
1233
+ const contractLoopDevDeps = {
1234
+ '@modelcontextprotocol/sdk': MCP_SDK_VERSION,
1235
+ };
1236
+ if (!hasTypescript) {
1237
+ contractLoopDevDeps.typescript = TYPESCRIPT_VERSION;
1238
+ }
1239
+ // Browser-mode Storybook tests (owner correction 2026-09-10 to ADR-0123):
1240
+ // the selected framework needs its own Vite plugin for the vitest browser
1241
+ // pipeline, added only when the framework's own application generator
1242
+ // (above) didn't already bring it in. React and Vue's vite-based app
1243
+ // generators typically already do; Angular's esbuild-based one never does.
1244
+ const viteFrameworkDevDeps = {};
1245
+ if (framework === 'react' && !existingDeps['@vitejs/plugin-react']) {
1246
+ viteFrameworkDevDeps['@vitejs/plugin-react'] = VITE_PLUGIN_REACT_VERSION;
1247
+ }
1248
+ if (framework === 'vue' && !existingDeps['@vitejs/plugin-vue']) {
1249
+ viteFrameworkDevDeps['@vitejs/plugin-vue'] = VITE_PLUGIN_VUE_VERSION;
1250
+ }
1251
+ if (framework === 'angular' &&
1252
+ !existingDeps['@analogjs/vite-plugin-angular']) {
1253
+ viteFrameworkDevDeps['@analogjs/vite-plugin-angular'] =
1254
+ ANALOGJS_VITE_PLUGIN_ANGULAR_VERSION;
1255
+ }
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']) {
1259
+ viteFrameworkDevDeps['@testing-library/jest-dom'] =
1260
+ TESTING_LIBRARY_JEST_DOM_VERSION;
1261
+ }
1262
+ if (framework === 'vue' && !existingDeps['eslint-config-prettier']) {
1263
+ viteFrameworkDevDeps['eslint-config-prettier'] =
1264
+ ESLINT_CONFIG_PRETTIER_VERSION;
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
+ }
1291
+ // Ported CSS-discipline rules (ADR-0130). No postcss-html: that's only
1292
+ // needed to lint .astro files, and the scaffold has none.
1293
+ const stylelintDevDeps = {
1294
+ stylelint: STYLELINT_VERSION,
1295
+ };
1296
+ // Formatting enforcement — see the "Prettier" section above for why this
1297
+ // is written at all.
1298
+ const prettierDevDeps = {
1299
+ prettier: PRETTIER_VERSION,
1300
+ };
1301
+ // Install selected @atelier-ui/* packages (dependencies) and Storybook +
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));
207
1306
  // Remove the preset package itself — create-nx-workspace adds it automatically
208
1307
  // but it's a build-time tool and should not be in the workspace's dependencies
209
1308
  const removePresetTask = (0, devkit_1.removeDependenciesFromPackageJson)(tree, ['@atelier-ui/create-workspace'], []);
@@ -217,20 +1316,90 @@ file exports). The Desktop Bridge covers creation and inspection without a token
217
1316
  var _a;
218
1317
  pkg.scripts = (_a = pkg.scripts) !== null && _a !== void 0 ? _a : {};
219
1318
  pkg.scripts.preflight = 'node tools/scripts/preflight.mjs';
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.
1326
+ pkg.scripts['check:contracts'] = 'node tools/scripts/check-contracts.mjs';
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>';
1330
+ // Browser-mode Storybook tests (owner correction 2026-09-10 to ADR-0123).
1331
+ // Identical to the monorepo's own root package.json script.
1332
+ pkg.scripts['check:stories'] = 'nx run-many -t storybook-test --parallel=1';
1333
+ // Ported CSS-discipline rules (ADR-0130). Identical to the monorepo's own
1334
+ // root package.json script.
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';
1343
+ // Formatting enforcement. Deliberately this monorepo's own
1344
+ // `prettier --write .` / `prettier --check .` shape, not `nx format:*` —
1345
+ // measured 2026-09-12 against a real generated workspace, two distinct
1346
+ // failure modes:
1347
+ // 1. Unconditional, on the pristine, untouched scaffold: with no
1348
+ // formatter resolvable in node_modules, `nx format:check` exits 0
1349
+ // printing "No formatter configured" — a silent pass before any git
1350
+ // logic even runs. Worth keeping in mind even though this preset
1351
+ // now installs prettier: the tool's own failure mode is "nothing is
1352
+ // configured, so nothing is wrong", not a loud error.
1353
+ // 2. Conditional: once prettier is installed, `nx format:check`
1354
+ // un-flagged does NOT silently pass immediately after scaffolding —
1355
+ // `git init` stages files without committing, so the `main` ref
1356
+ // doesn't resolve yet, Nx catches that specific git failure and
1357
+ // falls back to an all-files scan, correctly reporting every
1358
+ // unformatted file with exit 1 (after an alarming
1359
+ // `Command failed: ... fatal: ambiguous argument 'main'` on
1360
+ // stderr). The silent zero-file pass only appears once the
1361
+ // attendee makes their own first commit, putting `main` and `HEAD`
1362
+ // at the same revision — the steady state a workspace reaches
1363
+ // within minutes of scaffolding, and the one `nx format:check`
1364
+ // un-flagged reads as "nothing changed, nothing to check".
1365
+ // `prettier --check .` has neither failure mode: it always scans the
1366
+ // whole tree (honouring .gitignore's node_modules/dist/.nx exclusions
1367
+ // already, so no .prettierignore is needed), and if prettier were ever
1368
+ // missing it fails loudly rather than reporting a silent pass. A script
1369
+ // an attendee runs unmodified should not depend on remembering `--all`.
1370
+ pkg.scripts.format = 'prettier --write .';
1371
+ pkg.scripts['check:format'] = 'prettier --check .';
220
1372
  return pkg;
221
1373
  });
222
- // Write .mcp.json with MCP servers for selected frameworks
1374
+ // Write .mcp.json with MCP servers for the selected framework
223
1375
  const mcpServers = {
224
1376
  'nx-mcp': {
225
1377
  type: 'stdio',
226
1378
  command: 'npx',
227
1379
  args: ['nx', 'mcp'],
228
1380
  },
229
- };
230
- for (const framework of frameworks) {
231
- mcpServers[`storybook-${framework}`] = {
1381
+ [`storybook-${framework}`]: {
232
1382
  type: 'http',
233
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'],
234
1403
  };
235
1404
  }
236
1405
  if (options.figmaMcp) {
@@ -251,20 +1420,203 @@ file exports). The Desktop Bridge covers creation and inspection without a token
251
1420
 
252
1421
  ## Apps
253
1422
 
254
- ${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\`.
255
1430
 
256
1431
  ## Getting started
257
1432
 
258
1433
  \`\`\`bash
259
1434
  npm install
260
- npx nx serve workshop-${frameworks[0]}
1435
+ npx playwright install chromium # one-time — needed by npm run check:stories
1436
+ npx nx serve ${appName}
1437
+ \`\`\`
1438
+
1439
+ ## Formatting
1440
+
1441
+ Prettier is configured (\`.prettierrc\`): \`npm run format\` (\`prettier --write .\`) and
1442
+ \`npm run check:format\` (\`prettier --check .\`). The scaffold is already
1443
+ Prettier-clean out of the box — \`check:format\` passes right after \`npm install\`.
1444
+
1445
+ ## Storybook
1446
+
1447
+ - \`${appName}\` — \`npx nx storybook ${appName}\` — http://localhost:6006
1448
+
1449
+ Every story is also a browser-mode test — run them all headless in Chromium with
1450
+ \`npm run check:stories\`.
1451
+
1452
+ ## Agent Skills
1453
+
1454
+ ${skillsEnabled
1455
+ ? `The scaffold attempted to install the four \`storybookjs/mcp\` skills (\`stories\`,
1456
+ \`storybook-init\`, \`storybook-setup\`, \`storybook-upgrade\`) for Claude Code under
1457
+ \`.claude/skills/\` — check that directory, since a failed clone doesn't stop the
1458
+ workspace from being created. Re-run or update them with:
1459
+
1460
+ \`\`\`bash
1461
+ ${SKILLS_ADD_COMMAND_FOR_HUMANS}
261
1462
  \`\`\`
262
1463
 
1464
+ Note: \`test-run\` works once a local Storybook is running — every story here is a
1465
+ render + accessibility test (\`@storybook/addon-vitest\`, also runnable offline via
1466
+ \`npm run check:stories\`). See CLAUDE.md for details.`
1467
+ : `Skipped (\`skills: false\`). Install by hand:
1468
+
1469
+ \`\`\`bash
1470
+ ${SKILLS_ADD_COMMAND_FOR_HUMANS}
1471
+ \`\`\``}
1472
+
263
1473
  ## MCP
264
1474
 
265
1475
  Claude Code MCP servers are pre-configured in \`.mcp.json\`.
266
1476
  Browse components at ${SITE_URL}
267
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`);
268
1620
  console.log(`\n◇ Formatting files…`);
269
1621
  yield (0, devkit_1.formatFiles)(tree);
270
1622
  // Wrap installTask + removePresetTask so the (multi-second, otherwise silent)
@@ -275,6 +1627,7 @@ Browse components at ${SITE_URL}
275
1627
  yield installTask();
276
1628
  console.log(`\n◇ Cleaning up preset package…`);
277
1629
  yield removePresetTask();
1630
+ yield installSkills(tree, skillsEnabled);
278
1631
  });
279
1632
  });
280
1633
  }