@wssto2/vue-core 0.11.0 → 0.12.1

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.12.1 — 2026-10-18
+
+go-core `v1.16.1`: a type the wire writes as text is generated as a string.
+
+### Fixed
+- **modules:** regenerated from go-core v1.16.1. In the identity entities `ClauseInfo.qualifier` and `PermissionAccess.qualifier` are `Qualifier` (`"own" | "own_location" | "all"`, exported from `modules/identity/entities`); they were `number`, while the wire sends the text.
+- **playwright:** `SessionExtra.access` and `accessOf` use the generated `MyAccess`; the `WireAccess` workaround for the number-typed qualifier is gone.
+
+## 0.12.0 — 2026-10-18
+
+The developer kit an application copied: one `vue-core` command for the ratcheted lint, the feature-folder architecture rules, the feature generator and the e2e timings, the ESLint config, and Playwright mocks of the library's own endpoints. Nothing existing changes. go-core is unchanged (`v1.15.0`; v1.16.0 changes no wire type).
+
+### New
+- **bin:** the `vue-core` command, `vue-core [--config <path>] <command>`: `lint`, `check-architecture`, `feature`, `e2e-timings`, all reading one `vue-core.config.mjs` (found from the current folder upwards). `@wssto2/vue-core/config` exports `defineConfig` and the config types.
+- **lint:** `vue-core lint` runs ESLint with per-file, per-rule ceilings that only go down (`--fix`, `--update`, `--all`, `--report`, `--rule=`, `--file=`, `--summary`; `LINT_TYPED=1` lints the changed files type-aware). The `lint` section sets `baselines`, `generated`, `patternCounters`, `commands` and `policy`.
+- **eslint:** `@wssto2/vue-core/eslint`: `vueCoreConfig({ typed, tsconfigRootDir, ignores, rules })`, the generic flat config, and `TYPED_RULES` / `TYPED_RULE_SET`, the one list of type-aware rules.
+- **architecture:** `vue-core check-architecture`: outside code reaches a feature only through `index.ts` / `routes.ts`, no feature imports another, the shared layer imports no feature, generated code only through its subpaths, HTTP only in `api.ts`, one `ApiError`, single-word folder names, `views/` needs `index.ts` + `routes.ts`. Opt-in packs `design-values` and `presentation`, allowlists that only shrink, and an application's own rules (`architecture.rules`).
+- **feature:** `vue-core feature <a/b> --entity <Name>` scaffolds a CRUD feature folder on go-core's route table. The default template uses vue-core subpaths only and creates its own modal; `generator.template` and `generator.out` configure it.
+- **e2e-timings:** `vue-core e2e-timings [--report] [--top]`: the slowest files and tests of a Playwright JSON report.
+- **playwright:** `@wssto2/vue-core/playwright`: Playwright mocks for the library's own endpoints (the go-core envelope, `/auth/me`, access, notifications, profile, users and service accounts), typed from the go-core module types. See docs/recipes/e2e.md.
+
+### Changed
+- `eslint`, `@eslint/js`, `eslint-plugin-vue`, `typescript-eslint`, `vue-eslint-parser`, `globals` and `@playwright/test` are optional peer dependencies: an application that does not lint or test with Playwright installs nothing.
+- The library's own `eslint.config.js` uses `vueCoreConfig`.
+
 ## 0.11.0 — 2026-10-17
 
 The five gaps an application met adopting 0.10.0's users screens and quick search. go-core is unchanged (`v1.15.0`).

package/README.md

@@ -23,6 +23,7 @@ Its plan and rules are in [PLAN.md](PLAN.md).
 | `@wssto2/vue-core/notifications` | go-core's notification and events modules: `notificationsFeature({ categories, deadLetters })`: the bell with the unread count, the inbox (popover, bottom sheet on phones), the live stream, the failed-events page: [notifications](docs/recipes/notifications.md) |
 | `@wssto2/vue-core/incidents` | go-core's incident module: `incidentsFeature({ destination, appVersion })`: the list, an incident with its reports, comments and management form, "Report a bug" in the account menu; `clientErrorReporter({ platform })`: the browser's own errors reported as incidents: [incidents](docs/recipes/incidents.md) |
 | `@wssto2/vue-core/testing` | `createTestPlatform`, `createTestApp`, fake transports: for your tests, [testing](docs/recipes/testing.md) |
+| `@wssto2/vue-core/playwright` | `mockAuth`, `serveAccess`, `serveNotifications`, `serveProfile`, `serveUsers`: Playwright mocks of the library's endpoints, [end-to-end specs](docs/recipes/e2e.md) |
 
 Nothing is reachable by a deep import. The peers are `vue`, `vue-router` and `vue-i18n`; the library never bundles them.
 
@@ -339,13 +340,38 @@ The library's own texts are under the `core` namespace in English, Croatian, Bos
 - [Users and profile](docs/recipes/users.md): the users list and a person's record, "my profile" with the e-mail change by code, opting out, extra sections, refusals
 - [Service accounts](docs/recipes/service-accounts.md): the list and an account's record, its roles, API keys shown once, tenants, linking
 - [Roles and access](docs/recipes/access.md): go-core's access module: the roles list and editor from your catalogue, a person's roles and effective access, where a role applies, the refusals
+- [Lint](docs/recipes/lint.md): `vue-core lint` and `@wssto2/vue-core/eslint`: ceilings per file and rule that only go down, the typed run on changed files
 - [Notifications](docs/recipes/notifications.md): the bell, the inbox and the live stream, categories, the failed-events page, trying it against go-core's dev server
 - [Incidents](docs/recipes/incidents.md): go-core's incident module: the list and an incident, "Report a bug", the browser's errors reported (what is and is not sent), source maps
 - [Theming](docs/recipes/theming.md): brand accent, dark mode, tokens, status tones and category hues
 - [Testing](docs/recipes/testing.md): the application's environment and a fake backend for your tests
+- [End-to-end specs](docs/recipes/e2e.md): `@wssto2/vue-core/playwright`, the Playwright mocks of go-core's envelope, session, access, notification, profile and users routes
+- [Feature generator and e2e timings](docs/recipes/feature-generator.md): `vue-core feature` and `vue-core e2e-timings`
 
 Forms have their own recipe when that phase lands.
 
+## The `vue-core` command
+
+The package installs one command, `vue-core`, with the subcommands `lint`, `check-architecture`, `feature` and `e2e-timings` (`npx vue-core --help`). Each reads its own section of one `vue-core.config.mjs`, found from the current folder upwards (or `--config <path>`); a command with no section runs on its defaults. `eslint`, its plugins and `@playwright/test` are optional peers, installed only by the applications that use them.
+
+```bash
+npx vue-core --help
+npx vue-core lint --config tools/vue-core.config.mjs
+```
+
+<!-- example: docs/examples/devkit/vue-core.config.ts -->
+```ts
+import { defineConfig } from "@wssto2/vue-core/config";
+
+// vue-core.config.mjs at the root of the application; one section per command.
+export default defineConfig({
+  lint: {},
+  architecture: {},
+  generator: {},
+  e2eTimings: {},
+});
+```
+
 ## Working on the library
 
 ```bash

package/bin/architecture/engine.mjs

@@ -0,0 +1,225 @@
+// The checks behind `vue-core check-architecture`: walks the source tree under `root` and returns the violations and warnings
+// in the order they are found (per file in path order, then the stale allowlist entries, then the feature-folder rules).
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+
+import { PACKS } from "./packs.mjs";
+
+const SOURCE_EXTENSIONS = new Set([".ts", ".vue"]);
+const toPosix = (value) => value.split(path.sep).join("/");
+const byName = (a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+const entries = (dir) => readdirSync(dir, { withFileTypes: true }).sort(byName);
+const sentence = (items) => (items.length > 1 ? `${items.slice(0, -1).join(", ")} or ${items.at(-1)}` : items[0]);
+
+/**
+ * @param {object} options
+ * @param {string} options.root the folder the config file lives in; `alias` points at it
+ * @param {object} options.config the `architecture` section, defaults applied
+ * @param {string} options.configName how a stale allowlist message names the config file
+ */
+export function check({ root, config, configName }) {
+  const { featuresDir, alias, sharedLayers, generated, skip, uiDirs, doc } = config;
+  const allow = Object.fromEntries(Object.entries(config.allow).map(([rule, files]) => [rule, new Set(files)]));
+  const allowed = (rule) => allow[rule] ?? new Set();
+  const docRef = (key, join = " (") => (doc[key] ? `${join}${doc[key]}${join === " (" ? ")" : ""}` : "");
+  const packs = config.packs.map((name) => PACKS[name]);
+  const packRules = packs.flatMap((pack, index) => pack.rules.map((rule) => ({ ...rule, pack: packs[index], seen: new Set() })));
+  const featuresRoot = path.join(root, featuresDir);
+  const violations = [];
+  const warnings = [];
+
+  const featureRoots = getFeatureRoots();
+  const owningFeature = (relativePath) => featureRoots.find((feature) => relativePath === feature || relativePath.startsWith(`${feature}/`)) ?? null;
+  const featuresPrefix = `${alias}${featuresDir}/`;
+  const generatedPrefix = `${alias}${generated.dir}/`;
+  const generatedAllowed = generated.allowed.map((entry) => `${alias}${generated.dir}/${entry}`);
+  const isGeneratedAllowed = (specifier) =>
+    generatedAllowed.some((entry) => (entry.endsWith("/*") ? specifier.startsWith(entry.slice(0, -1)) : specifier === entry));
+
+  for (const filePath of collectSourceFiles(root)) {
+    const file = toPosix(path.relative(root, filePath));
+    const importerFeature = owningFeature(file);
+    const content = readFileSync(filePath, "utf8");
+    const isVue = file.endsWith(".vue");
+    const isApiFile = /(^|\/)api\.ts$/.test(file);
+    const isTest = /(^|\/)tests?\//.test(file) || /\.(test|spec)\.[jt]sx?$/.test(file);
+    const imports = extractImportSpecifiers(content);
+
+    for (const specifier of imports) {
+      // the shared layer imports no feature (aliased or relative)
+      if (sharedLayers.some((layer) => file.startsWith(`${layer}/`))) {
+        const target = specifier.startsWith(alias) ? specifier.slice(alias.length) : specifier.startsWith(".") ? toPosix(path.join(path.dirname(file), specifier)) : null;
+        if (target === featuresDir || target?.startsWith(`${featuresDir}/`)) {
+          violations.push(
+            `${file}: the shared layer (${sharedLayers.map((layer) => `${layer}/`).join(", ")}) cannot import "${specifier}" — take what the feature provides as a prop or callback, or move this code into the feature${docRef("shared-layer")}.`,
+          );
+        }
+      }
+
+      for (const [from, to] of Object.entries(generated.moved)) {
+        if (specifier.startsWith(from)) violations.push(`${file}: replace legacy "${from.replace(/\/$/, "")}" imports with "${to}".`);
+      }
+
+      if (specifier.startsWith(generatedPrefix) && !isGeneratedAllowed(specifier)) {
+        violations.push(`${file}: import generated code only through ${sentence(generatedAllowed.map((entry) => `"${entry}"`))}.`);
+      }
+
+      // deep import into a feature from outside every feature: `index.ts` is the public surface, `routes.ts` the one extra entry point
+      if (!importerFeature && specifier.startsWith(featuresPrefix)) {
+        const bare = specifier.slice(alias.length);
+        const importedFeature = owningFeature(bare);
+        if (importedFeature && bare !== importedFeature && bare !== `${importedFeature}/routes` && !allowed("deep-import").has(`${file} -> ${specifier}`)) {
+          violations.push(`${file}: import feature code through "${alias}${importedFeature}" (or "${alias}${importedFeature}/routes"), not the internal path "${specifier}".`);
+        }
+      }
+
+      if (!importerFeature || !specifier.startsWith(featuresPrefix)) continue;
+      const importedFeature = owningFeature(specifier.slice(alias.length));
+      if (!importedFeature || importedFeature === importerFeature) continue;
+      violations.push(`${file}: feature "${importerFeature}" cannot import "${specifier}". Import shared code or the owning app-shell route instead.`);
+    }
+
+    // raw fetch()/axios outside an api.ts (tests exempt). A URL/string first argument tells a real global-fetch call from a
+    // bare `fetch()` invocation of a local refresh function.
+    if (!isApiFile && !isTest) {
+      const rawFetch = /(?<![.\w])fetch\s*\(\s*[`'"]/.test(content);
+      const usesAxios = /(?<![.\w])axios\s*[.(]/.test(content) || /["'`]axios["'`]/.test(content);
+      if ((rawFetch || usesAxios) && !allowed("raw-http").has(file)) {
+        violations.push(
+          `${file}: no raw fetch()/axios outside an api.ts — route the call through the platform client (currentRuntime().platform.http) so it shares error handling and ApiError.`,
+        );
+      }
+    }
+
+    // the application's own rules
+    if (config.rules.length > 0) {
+      const template = content.match(/<template>([\s\S]*)<\/template>/)?.[1] ?? "";
+      for (const rule of config.rules) {
+        for (const message of rule({ file, content, template, imports, isVue, isTest }) ?? []) violations.push(`${file}: ${message}`);
+      }
+    }
+
+    // a failed request is vue-core's `ApiError`; a second class makes `isApiError` miss the errors of the other client
+    if (/\bclass\s+\w*ApiError\b/.test(content)) {
+      violations.push(
+        `${file}: declares a second ApiError class — a failed request is vue-core's ApiError (import { ApiError, isApiError } from "@wssto2/vue-core/client"${docRef("api-error", "; ")}).`,
+      );
+    }
+    for (const m of content.matchAll(/import\s*\{([^}]*)\}\s*from\s*["']([^"']+)["']/g)) {
+      if (m[2] !== "@wssto2/vue-core/client" && /(^|[\s,])(ApiError|isApiError)\b/.test(m[1].replace(/\bas\s+\w+/g, ""))) {
+        violations.push(`${file}: imports ApiError from "${m[2]}" — the one error class comes from "@wssto2/vue-core/client"${docRef("api-error")}.`);
+      }
+    }
+
+    // the packs
+    if (packs.length > 0) {
+      const template = content.match(/<template>([\s\S]*)<\/template>/)?.[1] ?? "";
+      const classLists = [...content.matchAll(/(?:\bclass|:class)="([^"]*)"/g)].map((m) => m[1].split(/\s+/).filter(Boolean));
+      for (const rule of packRules) {
+        if (!rule.pack.applies({ file, isVue, featuresDir, uiDirs }) || !rule.test(content, template, classLists)) continue;
+        if (allowed(rule.id).has(file)) rule.seen.add(file);
+        else violations.push(`${file}: ${rule.id} — ${rule.hint}${docRef(rule.id)}.`);
+      }
+    }
+  }
+
+  // a stale allowlist entry (the file no longer trips the rule) is a violation: the lists only shrink
+  for (const rule of packRules) {
+    for (const entry of allowed(rule.id)) {
+      if (!rule.seen.has(entry)) {
+        violations.push(`${entry}: stale ${rule.id} allowlist entry in ${configName} — the file no longer trips the rule; remove it from the allowlist.`);
+      }
+    }
+  }
+
+  // every directory name under the features folder is a single lowercase word
+  for (const dirPath of collectFeatureDirs(featuresRoot)) {
+    const rel = toPosix(path.relative(root, dirPath));
+    const name = rel.split("/").pop();
+    if (!/^[a-z][a-z0-9]*$/.test(name) && !allowed("feature-name").has(rel)) {
+      violations.push(`${rel}: feature directory name "${name}" must be a single lowercase word (^[a-z][a-z0-9]*$), matching the backend route/policy convention.`);
+    }
+  }
+
+  // a feature leaf (a directory at depth 1 or 2 that directly holds views/) ships index.ts and routes.ts; api.ts is a warning
+  for (const leaf of collectFeatureLeaves(featuresRoot)) {
+    const rel = toPosix(path.relative(root, leaf));
+    if (allowed("feature-shape").has(rel)) continue;
+    for (const required of ["index.ts", "routes.ts"]) {
+      if (!existsSync(path.join(leaf, required))) violations.push(`${rel}: a feature with views/ must ship ${required} (its public surface / route table).`);
+    }
+    if (!existsSync(path.join(leaf, "api.ts"))) warnings.push(`${rel}: no api.ts — expected for any feature that talks to the backend.`);
+  }
+
+  return { violations, warnings };
+
+  // the directories with an index.ts at depth 1 or 2 under the features folder, the longest path first
+  function getFeatureRoots() {
+    const roots = [];
+    for (const entry of entries(featuresRoot)) {
+      if (!entry.isDirectory()) continue;
+      const top = path.join(featuresRoot, entry.name);
+      if (existsSync(path.join(top, "index.ts"))) roots.push(toPosix(path.relative(root, top)));
+      for (const nested of entries(top)) {
+        if (!nested.isDirectory()) continue;
+        const nestedPath = path.join(top, nested.name);
+        if (existsSync(path.join(nestedPath, "index.ts"))) roots.push(toPosix(path.relative(root, nestedPath)));
+      }
+    }
+    return roots.sort((left, right) => right.length - left.length);
+  }
+
+  function collectSourceFiles(directoryPath) {
+    const files = [];
+    for (const entry of entries(directoryPath)) {
+      if (skip.includes(entry.name)) continue;
+      const entryPath = path.join(directoryPath, entry.name);
+      if (entry.isDirectory()) files.push(...collectSourceFiles(entryPath));
+      else if (SOURCE_EXTENSIONS.has(path.extname(entry.name))) files.push(entryPath);
+    }
+    return files;
+  }
+}
+
+function collectFeatureDirs(directoryPath) {
+  const dirs = [];
+  for (const entry of entries(directoryPath)) {
+    if (!entry.isDirectory() || entry.name === "node_modules") continue;
+    const entryPath = path.join(directoryPath, entry.name);
+    dirs.push(entryPath, ...collectFeatureDirs(entryPath));
+  }
+  return dirs;
+}
+
+// depth 1 or 2 keeps nested view groups (features/vehicles/views/new/<phase>/views) out of scope
+function collectFeatureLeaves(directoryPath) {
+  const hasViews = (dir) => existsSync(path.join(dir, "views")) && statSync(path.join(dir, "views")).isDirectory();
+  const leaves = [];
+  for (const entry of entries(directoryPath)) {
+    if (!entry.isDirectory()) continue;
+    const level1 = path.join(directoryPath, entry.name);
+    if (hasViews(level1)) leaves.push(level1);
+    for (const nested of entries(level1)) {
+      if (!nested.isDirectory()) continue;
+      const level2 = path.join(level1, nested.name);
+      if (hasViews(level2)) leaves.push(level2);
+    }
+  }
+  return leaves;
+}
+
+function extractImportSpecifiers(fileContent) {
+  const specifiers = new Set();
+  const patterns = [
+    /import\s+(?:[^"'`]*?\sfrom\s*)?["'`]([^"'`]+)["'`]/g,
+    /import\(\s*["'`]([^"'`]+)["'`]\s*\)/g,
+    // re-exports reach a module as much as imports do
+    /export\s+(?:type\s+)?(?:\*(?:\s+as\s+\w+)?|\{[^}]*\})\s*from\s*["'`]([^"'`]+)["'`]/g,
+  ];
+  for (const pattern of patterns) {
+    for (const match of fileContent.matchAll(pattern)) {
+      if (match[1]) specifiers.add(match[1]);
+    }
+  }
+  return [...specifiers];
+}

package/bin/architecture/packs.mjs

@@ -0,0 +1,107 @@
+// The rule packs `vue-core check-architecture` ships, opt in by name (`packs: ["design-values", "presentation"]`):
+// "design-values" keeps the look in vue-core's theme (colours, type weights, shadows), "presentation" asks for the library's
+// components instead of hand-built markup. A pack's rule has an `id`, a `hint` and `test(content, template, classLists)`;
+// the engine reports `<file>: <id> — <hint>.` and keeps the pack's per-rule allowlist (`allow[<id>]`) a ratchet in both
+// directions: an entry that no longer trips its rule is a violation too.
+
+const UTIL = "(?:bg|text|border|border-[trblxy]|ring|ring-offset|divide|fill|stroke|outline|decoration|from|via|to|placeholder|caret|accent|shadow)";
+
+const pattern = (id, hint, regex) => ({ id, hint, test: (content) => regex.test(content) });
+
+// The shared field components' opening tags in a template that renders FormGroups,
+// keeping only those that bind their own `editable` (rule no-field-editable-in-group).
+function fieldTagsWithEditable(template) {
+  if (!/<(?:FormGroup|form-group)[\s>]/.test(template)) return [];
+  const names = "(?:text|textarea|select|combo|date|date-time|month-year|switch|segmented-select)-field|(?:Text|Textarea|Select|Combo|Date|DateTime|MonthYear|Switch|SegmentedSelect)Field|choice-chips|ChoiceChips";
+  const found = [];
+  for (const match of template.matchAll(new RegExp(`<(${names})(?=[\\s/>])`, "g"))) {
+    let end = match.index + match[0].length;
+    let quote = null;
+    for (; end < template.length; end += 1) {
+      const char = template[end];
+      if (quote) { if (char === quote) quote = null; }
+      else if (char === '"' || char === "'") quote = char;
+      else if (char === ">") break;
+    }
+    const tag = template.slice(match.index, end);
+    if (/(?<![\w-])(?::|v-bind:)?editable=/.test(tag)) found.push(tag);
+  }
+  return found;
+}
+
+export const PACKS = {
+  "design-values": {
+    // .vue / .ts of the UI folders, tests excluded
+    applies: ({ file, uiDirs }) => uiDirs.some((dir) => file.startsWith(`${dir}/`)) && /\.(vue|ts)$/.test(file) && !/(^|\/)tests\/|\.test\.ts$|\.spec\.ts$/.test(file),
+    rules: [
+      pattern("no-stray-neutral", "neutral / zinc / slate / stone colour — the one neutral is gray (vue-core theme.css)", new RegExp(`(?<![\\w-])(?:[\\w-]+:)*${UTIL}-(?:neutral|zinc|slate|stone)-\\d{2,3}(?![\\w-])`)),
+      pattern("no-raw-brand-hue", "green / emerald colour — the brand green is primary-* (a stepper tick, switch, success or active state)", new RegExp(`(?<![\\w-])(?:[\\w-]+:)*${UTIL}-(?:green|emerald)-\\d{2,3}(?![\\w-])`)),
+      pattern("no-unbranded-focus", "blue / sky / cyan / indigo focus colour — focus rings and borders are primary-* everywhere (decorative rings are fine)", /(?<![\w-])(?:[\w-]+:)*(?:focus|focus-within|focus-visible|peer-focus|checked)(?::[\w-]+)*:(?:ring|border|outline)-(?:blue|sky|cyan|indigo)-\d{2,3}/),
+      pattern("no-unloaded-font-weight", "font-bold / extrabold / black — the type scale stops at semibold until decision D9; use font-semibold", /(?<![\w-])(?:[\w-]+:)*font-(?:bold|extrabold|black)(?![\w-])/),
+      pattern("no-arbitrary-design-value", "arbitrary shadow / radius / hex colour — add the value to vue-core theme.css and use its utility", /(?<![\w-])(?:[\w-]+:)*(?:shadow-\[[^\]]+\]|rounded(?:-[trblse]{1,2})?-\[[^\]]+\]|(?:bg|text|border|ring|fill|stroke)-\[#[0-9a-fA-F]{3,8}\])/),
+    ],
+  },
+  presentation: {
+    // the .vue files of the features folder
+    applies: ({ file, isVue, featuresDir }) => isVue && file.startsWith(`${featuresDir}/`),
+    rules: [
+      {
+        id: "no-field-editable-in-group",
+        hint: "a shared field with its own `editable` in a grouped form — put read mode on the FormGroup / ResourceForm (`:editable`) and lock a single value with `disabled`",
+        test: (_content, template) => fieldTagsWithEditable(template).length > 0,
+      },
+      {
+        id: "no-adhoc-alert",
+        // a class list with an un-prefixed (optionally dark:) bg-{red|amber|green|emerald|blue|orange}-{50|100}, a rounded* and a p*- token
+        hint: "coloured alert box — use <Banner type=…> instead of a bg-*-50 rounded p-* div",
+        test: (_content, _template, classLists) =>
+          classLists.some((toks) => {
+            const bg = toks.some((t) => /^(?:dark:)?bg-(?:red|amber|green|emerald|blue|orange)-(?:50|100)(?:\/\d+)?$/.test(t));
+            const rounded = toks.some((t) => /^rounded(-.+)?$/.test(t));
+            const pad = toks.some((t) => /^p[xytblr]?-/.test(t));
+            return bg && rounded && pad;
+          }),
+      },
+      {
+        id: "no-raw-table",
+        hint: "raw <table> — use <DataTable> (child collections) or <collection-table> (paginated lists)",
+        test: (content) => /<table[\s>]/.test(content),
+      },
+      {
+        id: "no-raw-form-control",
+        hint: "raw <input>/<select>/<textarea>/<label> in a feature .vue — use the field components",
+        test: (_content, template) => /<(input|select|textarea|label)(\s|>|\/)/.test(template),
+      },
+      {
+        id: "no-arbitrary-type-scale",
+        hint: "arbitrary text-[N px|rem] or font-[N] — use the type scale (text-2xs…text-3xl, font-medium/semibold; vue-core theme.css)",
+        test: (content) => /text-\[\d*\.?\d+(?:px|rem|em)\]|font-\[\d{3}\]/.test(content),
+      },
+      {
+        id: "no-bare-loading-text",
+        hint: "the word “Loading” rendered directly — render <AsyncSection>'s skeleton instead",
+        test: (_content, template) => /general\.loading/.test(template),
+      },
+      {
+        // a class list with `uppercase`, a micro text size, `rounded*` and `px-*` (a hand-built pill; .label-micro / <MicroLabel> is a label)
+        id: "no-adhoc-badge",
+        hint: "hand-built uppercase badge — use <Badge tone=…> (@wssto2/vue-core/state)",
+        test: (_content, _template, classLists) =>
+          classLists.some(
+            (toks) =>
+              toks.includes("uppercase") &&
+              toks.some((t) => /^text-(?:3xs|2xs)$/.test(t)) &&
+              toks.some((t) => /^rounded(-.+)?$/.test(t)) &&
+              toks.some((t) => /^px-/.test(t)),
+          ),
+      },
+      {
+        // columns built in a separate .ts must still carry the role in the view
+        id: "collection-table-roles",
+        hint: "CollectionTable without column `mobile` roles (or with the retired #mobile-row slot) — give the columns primary / accessory / meta roles",
+        test: (content, template) =>
+          (/<(?:collection-table|CollectionTable)[\s>/]/.test(template) && !/\bmobile:\s*["']/.test(content)) || /(?:#|v-slot:)mobile-row\b/.test(template),
+      },
+    ],
+  },
+};

package/bin/cli.mjs

@@ -0,0 +1,57 @@
+// The `vue-core` dispatcher: `vue-core <command> [options]`. A command is bin/commands/<name>.mjs whose default export is
+// `async (context) => exitCode | void`, where context = { args, config, root, configPath, cwd, out, err } and `config` is that
+// command's own section of vue-core.config.mjs (defaults applied).
+import { ConfigError, loadConfig } from "./config.mjs";
+
+/** command name -> its section in the config, and the line `--help` shows */
+export const COMMANDS = {
+  lint: { section: "lint", summary: "ESLint with per-file ceilings that only go down" },
+  "check-architecture": { section: "architecture", summary: "feature-folder import and layer rules" },
+  feature: { section: "generator", summary: "scaffold a CRUD feature folder" },
+  "e2e-timings": { section: "e2eTimings", summary: "the slowest specs of a Playwright JSON report" },
+};
+
+const usage = () =>
+  [
+    "Usage: vue-core [--config <path>] <command> [options]",
+    "",
+    "Commands:",
+    ...Object.entries(COMMANDS).map(([name, { summary }]) => `  ${name.padEnd(20)}${summary}`),
+    "",
+    "Options are read from vue-core.config.mjs, found from the current folder upwards (or --config <path>).",
+  ].join("\n");
+
+/** Takes `--config <path>` / `--config=<path>` out of `argv`, wherever it stands. */
+function takeConfigFlag(argv) {
+  const rest = [];
+  let path;
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--config") path = argv[++i];
+    else if (argv[i].startsWith("--config=")) path = argv[i].slice("--config=".length);
+    else rest.push(argv[i]);
+  }
+  return { path, rest };
+}
+
+/** @returns {Promise<number>} the exit code */
+export async function main(argv, { cwd = process.cwd(), out = console.log, err = console.error, load = (name) => import(`./commands/${name}.mjs`) } = {}) {
+  const { path, rest } = takeConfigFlag(argv);
+  const [name, ...args] = rest;
+  if (name === "--help" || name === "-h" || name === "help") {
+    out(usage());
+    return 0;
+  }
+  if (!name || !Object.hasOwn(COMMANDS, name)) {
+    err(name ? `vue-core: unknown command "${name}"\n\n${usage()}` : usage());
+    return 2;
+  }
+  try {
+    const { config, root, path: configPath } = await loadConfig({ cwd, path });
+    const command = await load(name);
+    return (await command.default({ args, config: config[COMMANDS[name].section], root, configPath, cwd, out, err })) ?? 0;
+  } catch (error) {
+    if (!(error instanceof ConfigError)) throw error;
+    err(`vue-core: ${error.message}`);
+    return 2;
+  }
+}

package/bin/commands/check-architecture.mjs

@@ -0,0 +1,38 @@
+// `vue-core check-architecture`: the feature-folder rules (features import no other feature, outside code reaches a feature
+// only through index.ts / routes.ts, the shared layer imports no feature, generated code only through its subpaths, HTTP only in
+// api.ts, one ApiError, single-word folder names, views/ needs index.ts + routes.ts) plus the opt-in packs. Exit 1 on a violation.
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+import { check } from "../architecture/engine.mjs";
+import { PACKS } from "../architecture/packs.mjs";
+
+const ALLOW_RULES = ["deep-import", "raw-http", "feature-name", "feature-shape"];
+const DOC_KEYS = ["shared-layer", "api-error"];
+
+export default function run({ config, root, configPath, err }) {
+  const generated = { dir: "generated", allowed: ["entities/*", "schemas/*", "routes/*"], moved: {}, ...config.generated };
+  const settings = { ...config, generated, uiDirs: config.uiDirs ?? [config.featuresDir, "components"] };
+
+  const problems = [];
+  for (const name of settings.packs) if (!Object.hasOwn(PACKS, name)) problems.push(`packs: unknown pack "${name}"; the packs are ${Object.keys(PACKS).join(", ")}`);
+  const packRules = settings.packs.filter((name) => Object.hasOwn(PACKS, name)).flatMap((name) => PACKS[name].rules.map((rule) => rule.id));
+  for (const rule of Object.keys(settings.allow)) {
+    if (!ALLOW_RULES.includes(rule) && !packRules.includes(rule)) problems.push(`allow.${rule}: no such rule; the allowlists are ${[...ALLOW_RULES, ...packRules].join(", ")}`);
+  }
+  for (const key of Object.keys(settings.doc)) if (!DOC_KEYS.includes(key) && !packRules.includes(key)) problems.push(`doc.${key}: no such rule; the doc references are ${[...DOC_KEYS, ...packRules].join(", ")}`);
+  for (const rule of settings.rules) if (typeof rule !== "function") problems.push("rules: every entry must be a function ({ file, content, template, imports, isVue, isTest }) => string[]");
+  if (!existsSync(path.join(root, settings.featuresDir))) problems.push(`featuresDir: ${path.join(root, settings.featuresDir)} does not exist`);
+  if (problems.length > 0) {
+    err(`vue-core check-architecture: ${configPath ?? "no config file"}\n${problems.map((problem) => `  ${problem}`).join("\n")}`);
+    return 2;
+  }
+
+  const { violations, warnings } = check({ root, config: settings, configName: configPath ? path.basename(configPath) : "the architecture config" });
+  if (warnings.length > 0) err(`Frontend architecture warnings:\n\n${warnings.map((warning) => `- ${warning}`).join("\n")}\n`);
+  if (violations.length > 0) {
+    err(`Frontend architecture violations:\n\n${violations.map((violation) => `- ${violation}`).join("\n")}`);
+    return 1;
+  }
+  return 0;
+}

package/bin/commands/e2e-timings.mjs

@@ -0,0 +1,58 @@
+// Summarises a Playwright JSON report (the `json` reporter, `e2eTimings.report`): the slowest spec files and tests,
+// so trimming or splitting the e2e suite starts from measurements.
+//   vue-core e2e-timings [--report <path>] [--top 20]
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+export default function run({ args, config, root, cwd, out, err }) {
+  const topArg = args.indexOf("--top");
+  const TOP = topArg >= 0 ? Number(args[topArg + 1]) || 15 : 15;
+  const reportArg = args.indexOf("--report");
+  const REPORT = reportArg >= 0 ? args[reportArg + 1] : config.report;
+  // a `--report` is relative to where the command runs, the configured one to the config's folder
+  const reportPath = reportArg >= 0 ? path.resolve(cwd, REPORT) : path.resolve(root, REPORT);
+
+  let report;
+  try {
+    report = JSON.parse(readFileSync(reportPath, "utf8"));
+  } catch {
+    err(`No ${REPORT} — run the e2e suite first (npm run test:e2e).`);
+    return 1;
+  }
+
+  const tests = [];
+  function walk(suite, file) {
+    const here = suite.file ?? file;
+    for (const spec of suite.specs ?? []) {
+      for (const test of spec.tests ?? []) {
+        const duration = (test.results ?? []).reduce((sum, result) => sum + (result.duration ?? 0), 0);
+        tests.push({ file: here, title: spec.title, duration, status: test.status });
+      }
+    }
+    for (const child of suite.suites ?? []) walk(child, here);
+  }
+  for (const suite of report.suites ?? []) walk(suite, suite.file);
+
+  const byFile = new Map();
+  for (const test of tests) {
+    const entry = byFile.get(test.file) ?? { file: test.file, duration: 0, count: 0 };
+    entry.duration += test.duration;
+    entry.count += 1;
+    byFile.set(test.file, entry);
+  }
+
+  const seconds = (ms) => `${(ms / 1000).toFixed(1)}s`.padStart(7);
+  const total = tests.reduce((sum, test) => sum + test.duration, 0);
+  const wall = report.stats?.duration ?? 0;
+
+  out(`${tests.length} tests, ${seconds(total).trim()} of test time, ${seconds(wall).trim()} wall clock\n`);
+  out(`Slowest files (test time, share, tests):`);
+  for (const entry of [...byFile.values()].sort((a, b) => b.duration - a.duration).slice(0, TOP)) {
+    out(`${seconds(entry.duration)}  ${((entry.duration / total) * 100).toFixed(1).padStart(5)}%  ${String(entry.count).padStart(3)}  ${entry.file}`);
+  }
+  out(`\nSlowest tests:`);
+  for (const test of [...tests].sort((a, b) => b.duration - a.duration).slice(0, TOP)) {
+    out(`${seconds(test.duration)}  ${test.file} › ${test.title}${test.status === "expected" ? "" : ` [${test.status}]`}`);
+  }
+  return 0;
+}