@atelier-ui/create-workspace 0.3.1 → 0.3.3

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 (24) hide show
  1. package/CHANGELOG.md +28 -0
  2. package/package.json +1 -1
  3. package/src/generators/preset/files/claude/agents/component-review.no-figma.md +42 -0
  4. package/src/generators/preset/files/claude/commands/verify.no-figma.md +27 -0
  5. package/src/generators/preset/files/claude/skills/atelier-component/SKILL.md +7 -7
  6. package/src/generators/preset/files/claude/skills/atelier-component/SKILL.no-figma.md +63 -0
  7. package/src/generators/preset/files/storybook/angular/main.ts.template +8 -0
  8. package/src/generators/preset/files/storybook/angular/preview.ts.template +17 -0
  9. package/src/generators/preset/files/storybook/react/atl-button.stories.tsx +1 -1
  10. package/src/generators/preset/files/storybook/react/main.ts.template +8 -0
  11. package/src/generators/preset/files/storybook/react/preview.tsx +18 -1
  12. package/src/generators/preset/files/storybook/vue/atl-button.stories.ts.template +1 -1
  13. package/src/generators/preset/files/storybook/vue/main.ts.template +8 -0
  14. package/src/generators/preset/files/storybook/vue/preview.ts.template +18 -1
  15. package/src/generators/preset/files/testing/angular/test-setup.ts.template +6 -0
  16. package/src/generators/preset/files/testing/react/atl-button.spec.tsx +17 -18
  17. package/src/generators/preset/files/testing/react/test-setup-stories.ts.template +17 -0
  18. package/src/generators/preset/files/testing/react/vitest.unit.config.ts.template +1 -1
  19. package/src/generators/preset/files/testing/vue/atl-button.spec.ts.template +17 -21
  20. package/src/generators/preset/files/testing/vue/test-setup-stories.ts.template +17 -0
  21. package/src/generators/preset/files/testing/vue/vitest.unit.config.ts.template +1 -1
  22. package/src/generators/preset/files/tools/scripts/preflight.mjs +40 -0
  23. package/src/generators/preset/preset.js +613 -153
  24. package/src/generators/preset/preset.js.map +1 -1
@@ -87,12 +87,17 @@ function testingTemplateName(framework, base) {
87
87
  return `testing/${framework}/${base}.ts.template`;
88
88
  }
89
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.
90
+ // ships as a static `files/` template, in two variants selected by
91
+ // `figmaMcp` (ADR-0144: SKILL.md when `--figma`, SKILL.no-figma.md
92
+ // otherwise — whole sections differ, not just a couple of words, so this is
93
+ // the same "pick a static file" shape as the per-framework templates below,
94
+ // not a third substitution token). Within whichever file is picked,
95
+ // instructions don't vary by framework except for two names: the app
96
+ // directory (`workshop-<fw>`) and the `@atelier-ui/<fw>` package/framework
97
+ // name. Rather than rewrite those per-framework spots as a JS template string
98
+ // (like CLAUDE.md/README.md below, which vary in far more places), each file
99
+ // stays a template with those two spots marked `<app>`/`<framework>`,
100
+ // substituted here at generate time.
96
101
  //
97
102
  // `<app>` and `<framework>` (angle-bracket-wrapped) were chosen as the
98
103
  // substitution tokens deliberately, over inventing a new one: the skill's own
@@ -100,17 +105,27 @@ function testingTemplateName(framework, base) {
100
105
  // English (e.g. "one app (`workshop-<framework>`), one framework, ..." and "
101
106
  // ... two-way bindings ... for this framework"), so a substitution key of the
102
107
  // 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) {
108
+ // the one substring that appears ONLY at the spots meant to be filled in
109
+ // (SKILL.md: five `<app>`, three `<framework>`; SKILL.no-figma.md: three
110
+ // `<app>`, two `<framework>` — smaller by exactly the sections it drops) —
111
+ // verified against each shipped file, not assumed — and is distinct from the
112
+ // files' other bracketed placeholder, `<name>` (a component name, e.g. in
113
+ // `<name>.contract.ts`), which stays generic prose for the reader and must
114
+ // NOT be substituted.
115
+ // `figmaMcp` (ADR-0144) picks between two source files, not a third
116
+ // substitution token: the difference between the two is not a couple of
117
+ // filled-in spots but whole sections (the contract loop, its finding-code
118
+ // table, the Figma-specific loop steps) that either exist or don't — the
119
+ // same "select a static template by parameter" shape `storybookTemplateName`/
120
+ // `testingTemplateName` above already use for the per-framework axis.
121
+ function renderAtelierComponentSkill(appName, framework, figmaMcp) {
110
122
  // `.split(token).join(value)` rather than `String.prototype.replaceAll`:
111
123
  // this package's tsconfig targets a lib below ES2021, where `replaceAll`
112
124
  // doesn't type-check.
113
- return readTemplate('claude/skills/atelier-component/SKILL.md')
125
+ const templatePath = figmaMcp
126
+ ? 'claude/skills/atelier-component/SKILL.md'
127
+ : 'claude/skills/atelier-component/SKILL.no-figma.md';
128
+ return readTemplate(templatePath)
114
129
  .split('<app>')
115
130
  .join(appName)
116
131
  .split('<framework>')
@@ -260,6 +275,17 @@ const MCP_SDK_VERSION = '^1.29.0';
260
275
  // constant in the devDependencies write when `typescript` isn't already
261
276
  // present.
262
277
  const TYPESCRIPT_VERSION = '6.0.3';
278
+ // Strictness (ADR-0140): typescript-eslint's own meta-package, for
279
+ // `tseslint.configs.recommendedTypeChecked` (lever 5) — a defensive add, not
280
+ // the primary source, like TYPESCRIPT_VERSION above: a real generated tree
281
+ // for all three frameworks already carries it in devDependencies (each
282
+ // framework's own `@nx/{angular,react,vue}:application` generator adds it
283
+ // independently, confirmed against a real run), so the conditional add near
284
+ // the end of presetGenerator only fires if some future generator version
285
+ // stops doing that. Matches root package.json's own declared range
286
+ // (`^8.40.0`) — a caret range mirrored verbatim, like VITEST_VERSION above,
287
+ // not the exact version those generators happened to resolve on their own.
288
+ const TYPESCRIPT_ESLINT_VERSION = '^8.40.0';
263
289
  // Ported CSS-discipline stylelint rules (ADR-0130): pinned the same way
264
290
  // STORYBOOK_VERSION above is — the exact version this monorepo actually
265
291
  // runs, not the caret range root package.json declares (`^17.15.0`); the
@@ -492,7 +518,7 @@ function installSkills(tree, skillsEnabled) {
492
518
  }
493
519
  function presetGenerator(tree, options) {
494
520
  return tslib_1.__awaiter(this, void 0, void 0, function* () {
495
- var _a, _b, _c, _d, _e, _f;
521
+ var _a, _b, _c, _d, _e, _f, _g;
496
522
  const framework = (_a = options.framework) !== null && _a !== void 0 ? _a : 'angular';
497
523
  const skillsEnabled = (_b = options.skills) !== null && _b !== void 0 ? _b : true;
498
524
  // Pinned, not `latest` — see readOwnVersion()'s comment.
@@ -509,6 +535,13 @@ function presetGenerator(tree, options) {
509
535
  '@storybook/addon-mcp': STORYBOOK_VERSION,
510
536
  '@storybook/addon-a11y': STORYBOOK_VERSION,
511
537
  '@storybook/addon-docs': STORYBOOK_VERSION,
538
+ // Manual dark-mode toolbar: tokens.css ships dark mode but nothing let a
539
+ // scaffolded workspace preview it before (only the OS-level
540
+ // prefers-color-scheme fallback). Previewing is all this adds — the a11y
541
+ // axe check still only runs against each story's default (light) render,
542
+ // same as before (see plan/adr/0142 in the monorepo this is scaffolded
543
+ // from).
544
+ '@storybook/addon-themes': STORYBOOK_VERSION,
512
545
  // Browser-mode Storybook tests (owner correction 2026-09-10 to ADR-0123) —
513
546
  // written unconditionally, independent of which framework is selected; the
514
547
  // framework-specific Vite plugin is added conditionally, further below,
@@ -517,6 +550,12 @@ function presetGenerator(tree, options) {
517
550
  vitest: VITEST_VERSION,
518
551
  '@vitest/browser-playwright': VITEST_BROWSER_PLAYWRIGHT_VERSION,
519
552
  playwright: PLAYWRIGHT_VERSION,
553
+ // Lever 4 (ADR-0140): "the stories are the claims" (ADR-0121) and nothing
554
+ // lints them today — wired into each app's eslint.config.mjs below, the
555
+ // same `flat/recommended` this monorepo's own libs/{angular,react,vue}
556
+ // already use. Pinned to STORYBOOK_VERSION like every other Storybook
557
+ // devDependency above, not a separate range.
558
+ 'eslint-plugin-storybook': STORYBOOK_VERSION,
520
559
  };
521
560
  const appName = `workshop-${framework}`;
522
561
  if (framework === 'angular') {
@@ -558,8 +597,30 @@ function presetGenerator(tree, options) {
558
597
  // React and Vue below already pass this explicitly; Angular didn't,
559
598
  // which was the actual defect, not merely a posture gap.
560
599
  linter: 'eslint',
600
+ // Lever 2 (ADR-0140): explicit, not relied-upon-as-default.
601
+ // `@nx/angular:application`'s own schema already defaults `strict` to
602
+ // `true` (`normalize-options.js`), and that default is what already
603
+ // writes `compilerOptions.strict: true` plus the three
604
+ // `angularCompilerOptions` flags below into `${appName}/tsconfig.json`
605
+ // today — verified against the real generator's source
606
+ // (`enable-strict-type-checking.js`) and a real generated tree, not
607
+ // assumed. Passing it explicitly stops that outcome from depending on
608
+ // an upstream default this repo does not control; the `updateJson`
609
+ // backstop below makes it certain either way.
610
+ strict: true,
561
611
  });
562
612
  deps['@atelier-ui/angular'] = componentPackageVersion;
613
+ // Lever 2 (ADR-0140) backstop: `angularAppGenerator`'s own `strict: true`
614
+ // above already writes these three flags (see its comment), but this
615
+ // preset's OWN generation of the outcome shouldn't depend on an nx
616
+ // default it does not control — same posture as
617
+ // `appendToFlatEslintConfig`'s throw-if-missing below. `updateJson`
618
+ // throws if `${appName}/tsconfig.json` is missing, which the application
619
+ // generator above always writes.
620
+ (0, devkit_1.updateJson)(tree, `${appName}/tsconfig.json`, (json) => {
621
+ json.angularCompilerOptions = Object.assign(Object.assign({}, json.angularCompilerOptions), { strictTemplates: true, strictInjectionParameters: true, strictInputAccessModifiers: true });
622
+ return json;
623
+ });
563
624
  // `flat/angular-template` above (written into workshop-angular's own
564
625
  // eslint.config.mjs by the application generator, confirmed by a real
565
626
  // run) already carries angular-eslint's `templateAccessibility` preset
@@ -568,6 +629,39 @@ function presetGenerator(tree, options) {
568
629
  // tagged in angular-eslint's README): WCAG 2.4.3, positive tabindex
569
630
  // fights natural DOM tab order. Same addition libs/angular's own config
570
631
  // makes on top of the identical preset.
632
+ //
633
+ // Levers 3/4/5 (ADR-0140) follow, all appended to the same file:
634
+ // - lever 3: promotes this framework's four warning-only rules that are
635
+ // genuine correctness bugs — matching this repo's OWN
636
+ // libs/angular/eslint.config.mjs, which already sets exactly these
637
+ // four to 'error' (verified: a real generated Angular app's eslint
638
+ // config leaves exactly these four, and no others, at 'warn').
639
+ // - lever 4: wires eslint-plugin-storybook's `flat/recommended` plus the
640
+ // `no-uninstalled-addons` rule, mirroring libs/angular/eslint.config.mjs
641
+ // (packageJsonLocation is one level up here — Storybook addons install
642
+ // at the scaffold's own root, not two levels up the way this
643
+ // monorepo's own libs/ nests).
644
+ // - lever 5: type-aware linting (`recommendedTypeChecked`), scoped to
645
+ // `src/**/*.ts` — exactly what `tsconfig.app.json`/`tsconfig.spec.json`
646
+ // both include, verified against a real generated tree so every file
647
+ // this matches already resolves inside one of the two referenced
648
+ // projects. The `**/*.js`/`.jsx`/`.cjs`/`.mjs` block below is a
649
+ // necessary companion, not an extra feature: `nx.configs['flat/typescript']`
650
+ // (in baseConfig) already assigns typescript-eslint's parser to
651
+ // `.ts`/`.tsx`/`.cts`/`.mts` files WITH an explicit `tsconfigRootDir`
652
+ // (the workspace root, where `nx lint` actually runs from) but its
653
+ // `.js`/`.jsx`/`.cjs`/`.mjs` sibling block assigns the same parser with
654
+ // none at all — harmless on its own, but once ANY block anywhere in
655
+ // this config enables `projectService` (as lever 5 does), typescript-
656
+ // eslint's parser service scans the whole run for tsconfig roots and
657
+ // refuses to guess a default for a file with none of its own, once more
658
+ // than one distinct root exists anywhere in the run. `eslint.config.mjs`
659
+ // itself (an `.mjs` file, linted like any other file in this project)
660
+ // hits this immediately. Verified against a real generated workspace:
661
+ // without this block, `eslint.config.mjs` fails to lint with "No
662
+ // tsconfigRootDir was set, and multiple candidate TSConfigRootDirs are
663
+ // present". Giving these files the same root nx's own block already
664
+ // uses closes the gap.
571
665
  appendToFlatEslintConfig(tree, `${appName}/eslint.config.mjs`, `,
572
666
  {
573
667
  // Not covered by \`flat/angular-template\` above (angular-eslint's own
@@ -579,7 +673,50 @@ function presetGenerator(tree, options) {
579
673
  '@angular-eslint/template/no-positive-tabindex': 'error',
580
674
  },
581
675
  },
582
- `);
676
+ ...tseslint.configs.recommendedTypeChecked.map((cfg) =>
677
+ cfg.files ? cfg : { ...cfg, files: ['src/**/*.ts'] },
678
+ ),
679
+ {
680
+ files: ['src/**/*.ts'],
681
+ languageOptions: {
682
+ parserOptions: {
683
+ projectService: true,
684
+ tsconfigRootDir: import.meta.dirname,
685
+ },
686
+ },
687
+ },
688
+ {
689
+ files: ['**/*.js', '**/*.jsx', '**/*.cjs', '**/*.mjs'],
690
+ languageOptions: {
691
+ parserOptions: {
692
+ tsconfigRootDir: dirname(import.meta.dirname),
693
+ },
694
+ },
695
+ },
696
+ {
697
+ files: ['**/*.ts'],
698
+ rules: {
699
+ '@angular-eslint/use-lifecycle-interface': 'error',
700
+ '@typescript-eslint/no-explicit-any': 'error',
701
+ '@typescript-eslint/no-non-null-assertion': 'error',
702
+ '@typescript-eslint/no-unused-vars': 'error',
703
+ },
704
+ },
705
+ ...storybook.configs['flat/recommended'],
706
+ {
707
+ files: ['.storybook/main.ts'],
708
+ rules: {
709
+ 'storybook/no-uninstalled-addons': [
710
+ 'error',
711
+ { packageJsonLocation: '../package.json' },
712
+ ],
713
+ },
714
+ },
715
+ `, [
716
+ `import { dirname } from 'node:path';`,
717
+ `import tseslint from 'typescript-eslint';`,
718
+ `import storybook from 'eslint-plugin-storybook';`,
719
+ ]);
583
720
  }
584
721
  if (framework === 'react') {
585
722
  console.log(`\n◇ Generating React workshop app…`);
@@ -597,11 +734,110 @@ function presetGenerator(tree, options) {
597
734
  skipFormat: true,
598
735
  });
599
736
  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.
737
+ // `flat/react` above (written into workshop-react's own eslint.config.mjs
738
+ // by the application generator, confirmed by a real run) already carries
739
+ // jsx-a11y's full 18-rule active set — the same rule set
740
+ // libs/react/eslint.config.mjs relies on without adding anything of its
741
+ // own either. None of jsx-a11y's own warning-only rules are touched
742
+ // below: a11y stays enforced by axe in check:stories (storybook-test), a
743
+ // stronger runtime check than these static heuristics.
744
+ //
745
+ // Levers 3/4/5 (ADR-0140), all appended below — see the identical
746
+ // structure's comment in the Angular branch above for lever 5's
747
+ // `.js`/`.jsx`/`.cjs`/`.mjs` companion block; the reasoning is the same
748
+ // for every framework, not repeated here.
749
+ //
750
+ // Lever 3: the correctness/security family of React's own warning-only
751
+ // rules. Verified against a real generated tree's own
752
+ // `eslint --print-config` for a `.tsx` file: 68 rules sit at 'warn'; the
753
+ // 26 below are the ones that flag a behavioural bug or a real security
754
+ // footgun (e.g. `react/jsx-no-target-blank`'s reverse-tabnabbing), not a
755
+ // style preference — the rest (unicode-bom, no-extra-bind,
756
+ // react/jsx-pascal-case, …) stay warnings. `react-hooks/exhaustive-deps`
757
+ // is deliberately NOT promoted: this repo's own
758
+ // libs/react/eslint.config.mjs makes the identical call (leaves it
759
+ // untouched at 'warn', the only rule this whole file doesn't already
760
+ // decide on) — a missing dependency is a real bug worth flagging, but the
761
+ // rule has a well-known false-positive rate around intentionally-omitted
762
+ // stable references (a `dispatch`, a `setState` function, a ref) and
763
+ // "run once" effects — a strict rule that fires on legitimate code
764
+ // teaches the wrong fix (suppress the warning) to a beginner audience of
765
+ // attendees and LLM agents, the one failure mode this whole change is
766
+ // built to avoid (ADR-0140).
767
+ appendToFlatEslintConfig(tree, `${appName}/eslint.config.mjs`, `,
768
+ ...tseslint.configs.recommendedTypeChecked.map((cfg) =>
769
+ cfg.files
770
+ ? cfg
771
+ : {
772
+ ...cfg,
773
+ files: ['src/**/*.ts', 'src/**/*.tsx'],
774
+ ignores: ['src/**/*.spec.ts', 'src/**/*.spec.tsx'],
775
+ },
776
+ ),
777
+ {
778
+ files: ['src/**/*.ts', 'src/**/*.tsx'],
779
+ ignores: ['src/**/*.spec.ts', 'src/**/*.spec.tsx'],
780
+ languageOptions: {
781
+ parserOptions: {
782
+ projectService: true,
783
+ tsconfigRootDir: import.meta.dirname,
784
+ },
785
+ },
786
+ },
787
+ {
788
+ files: ['**/*.js', '**/*.jsx', '**/*.cjs', '**/*.mjs'],
789
+ languageOptions: {
790
+ parserOptions: {
791
+ tsconfigRootDir: dirname(import.meta.dirname),
792
+ },
793
+ },
794
+ },
795
+ {
796
+ files: ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx'],
797
+ rules: {
798
+ eqeqeq: 'error',
799
+ 'no-eval': 'error',
800
+ 'no-implied-eval': 'error',
801
+ 'array-callback-return': 'error',
802
+ 'no-new-func': 'error',
803
+ 'no-script-url': 'error',
804
+ 'no-caller': 'error',
805
+ 'no-extend-native': 'error',
806
+ 'no-iterator': 'error',
807
+ 'no-label-var': 'error',
808
+ 'no-loop-func': 'error',
809
+ 'no-native-reassign': 'error',
810
+ 'no-negated-in-lhs': 'error',
811
+ 'no-new-wrappers': 'error',
812
+ 'no-octal-escape': 'error',
813
+ 'no-self-compare': 'error',
814
+ 'no-sequences': 'error',
815
+ 'no-template-curly-in-string': 'error',
816
+ 'no-throw-literal': 'error',
817
+ 'react/jsx-no-target-blank': 'error',
818
+ 'react/jsx-no-duplicate-props': 'error',
819
+ 'react/jsx-no-comment-textnodes': 'error',
820
+ 'react/no-direct-mutation-state': 'error',
821
+ 'react/no-is-mounted': 'error',
822
+ 'react/no-danger-with-children': 'error',
823
+ 'react/style-prop-object': 'error',
824
+ },
825
+ },
826
+ ...storybook.configs['flat/recommended'],
827
+ {
828
+ files: ['.storybook/main.ts'],
829
+ rules: {
830
+ 'storybook/no-uninstalled-addons': [
831
+ 'error',
832
+ { packageJsonLocation: '../package.json' },
833
+ ],
834
+ },
835
+ },
836
+ `, [
837
+ `import { dirname } from 'node:path';`,
838
+ `import tseslint from 'typescript-eslint';`,
839
+ `import storybook from 'eslint-plugin-storybook';`,
840
+ ]);
605
841
  }
606
842
  if (framework === 'vue') {
607
843
  console.log(`\n◇ Generating Vue workshop app…`);
@@ -653,6 +889,40 @@ function presetGenerator(tree, options) {
653
889
  // the generator, and @nx/vue already turns off the rule most likely to
654
890
  // misfire on plain .ts — vue/multi-word-component-names — project-wide
655
891
  // on its own). Recorded here rather than silently left unmentioned.
892
+ // Levers 3/4/5 (ADR-0140), appended below alongside the two blocks above.
893
+ //
894
+ // Lever 3: four of the ~30 `vue/*` rules Vue's own warning tier carries
895
+ // are genuine correctness/security bugs, not the layout/whitespace style
896
+ // rules the eslintConfigPrettier block above already neutralises —
897
+ // `no-v-html` is this framework's `dangerouslySetInnerHTML` (an XSS
898
+ // vector, the same security family as `no-eval`), `no-required-prop-with-default`
899
+ // and `no-template-shadow` catch real logic bugs, and
900
+ // `require-explicit-emits` is the emitted-event counterpart to the
901
+ // already-promoted `no-unused-properties` (declare what you actually
902
+ // emit, the same way you declare what you actually read). The rest —
903
+ // attribute ordering, html-indent, component-name casing, and every
904
+ // other rule eslintConfigPrettier.rules doesn't already turn off — stay
905
+ // warnings: this repo's own libs/vue/eslint.config.mjs makes the
906
+ // identical call (it doesn't touch a single one of them either).
907
+ //
908
+ // Lever 4: eslint-plugin-storybook's `flat/recommended`, mirroring
909
+ // libs/vue/eslint.config.mjs (packageJsonLocation is one level up here).
910
+ //
911
+ // Lever 5: type-aware linting, including `.vue` SFCs — most Vue
912
+ // component code lives in `.vue` files, not `.ts`, so a `.ts`-only scope
913
+ // would miss the majority of what an attendee actually writes. The
914
+ // `.vue`-scoped block below re-specifies `parser` alongside
915
+ // `projectService`/`tsconfigRootDir`/`extraFileExtensions` in ONE
916
+ // object, not split across two — verified against a real generated
917
+ // workspace that splitting them (a second, later block adding only
918
+ // `projectService`+`tsconfigRootDir` next to the app generator's own
919
+ // parser-only block above) reproduces the exact "No tsconfigRootDir was
920
+ // set, and multiple candidate TSConfigRootDirs are present" failure
921
+ // lever 5's own `.js`/`.jsx`/`.cjs`/`.mjs` companion block (see the
922
+ // identical block's comment in the Angular branch above) exists to avoid
923
+ // for plain files — vue-eslint-parser's delegate-parsing does not pick
924
+ // up a later block's parserOptions the same way ESLint's own
925
+ // language-options merge does for every other file type in this preset.
656
926
  appendToFlatEslintConfig(tree, `${appName}/eslint.config.mjs`, `,
657
927
  {
658
928
  // eslint-plugin-vue's flat/recommended (spread above by @nx/vue's own
@@ -670,8 +940,106 @@ function presetGenerator(tree, options) {
670
940
  'vue/no-unused-properties': ['error', { groups: ['props'] }],
671
941
  },
672
942
  },
673
- `, [`import eslintConfigPrettier from 'eslint-config-prettier';`]);
943
+ ...tseslint.configs.recommendedTypeChecked.map((cfg) =>
944
+ cfg.files
945
+ ? cfg
946
+ : {
947
+ ...cfg,
948
+ files: ['src/**/*.ts', 'src/**/*.vue'],
949
+ ignores: ['src/**/*.spec.ts'],
950
+ },
951
+ ),
952
+ {
953
+ // Re-specifies \`parser\` alongside the type-aware options in one block —
954
+ // see this branch's comment above for why splitting them fails.
955
+ files: ['**/*.vue'],
956
+ languageOptions: {
957
+ parserOptions: {
958
+ parser: await import('@typescript-eslint/parser'),
959
+ projectService: true,
960
+ tsconfigRootDir: import.meta.dirname,
961
+ extraFileExtensions: ['.vue'],
962
+ },
963
+ },
964
+ },
965
+ {
966
+ files: ['src/**/*.ts'],
967
+ ignores: ['src/**/*.spec.ts'],
968
+ languageOptions: {
969
+ parserOptions: {
970
+ projectService: true,
971
+ tsconfigRootDir: import.meta.dirname,
972
+ },
973
+ },
974
+ },
975
+ {
976
+ files: ['**/*.js', '**/*.jsx', '**/*.cjs', '**/*.mjs'],
977
+ languageOptions: {
978
+ parserOptions: {
979
+ tsconfigRootDir: dirname(import.meta.dirname),
980
+ },
981
+ },
982
+ },
983
+ {
984
+ files: ['**/*.vue'],
985
+ rules: {
986
+ 'vue/no-v-html': 'error',
987
+ 'vue/no-required-prop-with-default': 'error',
988
+ 'vue/no-template-shadow': 'error',
989
+ 'vue/require-explicit-emits': 'error',
990
+ },
991
+ },
992
+ ...storybook.configs['flat/recommended'],
993
+ {
994
+ files: ['.storybook/main.ts'],
995
+ rules: {
996
+ 'storybook/no-uninstalled-addons': [
997
+ 'error',
998
+ { packageJsonLocation: '../package.json' },
999
+ ],
1000
+ },
1001
+ },
1002
+ `, [
1003
+ `import eslintConfigPrettier from 'eslint-config-prettier';`,
1004
+ `import { dirname } from 'node:path';`,
1005
+ `import tseslint from 'typescript-eslint';`,
1006
+ `import storybook from 'eslint-plugin-storybook';`,
1007
+ ]);
674
1008
  }
1009
+ // ─── Strictness (lever 1, ADR-0140) ──────────────────────────────────────
1010
+ // `tsconfig.base.json` does NOT exist yet at the top of this function —
1011
+ // measured directly against a real `create-nx-workspace` run (not assumed
1012
+ // from reading `@nx/js`'s source): `create-nx-workspace` writes only
1013
+ // package.json/nx.json/.gitignore before invoking this preset, and
1014
+ // `tsconfig.base.json` is written for the first time by whichever
1015
+ // framework's own `@nx/{angular,react,vue}:application` generator just ran
1016
+ // above — confirmed for all three by running each real (unmocked)
1017
+ // generator against a tree with the file deliberately absent beforehand.
1018
+ // Placing this write any earlier reproduced exactly the failure this
1019
+ // comment now guards against: `updateJson` throwing `Cannot find
1020
+ // tsconfig.base.json` at scaffold time, before a single check could run.
1021
+ // `createTreeWithEmptyWorkspace()` (used by this file's own tests)
1022
+ // pre-seeds a bare `{ compilerOptions: { paths: {} } }` tsconfig.base.json
1023
+ // regardless of generator order, which is exactly why that in-memory-tree
1024
+ // testing setup could not have caught the ordering bug on its own — see
1025
+ // this preset's mocked app generators, which now also write
1026
+ // tsconfig.base.json themselves (dedicated tests below cover the ordering
1027
+ // directly instead).
1028
+ //
1029
+ // `tsConfigBaseOptions` (`@nx/js`'s own default, written by the framework
1030
+ // generator above) pins `strict: false` deliberately — "TS 6.0 flips the
1031
+ // `strict` default to true; pin false to keep this base config's behavior
1032
+ // identical on TS 5.8 and 6.0" (that package's own comment). Measured
1033
+ // against a real generated tree, all three frameworks: `strict: false`
1034
+ // there, and the app itself already builds clean with `strict: true` —
1035
+ // nobody has fixed code for this, so flipping it costs no migration.
1036
+ console.log(`\n◇ Wiring strict TypeScript…`);
1037
+ (0, devkit_1.updateJson)(tree, 'tsconfig.base.json', (json) => {
1038
+ var _a;
1039
+ json.compilerOptions = (_a = json.compilerOptions) !== null && _a !== void 0 ? _a : {};
1040
+ json.compilerOptions.strict = true;
1041
+ return json;
1042
+ });
675
1043
  // Copy design tokens into the scaffolded app so attendees can edit them
676
1044
  // directly. They're not imported from the @atelier-ui/<fw> npm package
677
1045
  // because (a) those published packages don't ship tokens.css, and (b) a
@@ -718,6 +1086,17 @@ function presetGenerator(tree, options) {
718
1086
  // app, same purpose as atl-button.stories.*: the pattern that gets copied.
719
1087
  tree.write(`${appName}/vitest.unit.config.ts`, readTemplate(testingTemplateName(framework, 'vitest.unit.config')));
720
1088
  tree.write(`${appName}/src/test-setup.ts`, readTemplate(testingTemplateName(framework, 'test-setup')));
1089
+ // Portable stories (composeStories) let a jsdom unit test import a
1090
+ // *.stories.* file directly instead of hand-duplicating what its stories
1091
+ // already claim (ADR-0121, ADR-0141). React and Vue only:
1092
+ // @storybook/angular(-vite)@10.6.0 exports setProjectAnnotations but not
1093
+ // composeStories/composeStory (verified against the installed dist;
1094
+ // tracked upstream as storybookjs/storybook#28897) — wiring
1095
+ // setProjectAnnotations alone would register project config nothing in
1096
+ // this workspace could yet consume. See ADR-0141.
1097
+ if (framework !== 'angular') {
1098
+ tree.write(`${appName}/src/test-setup-stories.ts`, readTemplate(testingTemplateName(framework, 'test-setup-stories')));
1099
+ }
721
1100
  tree.write(`${appName}/src/atl-button.spec.${storybookOutputExt(framework)}`, readTemplate(testingTemplateName(framework, 'atl-button.spec')));
722
1101
  // The application generator (@nx/{angular,react,vue}:application, above)
723
1102
  // guarantees `${appName}/project.json` exists at this point — updateJson
@@ -788,19 +1167,30 @@ function presetGenerator(tree, options) {
788
1167
  return config;
789
1168
  });
790
1169
  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:
1170
+ // @storybook/react-vite and @storybook/vue3-vite each carry their non-vite
1171
+ // renderer counterpart as a plain (non-peer) `dependency` regardless of
1172
+ // whether it's declared explicitly here. It used to also be load-bearing
1173
+ // for a type import: the story and preview templates imported
1174
+ // `Meta`/`StoryObj`/`Preview` straight from '@storybook/react' /
1175
+ // '@storybook/vue3', which resolved only because npm hoists it (pnpm's
1176
+ // stricter, non-hoisted layout would have left it unresolved). ADR-0140
1177
+ // (lever 4, eslint-plugin-storybook) moved both templates to import those
1178
+ // same types from '@storybook/react-vite' / '@storybook/vue3-vite' instead
1179
+ // — the same types are re-exported there (confirmed: this monorepo's own
1180
+ // libs/react and libs/vue stories already import them from the `-vite`
1181
+ // packages) — because eslint-plugin-storybook's `no-renderer-packages` rule
1182
+ // flags importing the renderer package directly, and the scaffold's own
1183
+ // example must pass its own new linter. The explicit devDependency below
1184
+ // stays anyway: harmless (the vite package already pulls it in
1185
+ // transitively), and it remains available for anyone who wants the
1186
+ // renderer package's own types directly. Angular has no matching case:
798
1187
  // '@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).
1188
+ // angular templates already imported their types from
1189
+ // '@storybook/angular-vite' itself (see files/storybook/angular/*.template)
1190
+ // — adding '@storybook/angular' back here would reintroduce exactly the
1191
+ // ERESOLVE this generator now avoids (its peer on
1192
+ // @angular-devkit/build-angular is not satisfiable by a freshly scaffolded
1193
+ // Angular 22 app).
804
1194
  if (framework === 'react') {
805
1195
  storybookDevDeps['@storybook/react'] = STORYBOOK_VERSION;
806
1196
  }
@@ -861,33 +1251,47 @@ function presetGenerator(tree, options) {
861
1251
  };
862
1252
  return config;
863
1253
  });
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
- });
1254
+ // ─── The contract loop (ADR-0121 S4, gated by --figma since ADR-0144) ────
1255
+ // ADR-0121 defines a contract AS the set of deliberate Figma ↔ code
1256
+ // mismatches — with no Figma there is nothing for a contract to disagree
1257
+ // with, so `options.figmaMcp` (the same flag that decides whether
1258
+ // `figma-console` reaches .mcp.json, below) is the one switch for this
1259
+ // whole loop: the contract files, the two loop scripts + their shared
1260
+ // lib/, the Figma snapshot projection, and contracts.config.json.
1261
+ // check-contracts.mjs's own snapshot read
1262
+ // (`JSON.parse(fs.readFileSync(snapshotPath, ...))`) is unguarded — it
1263
+ // throws, not degrades, the moment tools/figma/snapshot.json is missing —
1264
+ // so shipping the script without the rest of this block would hand an
1265
+ // attendee a gate that crashes on first run, not a lenient one.
1266
+ if (options.figmaMcp) {
1267
+ console.log(`\n◇ Writing the contract loop (check:contracts, the example AtlButton contract, the Figma snapshot projection)…`);
1268
+ // .ts.template, not .ts — see the comment on storybookTemplateName() above:
1269
+ // a literal `.ts` file under files/ is compiled away by this package's own
1270
+ // tsconfig.lib.json (`include: ["src/**/*.ts"]`) and never reaches dist/
1271
+ // under a name readTemplate() can find at runtime. The OUTPUT filenames
1272
+ // below stay plain `.ts` — only the template source needs the suffix.
1273
+ tree.write(`${appName}/src/contracts/types.ts`, readTemplate('contracts/types.ts.template'));
1274
+ tree.write(`${appName}/src/contracts/README.md`, readTemplate('contracts/README.md'));
1275
+ tree.write(`${appName}/src/contracts/button.contract.ts`, readTemplate('contracts/button.contract.ts.template'));
1276
+ tree.write('tools/scripts/check-contracts.mjs', readTemplate('tools/scripts/check-contracts.mjs'));
1277
+ tree.write('tools/scripts/lib/ts-eval.js', readTemplate('tools/scripts/lib/ts-eval.js'));
1278
+ tree.write('tools/scripts/lib/docgen.mjs', readTemplate('tools/scripts/lib/docgen.mjs'));
1279
+ tree.write('tools/scripts/figma-snapshot-contracts.mjs', readTemplate('tools/scripts/figma-snapshot-contracts.mjs'));
1280
+ // The AtlButton-only projection of this repo's own tools/figma/snapshot.json
1281
+ // (gen-scaffold-snapshot.mjs) — gives check:contracts a Figma side for the
1282
+ // example contract + story on day one, before the attendee ever runs
1283
+ // figma:snapshot themselves.
1284
+ tree.write('tools/figma/snapshot.json', readTemplate('figma/snapshot.json'));
1285
+ (0, devkit_1.writeJson)(tree, 'contracts.config.json', {
1286
+ framework,
1287
+ contracts: `${appName}/src/contracts`,
1288
+ stories: [`${appName}/src`],
1289
+ snapshot: 'tools/figma/snapshot.json',
1290
+ });
1291
+ }
1292
+ else {
1293
+ console.log(`\n◇ Skipping the contract loop (--no-figma) — no Figma, no contract (ADR-0144)…`);
1294
+ }
891
1295
  console.log(`\n◇ Writing project files (CLAUDE.md, README, .mcp.json)…`);
892
1296
  // Write CLAUDE.md with framework-specific guidance
893
1297
  let frameworkSection = '';
@@ -994,6 +1398,73 @@ npm install @atelier-ui/${framework}@latest
994
1398
  duplicate the file again`
995
1399
  : `edit the \`--file\` placeholder in \`package.json\`'s \`figma:snapshot\` script to
996
1400
  your own Figma file key`;
1401
+ // The Contract Loop (ADR-0121 S4) is gated on Figma too (ADR-0144): ADR-0121
1402
+ // defines a contract AS the deliberate Figma ↔ code mismatch set, so with no
1403
+ // Figma there is nothing for one to disagree with — the whole section is
1404
+ // omitted under --no-figma, not left dangling pointing at files this
1405
+ // workspace never wrote.
1406
+ const contractLoopSection = options.figmaMcp
1407
+ ? `
1408
+ ## The Contract Loop
1409
+
1410
+ A contract (\`${appName}/src/contracts/<name>.contract.ts\`) is the one hand-authored
1411
+ spec file per component: the Figma master's node id, plus intentional Figma ↔ code
1412
+ mismatches (\`figmaOnly\`, \`codeOnly\`, \`axisMap\`) — never props, defaults, or
1413
+ descriptions; those live in the component's own types/JSDoc and its stories.
1414
+
1415
+ Order: read the Figma handoff → write the contract → write one story per variant and
1416
+ interaction state → \`npm run check:contracts\` → \`figma_check_design_parity\` in Storybook.
1417
+
1418
+ \`check:contracts\` joins the contract, the component's docgen, and \`tools/figma/snapshot.json\`
1419
+ offline — no browser, no Storybook build — and reports one line per finding:
1420
+ - \`[CONTRACT-MISSING]\` / \`[CONTRACT-NODE]\` — no contract file, or its node id disagrees
1421
+ - \`[AXIS]\` / \`[BOOLEAN]\` / \`[ENUM-UNDRAWN]\` — a Figma property has no matching code prop
1422
+ - \`[COVERAGE]\` / \`[COVERAGE-BOOL]\` — a variant value or boolean is never rendered by a story
1423
+ - \`[FIGMA-ONLY]\` / \`[STALE-EXEMPTION]\` / \`[UNMIRRORED]\` — an exemption is missing, stale, or unexplained
1424
+ - \`[NO-STORY-META]\` / \`[NO-MASTER]\` — a contract with nothing yet to check it against
1425
+ - \`[CONTRACT-IMPORT]\` — a story meta doesn't import its component's contract and set
1426
+ \`contract\` in \`parameters\` (a warning here, until this workspace ships a docs block
1427
+ that renders it)
1428
+
1429
+ Refresh \`tools/figma/snapshot.json\` from the real master with the Figma Desktop Bridge
1430
+ connected: ${figmaSnapshotRefreshInstruction}, then run \`npm run figma:snapshot\`.
1431
+
1432
+ \`check:contracts\` proves shape and story coverage; \`npm run check:stories\` (every story,
1433
+ rendered headless in Chromium via \`@storybook/addon-vitest\`, with axe) proves rendering
1434
+ and accessibility. It does so for components whose source lives in this workspace. For
1435
+ components imported from \`@atelier-ui/${framework}\` — the example \`AtlButton\`
1436
+ included — the check recognises that the import resolves into \`node_modules\` and skips
1437
+ docgen for it — the same rule in every framework — so it has nothing to compare and
1438
+ reports only \`[NO-STORY-META]\`; their prop tables come from the hosted
1439
+ Storybook MCP (\`docs-show\`) instead. A green \`check:contracts\` on the example story
1440
+ therefore proves the wiring, not the example. Run \`npx playwright install chromium\`
1441
+ once after \`npm install\` — see Storybook below.
1442
+ `
1443
+ : '';
1444
+ // Agent Skills intro blurb (below): the two sentences naming what the
1445
+ // unconditional atelier-component skill actually runs vary with the same
1446
+ // flag — no dangling mention of check:contracts when this workspace never
1447
+ // wrote one.
1448
+ const atelierComponentSkillBlurb = options.figmaMcp
1449
+ ? `It runs the Figma → contract → stories → checks loop scoped to what this workspace can
1450
+ actually check — see the skill itself, or ask Claude Code to use it, for the loop and
1451
+ \`check:contracts\`'s finding codes.`
1452
+ : `It runs the component → stories → checks loop this workspace ships without Figma —
1453
+ see the skill itself, or ask Claude Code to use it, for what each check actually proves.`;
1454
+ // Definition of Done (below): four checks without Figma, five with it —
1455
+ // `check:contracts` only exists when the contract loop does (ADR-0144).
1456
+ const doneChecks = [
1457
+ '`npm run check:format` — Prettier',
1458
+ '`npm run check:stylelint` — the ported CSS-discipline rules',
1459
+ ...(options.figmaMcp
1460
+ ? [
1461
+ '`npm run check:contracts` — contract ↔ docgen ↔ Figma-snapshot parity',
1462
+ ]
1463
+ : []),
1464
+ '`npm run check:unit` — jsdom unit tests (components, composables, helpers)',
1465
+ '`npm run check:stories` — every story, rendered in Chromium, axe-checked',
1466
+ ];
1467
+ const doneCountWord = doneChecks.length === 5 ? 'five' : 'four';
997
1468
  tree.write('CLAUDE.md', `# Atelier Workshop
998
1469
 
999
1470
  This workspace uses Atelier for all UI components.
@@ -1083,10 +1554,7 @@ npm run check:stories
1083
1554
 
1084
1555
  This workspace also ships \`atelier-component\` (\`.claude/skills/atelier-component/SKILL.md\`)
1085
1556
  unconditionally — this generator writes it straight to disk as part of scaffolding, with no
1086
- network fetch and no \`skills: false\` opt-out, unlike the four skills below. It runs the
1087
- Figma → contract → stories → checks loop scoped to what this workspace can actually check —
1088
- see the skill itself, or ask Claude Code to use it, for the loop and \`check:contracts\`'s
1089
- finding codes.
1557
+ network fetch and no \`skills: false\` opt-out, unlike the four skills below. ${atelierComponentSkillBlurb}
1090
1558
 
1091
1559
  ${skillsEnabled
1092
1560
  ? `The scaffold attempted to install four \`storybookjs/mcp\` skills for Claude
@@ -1129,7 +1597,7 @@ then add this to \`.mcp.json\`'s \`mcpServers\` (only while that Storybook is up
1129
1597
  (\`<port>\` is the one listed for that app under Storybook below.) \`test-run\`
1130
1598
  works too, once that local Storybook is running — every story here IS a
1131
1599
  render + accessibility test (\`@storybook/addon-vitest\`, run offline via
1132
- \`npm run check:stories\`; see "The Contract Loop" below).`
1600
+ \`npm run check:stories\`${options.figmaMcp ? '; see "The Contract Loop" below' : ''}).`
1133
1601
  : `Skipped for this workspace (\`skills: false\`). Install the four \`storybookjs/mcp\`
1134
1602
  skills for Claude Code by hand:
1135
1603
 
@@ -1147,56 +1615,25 @@ has generated code for one component can infer the shape of the next. When you d
1147
1615
  the API of your own component, these are the rules the library itself follows:
1148
1616
 
1149
1617
  - Guide: ${SITE_URL}/design-principles
1150
-
1151
- ## The Contract Loop
1152
-
1153
- A contract (\`${appName}/src/contracts/<name>.contract.ts\`) is the one hand-authored
1154
- spec file per component: the Figma master's node id, plus intentional Figma ↔ code
1155
- mismatches (\`figmaOnly\`, \`codeOnly\`, \`axisMap\`) — never props, defaults, or
1156
- descriptions; those live in the component's own types/JSDoc and its stories.
1157
-
1158
- Order: read the Figma handoff → write the contract → write one story per variant and
1159
- interaction state → \`npm run check:contracts\` → \`figma_check_design_parity\` in Storybook.
1160
-
1161
- \`check:contracts\` joins the contract, the component's docgen, and \`tools/figma/snapshot.json\`
1162
- offline — no browser, no Storybook build — and reports one line per finding:
1163
- - \`[CONTRACT-MISSING]\` / \`[CONTRACT-NODE]\` — no contract file, or its node id disagrees
1164
- - \`[AXIS]\` / \`[BOOLEAN]\` / \`[ENUM-UNDRAWN]\` — a Figma property has no matching code prop
1165
- - \`[COVERAGE]\` / \`[COVERAGE-BOOL]\` — a variant value or boolean is never rendered by a story
1166
- - \`[FIGMA-ONLY]\` / \`[STALE-EXEMPTION]\` / \`[UNMIRRORED]\` — an exemption is missing, stale, or unexplained
1167
- - \`[NO-STORY-META]\` / \`[NO-MASTER]\` — a contract with nothing yet to check it against
1168
- - \`[CONTRACT-IMPORT]\` — a story meta doesn't import its component's contract and set
1169
- \`contract\` in \`parameters\` (a warning here, until this workspace ships a docs block
1170
- that renders it)
1171
-
1172
- Refresh \`tools/figma/snapshot.json\` from the real master with the Figma Desktop Bridge
1173
- connected: ${figmaSnapshotRefreshInstruction}, then run \`npm run figma:snapshot\`.
1174
-
1175
- \`check:contracts\` proves shape and story coverage; \`npm run check:stories\` (every story,
1176
- rendered headless in Chromium via \`@storybook/addon-vitest\`, with axe) proves rendering
1177
- and accessibility. It does so for components whose source lives in this workspace. For
1178
- components imported from \`@atelier-ui/${framework}\` — the example \`AtlButton\`
1179
- included — the check recognises that the import resolves into \`node_modules\` and skips
1180
- docgen for it — the same rule in every framework — so it has nothing to compare and
1181
- reports only \`[NO-STORY-META]\`; their prop tables come from the hosted
1182
- Storybook MCP (\`docs-show\`) instead. A green \`check:contracts\` on the example story
1183
- therefore proves the wiring, not the example. Run \`npx playwright install chromium\`
1184
- once after \`npm install\` — see Storybook below.
1185
-
1618
+ ${contractLoopSection}
1186
1619
  ## Definition of Done
1187
1620
 
1188
- A change here is done when all five of these pass:
1621
+ This workspace is strict, not lenient-by-default: \`tsconfig.base.json\` has
1622
+ \`strict: true\`, and \`npm run lint\` promotes the correctness/security family of rules
1623
+ (\`eqeqeq\`, \`no-eval\`, and their kin — see \`eslint.config.mjs\` for the exact set) plus
1624
+ type-aware checks (\`no-floating-promises\`, \`no-misused-promises\`, \`await-thenable\`)
1625
+ to errors. That is the feedback loop this workspace hands an LLM, not friction to prompt
1626
+ around: code Claude Code (or you) writes has to satisfy \`npm run lint\` and \`npm run
1627
+ build\` before it is done, the same way it has to satisfy the ${doneCountWord} checks below.
1189
1628
 
1190
- - \`npm run check:format\` — Prettier
1191
- - \`npm run check:stylelint\` — the ported CSS-discipline rules
1192
- - \`npm run check:contracts\` — contract ↔ docgen ↔ Figma-snapshot parity
1193
- - \`npm run check:unit\` — jsdom unit tests (components, composables, helpers)
1194
- - \`npm run check:stories\` — every story, rendered in Chromium, axe-checked
1629
+ A change here is done when all ${doneCountWord} of these pass:
1630
+
1631
+ ${doneChecks.map((c) => `- ${c}`).join('\n')}
1195
1632
 
1196
1633
  **A gate's result is its exit code.** Run it as
1197
1634
  \`<command> > /tmp/x.log 2>&1; echo $?\` and read the log afterwards — never pipe
1198
1635
  a gate into \`head\` or \`grep\`. The pipe's own exit status is always \`0\`, which
1199
- silently turns a failing gate into a passing one. \`/verify\` runs all five and
1636
+ silently turns a failing gate into a passing one. \`/verify\` runs all ${doneCountWord} and
1200
1637
  reports each exit code (\`.claude/commands/verify.md\`).
1201
1638
 
1202
1639
  ## Troubleshooting
@@ -1228,20 +1665,32 @@ file exports). The Desktop Bridge covers creation and inspection without a token
1228
1665
  - MCP Playground (inspect tool responses): ${SITE_URL}/mcp
1229
1666
  - CLAUDE.md template: ${SITE_URL}/claude-md
1230
1667
  `);
1231
- // The contract loop's own devDependencies (ADR-0121 S4): the MCP SDK
1232
- // figma-snapshot-contracts.mjs imports directly, always; `typescript` only
1233
- // when the framework application generator (above) didn't already add it —
1234
- // read from the tree's package.json as it stands right now, after the
1235
- // framework's generator has run and before this generator's own writes
1236
- // below it.
1668
+ // The contract loop's own devDependencies (ADR-0121 S4), gated on Figma
1669
+ // (ADR-0144) — neither exists without `--figma`: the MCP SDK is only
1670
+ // imported by figma-snapshot-contracts.mjs, and the defensive `typescript`
1671
+ // add exists only because ts-eval.js (shared by check-contracts.mjs and
1672
+ // figma-snapshot-contracts.mjs) needs it at runtime — read from the tree's
1673
+ // package.json as it stands right now, after the framework's generator has
1674
+ // run and before this generator's own writes below it.
1237
1675
  const pkgSoFar = (0, devkit_1.readJson)(tree, 'package.json');
1238
1676
  const existingDeps = Object.assign(Object.assign({}, ((_d = pkgSoFar.dependencies) !== null && _d !== void 0 ? _d : {})), ((_e = pkgSoFar.devDependencies) !== null && _e !== void 0 ? _e : {}));
1239
1677
  const hasTypescript = Boolean(existingDeps.typescript);
1240
- const contractLoopDevDeps = {
1241
- '@modelcontextprotocol/sdk': MCP_SDK_VERSION,
1242
- };
1243
- if (!hasTypescript) {
1244
- contractLoopDevDeps.typescript = TYPESCRIPT_VERSION;
1678
+ const contractLoopDevDeps = {};
1679
+ if (options.figmaMcp) {
1680
+ contractLoopDevDeps['@modelcontextprotocol/sdk'] = MCP_SDK_VERSION;
1681
+ if (!hasTypescript) {
1682
+ contractLoopDevDeps.typescript = TYPESCRIPT_VERSION;
1683
+ }
1684
+ }
1685
+ // Lever 5 (ADR-0140): `typescript-eslint`, imported by each framework's own
1686
+ // eslint.config.mjs addition above (`tseslint.configs.recommendedTypeChecked`).
1687
+ // Defensive add, not the primary source — see TYPESCRIPT_ESLINT_VERSION's own
1688
+ // comment: a real generated tree for all three frameworks already carries
1689
+ // this in devDependencies, added independently by each framework's own
1690
+ // application generator.
1691
+ const typeAwareLintDevDeps = {};
1692
+ if (!existingDeps['typescript-eslint']) {
1693
+ typeAwareLintDevDeps['typescript-eslint'] = TYPESCRIPT_ESLINT_VERSION;
1245
1694
  }
1246
1695
  // Browser-mode Storybook tests (owner correction 2026-09-10 to ADR-0123):
1247
1696
  // the selected framework needs its own Vite plugin for the vitest browser
@@ -1309,7 +1758,7 @@ file exports). The Desktop Bridge covers creation and inspection without a token
1309
1758
  // the contract loop's own tools + the vitest browser-mode tooling + the
1310
1759
  // unit test runner's own tooling (S5) + stylelint + prettier
1311
1760
  // (devDependencies, exact pins — see the *_VERSION constants above)
1312
- 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));
1761
+ const installTask = (0, devkit_1.addDependenciesToPackageJson)(tree, deps, Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, storybookDevDeps), contractLoopDevDeps), viteFrameworkDevDeps), unitTestDevDeps), stylelintDevDeps), prettierDevDeps), typeAwareLintDevDeps));
1313
1762
  // Remove the preset package itself — create-nx-workspace adds it automatically
1314
1763
  // but it's a build-time tool and should not be in the workspace's dependencies
1315
1764
  const removePresetTask = (0, devkit_1.removeDependenciesFromPackageJson)(tree, ['@atelier-ui/create-workspace'], []);
@@ -1323,17 +1772,21 @@ file exports). The Desktop Bridge covers creation and inspection without a token
1323
1772
  var _a;
1324
1773
  pkg.scripts = (_a = pkg.scripts) !== null && _a !== void 0 ? _a : {};
1325
1774
  pkg.scripts.preflight = 'node tools/scripts/preflight.mjs';
1326
- // The contract loop (ADR-0121 S4). `figma:snapshot` names the attendee's
1327
- // own Figma file key (schema option `figmaFile`, S5a) when the caller
1328
- // supplied one — QMnDD8uZQPldPrlCwZZ58T is THIS repo's own file, never a
1329
- // default here. Most direct-preset callers have no key to hand, so
1330
- // without one it ships with the same literal placeholder as before;
1331
- // CLAUDE.md's "The Contract Loop" section (figmaSnapshotRefreshInstruction
1332
- // above) spells out how to fill it in either way.
1333
- pkg.scripts['check:contracts'] = 'node tools/scripts/check-contracts.mjs';
1334
- pkg.scripts['figma:snapshot'] = options.figmaFile
1335
- ? `node tools/scripts/figma-snapshot-contracts.mjs --file ${options.figmaFile}`
1336
- : 'node tools/scripts/figma-snapshot-contracts.mjs --file <YOUR_FIGMA_FILE_KEY>';
1775
+ // The contract loop (ADR-0121 S4), gated on Figma (ADR-0144): neither
1776
+ // script exists without `--figma` — see the contract-loop file-writing
1777
+ // block above. `figma:snapshot` names the attendee's own Figma file key
1778
+ // (schema option `figmaFile`, S5a) when the caller supplied one —
1779
+ // QMnDD8uZQPldPrlCwZZ58T is THIS repo's own file, never a default here.
1780
+ // Most direct-preset callers have no key to hand, so without one it ships
1781
+ // with the same literal placeholder as before; CLAUDE.md's "The Contract
1782
+ // Loop" section (figmaSnapshotRefreshInstruction above) spells out how to
1783
+ // fill it in either way.
1784
+ if (options.figmaMcp) {
1785
+ pkg.scripts['check:contracts'] = 'node tools/scripts/check-contracts.mjs';
1786
+ pkg.scripts['figma:snapshot'] = options.figmaFile
1787
+ ? `node tools/scripts/figma-snapshot-contracts.mjs --file ${options.figmaFile}`
1788
+ : 'node tools/scripts/figma-snapshot-contracts.mjs --file <YOUR_FIGMA_FILE_KEY>';
1789
+ }
1337
1790
  // Browser-mode Storybook tests (owner correction 2026-09-10 to ADR-0123).
1338
1791
  // Identical to the monorepo's own root package.json script.
1339
1792
  pkg.scripts['check:stories'] = 'nx run-many -t storybook-test --parallel=1';
@@ -1546,15 +1999,15 @@ Browse components at ${SITE_URL}
1546
1999
  // check) and anything an attendee or agent reaches for beyond the
1547
2000
  // fixed script set.
1548
2001
  'Bash(npx nx *)',
1549
- // The fourteen npm scripts this preset writes to package.json
1550
- // (preflight, check:contracts, figma:snapshot, check:unit,
1551
- // check:stories, check:stylelint, format, check:format, start,
1552
- // build, lint, storybook, build:storybook, test) — one wildcard
1553
- // entry rather than fourteen separate ones, since this workspace's
1554
- // package.json carries exactly this fixed, generator-written script
1555
- // set (a workshop attendee adding a script of their own opts into
1556
- // this same allowance by definition, having already edited
1557
- // package.json by hand).
2002
+ // The npm scripts this preset writes to package.json (preflight,
2003
+ // check:unit, check:stories, check:stylelint, format, check:format,
2004
+ // start, build, lint, storybook, build:storybook, test, plus
2005
+ // check:contracts/figma:snapshot when `--figma` is on, ADR-0144) —
2006
+ // one wildcard entry rather than one per script, since this
2007
+ // workspace's package.json carries exactly this fixed,
2008
+ // generator-written script set (a workshop attendee adding a script
2009
+ // of their own opts into this same allowance by definition, having
2010
+ // already edited package.json by hand).
1558
2011
  'Bash(npm run *)',
1559
2012
  // `npm run *` above does not match npm's own bare-word aliases —
1560
2013
  // `npm start` and `npm test` are literally different argv than `npm
@@ -1644,23 +2097,30 @@ Browse components at ${SITE_URL}
1644
2097
  // narrower, more honest fit for what this actually is: a fixed action a
1645
2098
  // person explicitly triggers, with nothing for the model to decide about
1646
2099
  // *whether* to invoke it — the thing SKILL.md's richer description-driven
1647
- // auto-triggering and multi-file bundling exist for. Four fixed npm
1648
- // scripts and "read the exit code" is exactly the shape commands/*.md is
1649
- // for.
1650
- tree.write('.claude/commands/verify.md', readTemplate('claude/commands/verify.md'));
2100
+ // auto-triggering and multi-file bundling exist for. Four or five fixed npm
2101
+ // scripts (ADR-0144 — `check:contracts` only exists with `--figma`) and
2102
+ // "read the exit code" is exactly the shape commands/*.md is for.
2103
+ tree.write('.claude/commands/verify.md', readTemplate(options.figmaMcp
2104
+ ? 'claude/commands/verify.md'
2105
+ : 'claude/commands/verify.no-figma.md'));
1651
2106
  // Read-only review subagent (Read/Grep/Glob/Bash only — no Edit/Write), so
1652
2107
  // it can inspect and even run a gate for corroboration but never fix what
1653
2108
  // it finds. Static, like the hook and the command above: the checklist
1654
- // (contract / stories / a11y) is the same shape regardless of framework,
1655
- // and the agent discovers the one scaffolded app itself via Glob.
1656
- tree.write('.claude/agents/component-review.md', readTemplate('claude/agents/component-review.md'));
2109
+ // (contract / stories / a11y) is the same shape regardless of framework —
2110
+ // it varies only with `--figma` (ADR-0144: no contract file exists to
2111
+ // review without one) — and the agent discovers the one scaffolded app
2112
+ // itself via Glob.
2113
+ tree.write('.claude/agents/component-review.md', readTemplate(options.figmaMcp
2114
+ ? 'claude/agents/component-review.md'
2115
+ : 'claude/agents/component-review.no-figma.md'));
1657
2116
  // The workspace's own component skill — written unconditionally (no
1658
2117
  // network, no `skills` opt-out), unlike the four storybookjs/mcp skills
1659
2118
  // installSkills fetches further below. See renderAtelierComponentSkill's
1660
- // comment above for the `<app>`/`<framework>` substitution it performs, and
1661
- // CLAUDE.md's "Agent Skills" section (built above) for why this one is
1662
- // called out separately from those four.
1663
- tree.write('.claude/skills/atelier-component/SKILL.md', renderAtelierComponentSkill(appName, framework));
2119
+ // comment above for the `<app>`/`<framework>` substitution it performs (and
2120
+ // the `figmaMcp`-selected source file, ADR-0144), and CLAUDE.md's "Agent
2121
+ // Skills" section (built above) for why this one is called out separately
2122
+ // from those four.
2123
+ tree.write('.claude/skills/atelier-component/SKILL.md', renderAtelierComponentSkill(appName, framework, (_f = options.figmaMcp) !== null && _f !== void 0 ? _f : false));
1664
2124
  // .gitignore: create-nx-workspace already writes this file (before any
1665
2125
  // preset runs) with its own standard ignores (node_modules, dist, .nx, …)
1666
2126
  // — appended to, never overwritten, so a future create-nx-workspace
@@ -1669,7 +2129,7 @@ Browse components at ${SITE_URL}
1669
2129
  // never be committed, unlike the shared `.claude/settings.json` written
1670
2130
  // above.
1671
2131
  const existingGitignore = tree.exists('.gitignore')
1672
- ? ((_f = tree.read('.gitignore', 'utf-8')) !== null && _f !== void 0 ? _f : '')
2132
+ ? ((_g = tree.read('.gitignore', 'utf-8')) !== null && _g !== void 0 ? _g : '')
1673
2133
  : '';
1674
2134
  const gitignoreBase = existingGitignore.replace(/\n+$/, '');
1675
2135
  tree.write('.gitignore', `${gitignoreBase}${gitignoreBase ? '\n\n' : ''}# Claude Code — personal overrides, never shared\n.claude/settings.local.json\n`);