@vectorasystems/cli 0.1.3 → 0.2.1

package/bin/vectora.js

@@ -94,6 +94,14 @@ projects
     await m.remove(id);
   });
 
+projects
+  .command('archive <id>')
+  .description('Archive a project')
+  .action(async (id) => {
+    const m = await import('../src/commands/projects.js');
+    await m.archive(id);
+  });
+
 // ── Chat ──────────────────────────────────────────────────────────────────────
 program
   .command('chat')
@@ -202,6 +210,103 @@ config
     await m.reset();
   });
 
+// ── Validate ─────────────────────────────────────────────────────────────────
+program
+  .command('validate')
+  .description('Run 4-agent validation pipeline on the idea')
+  .option('-p, --project <id>', 'Project ID (defaults to active)')
+  .option('-f, --format <fmt>', 'Output format: table or json')
+  .action(async (opts) => {
+    const m = await import('../src/commands/validate.js');
+    await m.validate(opts);
+  });
+
+// ── Lock ─────────────────────────────────────────────────────────────────────
+program
+  .command('lock')
+  .description('Lock the idea scope (requires 100% readiness)')
+  .option('-p, --project <id>', 'Project ID (defaults to active)')
+  .action(async (opts) => {
+    const m = await import('../src/commands/lock.js');
+    await m.lock(opts);
+  });
+
+// ── Feedback ─────────────────────────────────────────────────────────────────
+program
+  .command('feedback')
+  .description('Submit feedback on a completed phase')
+  .option('-p, --project <id>', 'Project ID (defaults to active)')
+  .requiredOption('--phase <phaseId>', 'Phase ID to give feedback on')
+  .requiredOption('--message <text>', 'Feedback message')
+  .option('--rating <n>', 'Rating 1-5')
+  .action(async (opts) => {
+    const m = await import('../src/commands/feedback.js');
+    await m.feedback(opts);
+  });
+
+// ── Handoff ──────────────────────────────────────────────────────────────────
+const handoff = program.command('handoff').description('View or trigger handoff bundles');
+
+handoff
+  .command('show')
+  .description('Show current handoff bundle')
+  .option('-p, --project <id>', 'Project ID (defaults to active)')
+  .action(async (opts) => {
+    const m = await import('../src/commands/handoff.js');
+    await m.show(opts);
+  });
+
+handoff
+  .command('trigger')
+  .description('Generate a new handoff bundle')
+  .option('-p, --project <id>', 'Project ID (defaults to active)')
+  .option('-t, --target <target>', 'Target: claudecode, codex, generic', 'generic')
+  .action(async (opts) => {
+    const m = await import('../src/commands/handoff.js');
+    await m.trigger(opts);
+  });
+
+// ── Settings ─────────────────────────────────────────────────────────────────
+const settings = program.command('settings').description('Manage API keys and preferences');
+
+const settingsApiKeys = settings.command('api-keys').description('View or update API keys');
+
+settingsApiKeys
+  .command('show')
+  .description('Show configured API keys (masked)')
+  .action(async () => {
+    const m = await import('../src/commands/settings.js');
+    await m.apiKeys();
+  });
+
+settingsApiKeys
+  .command('set')
+  .description('Set an API key for a provider')
+  .requiredOption('--provider <name>', 'Provider: anthropic, openai, google')
+  .requiredOption('--key <value>', 'API key (empty string to remove)')
+  .action(async (opts) => {
+    const m = await import('../src/commands/settings.js');
+    await m.apiKeysSet(opts);
+  });
+
+const settingsKeyMode = settings.command('key-mode').description('View or set key mode');
+
+settingsKeyMode
+  .command('show')
+  .description('Show current key mode preference')
+  .action(async () => {
+    const m = await import('../src/commands/settings.js');
+    await m.keyMode();
+  });
+
+settingsKeyMode
+  .command('set <mode>')
+  .description('Set key mode: own or server')
+  .action(async (mode) => {
+    const m = await import('../src/commands/settings.js');
+    await m.keyModeSet(mode);
+  });
+
 // ── TUI ───────────────────────────────────────────────────────────────────────
 program
   .command('ui')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectorasystems/cli",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "Vectora CLI — AI-powered project orchestration",
   "type": "module",
   "bin": {

package/src/commands/artifacts.js

@@ -101,10 +101,22 @@ export async function download(id, opts) {
     }
 
     // Get presigned URL + suggested filename from API
-    const { url, filename } = await getArtifactDownloadUrl(id);
+    const { url, filename, inlineBase64 } = await getArtifactDownloadUrl(id);
 
     const outPath = resolve(opts.out ?? filename);
 
+    // Local-storage fallback: API returns the file bytes inline when no
+    // presigned URL backend is configured.
+    if (inlineBase64) {
+      const buffer = Buffer.from(inlineBase64, 'base64');
+      await writeFile(outPath, buffer);
+      success(`Saved to ${chalk.bold(outPath)} ${chalk.dim(`(${(buffer.length / 1024).toFixed(1)} KB)`)}`);
+      return;
+    }
+    if (!url) {
+      throw new Error('Artifact download URL was not provided by the API');
+    }
+
     // Fetch directly from R2 via presigned URL
     const res = await fetch(url, { signal: AbortSignal.timeout(60_000) });
     if (!res.ok) {

package/src/commands/feedback.js

@@ -0,0 +1,54 @@
+// @vectora/cli — feedback command: submit feedback on a phase
+import chalk from 'chalk';
+import { submitFeedback } from '../lib/api-client.js';
+import { getConfigValue } from '../lib/config-store.js';
+import { handleError } from '../lib/errors.js';
+import { success, warn } from '../lib/output.js';
+
+const VALID_RATINGS = [1, 2, 3, 4, 5];
+
+/**
+ * vectora feedback --phase <phaseId> --message <text> [--rating <1-5>] [--project <id>]
+ */
+export async function feedback(opts) {
+  try {
+    const projectId = opts.project ?? getConfigValue('defaultProject');
+    if (!projectId) {
+      warn('No project selected. Use --project <id> or: vectora projects select <id>');
+      process.exitCode = 1;
+      return;
+    }
+
+    if (!opts.phase) {
+      console.error(chalk.red('--phase <phaseId> is required'));
+      process.exitCode = 1;
+      return;
+    }
+
+    if (!opts.message) {
+      console.error(chalk.red('--message <text> is required'));
+      process.exitCode = 1;
+      return;
+    }
+
+    const body = {
+      phaseId: opts.phase,
+      feedbackText: opts.message,
+    };
+
+    if (opts.rating !== undefined) {
+      const rating = Number(opts.rating);
+      if (!VALID_RATINGS.includes(rating)) {
+        console.error(chalk.red('--rating must be 1-5'));
+        process.exitCode = 1;
+        return;
+      }
+      body.rating = rating;
+    }
+
+    const result = await submitFeedback(projectId, body);
+    success(`Feedback submitted (artifact: ${result.artifact?.id ?? 'saved'})`);
+  } catch (err) {
+    handleError(err);
+  }
+}

package/src/commands/handoff.js

@@ -0,0 +1,84 @@
+// @vectora/cli — handoff command: view or trigger handoff bundles
+import chalk from 'chalk';
+import ora from 'ora';
+import { getHandoff, triggerHandoff } from '../lib/api-client.js';
+import { getConfigValue } from '../lib/config-store.js';
+import { handleError } from '../lib/errors.js';
+import { success, warn, info, renderTime } from '../lib/output.js';
+
+const VALID_TARGETS = ['claudecode', 'codex', 'generic'];
+
+/**
+ * vectora handoff show [--project <id>]
+ */
+export async function show(opts) {
+  try {
+    const projectId = opts.project ?? getConfigValue('defaultProject');
+    if (!projectId) {
+      warn('No project selected. Use --project <id> or: vectora projects select <id>');
+      process.exitCode = 1;
+      return;
+    }
+
+    const result = await getHandoff(projectId);
+    const bundle = result.bundle;
+
+    if (!bundle) {
+      warn('No handoff bundle found. Run: vectora handoff trigger');
+      return;
+    }
+
+    console.log();
+    console.log(chalk.cyan.bold('  Handoff Bundle'));
+    console.log(chalk.dim('  ─────────────────────────────'));
+    console.log(`  ${chalk.dim('ID:')}       ${bundle.id}`);
+    console.log(`  ${chalk.dim('Version:')}  v${bundle.version}`);
+    console.log(`  ${chalk.dim('Target:')}   ${bundle.target}`);
+    console.log(`  ${chalk.dim('Created:')}  ${renderTime(bundle.createdAt)}`);
+    if (bundle.publicUrl) {
+      console.log(`  ${chalk.dim('URL:')}      ${chalk.cyan(bundle.publicUrl)}`);
+    }
+    console.log();
+  } catch (err) {
+    handleError(err);
+  }
+}
+
+/**
+ * vectora handoff trigger [--target <target>] [--project <id>]
+ */
+export async function trigger(opts) {
+  try {
+    const projectId = opts.project ?? getConfigValue('defaultProject');
+    if (!projectId) {
+      warn('No project selected. Use --project <id> or: vectora projects select <id>');
+      process.exitCode = 1;
+      return;
+    }
+
+    const target = opts.target ?? 'generic';
+    if (!VALID_TARGETS.includes(target)) {
+      console.error(chalk.red(`Invalid target: ${target}. Valid: ${VALID_TARGETS.join(', ')}`));
+      process.exitCode = 1;
+      return;
+    }
+
+    const spinner = ora({ text: `Triggering handoff (target: ${target})...`, color: 'cyan' }).start();
+
+    let result;
+    try {
+      result = await triggerHandoff(projectId, target);
+    } catch (err) {
+      spinner.fail('Failed to trigger handoff');
+      throw err;
+    }
+
+    spinner.succeed('Handoff triggered');
+    if (result.jobId) {
+      info(`Job ID: ${result.jobId}`);
+      info('Check progress with: vectora status');
+    }
+  } catch (err) {
+    handleError(err);
+  }
+}

package/src/commands/lock.js

@@ -0,0 +1,74 @@
+// @vectora/cli — lock command: lock idea scope
+import chalk from 'chalk';
+import ora from 'ora';
+import { runPhase, getProject } from '../lib/api-client.js';
+import { getConfig, getConfigValue } from '../lib/config-store.js';
+import { requireToken } from '../lib/auth-store.js';
+import { streamPhaseProgress } from '../lib/sse-client.js';
+import { handleError } from '../lib/errors.js';
+import { warn, success, info } from '../lib/output.js';
+
+/**
+ * vectora lock [--project <id>]
+ */
+export async function lock(opts) {
+  try {
+    const projectId = opts.project ?? getConfigValue('defaultProject');
+    if (!projectId) {
+      warn('No project selected. Use --project <id> or: vectora projects select <id>');
+      process.exitCode = 1;
+      return;
+    }
+
+    const token = await requireToken();
+    const { apiUrl } = getConfig();
+
+    const spinner = ora({ text: 'Locking idea scope...', color: 'cyan' }).start();
+
+    let result;
+    try {
+      result = await runPhase(projectId, 'lock-idea');
+    } catch (err) {
+      spinner.fail('Failed to start lock-idea');
+      throw err;
+    }
+
+    const { jobId } = result;
+    spinner.text = `lock-idea queued (job: ${jobId?.slice(0, 8) ?? '?'})`;
+
+    // Stream SSE progress
+    try {
+      for await (const { event, data } of streamPhaseProgress(apiUrl, jobId, token)) {
+        switch (event) {
+          case 'job:status':
+            spinner.text = `lock-idea: ${data.status ?? 'processing'}`;
+            break;
+          case 'job:progress':
+            spinner.text = `lock-idea: ${data.step ?? data.message ?? ''}`;
+            break;
+          case 'job:completed':
+            spinner.succeed('Idea scope locked');
+            info('Scope is now frozen. Run validation next: vectora validate');
+            return;
+          case 'job:failed':
+            spinner.fail('lock-idea failed');
+            console.error(chalk.red(data.error ?? 'Unknown error'));
+            process.exitCode = 1;
+            return;
+          case 'job:timeout':
+            spinner.warn('lock-idea timed out');
+            info(`Check status with: vectora status --project ${projectId}`);
+            process.exitCode = 1;
+            return;
+        }
+      }
+      spinner.warn('lock-idea — SSE stream ended');
+    } catch (err) {
+      spinner.fail('lock-idea — lost connection');
+      info(`Phase may still be running. Check: vectora status --project ${projectId}`);
+      throw err;
+    }
+  } catch (err) {
+    handleError(err);
+  }
+}

package/src/commands/projects.js

@@ -185,6 +185,24 @@ export async function select(id) {
   }
 }
 
+/**
+ * vectora projects archive <id>
+ */
+export async function archive(id) {
+  try {
+    if (!id) {
+      console.error(chalk.red('Error — project ID is required'));
+      process.exitCode = 1;
+      return;
+    }
+
+    const project = await patchProject(id, { status: 'archived' });
+    success(`Archived project ${chalk.bold(project.name)} ${chalk.dim(`(${project.id})`)}`);
+  } catch (err) {
+    handleError(err);
+  }
+}
+
 /**
  * vectora projects delete <id>
  */

package/src/commands/settings.js

@@ -0,0 +1,94 @@
+// @vectora/cli — settings command: manage API keys and key mode
+import chalk from 'chalk';
+import { getApiKeys, updateApiKeys, getKeyMode, updateKeyMode } from '../lib/api-client.js';
+import { handleError } from '../lib/errors.js';
+import { success, warn } from '../lib/output.js';
+
+const VALID_PROVIDERS = ['anthropic', 'openai', 'google'];
+
+/**
+ * vectora settings api-keys — show configured API keys (masked)
+ */
+export async function apiKeys() {
+  try {
+    const keys = await getApiKeys();
+    console.log();
+    console.log(chalk.cyan.bold('  API Keys'));
+    console.log(chalk.dim('  ─────────────────────────────'));
+    for (const provider of VALID_PROVIDERS) {
+      const value = keys[provider];
+      const display = value ? chalk.green(value) : chalk.dim('not set');
+      console.log(`  ${provider.padEnd(12)} ${display}`);
+    }
+    console.log();
+  } catch (err) {
+    handleError(err);
+  }
+}
+
+/**
+ * vectora settings api-keys set --provider <name> --key <value>
+ */
+export async function apiKeysSet(opts) {
+  try {
+    if (!opts.provider) {
+      console.error(chalk.red('--provider is required (anthropic, openai, google)'));
+      process.exitCode = 1;
+      return;
+    }
+    if (!VALID_PROVIDERS.includes(opts.provider)) {
+      console.error(chalk.red(`Invalid provider. Valid: ${VALID_PROVIDERS.join(', ')}`));
+      process.exitCode = 1;
+      return;
+    }
+    if (!opts.key && opts.key !== '') {
+      console.error(chalk.red('--key is required (use empty string to delete)'));
+      process.exitCode = 1;
+      return;
+    }
+
+    await updateApiKeys({ [opts.provider]: opts.key });
+    if (opts.key === '') {
+      success(`Removed ${opts.provider} API key`);
+    } else {
+      success(`Updated ${opts.provider} API key`);
+    }
+  } catch (err) {
+    handleError(err);
+  }
+}
+
+/**
+ * vectora settings key-mode — show current key mode
+ */
+export async function keyMode() {
+  try {
+    const result = await getKeyMode();
+    console.log();
+    console.log(chalk.cyan.bold('  Key Mode'));
+    console.log(chalk.dim('  ─────────────────────────────'));
+    console.log(`  ${chalk.dim('Prefer own keys:')} ${result.preferOwnKeys ? chalk.green('yes') : chalk.dim('no')}`);
+    console.log(`  ${chalk.dim('Has own keys:')}    ${result.hasOwnKeys ? chalk.green('yes') : chalk.dim('no')}`);
+    console.log();
+  } catch (err) {
+    handleError(err);
+  }
+}
+
+/**
+ * vectora settings key-mode set <own|server>
+ */
+export async function keyModeSet(mode) {
+  try {
+    if (mode !== 'own' && mode !== 'server') {
+      console.error(chalk.red('Mode must be "own" or "server"'));
+      process.exitCode = 1;
+      return;
+    }
+    const preferOwnKeys = mode === 'own';
+    await updateKeyMode(preferOwnKeys);
+    success(`Key mode set to: ${mode}`);
+  } catch (err) {
+    handleError(err);
+  }
+}

package/src/commands/validate.js

@@ -0,0 +1,84 @@
+// @vectora/cli — validate command: run 4-agent validation pipeline
+import chalk from 'chalk';
+import ora from 'ora';
+import { runValidation } from '../lib/api-client.js';
+import { getConfigValue } from '../lib/config-store.js';
+import { handleError } from '../lib/errors.js';
+import { renderTable, warn, success, info } from '../lib/output.js';
+
+/**
+ * vectora validate [--project <id>] [--format <fmt>]
+ */
+export async function validate(opts) {
+  try {
+    const projectId = opts.project ?? getConfigValue('defaultProject');
+    if (!projectId) {
+      warn('No project selected. Use --project <id> or: vectora projects select <id>');
+      process.exitCode = 1;
+      return;
+    }
+
+    const spinner = ora({ text: 'Running validation pipeline (this may take a minute)...', color: 'cyan' }).start();
+
+    let result;
+    try {
+      result = await runValidation(projectId);
+    } catch (err) {
+      spinner.fail('Validation failed');
+      throw err;
+    }
+
+    spinner.succeed('Validation complete');
+    console.log();
+
+    // Summary
+    const recColor = result.recommendation === 'go' ? chalk.green :
+                     result.recommendation === 'no-go' ? chalk.red : chalk.yellow;
+    console.log(`  ${chalk.cyan.bold('Score:')}  ${result.score}/100`);
+    console.log(`  ${chalk.cyan.bold('Verdict:')} ${recColor(result.recommendation.toUpperCase())}`);
+    console.log();
+
+    if (opts.format === 'json') {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+
+    // Report table
+    const report = result.report;
+    if (report) {
+      if (report.viabilityScore) {
+        console.log(chalk.cyan.bold('  Viability'));
+        console.log(`  ${report.viabilityScore.reasoning}`);
+        console.log();
+      }
+
+      if (report.stressTest?.criticalAssumptions?.length) {
+        console.log(chalk.cyan.bold('  Critical Assumptions'));
+        for (const a of report.stressTest.criticalAssumptions) {
+          console.log(`  ${chalk.dim('•')} ${a}`);
+        }
+        console.log();
+      }
+
+      if (report.viabilityScore?.topRisks?.length) {
+        console.log(chalk.cyan.bold('  Top Risks'));
+        for (const r of report.viabilityScore.topRisks) {
+          console.log(`  ${chalk.dim('•')} ${r}`);
+        }
+        console.log();
+      }
+    }
+
+    if (result.warnings?.length) {
+      for (const w of result.warnings) {
+        warn(w);
+      }
+    }
+
+    if (result.artifactId) {
+      info(`Artifact saved: ${result.artifactId}`);
+    }
+  } catch (err) {
+    handleError(err);
+  }
+}

package/src/lib/api-client.js

@@ -125,8 +125,30 @@ export async function getArtifactDownloadUrl(artifactId) {
   return authedFetch(`/v1/artifacts/${artifactId}/download`);
 }
 
+// ─── Validation ─────────────────────────────────────────────────────────────
+
+export async function runValidation(projectId) {
+  return authedFetch(`/v1/projects/${projectId}/validate`, {
+    method: 'POST',
+    body: {},
+  });
+}
+
+// ─── Feedback ───────────────────────────────────────────────────────────────
+
+export async function submitFeedback(projectId, body) {
+  return authedFetch(`/v1/projects/${projectId}/feedback`, {
+    method: 'POST',
+    body,
+  });
+}
+
 // ─── Handoff ─────────────────────────────────────────────────────────────────
 
+export async function getHandoff(projectId) {
+  return authedFetch(`/v1/projects/${projectId}/handoff`);
+}
+
 export async function triggerHandoff(projectId, target) {
   return authedFetch(`/v1/projects/${projectId}/handoff`, {
     method: 'POST',
@@ -159,6 +181,22 @@ export async function getApiKeys() {
   return res.keys;
 }
 
+export async function updateApiKeys(keys) {
+  const res = await authedFetch('/v1/settings/api-keys', { method: 'PUT', body: keys });
+  return res.keys;
+}
+
+export async function getKeyMode() {
+  return authedFetch('/v1/settings/key-mode');
+}
+
+export async function updateKeyMode(preferOwnKeys) {
+  return authedFetch('/v1/settings/key-mode', {
+    method: 'PATCH',
+    body: { preferOwnKeys },
+  });
+}
+
 // ─── Auth (unauthenticated or special) ───────────────────────────────────────
 
 export async function getMe(token) {

package/src/lib/constants.js

@@ -1,7 +1,7 @@
 // @vectora/cli — constants
 // Inlined from @vectora/engine to avoid dependency in API-connected mode.
 
-export const VERSION = '0.1.3';
+export const VERSION = '0.2.0';
 
 export const BRAND = {
   name: 'VECTORA',
@@ -28,8 +28,11 @@ export const TEMPER_PHASES = [
   'plan-platform',
 ];
 
+/** Pre-pipeline phases (idea → validation → lock). */
+export const PRE_PIPELINE_PHASES = ['lock-idea', 'run-validation'];
+
 /** All valid phases for `vectora run`. */
-export const VALID_PHASES = [...FORGE_PHASES, ...TEMPER_PHASES];
+export const VALID_PHASES = [...PRE_PIPELINE_PHASES, ...FORGE_PHASES, ...TEMPER_PHASES];
 
 /** Directories to skip during workspace scanning. */
 export const WORKSPACE_IGNORED_DIRS = new Set([

package/src/tui/components/ArtifactBrowser.js

@@ -43,11 +43,23 @@ export function ArtifactBrowser({ projectId, onBack }) {
     setSavedPath(null);
     setError(null);
     try {
-      const { url, filename } = await getArtifactDownloadUrl(item.value);
+      const { url, filename, inlineBase64 } = await getArtifactDownloadUrl(item.value);
+      const outPath = resolve(filename);
+
+      // Local-storage fallback: the API can return inline bytes when no
+      // presigned URL backend is available.
+      if (inlineBase64) {
+        const buffer = Buffer.from(inlineBase64, 'base64');
+        await writeFile(outPath, buffer);
+        setSavedPath(outPath);
+        return;
+      }
+
+      if (!url) throw new Error('Artifact download URL was not provided by the API');
+
       const res = await fetch(url, { signal: AbortSignal.timeout(60_000) });
       if (!res.ok) throw new Error(`Download failed: HTTP ${res.status}`);
       const buffer = Buffer.from(await res.arrayBuffer());
-      const outPath = resolve(filename);
       await writeFile(outPath, buffer);
       setSavedPath(outPath);
     } catch (err) {