vibecarbon 0.1.0

package/src/lib/tracker.js

@@ -0,0 +1,242 @@
+/**
+ * Command Tracker — step-level timing and persistent log files for CLI commands
+ *
+ * Usage:
+ *   const tracker = createTracker('deploy', { environment: 'prod' });
+ *   const s = tracker.spinner();
+ *   s.start('Provisioning cluster');
+ *   s.stop('Cluster provisioned');
+ *   const { formatted } = tracker.finish();
+ */
+
+import { createWriteStream, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import * as p from '@clack/prompts';
+
+/**
+ * Format milliseconds into a human-readable duration string.
+ * @param {number} ms
+ * @returns {string} e.g. "3s", "2m 14s"
+ */
+function formatDuration(ms) {
+  const totalSecs = Math.round(ms / 1000);
+  const mins = Math.floor(totalSecs / 60);
+  const secs = totalSecs % 60;
+  return mins > 0 ? `${mins}m ${secs}s` : `${secs}s`;
+}
+
+/**
+ * Format a timestamp for log lines (HH:MM:SS)
+ * @param {Date} date
+ * @returns {string}
+ */
+function formatTime(date) {
+  return date.toISOString().slice(11, 19);
+}
+
+/**
+ * Right-pad a duration string to a fixed width for aligned output.
+ * @param {string} str
+ * @param {number} width
+ * @returns {string}
+ */
+function padDuration(str, width = 8) {
+  return str.padStart(width);
+}
+
+/**
+ * Create a CommandTracker for a CLI command.
+ *
+ * @param {string} command  - Command name (e.g. 'deploy', 'destroy')
+ * @param {object} [meta]  - Key/value metadata written to the log header
+ * @returns {CommandTracker}
+ */
+export function createTracker(command, meta = {}) {
+  return new CommandTracker(command, meta);
+}
+
+/**
+ * Create a prefixed tracker for parallel operations (e.g., HA deploys).
+ * Instead of real @clack spinners (which corrupt when two run concurrently),
+ * this uses p.log.info with a region/label prefix for each step.
+ *
+ * Duck-type compatible with CommandTracker — can be passed as options.tracker.
+ *
+ * @param {string} label - Prefix label (e.g., "fsn1", "nbg1")
+ * @param {object} [opts] - Options
+ * @param {CommandTracker} [opts.parent] - Parent tracker for log file writes
+ * @returns {object} Tracker-compatible object
+ */
+export function createPrefixedTracker(label, opts = {}) {
+  const parent = opts.parent;
+  const dim = (s) => `\x1b[2m${s}\x1b[22m`;
+  const prefix = dim(`[${label}]`);
+
+  return {
+    spinner() {
+      let stepStart = null;
+      let stepLabel = null;
+
+      return {
+        start(msg) {
+          stepStart = performance.now();
+          stepLabel = msg;
+          p.log.step(`${prefix} ${msg}`);
+          parent?.log?.(`[${label}] START  ${msg}`);
+        },
+        stop(msg) {
+          const elapsed = stepStart ? formatDuration(performance.now() - stepStart) : '';
+          const display = msg || stepLabel;
+          p.log.info(`${prefix} ${display} ${dim(`(${elapsed})`)}`);
+          parent?.log?.(`[${label}] DONE   ${display} (${elapsed})`);
+          stepStart = null;
+          stepLabel = null;
+        },
+        message(msg) {
+          p.log.info(`${prefix} ${msg}`);
+          parent?.log?.(`[${label}] UPDATE ${msg}`);
+        },
+      };
+    },
+    log(msg) {
+      parent?.log?.(`[${label}] ${msg}`);
+    },
+  };
+}
+
+class CommandTracker {
+  constructor(command, meta) {
+    this.command = command;
+    this.meta = meta;
+    this.startTime = performance.now();
+    this.steps = []; // { label, durationMs }
+    this._currentStep = null; // { label, startTime }
+    this._stream = null;
+
+    // Open log file
+    const logsDir = join(process.cwd(), '.vibecarbon', 'logs');
+    try {
+      if (!existsSync(logsDir)) {
+        mkdirSync(logsDir, { recursive: true });
+      }
+      const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+      const envSuffix = meta.environment ? `-${meta.environment}` : '';
+      const filename = `${command}${envSuffix}-${timestamp}.log`;
+      this.logPath = join(logsDir, filename);
+      this._stream = createWriteStream(this.logPath, { flags: 'a' });
+
+      // Write header
+      this._write(`=== vibecarbon ${command} ===`);
+      this._write(`Started: ${new Date().toISOString()}`);
+      for (const [key, value] of Object.entries(meta)) {
+        if (value != null) {
+          this._write(`  ${key}: ${value}`);
+        }
+      }
+      this._write('');
+    } catch {
+      // If we can't create the log file (e.g. no .vibecarbon dir), continue without logging
+      this.logPath = null;
+    }
+  }
+
+  /**
+   * Create a spinner wrapper that records timing and writes to the log.
+   * Duck-type compatible with p.spinner().
+   * @returns {{ start(msg: string): void, stop(msg: string, code?: number): void, message(msg: string): void }}
+   */
+  spinner() {
+    let realSpinner = p.spinner();
+    const tracker = this;
+
+    return {
+      start(msg) {
+        // If a previous step wasn't stopped, record it as-is
+        if (tracker._currentStep) {
+          const elapsed = performance.now() - tracker._currentStep.startTime;
+          tracker.steps.push({ label: tracker._currentStep.label, durationMs: elapsed });
+        }
+
+        tracker._currentStep = { label: msg, startTime: performance.now() };
+        tracker._write(`[${formatTime(new Date())}] START  ${msg}`);
+        // Create a fresh spinner — clack spinners don't cleanly restart after stop()
+        realSpinner = p.spinner();
+        realSpinner.start(msg);
+      },
+
+      stop(msg, code) {
+        if (tracker._currentStep) {
+          const elapsed = performance.now() - tracker._currentStep.startTime;
+          tracker.steps.push({ label: msg || tracker._currentStep.label, durationMs: elapsed });
+          tracker._write(
+            `[${formatTime(new Date())}] DONE   ${msg || tracker._currentStep.label} (${formatDuration(elapsed)})`,
+          );
+          tracker._currentStep = null;
+        }
+        realSpinner.stop(msg, code);
+      },
+
+      message(msg) {
+        tracker._write(`[${formatTime(new Date())}] UPDATE ${msg}`);
+        realSpinner.message(msg);
+      },
+    };
+  }
+
+  /**
+   * Write an arbitrary line to the log file.
+   * @param {string} msg
+   */
+  log(msg) {
+    this._write(`[${formatTime(new Date())}] LOG    ${msg}`);
+  }
+
+  /**
+   * Finalize tracking: write summary to log, print timing table to console.
+   * @returns {{ elapsed: number, formatted: string, logPath: string | null }}
+   */
+  finish() {
+    const totalMs = performance.now() - this.startTime;
+    const formatted = formatDuration(totalMs);
+
+    // Write step summary to log
+    if (this.steps.length > 0) {
+      this._write('');
+      this._write('=== Step Summary ===');
+      for (const step of this.steps) {
+        this._write(`  ${padDuration(formatDuration(step.durationMs))}  ${step.label}`);
+      }
+      this._write(`  ${padDuration(formatted)}  TOTAL`);
+    }
+    this._write('');
+    this._write(`Finished: ${new Date().toISOString()}`);
+
+    // Close stream
+    if (this._stream) {
+      this._stream.end();
+      this._stream = null;
+    }
+
+    // Print timing stats table to console (only if >1 step)
+    if (this.steps.length > 1) {
+      const lines = this.steps.map(
+        (step) => `${padDuration(formatDuration(step.durationMs))}  ${step.label}`,
+      );
+      lines.push(`${padDuration(formatted)}  Total`);
+      p.note(lines.join('\n'), 'Stats');
+    }
+
+    return { elapsed: totalMs, formatted, logPath: this.logPath };
+  }
+
+  /**
+   * Write a line to the log file stream.
+   * @param {string} line
+   * @private
+   */
+  _write(line) {
+    if (this._stream) {
+      this._stream.write(`${line}\n`);
+    }
+  }
+}

package/src/lib/upgrade-policy.js

@@ -0,0 +1,170 @@
+/**
+ * Upgrade policy — classifies template files into safe / merge / never categories
+ */
+
+import { readdirSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+// Files that can be auto-replaced when unmodified by the user
+const SAFE_PATTERNS = [
+  'Dockerfile',
+  'docker-entrypoint.sh',
+  '.dockerignore',
+  'docker-compose.prod.yml',
+  'docker-compose.observability.yml',
+  'docker-compose.observability.prod.yml',
+  'docker-compose.observability.override.yml',
+  'docker-compose.metabase.yml',
+  'docker-compose.metabase.override.yml',
+  'docker-compose.n8n.yml',
+  'docker-compose.n8n.override.yml',
+  'docker-compose.dev-init.yml',
+  'k8s/base/**',
+  'k8s/infra/**',
+  'k8s/flux/**',
+  'cloud-init/**',
+  '.github/workflows/**',
+  'biome.json',
+  'tsconfig.json',
+  'tsconfig.server.json',
+  'components.json',
+  'backup/**',
+  'scripts/**',
+  'volumes/kong/**',
+  'volumes/grafana/**',
+  'volumes/prometheus/**',
+  'volumes/loki/**',
+  'volumes/promtail/**',
+  'volumes/traefik/**',
+  'AGENTS.md',
+  'CLAUDE.md',
+  'PRODUCTION.md',
+  'DEVELOPMENT.md',
+  '.windsurfrules',
+  '.github/copilot-instructions.md',
+  '.cursor/rules/**',
+  '.claude/settings.json',
+  '.claude/hooks/**',
+  '.claude/agents/**',
+];
+
+// Files that always require user review
+const MERGE_PATTERNS = [
+  'docker-compose.yml',
+  'docker-compose.override.yml',
+  'package.json',
+  'vite.config.ts',
+  'k8s/overlays/**',
+  '.gitignore',
+];
+
+// Files that should never be touched
+const NEVER_PATTERNS = [
+  'src/**',
+  'content/**',
+  'supabase/**',
+  '.env',
+  '.env.local',
+  '.env.example',
+  'README.md',
+  'volumes/db/**',
+  'node_modules/**',
+  'dist/**',
+  'pnpm-lock.yaml',
+  'package-lock.json',
+  'bun.lock',
+  'bun.lockb',
+  '.git/**',
+  '.claude/agent-memory/**',
+];
+
+/**
+ * Convert a simple glob pattern to a RegExp.
+ * Supports `**` (any path depth) and `*` (any filename chars).
+ *
+ * @param {string} pattern
+ * @returns {RegExp}
+ */
+function globToRegex(pattern) {
+  const re = pattern
+    // Escape regex-special chars except * and /
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    // ** matches any number of path segments (including zero)
+    .replace(/\*\*/g, '{{GLOBSTAR}}')
+    // * matches anything except path separator
+    .replace(/\*/g, '[^/]*')
+    .replace(/\{\{GLOBSTAR\}\}/g, '.*');
+  return new RegExp(`^${re}$`);
+}
+
+/**
+ * Test if a path matches any pattern in a list
+ *
+ * @param {string} filePath
+ * @param {string[]} patterns
+ * @returns {boolean}
+ */
+function matchesAny(filePath, patterns) {
+  return patterns.some((p) => globToRegex(p).test(filePath));
+}
+
+/**
+ * Classify a file path into an upgrade policy category
+ *
+ * @param {string} relativePath - Path relative to project root
+ * @returns {'safe' | 'merge' | 'never'}
+ */
+export function getFilePolicy(relativePath) {
+  if (matchesAny(relativePath, NEVER_PATTERNS)) return 'never';
+  if (matchesAny(relativePath, MERGE_PATTERNS)) return 'merge';
+  if (matchesAny(relativePath, SAFE_PATTERNS)) return 'safe';
+  // Default: files not explicitly classified are never touched
+  return 'never';
+}
+
+/**
+ * Walk a directory tree and return all file paths relative to rootDir
+ *
+ * @param {string} rootDir - Root directory to walk
+ * @returns {string[]} - Array of relative file paths
+ */
+function walkDir(rootDir) {
+  const results = [];
+
+  function walk(dir) {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        // Skip node_modules and .git in template
+        if (entry.name === 'node_modules' || entry.name === '.git') continue;
+        walk(fullPath);
+      } else {
+        results.push(relative(rootDir, fullPath));
+      }
+    }
+  }
+
+  walk(rootDir);
+  return results;
+}
+
+/**
+ * Get all upgradeable files from the template directory
+ * Returns files that are classified as 'safe' or 'merge'
+ *
+ * @param {string} templateDir - Path to the carbon/ template directory
+ * @returns {string[]} - Array of relative file paths
+ */
+export function getUpgradeableFiles(templateDir) {
+  const allFiles = walkDir(templateDir);
+  return allFiles.filter((f) => {
+    const policy = getFilePolicy(f);
+    return policy === 'safe' || policy === 'merge';
+  });
+}

package/src/lib/validators.js

@@ -0,0 +1,105 @@
+/**
+ * Input validators shared across create, cli, restore, backup, configure.
+ *
+ * Every validator returns `undefined` on success and a human-readable error
+ * string on failure. This matches @clack/prompts' `validate` contract and
+ * lets the same function work for both interactive prompts and non-interactive
+ * CLI argument validation.
+ */
+
+import { basename } from 'node:path';
+
+const RESERVED_PROJECT_NAMES = new Set(['node_modules', 'dist', 'build', 'coverage', '__tests__']);
+
+const PROJECT_NAME_RE = /^[a-z]([a-z0-9-]*[a-z0-9])?$/;
+
+/**
+ * Validate a project name. Must be a bare basename, lowercase DNS-safe,
+ * not reserved, max 63 characters.
+ * Returns undefined on success, error string on failure.
+ */
+export function validateProjectName(name) {
+  if (!name) return 'Project name is required';
+  if (name !== basename(name) || name.startsWith('.')) {
+    return 'Project name must be a basename (no slashes, no ../, no dot-names)';
+  }
+  if (name.length > 63) return 'Project name must be 63 characters or fewer';
+  if (RESERVED_PROJECT_NAMES.has(name.toLowerCase())) {
+    return `"${name}" is a reserved name`;
+  }
+  if (!PROJECT_NAME_RE.test(name)) {
+    return 'Project name must be lowercase, start with a letter, and contain only letters, digits, and hyphens';
+  }
+  return undefined;
+}
+
+const EMAIL_RE = /^[A-Za-z0-9._+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$/;
+
+/**
+ * Validate an admin email address.
+ * Returns undefined on success, error string on failure.
+ */
+export function validateAdminEmail(email) {
+  if (!email) return 'Email is required';
+  if (!EMAIL_RE.test(email)) {
+    return 'Email must be a simple address (letters, digits, . _ + -, single @)';
+  }
+  return undefined;
+}
+
+const PRINTABLE_ASCII_RE = /^[\x20-\x7e]+$/;
+// Block chars that break single-quote escaping or cause expansion if quoting is
+// accidentally skipped. Other shell-special chars (| ; & etc.) are safe inside
+// shEscape's single-quoted output, so they're intentionally not blocked here.
+const SHELL_METACHARS_RE = /['"`$\\]/;
+// biome-ignore lint/suspicious/noControlCharactersInRegex: intentional — rejecting control chars
+const CONTROL_CHARS_RE = /[\u0000-\u001f\u007f]/;
+
+/**
+ * Validate an admin password. Must be printable ASCII, no shell metacharacters.
+ * Returns undefined on success, error string on failure.
+ */
+export function validateAdminPassword(password) {
+  if (!password || password.length < 8) return 'Password must be at least 8 characters';
+  if (CONTROL_CHARS_RE.test(password)) return 'Password must not contain control characters';
+  if (SHELL_METACHARS_RE.test(password)) {
+    return `Password must not contain ', ", backtick, $, or \\`;
+  }
+  if (!PRINTABLE_ASCII_RE.test(password)) return 'Password must be printable ASCII only';
+  return undefined;
+}
+
+const DOMAIN_LABEL_RE = /^[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?$/;
+
+/**
+ * Validate a domain name. Must be a valid DNS hostname, max 253 characters.
+ * Returns undefined on success, error string on failure.
+ */
+export function validateDomain(domain) {
+  if (!domain) return 'Domain is required';
+  if (domain.length > 253) return 'Domain must be 253 characters or fewer';
+  if (domain.startsWith('.') || domain.endsWith('.')) {
+    return 'Domain must not start or end with a dot';
+  }
+  const labels = domain.split('.');
+  if (labels.length < 2) return 'Domain must contain at least one dot';
+  for (const label of labels) {
+    if (!DOMAIN_LABEL_RE.test(label)) return `"${label}" is not a valid domain label`;
+  }
+  return undefined;
+}
+
+const BACKUP_FILENAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*\.(tar\.gz|sql\.gz|tar|sql)$/;
+
+/**
+ * Validate a backup filename. Must be a safe basename with a recognised extension.
+ * Returns undefined on success, error string on failure.
+ */
+export function validateBackupFilename(name) {
+  if (!name) return 'Backup filename is required';
+  if (name !== basename(name)) return 'Backup filename must be a basename (no paths)';
+  if (!BACKUP_FILENAME_RE.test(name)) {
+    return 'Backup filename must match <safe-name>.(tar|sql)[.gz]';
+  }
+  return undefined;
+}

package/src/lib/version.js

@@ -0,0 +1,5 @@
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { version } = require('../../package.json');
+export const VERSION = version;