@birdapi/velinstyle 1.2.1 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@birdapi/velinstyle",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
@@ -24,12 +24,20 @@
     "./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"
+    "./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"
@@ -52,7 +60,13 @@
     "packages/velinstyle-skills/",
     "schemas/",
     "examples/search-index.schema.json",
-    "icons/velin-icons.svg"
+    "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",
@@ -75,7 +89,8 @@
     "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: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",

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; } };
+}

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

@@ -0,0 +1,129 @@
+/**
+ * Experience command runner — lifecycle + bus + contract collection.
+ */
+import { createEventBus } from './event-bus.js';
+import { createEmptyContract, validateContract } from './contract.js';
+import { createLifecycleTracker } from './lifecycle.js';
+import { loadExperienceConfig, recordUsage, suggestFromAnalytics } from './config.js';
+
+/**
+ * @param {object} opts
+ * @param {string} opts.commandId
+ * @param {object} [opts.configOverrides]
+ * @param {string} [opts.cwd]
+ * @param {(ctx: object) => Promise<object>|object} opts.run — returns contract partial or full contract
+ */
+export async function runExperienceCommand(opts) {
+  const {
+    commandId,
+    configOverrides = {},
+    cwd = process.cwd(),
+    run,
+    layout = 'standard',
+    meta = {},
+  } = opts;
+
+  const config = loadExperienceConfig(cwd, configOverrides);
+  const bus = createEventBus();
+  const lifecycle = createLifecycleTracker();
+  const startedAt = Date.now();
+
+  const events = [];
+  const recordEvent = (type, payload) => {
+    events.push({ type, payload, at: new Date().toISOString() });
+  };
+
+  for (const ev of ['onStart', 'onProgress', 'onWarning', 'onSuggestion', 'onResult', 'onFinish', 'onNotification']) {
+    bus.on(ev, (payload) => recordEvent(ev, payload));
+  }
+
+  lifecycle.enter('init');
+  bus.emit('onStart', { commandId, config });
+
+  lifecycle.enter('loadConfig');
+  lifecycle.enter('environment');
+
+  if (config.analytics) {
+    try {
+      recordUsage(commandId, cwd);
+    } catch {
+      /* ignore analytics failures */
+    }
+  }
+
+  let contract = createEmptyContract({
+    project: { cwd, commandId },
+    meta: { ...meta, layout, commandId, version: meta.version || null },
+  });
+
+  lifecycle.enter('input');
+  lifecycle.enter('analysis');
+  lifecycle.enter('processing');
+
+  const ctx = {
+    bus,
+    config,
+    cwd,
+    commandId,
+    lifecycle,
+    contract,
+    emitProgress: (label, percent) => bus.emit('onProgress', { label, percent }),
+    notify: (message, tone = 'info') => {
+      bus.emit('onNotification', { message, tone });
+      contract.notifications.push({ message, tone });
+    },
+  };
+
+  const result = await run(ctx);
+  if (result && typeof result === 'object') {
+    contract = {
+      ...contract,
+      ...result,
+      widgets: result.widgets || contract.widgets,
+      suggestions: result.suggestions || contract.suggestions,
+      diagnostics: result.diagnostics || contract.diagnostics,
+      notifications: result.notifications || contract.notifications,
+      project: { ...contract.project, ...(result.project || {}) },
+      stats: { ...contract.stats, ...(result.stats || {}) },
+      result: result.result || contract.result,
+      meta: { ...contract.meta, ...(result.meta || {}) },
+    };
+  }
+
+  lifecycle.enter('validation');
+  const validation = validateContract(contract);
+  if (!validation.ok) {
+    contract.diagnostics.push({
+      severity: 'warning',
+      message: `Contract validation: ${validation.problems.join('; ')}`,
+    });
+  }
+
+  lifecycle.enter('hints');
+  if (config.analytics) {
+    const tip = suggestFromAnalytics(cwd);
+    if (tip) {
+      contract.suggestions.push({ text: tip, source: 'analytics' });
+      bus.emit('onSuggestion', { text: tip });
+    }
+  }
+
+  lifecycle.enter('result');
+  contract.lifecycle = lifecycle.snapshot();
+  bus.emit('onResult', { result: contract.result });
+
+  lifecycle.enter('summary');
+  contract.meta = {
+    ...contract.meta,
+    durationMs: Date.now() - startedAt,
+    layout: contract.meta.layout || layout,
+  };
+  bus.emit('onFinish', { contract, durationMs: contract.meta.durationMs });
+
+  return {
+    contract,
+    config,
+    events,
+    bus,
+  };
+}