@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.
- package/CHANGELOG.md +28 -0
- package/package.json +1 -1
- package/src/generators/preset/files/claude/agents/component-review.no-figma.md +42 -0
- package/src/generators/preset/files/claude/commands/verify.no-figma.md +27 -0
- package/src/generators/preset/files/claude/skills/atelier-component/SKILL.md +7 -7
- package/src/generators/preset/files/claude/skills/atelier-component/SKILL.no-figma.md +63 -0
- package/src/generators/preset/files/storybook/angular/main.ts.template +8 -0
- package/src/generators/preset/files/storybook/angular/preview.ts.template +17 -0
- package/src/generators/preset/files/storybook/react/atl-button.stories.tsx +1 -1
- package/src/generators/preset/files/storybook/react/main.ts.template +8 -0
- package/src/generators/preset/files/storybook/react/preview.tsx +18 -1
- package/src/generators/preset/files/storybook/vue/atl-button.stories.ts.template +1 -1
- package/src/generators/preset/files/storybook/vue/main.ts.template +8 -0
- package/src/generators/preset/files/storybook/vue/preview.ts.template +18 -1
- package/src/generators/preset/files/testing/angular/test-setup.ts.template +6 -0
- package/src/generators/preset/files/testing/react/atl-button.spec.tsx +17 -18
- package/src/generators/preset/files/testing/react/test-setup-stories.ts.template +17 -0
- package/src/generators/preset/files/testing/react/vitest.unit.config.ts.template +1 -1
- package/src/generators/preset/files/testing/vue/atl-button.spec.ts.template +17 -21
- package/src/generators/preset/files/testing/vue/test-setup-stories.ts.template +17 -0
- package/src/generators/preset/files/testing/vue/vitest.unit.config.ts.template +1 -1
- package/src/generators/preset/files/tools/scripts/preflight.mjs +40 -0
- package/src/generators/preset/preset.js +613 -153
- 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
|
|
91
|
-
//
|
|
92
|
-
//
|
|
93
|
-
//
|
|
94
|
-
//
|
|
95
|
-
//
|
|
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
|
|
104
|
-
//
|
|
105
|
-
//
|
|
106
|
-
//
|
|
107
|
-
// component name, e.g. in
|
|
108
|
-
// for the reader and must
|
|
109
|
-
|
|
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
|
-
|
|
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
|
-
//
|
|
601
|
-
//
|
|
602
|
-
//
|
|
603
|
-
//
|
|
604
|
-
//
|
|
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
|
-
|
|
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
|
-
//
|
|
793
|
-
//
|
|
794
|
-
//
|
|
795
|
-
//
|
|
796
|
-
//
|
|
797
|
-
// layout would
|
|
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
|
|
800
|
-
// itself (see files/storybook/angular/*.template)
|
|
801
|
-
// '@storybook/angular' back here would reintroduce exactly the
|
|
802
|
-
// this generator now avoids (its peer on
|
|
803
|
-
// not satisfiable by a freshly scaffolded
|
|
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
|
-
//
|
|
866
|
-
//
|
|
867
|
-
|
|
868
|
-
// .
|
|
869
|
-
//
|
|
870
|
-
//
|
|
871
|
-
//
|
|
872
|
-
//
|
|
873
|
-
|
|
874
|
-
|
|
875
|
-
|
|
876
|
-
|
|
877
|
-
|
|
878
|
-
|
|
879
|
-
|
|
880
|
-
|
|
881
|
-
|
|
882
|
-
|
|
883
|
-
|
|
884
|
-
|
|
885
|
-
|
|
886
|
-
|
|
887
|
-
|
|
888
|
-
|
|
889
|
-
snapshot
|
|
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.
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
1191
|
-
|
|
1192
|
-
|
|
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
|
|
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)
|
|
1232
|
-
//
|
|
1233
|
-
//
|
|
1234
|
-
//
|
|
1235
|
-
//
|
|
1236
|
-
//
|
|
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
|
-
|
|
1242
|
-
|
|
1243
|
-
|
|
1244
|
-
|
|
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)
|
|
1327
|
-
//
|
|
1328
|
-
//
|
|
1329
|
-
//
|
|
1330
|
-
//
|
|
1331
|
-
//
|
|
1332
|
-
//
|
|
1333
|
-
|
|
1334
|
-
|
|
1335
|
-
|
|
1336
|
-
: 'node tools/scripts/
|
|
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
|
|
1550
|
-
//
|
|
1551
|
-
//
|
|
1552
|
-
//
|
|
1553
|
-
// entry rather than
|
|
1554
|
-
// package.json carries exactly this fixed,
|
|
1555
|
-
// set (a workshop attendee adding a script
|
|
1556
|
-
// this same allowance by definition, having
|
|
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
|
|
1649
|
-
// for.
|
|
1650
|
-
tree.write('.claude/commands/verify.md', readTemplate(
|
|
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
|
-
//
|
|
1656
|
-
|
|
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
|
|
1661
|
-
// CLAUDE.md's "Agent
|
|
1662
|
-
// called out separately
|
|
1663
|
-
|
|
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
|
-
? ((
|
|
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`);
|