@birdapi/velinstyle 1.2.2 → 1.3.0

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