@birdapi/velinstyle 1.2.2 → 1.3.0

package/package.json

@@ -1,143 +1,158 @@
-{
-  "name": "@birdapi/velinstyle",
-  "version": "1.2.2",
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org"
-  },
-  "types": "dist/velinstyle.d.ts",
-  "sideEffects": [
-    "components/index.js",
-    "components/velin-*.js"
-  ],
-  "description": "WCAG 2.2 AAA CSS + Web Components: OKLCH themes, PII scanner, perf CLI, runtime tree-shaking. Ship inclusive UI faster.",
-  "type": "module",
-  "main": "dist/velinstyle.css",
-  "module": "dist/velinstyle-components.js",
-  "exports": {
-    ".": "./components/runtime-entry.js",
-    "./bundle": "./dist/velinstyle-components.min.js",
-    "./css": "./dist/velinstyle.min.css",
-    "./sanitize": "./components/sanitize.js",
-    "./runtime": "./components/runtime/index.js",
-    "./secure": "./components/velin-secure-field.js",
-    "./email": "./components/velin-email.js",
-    "./search": "./core/search/index.js",
-    "./motion": "./core/motion/index.js",
-    "./attributes": "./core/attributes/index.js",
-    "./highlight": "./core/highlight/index.js",
-    "./meta": "./core/meta/index.js",
-    "./transparency": "./core/transparency/index.js",
-    "./a11y": "./components/a11y-entry.js",
-    "./skills-registry": "./packages/velinstyle-skills/registry.json"
-  },
-  "bin": {
-    "velinstyle": "cli/index.js"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/SkyliteDesign/velinstyle.git"
-  },
-  "homepage": "https://velinstyle.info",
-  "bugs": {
-    "url": "https://github.com/SkyliteDesign/velinstyle/issues"
-  },
-  "files": [
-    "dist/",
-    "src/",
-    "components/",
-    "core/",
-    "cli/",
-    "packages/skill-engine/",
-    "packages/velinstyle-skills/",
-    "schemas/",
-    "examples/search-index.schema.json",
-    "icons/velin-icons.svg"
-  ],
-  "scripts": {
-    "build": "npm run build:css:min && npm run build:css:dev && npm run build:js:min && npm run build:js:dev && npm run build:js:iife && npm run build:js:chunks && npm run build:loaders && npm run build:react:src && npm run build:types && npm run build:themes && npm run build:icons",
-    "build:loaders": "node scripts/generate-component-loaders.mjs",
-    "build:react:src": "node scripts/generate-react-wrappers.mjs",
-    "build:react": "npm run build:react:src && npm --prefix packages/react run build",
-    "build:types": "node scripts/generate-types.mjs",
-    "build:js:chunks": "esbuild components/runtime-entry.js --bundle --splitting --format=esm --outdir=dist/chunks --chunk-names=[name]-[hash]",
-    "build:css:min": "lightningcss --bundle --minify src/velinstyle.css -o dist/velinstyle.min.css",
-    "build:css:dev": "lightningcss --bundle src/velinstyle.css -o dist/velinstyle.css",
-    "build:js:min": "esbuild components/index.js --bundle --minify --format=esm --outfile=dist/velinstyle-components.min.js",
-    "build:js:dev": "esbuild components/index.js --bundle --format=esm --outfile=dist/velinstyle-components.js",
-    "build:js:iife": "esbuild components/index.js --bundle --format=iife --outfile=dist/velinstyle-components.iife.js",
-    "build:themes": "node scripts/build-themes.js",
-    "build:icons": "node icons/build-sprite.js",
-    "dev": "npx serve . --cors -l 3000",
-    "watch": "lightningcss --bundle src/velinstyle.css -o dist/velinstyle.css --watch",
-    "lint": "stylelint \"src/**/*.css\"",
-    "test": "vitest run",
-    "test:a11y": "node tests/a11y/run.js",
-    "test:a11y:coverage": "node tests/a11y/coverage.js",
-    "test:contrast": "node scripts/check-contrast.js",
-    "test:security": "vitest run tests/sanitize.test.js tests/cli-security-scanner.test.js",
-    "test:perf": "vitest run tests/perf-audit.test.js",
-    "test:search:bench": "vitest run tests/search-benchmark.test.js",
-    "test:e2e": "playwright test",
-    "test:e2e:chromium": "playwright test --project=chromium",
-    "docs:patch-theme-picker": "node scripts/patch-docs-theme-picker.mjs",
-    "tokens:validate": "node cli/index.js tokens validate --input examples/tokens.sample.json",
-    "tokens:validate:full": "node cli/index.js tokens validate --input examples/tokens.full.json",
-    "docs:generate": "node cli/index.js docs generate",
-    "search:index": "node cli/index.js search index",
-    "skills:generate": "node packages/velinstyle-skills/scripts/generate-assets.mjs && node -e \"import('./packages/velinstyle-skills/index.js').then(m=>m.writeCatalogFile())\"",
-    "skills:validate": "node scripts/validate-skills.mjs",
-    "skills:doctor": "node scripts/check-skills-paths.mjs",
-    "meta:build": "node cli/index.js meta",
-    "ci:checks": "node scripts/ci-checks.mjs",
-    "check:blueprints": "node scripts/check-blueprint-classes.mjs",
-    "check:chaos": "node scripts/check-chaos-detection.mjs",
-    "release:check": "node scripts/check-release-sync.mjs",
-    "release:sync": "node scripts/check-release-sync.mjs --fix",
-    "intelligence:validate": "node scripts/validate-intelligence-schemas.mjs",
-    "prepublishOnly": "npm run build && npm run check:blueprints && npm run search:index && npm run skills:generate && npm run skills:validate && npm run skills:doctor && npm run meta:build && npm run intelligence:validate && npm run release:check -- --skip-site",
-    "pack:check": "npm pack --dry-run",
-    "docs:prepare": "npm run build && node scripts/prepare-docs-pages.js",
-    "docs:patch-nav": "node scripts/patch-docs-nav.js",
-    "docs:sync-site": "npm run build && npm run docs:generate && python ../velinstyle-site/tools/sync-framework-0.9.0.py && python ../velinstyle-site/tools/patch-site-a11y-aaa.py && python ../velinstyle-site/tools/patch-docs-090-final.py",
-    "readme:capture": "node tools/capture-readme-demos.mjs",
-    "readme:assets:webp": "node tools/readme-png-to-webp.mjs",
-    "demos:sync": "node tools/sync-demos-to-repo.mjs --out showcase-demos && node tools/sync-demos-to-repo.mjs --out ../velinstyle-demos",
-    "strategy:bootstrap-issues": "node scripts/bootstrap-github-backlog.mjs",
-    "strategy:bootstrap-issues:dry": "node scripts/bootstrap-github-backlog.mjs --dry-run",
-    "strategy:bootstrap-next30": "node scripts/bootstrap-github-backlog.mjs --issues-only --seed=../interne_docs/strategy/next-30-issues.json --map=../interne_docs/strategy/next-30-issue-map.json",
-    "strategy:bootstrap-next30:dry": "node scripts/bootstrap-github-backlog.mjs --dry-run --issues-only --seed=../interne_docs/strategy/next-30-issues.json --map=../interne_docs/strategy/next-30-issue-map.json"
-  },
-  "keywords": [
-    "css",
-    "framework",
-    "accessibility",
-    "a11y",
-    "wcag",
-    "mobile-first",
-    "container-queries",
-    "oklch",
-    "web-components",
-    "design-tokens",
-    "dark-mode",
-    "rtl"
-  ],
-  "author": "SkyliteDesign",
-  "license": "MIT",
-  "devDependencies": {
-    "@playwright/test": "^1.60.0",
-    "axe-core": "^4.10.0",
-    "esbuild": "^0.24.0",
-    "jsdom": "^26.1.0",
-    "lightningcss-cli": "^1.28.0",
-    "playwright": "^1.60.0",
-    "serve": "^14.0.0",
-    "sharp": "^0.34.5",
-    "stylelint": "^16.0.0",
-    "stylelint-config-standard": "^36.0.0",
-    "vitest": "^3.2.0"
-  },
-  "dependencies": {
-    "isomorphic-dompurify": "^3.21.0"
-  }
-}
+{
+  "name": "@birdapi/velinstyle",
+  "version": "1.3.0",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "types": "dist/velinstyle.d.ts",
+  "sideEffects": [
+    "components/index.js",
+    "components/velin-*.js"
+  ],
+  "description": "WCAG 2.2 AAA CSS + Web Components: OKLCH themes, PII scanner, perf CLI, runtime tree-shaking. Ship inclusive UI faster.",
+  "type": "module",
+  "main": "dist/velinstyle.css",
+  "module": "dist/velinstyle-components.js",
+  "exports": {
+    ".": "./components/runtime-entry.js",
+    "./bundle": "./dist/velinstyle-components.min.js",
+    "./css": "./dist/velinstyle.min.css",
+    "./sanitize": "./components/sanitize.js",
+    "./runtime": "./components/runtime/index.js",
+    "./secure": "./components/velin-secure-field.js",
+    "./email": "./components/velin-email.js",
+    "./search": "./core/search/index.js",
+    "./motion": "./core/motion/index.js",
+    "./motion-clip": "./packages/velinstyle-motion/src/index.js",
+    "./attributes": "./core/attributes/index.js",
+    "./highlight": "./core/highlight/index.js",
+    "./meta": "./core/meta/index.js",
+    "./transparency": "./core/transparency/index.js",
+    "./security": "./core/security/index.js",
+    "./a11y": "./components/a11y-entry.js",
+    "./skills-registry": "./packages/velinstyle-skills/registry.json",
+    "./experience": "./cli/experience.js",
+    "./cli-core": "./packages/velinstyle-cli-core/src/index.js",
+    "./cli-registry": "./packages/velinstyle-cli-registry/src/index.js",
+    "./cli-theme": "./packages/velinstyle-cli-theme/src/index.js",
+    "./cli-ui": "./packages/velinstyle-cli-ui/src/index.js",
+    "./cli-renderer": "./packages/velinstyle-cli-renderer/src/index.js"
+  },
+  "bin": {
+    "velinstyle": "cli/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SkyliteDesign/velinstyle.git"
+  },
+  "homepage": "https://velinstyle.info",
+  "bugs": {
+    "url": "https://github.com/SkyliteDesign/velinstyle/issues"
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "components/",
+    "core/",
+    "cli/",
+    "packages/skill-engine/",
+    "packages/velinstyle-skills/",
+    "schemas/",
+    "examples/search-index.schema.json",
+    "icons/velin-icons.svg",
+    "packages/velinstyle-cli-core/",
+    "packages/velinstyle-cli-registry/",
+    "packages/velinstyle-cli-theme/",
+    "packages/velinstyle-cli-ui/",
+    "packages/velinstyle-cli-renderer/",
+    "packages/velinstyle-motion/"
+  ],
+  "scripts": {
+    "build": "npm run build:css:min && npm run build:css:dev && npm run build:js:min && npm run build:js:dev && npm run build:js:iife && npm run build:js:chunks && npm run build:loaders && npm run build:react:src && npm run build:types && npm run build:themes && npm run build:icons",
+    "build:loaders": "node scripts/generate-component-loaders.mjs",
+    "build:react:src": "node scripts/generate-react-wrappers.mjs",
+    "build:react": "npm run build:react:src && npm --prefix packages/react run build",
+    "build:types": "node scripts/generate-types.mjs",
+    "build:js:chunks": "esbuild components/runtime-entry.js --bundle --splitting --format=esm --outdir=dist/chunks --chunk-names=[name]-[hash]",
+    "build:css:min": "lightningcss --bundle --minify src/velinstyle.css -o dist/velinstyle.min.css",
+    "build:css:dev": "lightningcss --bundle src/velinstyle.css -o dist/velinstyle.css",
+    "build:js:min": "esbuild components/index.js --bundle --minify --format=esm --outfile=dist/velinstyle-components.min.js",
+    "build:js:dev": "esbuild components/index.js --bundle --format=esm --outfile=dist/velinstyle-components.js",
+    "build:js:iife": "esbuild components/index.js --bundle --format=iife --outfile=dist/velinstyle-components.iife.js",
+    "build:themes": "node scripts/build-themes.js",
+    "build:icons": "node icons/build-sprite.js",
+    "dev": "npx serve . --cors -l 3000",
+    "watch": "lightningcss --bundle src/velinstyle.css -o dist/velinstyle.css --watch",
+    "lint": "stylelint \"src/**/*.css\"",
+    "test": "vitest run",
+    "test:a11y": "node tests/a11y/run.js",
+    "test:a11y:coverage": "node tests/a11y/coverage.js",
+    "test:contrast": "node scripts/check-contrast.js",
+    "test:motion-clip": "vitest run tests/motion-clip.test.js",
+    "test:security": "vitest run tests/sanitize.test.js tests/cli-security-scanner.test.js tests/security.test.js",
+    "test:perf": "vitest run tests/perf-audit.test.js",
+    "test:search:bench": "vitest run tests/search-benchmark.test.js",
+    "test:e2e": "playwright test",
+    "test:e2e:chromium": "playwright test --project=chromium",
+    "docs:patch-theme-picker": "node scripts/patch-docs-theme-picker.mjs",
+    "tokens:validate": "node cli/index.js tokens validate --input examples/tokens.sample.json",
+    "tokens:validate:full": "node cli/index.js tokens validate --input examples/tokens.full.json",
+    "docs:generate": "node cli/index.js docs generate",
+    "search:index": "node cli/index.js search index",
+    "skills:generate": "node packages/velinstyle-skills/scripts/generate-assets.mjs && node -e \"import('./packages/velinstyle-skills/index.js').then(m=>m.writeCatalogFile())\"",
+    "skills:validate": "node scripts/validate-skills.mjs",
+    "skills:doctor": "node scripts/check-skills-paths.mjs",
+    "meta:build": "node cli/index.js meta",
+    "ci:checks": "node scripts/ci-checks.mjs",
+    "check:blueprints": "node scripts/check-blueprint-classes.mjs",
+    "check:chaos": "node scripts/check-chaos-detection.mjs",
+    "release:check": "node scripts/check-release-sync.mjs",
+    "release:sync": "node scripts/check-release-sync.mjs --fix",
+    "intelligence:validate": "node scripts/validate-intelligence-schemas.mjs",
+    "prepublishOnly": "npm run build && npm run check:blueprints && npm run search:index && npm run skills:generate && npm run skills:validate && npm run skills:doctor && npm run meta:build && npm run intelligence:validate && npm run release:check -- --skip-site",
+    "pack:check": "npm pack --dry-run",
+    "docs:prepare": "npm run build && node scripts/prepare-docs-pages.js",
+    "docs:patch-nav": "node scripts/patch-docs-nav.js",
+    "docs:sync-site": "npm run build && npm run docs:generate && python ../velinstyle-site/tools/sync-framework-0.9.0.py && python ../velinstyle-site/tools/patch-site-a11y-aaa.py && python ../velinstyle-site/tools/patch-docs-090-final.py",
+    "readme:capture": "node tools/capture-readme-demos.mjs",
+    "readme:assets:webp": "node tools/readme-png-to-webp.mjs",
+    "demos:sync": "node tools/sync-demos-to-repo.mjs --out showcase-demos && node tools/sync-demos-to-repo.mjs --out ../velinstyle-demos",
+    "strategy:bootstrap-issues": "node scripts/bootstrap-github-backlog.mjs",
+    "strategy:bootstrap-issues:dry": "node scripts/bootstrap-github-backlog.mjs --dry-run",
+    "strategy:bootstrap-next30": "node scripts/bootstrap-github-backlog.mjs --issues-only --seed=../interne_docs/strategy/next-30-issues.json --map=../interne_docs/strategy/next-30-issue-map.json",
+    "strategy:bootstrap-next30:dry": "node scripts/bootstrap-github-backlog.mjs --dry-run --issues-only --seed=../interne_docs/strategy/next-30-issues.json --map=../interne_docs/strategy/next-30-issue-map.json"
+  },
+  "keywords": [
+    "css",
+    "framework",
+    "accessibility",
+    "a11y",
+    "wcag",
+    "mobile-first",
+    "container-queries",
+    "oklch",
+    "web-components",
+    "design-tokens",
+    "dark-mode",
+    "rtl"
+  ],
+  "author": "SkyliteDesign",
+  "license": "MIT",
+  "devDependencies": {
+    "@playwright/test": "^1.60.0",
+    "axe-core": "^4.10.0",
+    "esbuild": "^0.24.0",
+    "jsdom": "^26.1.0",
+    "lightningcss-cli": "^1.28.0",
+    "playwright": "^1.60.0",
+    "serve": "^14.0.0",
+    "sharp": "^0.34.5",
+    "stylelint": "^16.0.0",
+    "stylelint-config-standard": "^36.0.0",
+    "vitest": "^3.2.0"
+  },
+  "dependencies": {
+    "isomorphic-dompurify": "^3.21.0"
+  }
+}

package/packages/velinstyle-cli-core/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@birdapi/velinstyle-cli-core",
+  "version": "1.3.0",
+  "private": true,
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "description": "Velin Experience core — lifecycle, event bus, config, output contract"
+}

package/packages/velinstyle-cli-core/src/config.js

@@ -0,0 +1,84 @@
+/**
+ * Velin Experience config — velinstyle-cli.json (+ flags/env).
+ */
+import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'fs';
+import { join, resolve } from 'path';
+
+export const DEFAULT_EXPERIENCE_CONFIG = {
+  theme: 'modern',
+  output: 'standard',
+  icons: true,
+  unicode: true,
+  animations: true,
+  progress: true,
+  compact: false,
+  analytics: false,
+  record: false,
+};
+
+const CONFIG_NAMES = ['velinstyle-cli.json', 'velin-experience.json'];
+
+export function loadExperienceConfig(cwd = process.cwd(), overrides = {}) {
+  const root = resolve(cwd);
+  let fileConfig = {};
+  for (const name of CONFIG_NAMES) {
+    const path = join(root, name);
+    if (existsSync(path)) {
+      try {
+        fileConfig = JSON.parse(readFileSync(path, 'utf8'));
+      } catch {
+        fileConfig = {};
+      }
+      break;
+    }
+  }
+
+  const envTheme = process.env.VELIN_EXPERIENCE_THEME;
+  const envOutput = process.env.VELIN_EXPERIENCE_OUTPUT;
+
+  return {
+    ...DEFAULT_EXPERIENCE_CONFIG,
+    ...fileConfig,
+    ...(envTheme ? { theme: envTheme } : {}),
+    ...(envOutput ? { output: envOutput } : {}),
+    ...overrides,
+  };
+}
+
+export function analyticsPath(cwd = process.cwd()) {
+  return join(resolve(cwd), '.velin', 'experience-analytics.json');
+}
+
+export function recordUsage(commandId, cwd = process.cwd()) {
+  const path = analyticsPath(cwd);
+  mkdirSync(join(resolve(cwd), '.velin'), { recursive: true });
+  let data = { commands: {} };
+  if (existsSync(path)) {
+    try {
+      data = JSON.parse(readFileSync(path, 'utf8'));
+    } catch {
+      data = { commands: {} };
+    }
+  }
+  data.commands[commandId] = (data.commands[commandId] || 0) + 1;
+  data.updatedAt = new Date().toISOString();
+  writeFileSync(path, JSON.stringify(data, null, 2));
+  return data;
+}
+
+export function suggestFromAnalytics(cwd = process.cwd()) {
+  const path = analyticsPath(cwd);
+  if (!existsSync(path)) return null;
+  let data;
+  try {
+    data = JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+  const cmds = data.commands || {};
+  const hot = ['production', 'review', 'doctor'].filter((id) => (cmds[id] || 0) >= 2);
+  if (hot.length >= 2 && !(cmds.dashboard > 0)) {
+    return 'You often run production / review / doctor — try `velinstyle dashboard`.';
+  }
+  return null;
+}

package/packages/velinstyle-cli-core/src/contract.js

@@ -0,0 +1,56 @@
+/**
+ * Output Contract — every command fills the same shape (no free-form text).
+ */
+
+export function createEmptyContract(partial = {}) {
+  return {
+    project: partial.project || {},
+    lifecycle: partial.lifecycle || { stage: 'init', stages: [] },
+    result: partial.result || { status: 'PASS', message: '' },
+    stats: partial.stats || {},
+    widgets: Array.isArray(partial.widgets) ? [...partial.widgets] : [],
+    suggestions: Array.isArray(partial.suggestions) ? [...partial.suggestions] : [],
+    diagnostics: Array.isArray(partial.diagnostics) ? [...partial.diagnostics] : [],
+    notifications: Array.isArray(partial.notifications) ? [...partial.notifications] : [],
+    meta: partial.meta || {},
+  };
+}
+
+export function validateContract(contract) {
+  const problems = [];
+  if (!contract || typeof contract !== 'object') {
+    return { ok: false, problems: ['contract must be an object'] };
+  }
+  for (const key of ['project', 'lifecycle', 'result', 'stats']) {
+    if (contract[key] == null || typeof contract[key] !== 'object') {
+      problems.push(`missing or invalid "${key}"`);
+    }
+  }
+  for (const key of ['widgets', 'suggestions', 'diagnostics']) {
+    if (!Array.isArray(contract[key])) problems.push(`"${key}" must be an array`);
+  }
+  if (contract.result && !['PASS', 'WARNING', 'ERROR', 'SUGGESTION'].includes(contract.result.status)) {
+    problems.push('result.status must be PASS|WARNING|ERROR|SUGGESTION');
+  }
+  return { ok: problems.length === 0, problems };
+}
+
+export function pushWidget(contract, id, props = {}) {
+  contract.widgets.push({ id, props });
+  return contract;
+}
+
+export function pushSuggestion(contract, text, opts = {}) {
+  contract.suggestions.push({ text, ...opts });
+  return contract;
+}
+
+export function pushDiagnostic(contract, diagnostic) {
+  contract.diagnostics.push(diagnostic);
+  return contract;
+}
+
+export function setResult(contract, status, message = '') {
+  contract.result = { status, message };
+  return contract;
+}

package/packages/velinstyle-cli-core/src/event-bus.js

@@ -0,0 +1,50 @@
+/**
+ * Velin Experience event bus — commands emit; renderers/plugins subscribe.
+ */
+export function createEventBus() {
+  /** @type {Map<string, Set<Function>>} */
+  const listeners = new Map();
+
+  function on(event, handler) {
+    if (!listeners.has(event)) listeners.set(event, new Set());
+    listeners.get(event).add(handler);
+    return () => off(event, handler);
+  }
+
+  function off(event, handler) {
+    listeners.get(event)?.delete(handler);
+  }
+
+  function emit(event, payload) {
+    const set = listeners.get(event);
+    if (!set) return;
+    for (const handler of set) {
+      try {
+        handler(payload);
+      } catch (err) {
+        if (event !== 'onError') emit('onError', { error: err, source: event });
+      }
+    }
+  }
+
+  function once(event, handler) {
+    const wrap = (payload) => {
+      off(event, wrap);
+      handler(payload);
+    };
+    return on(event, wrap);
+  }
+
+  return { on, off, once, emit };
+}
+
+export const EXPERIENCE_EVENTS = [
+  'onStart',
+  'onProgress',
+  'onWarning',
+  'onSuggestion',
+  'onResult',
+  'onFinish',
+  'onError',
+  'onNotification',
+];

package/packages/velinstyle-cli-core/src/index.js

@@ -0,0 +1,18 @@
+export { createEventBus, EXPERIENCE_EVENTS } from './event-bus.js';
+export {
+  createEmptyContract,
+  validateContract,
+  pushWidget,
+  pushSuggestion,
+  pushDiagnostic,
+  setResult,
+} from './contract.js';
+export { LIFECYCLE_STAGES, createLifecycleTracker } from './lifecycle.js';
+export {
+  DEFAULT_EXPERIENCE_CONFIG,
+  loadExperienceConfig,
+  recordUsage,
+  suggestFromAnalytics,
+  analyticsPath,
+} from './config.js';
+export { runExperienceCommand } from './runner.js';

package/packages/velinstyle-cli-core/src/lifecycle.js

@@ -0,0 +1,33 @@
+/** Fixed lifecycle stages for every Experience command. */
+export const LIFECYCLE_STAGES = [
+  'init',
+  'loadConfig',
+  'environment',
+  'input',
+  'analysis',
+  'processing',
+  'validation',
+  'result',
+  'hints',
+  'summary',
+];
+
+export function createLifecycleTracker() {
+  const stages = [];
+  let current = 'init';
+
+  function enter(stage) {
+    if (!LIFECYCLE_STAGES.includes(stage)) {
+      throw new Error(`Unknown lifecycle stage: ${stage}`);
+    }
+    current = stage;
+    stages.push({ stage, at: new Date().toISOString() });
+    return current;
+  }
+
+  function snapshot() {
+    return { stage: current, stages: [...stages] };
+  }
+
+  return { enter, snapshot, get stage() { return current; } };
+}