@vectorasystems/cli 0.1.0

package/src/lib/auth-store.js

@@ -0,0 +1,62 @@
+// @vectora/cli — credential persistence (~/.vectora/credentials)
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+
+const CREDENTIALS_DIR = path.join(os.homedir(), '.vectora');
+const CREDENTIALS_PATH = path.join(CREDENTIALS_DIR, 'credentials');
+
+/**
+ * @typedef {Object} Credentials
+ * @property {'device-flow'|'api-key'} method
+ * @property {string} apiToken  — the vk_ prefixed API key
+ * @property {string} userId
+ * @property {string} orgId
+ * @property {string} [email]
+ * @property {string} [orgName]
+ * @property {string} createdAt
+ */
+
+/**
+ * Read stored credentials.
+ * @returns {Promise<Credentials|null>}
+ */
+export async function getCredentials() {
+  try {
+    const raw = await fs.readFile(CREDENTIALS_PATH, 'utf-8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Persist credentials to disk.
+ * @param {Credentials} creds
+ */
+export async function saveCredentials(creds) {
+  await fs.mkdir(CREDENTIALS_DIR, { recursive: true });
+  await fs.writeFile(CREDENTIALS_PATH, JSON.stringify(creds, null, 2), 'utf-8');
+  // Best-effort: restrict permissions on Unix
+  try { await fs.chmod(CREDENTIALS_PATH, 0o600); } catch { /* Windows */ }
+}
+
+/**
+ * Clear stored credentials.
+ */
+export async function clearCredentials() {
+  try { await fs.unlink(CREDENTIALS_PATH); } catch { /* missing is fine */ }
+}
+
+/**
+ * Get the API token or throw AuthError.
+ * @returns {Promise<string>}
+ */
+export async function requireToken() {
+  const creds = await getCredentials();
+  if (!creds?.apiToken) {
+    const { AuthError } = await import('./errors.js');
+    throw new AuthError();
+  }
+  return creds.apiToken;
+}

package/src/lib/config-store.js

@@ -0,0 +1,60 @@
+// @vectora/cli — config persistence (~/.vectora/config.json)
+import Conf from 'conf';
+
+const DEFAULTS = {
+  apiUrl: 'https://api.vectora.build',
+  appUrl: 'https://vectora.build',
+  defaultWorkspace: null,
+  defaultProject: null,
+  outputFormat: 'table',
+  color: true,
+};
+
+const ALLOWED_KEYS = new Set(Object.keys(DEFAULTS));
+
+const config = new Conf({
+  projectName: 'vectora',
+  defaults: DEFAULTS,
+  schema: {
+    apiUrl: { type: 'string' },
+    appUrl: { type: 'string' },
+    defaultWorkspace: { type: ['string', 'null'] },
+    defaultProject: { type: ['string', 'null'] },
+    outputFormat: { type: 'string', enum: ['table', 'json'] },
+    color: { type: 'boolean' },
+  },
+});
+
+export function getConfig() {
+  return { ...DEFAULTS, ...config.store };
+}
+
+export function getConfigValue(key) {
+  if (!ALLOWED_KEYS.has(key)) throw new Error(`Unknown config key: ${key}`);
+  return config.get(key);
+}
+
+export function setConfigValue(key, value) {
+  if (!ALLOWED_KEYS.has(key)) throw new Error(`Unknown config key: ${key}`);
+  // Type coercion for boolean
+  if (key === 'color') {
+    config.set(key, value === 'true' || value === true);
+    return;
+  }
+  // Null for clearing
+  if (value === 'null' || value === '') {
+    config.set(key, null);
+    return;
+  }
+  config.set(key, value);
+}
+
+export function listConfig() {
+  return config.store;
+}
+
+export function resetConfig() {
+  config.clear();
+}
+
+export { ALLOWED_KEYS };

package/src/lib/constants.js

@@ -0,0 +1,94 @@
+// @vectora/cli — constants
+// Inlined from @vectora/engine to avoid dependency in API-connected mode.
+
+export const VERSION = '0.1.0';
+
+export const BRAND = {
+  name: 'VECTORA',
+  tagline: 'AI-powered product development',
+  accent: '#00e5ff',
+  green: '#00c853',
+};
+
+/** Forge orchestrator phases (MVP pipeline). */
+export const FORGE_PHASES = [
+  'analyze-codebase',
+  'plan-mvp',
+  'scope-loop',
+  'plan-roadmap',
+  'package-handoff',
+];
+
+/** Temper orchestrator phases (post-MVP pipeline). */
+export const TEMPER_PHASES = [
+  'assess-health',
+  'plan-growth',
+  'harden-reliability',
+  'plan-scale',
+  'plan-platform',
+];
+
+/** All valid phases for `vectora run`. */
+export const VALID_PHASES = [...FORGE_PHASES, ...TEMPER_PHASES];
+
+/** Directories to skip during workspace scanning. */
+export const WORKSPACE_IGNORED_DIRS = new Set([
+  '.git', 'node_modules', '.next', 'dist', 'build', 'coverage',
+  '.turbo', '.cache', 'vendor', 'target', '.idea', '.vscode',
+  '.svn', '__pycache__', '.tox', '.eggs', '.mypy_cache',
+  '.pytest_cache', '.nuxt', '.output', 'out',
+]);
+
+/** Manifest files to detect during workspace scanning. */
+export const WORKSPACE_MANIFEST_FILES = new Set([
+  'package.json', 'pnpm-lock.yaml', 'yarn.lock', 'package-lock.json',
+  'tsconfig.json', 'next.config.js', 'next.config.mjs', 'next.config.ts',
+  'pyproject.toml', 'requirements.txt', 'go.mod', 'Cargo.toml',
+  'pom.xml', 'build.gradle', 'docker-compose.yml', 'Dockerfile',
+  'README.md', '.env.example',
+]);
+
+/**
+ * Manifest files whose CONTENTS are safe to read and send to the API.
+ * Only small, non-secret config files. Lock files excluded (too large).
+ */
+export const WORKSPACE_MANIFEST_CONTENT_FILES = new Set([
+  'package.json',
+  'tsconfig.json',
+  'next.config.js', 'next.config.mjs', 'next.config.ts',
+  'pyproject.toml', 'requirements.txt',
+  'go.mod', 'go.sum',
+  'Cargo.toml',
+  'pom.xml', 'build.gradle',
+  'docker-compose.yml', 'Dockerfile',
+  '.env.example',
+]);
+
+/**
+ * File patterns that should NEVER have their contents read.
+ * Lowercase match. Can be exact names or RegExp.
+ */
+export const SENSITIVE_FILE_PATTERNS = [
+  '.env', '.env.local', '.env.production', '.env.development',
+  '.env.staging', '.env.test',
+  /^\.env\..+/,        // .env.anything (except .env.example handled above)
+  '.npmrc', '.pypirc',
+  'credentials', 'credentials.json',
+  'secrets.yml', 'secrets.yaml', 'secrets.json',
+  'id_rsa', 'id_ed25519', 'id_ecdsa',
+  /\.pem$/, /\.key$/, /\.p12$/, /\.pfx$/,
+  /\.tfstate$/,
+];
+
+export const DEFAULT_WORKSPACE_SCAN_MAX_FILES = 800;
+
+/** Max size in bytes for reading a manifest file's contents (100KB). */
+export const MAX_MANIFEST_CONTENT_SIZE = 100 * 1024;
+
+/** Exit codes. */
+export const EXIT = {
+  OK: 0,
+  ERROR: 1,
+  AUTH: 2,
+  OFFLINE: 3,
+};

package/src/lib/errors.js

@@ -0,0 +1,62 @@
+// @vectora/cli — error classes and handler
+import chalk from 'chalk';
+import { EXIT } from './constants.js';
+
+export class VectoraApiError extends Error {
+  constructor(message, statusCode, code) {
+    super(message);
+    this.name = 'VectoraApiError';
+    this.statusCode = statusCode;
+    this.code = code;
+  }
+}
+
+export class OfflineError extends Error {
+  constructor(url) {
+    super(`Cannot reach the Vectora API at ${url}`);
+    this.name = 'OfflineError';
+  }
+}
+
+export class AuthError extends Error {
+  constructor(message = 'Not authenticated. Run `vectora login` to authenticate.') {
+    super(message);
+    this.name = 'AuthError';
+  }
+}
+
+/**
+ * Top-level error handler — formats errors for the terminal and sets exit code.
+ * @param {Error} error
+ */
+export function handleError(error) {
+  if (error instanceof OfflineError) {
+    console.error(chalk.red('Offline — ') + error.message);
+    console.error(chalk.dim('Check your internet connection or run: vectora config set apiUrl <url>'));
+    process.exitCode = EXIT.OFFLINE;
+    return;
+  }
+
+  if (error instanceof AuthError) {
+    console.error(chalk.red('Auth — ') + error.message);
+    process.exitCode = EXIT.AUTH;
+    return;
+  }
+
+  if (error instanceof VectoraApiError) {
+    const prefix = error.statusCode >= 500 ? 'Server error' : 'API error';
+    console.error(chalk.red(`${prefix} (${error.statusCode}) — `) + error.message);
+    if (error.statusCode === 403) {
+      console.error(chalk.dim('Your plan may not include this feature. Check your billing at the dashboard.'));
+    }
+    if (error.statusCode === 429) {
+      console.error(chalk.dim('Rate limited. Wait a moment and try again.'));
+    }
+    process.exitCode = EXIT.ERROR;
+    return;
+  }
+
+  // Generic
+  console.error(chalk.red('Error — ') + (error.message || String(error)));
+  process.exitCode = EXIT.ERROR;
+}

package/src/lib/output.js

@@ -0,0 +1,98 @@
+// @vectora/cli — output formatters
+import chalk from 'chalk';
+import Table from 'cli-table3';
+
+/**
+ * Render a table to stdout.
+ * @param {string[]} head — column headers
+ * @param {string[][]} rows — row data
+ */
+export function renderTable(head, rows) {
+  const table = new Table({
+    head: head.map((h) => chalk.cyan.bold(h)),
+    style: { head: [], border: ['dim'] },
+    chars: {
+      top: '─', 'top-mid': '┬', 'top-left': '┌', 'top-right': '┐',
+      bottom: '─', 'bottom-mid': '┴', 'bottom-left': '└', 'bottom-right': '┘',
+      left: '│', 'left-mid': '├', mid: '─', 'mid-mid': '┼',
+      right: '│', 'right-mid': '┤', middle: '│',
+    },
+  });
+  for (const row of rows) table.push(row);
+  console.log(table.toString());
+}
+
+/**
+ * Render data as formatted JSON.
+ * @param {unknown} data
+ */
+export function renderJson(data) {
+  console.log(JSON.stringify(data, null, 2));
+}
+
+/**
+ * Render a phase status string with color.
+ * @param {string} status
+ * @returns {string}
+ */
+export function renderPhaseStatus(status) {
+  switch (status) {
+    case 'completed': return chalk.green('completed');
+    case 'failed': return chalk.red('failed');
+    case 'running': return chalk.yellow('running');
+    case 'queued': return chalk.dim('queued');
+    default: return chalk.dim(status);
+  }
+}
+
+/**
+ * Render a visual readiness bar.
+ * @param {number} score — 0 to 100
+ * @returns {string}
+ */
+export function renderReadinessBar(score) {
+  const filled = Math.round(score / 10);
+  const empty = 10 - filled;
+  const bar = chalk.green('█'.repeat(filled)) + chalk.dim('░'.repeat(empty));
+  return `[${bar}] ${score}%`;
+}
+
+/**
+ * Render a timestamp as a short relative or absolute string.
+ * @param {string} iso
+ * @returns {string}
+ */
+export function renderTime(iso) {
+  if (!iso) return chalk.dim('—');
+  const d = new Date(iso);
+  const now = Date.now();
+  const diffMs = now - d.getTime();
+  if (diffMs < 60_000) return chalk.dim('just now');
+  if (diffMs < 3600_000) return chalk.dim(`${Math.floor(diffMs / 60_000)}m ago`);
+  if (diffMs < 86400_000) return chalk.dim(`${Math.floor(diffMs / 3600_000)}h ago`);
+  return chalk.dim(d.toLocaleDateString());
+}
+
+/**
+ * Print a success message.
+ * @param {string} msg
+ */
+export function success(msg) {
+  console.log(chalk.green('✓') + ' ' + msg);
+}
+
+/**
+ * Print a warning message.
+ * @param {string} msg
+ */
+export function warn(msg) {
+  console.log(chalk.yellow('!') + ' ' + msg);
+}
+
+/**
+ * Print an info message.
+ * @param {string} msg
+ */
+export function info(msg) {
+  console.log(chalk.cyan('i') + ' ' + msg);
+}

package/src/lib/sse-client.js

@@ -0,0 +1,92 @@
+// @vectora/cli — SSE stream consumer
+// Handles both GET-based (phase SSE) and POST-based (idea-chat SSE) patterns.
+
+/**
+ * Parse an SSE stream from a ReadableStream<Uint8Array>.
+ * Yields `{ event, data }` for each SSE frame.
+ * @param {ReadableStream} body
+ */
+export async function* parseSseStream(body) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  let currentEvent = '';
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split('\n');
+      buffer = lines.pop() ?? '';
+
+      for (const line of lines) {
+        if (line.startsWith('event: ')) {
+          currentEvent = line.slice(7).trim();
+          continue;
+        }
+        if (line.startsWith('data: ')) {
+          try {
+            const data = JSON.parse(line.slice(6));
+            yield { event: currentEvent, data };
+          } catch { /* skip malformed frames */ }
+          currentEvent = '';
+        }
+        // Ignore ': ping' keepalive comments and empty lines
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+/**
+ * Stream phase progress events via GET SSE.
+ * @param {string} baseUrl
+ * @param {string} jobId
+ * @param {string} token
+ * @yields {{ event: string, data: object }}
+ */
+export async function* streamPhaseProgress(baseUrl, jobId, token) {
+  const res = await fetch(`${baseUrl}/v1/phases/${jobId}?token=${token}`, {
+    signal: AbortSignal.timeout(5 * 60 * 1000), // 5 min
+  });
+
+  if (!res.ok || !res.body) {
+    throw new Error(`Phase SSE failed: HTTP ${res.status}`);
+  }
+
+  yield* parseSseStream(res.body);
+}
+
+/**
+ * Stream idea-chat events via POST SSE.
+ * @param {string} baseUrl
+ * @param {string} token
+ * @param {string} projectId
+ * @param {string} message
+ * @param {object} [opts]
+ * @yields {{ event: string, data: object }}
+ */
+export async function* streamIdeaChat(baseUrl, token, projectId, message, opts) {
+  const res = await fetch(`${baseUrl}/v1/projects/${projectId}/idea-chat`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${token}`,
+    },
+    body: JSON.stringify({ message, ...opts }),
+    signal: AbortSignal.timeout(5 * 60 * 1000),
+  });
+
+  if (!res.ok || !res.body) {
+    let errMsg = `Idea chat failed: HTTP ${res.status}`;
+    try {
+      const errBody = await res.json();
+      errMsg = errBody.error ?? errBody.message ?? errMsg;
+    } catch { /* ignore */ }
+    throw new Error(errMsg);
+  }
+
+  yield* parseSseStream(res.body);
+}

package/src/lib/workspace-scanner.js

@@ -0,0 +1,227 @@
+// @vectora/cli — workspace snapshot collector
+// Hardened BFS scanner with symlink loop detection, binary skip,
+// cross-platform path normalization, and manifest content reading.
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {
+  WORKSPACE_IGNORED_DIRS,
+  WORKSPACE_MANIFEST_FILES,
+  WORKSPACE_MANIFEST_CONTENT_FILES,
+  SENSITIVE_FILE_PATTERNS,
+  DEFAULT_WORKSPACE_SCAN_MAX_FILES,
+  MAX_MANIFEST_CONTENT_SIZE,
+} from './constants.js';
+
+// Binary file extensions — skip during sampling
+const BINARY_EXTENSIONS = new Set([
+  '.png', '.jpg', '.jpeg', '.gif', '.bmp', '.ico', '.webp', '.svg',
+  '.mp3', '.mp4', '.wav', '.avi', '.mov', '.mkv', '.flac',
+  '.zip', '.gz', '.tar', '.rar', '.7z', '.bz2', '.xz',
+  '.wasm', '.so', '.dll', '.dylib', '.exe', '.bin',
+  '.pdf', '.doc', '.docx', '.xls', '.xlsx', '.ppt', '.pptx',
+  '.ttf', '.otf', '.woff', '.woff2', '.eot',
+  '.pyc', '.pyo', '.class', '.o', '.a', '.lib',
+  '.sqlite', '.db', '.sqlite3',
+  '.DS_Store', '.lock',
+]);
+
+/**
+ * Infer source roots from the scanned file list.
+ */
+function inferSourceRoots(files) {
+  const roots = new Set();
+  const srcDirs = new Set(['src', 'app', 'pages', 'server', 'lib', 'cmd', 'internal', 'pkg']);
+  for (const f of files) {
+    const parts = f.split('/');
+    if (parts.length >= 2 && srcDirs.has(parts[0])) {
+      roots.add(parts[0]);
+    }
+  }
+  return [...roots].sort();
+}
+
+/**
+ * Check whether a filename matches sensitive file patterns that should never
+ * have their contents read (even if they are manifest-like).
+ */
+function isSensitiveFile(name) {
+  const lower = name.toLowerCase();
+  return SENSITIVE_FILE_PATTERNS.some((p) => {
+    if (p instanceof RegExp) return p.test(lower);
+    return lower === p || lower.endsWith(p);
+  });
+}
+
+/**
+ * Normalize a path to forward slashes (Windows compat).
+ */
+function normalizePath(p) {
+  return p.replace(/\\/g, '/');
+}
+
+/**
+ * Safely read a manifest file's contents (text, capped at MAX_MANIFEST_CONTENT_SIZE).
+ * Returns null on any error or if the file is too large.
+ */
+async function readManifestContent(absPath) {
+  try {
+    const stat = await fs.stat(absPath);
+    if (stat.size > MAX_MANIFEST_CONTENT_SIZE) return null;
+    const content = await fs.readFile(absPath, 'utf-8');
+    return content;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Collect a workspace snapshot via BFS directory traversal.
+ *
+ * Hardened against:
+ * - Symlink loops (tracks visited inodes via realpath)
+ * - Binary files (skipped by extension)
+ * - Sensitive files (never read contents)
+ * - Windows paths (normalized to forward slashes)
+ * - Deep nesting (max depth cap)
+ * - Manifest content reading (safe subset, size-capped)
+ *
+ * @param {string} workspaceRoot — absolute path to the workspace
+ * @param {number} [maxFiles] — cap on sample files (default 800)
+ * @returns {Promise<object>}
+ */
+export async function collectWorkspaceSnapshot(workspaceRoot, maxFiles = DEFAULT_WORKSPACE_SCAN_MAX_FILES) {
+  const safeMax = Math.max(50, Math.min(maxFiles, 5000));
+  const MAX_DEPTH = 30;
+  const queue = [{ rel: '', depth: 0 }];
+  const visitedDirs = new Set(); // realpath set for symlink loop detection
+  const sampleFiles = [];
+  const manifests = [];
+  const keyFiles = [];
+  const manifestContents = {}; // relPath → file content (safe manifests only)
+  const warnings = [];
+  let totalFiles = 0;
+  let totalDirs = 0;
+
+  // Resolve workspace root realpath once
+  let rootReal;
+  try {
+    rootReal = await fs.realpath(workspaceRoot);
+  } catch {
+    rootReal = workspaceRoot;
+  }
+
+  while (queue.length && sampleFiles.length < safeMax) {
+    const { rel, depth } = queue.shift();
+
+    // Depth guard
+    if (depth > MAX_DEPTH) {
+      if (warnings.length < 10) warnings.push(`Skipped: ${rel} (depth > ${MAX_DEPTH})`);
+      continue;
+    }
+
+    const abs = path.join(rootReal, rel);
+
+    // Symlink loop detection: resolve realpath and check if visited
+    let realDir;
+    try {
+      realDir = await fs.realpath(abs);
+    } catch {
+      continue; // broken symlink or permission error
+    }
+
+    if (visitedDirs.has(realDir)) {
+      if (warnings.length < 10) warnings.push(`Skipped symlink loop: ${rel}`);
+      continue;
+    }
+    visitedDirs.add(realDir);
+
+    let entries;
+    try {
+      entries = await fs.readdir(abs, { withFileTypes: true });
+    } catch {
+      continue; // permission denied or other fs error
+    }
+
+    for (const entry of entries) {
+      // Skip ignored directories by name
+      if (WORKSPACE_IGNORED_DIRS.has(entry.name)) continue;
+
+      // Skip hidden files/dirs (dotfiles) except known ones
+      if (entry.name.startsWith('.') && !WORKSPACE_MANIFEST_FILES.has(entry.name)) continue;
+
+      const entryRel = normalizePath(rel ? `${rel}/${entry.name}` : entry.name);
+
+      if (entry.isDirectory() || entry.isSymbolicLink()) {
+        // For symlinks, verify the target is a directory
+        if (entry.isSymbolicLink()) {
+          try {
+            const linkTarget = path.join(abs, entry.name);
+            const stat = await fs.stat(linkTarget);
+            if (!stat.isDirectory()) {
+              // It's a symlink to a file — treat as file below
+              totalFiles++;
+              if (sampleFiles.length < safeMax && !isBinaryFile(entry.name)) {
+                sampleFiles.push(entryRel);
+              }
+              continue;
+            }
+          } catch {
+            continue; // broken symlink
+          }
+        }
+        totalDirs++;
+        queue.push({ rel: entryRel, depth: depth + 1 });
+      } else if (entry.isFile()) {
+        totalFiles++;
+
+        const isManifest = WORKSPACE_MANIFEST_FILES.has(entry.name);
+        if (isManifest) {
+          manifests.push(entryRel);
+        }
+
+        // Key files: manifests at workspace root
+        if (!rel && isManifest) {
+          keyFiles.push(entryRel);
+        }
+
+        // Read safe manifest contents (not sensitive, in the allow-list)
+        if (WORKSPACE_MANIFEST_CONTENT_FILES.has(entry.name) && !isSensitiveFile(entry.name)) {
+          const content = await readManifestContent(path.join(abs, entry.name));
+          if (content !== null) {
+            manifestContents[entryRel] = content;
+          }
+        }
+
+        // Sample file path (skip binaries)
+        if (sampleFiles.length < safeMax && !isBinaryFile(entry.name)) {
+          sampleFiles.push(entryRel);
+        }
+      }
+    }
+  }
+
+  const srcRoots = inferSourceRoots(sampleFiles);
+
+  return {
+    scannedAt: new Date().toISOString(),
+    sampledFileCount: sampleFiles.length,
+    maxFiles: safeMax,
+    manifests,
+    manifestContents,
+    srcRoots,
+    keyFiles,
+    sampleFiles,
+    totalFiles,
+    totalDirs,
+    truncated: totalFiles > safeMax,
+    ...(warnings.length > 0 && { warnings }),
+  };
+}
+
+/**
+ * Check if a filename looks like a binary file by extension.
+ */
+function isBinaryFile(name) {
+  const ext = path.extname(name).toLowerCase();
+  return BINARY_EXTENSIONS.has(ext);
+}