@vibecompass/vibecompass 0.2.1 → 0.3.1

package/src/cli.js

@@ -2,10 +2,17 @@
 
 import { realpathSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
-import { initializeProjectMemory } from './init.js';
-import { resolveInitCliOptions } from './setup.js';
+import { connectHostedProjectMemory, initializeProjectMemory } from './init.js';
+import { preflightDocsReview } from './docs-review.js';
+import { resolveConnectHostedCliOptions, resolveInitCliOptions } from './setup.js';
 import { closeProjectSession, listProjectSessions, startProjectSession, switchProjectSession } from './session.js';
 import { syncAgentInstructionFiles } from './generators/agent-files/index.js';
+import {
+  applyPullExport,
+  pullExportProjectMemory,
+  pullPreviewProjectMemory,
+  pushProjectMemory,
+} from './sync.js';
 
 export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
   const parsed = parseCliArgs(argv);
@@ -40,7 +47,20 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
     );
 
     if (result.syncEnvVar) {
-      io.stdout.write(`Next step: set ${result.syncEnvVar} locally before your first sync.\n`);
+      const rootFlag = formatOptionalRootFlag(initPlan.initOptions.rootDir);
+      io.stdout.write(`Hosted binding: configured for ${initPlan.initOptions.mode}\n`);
+      io.stdout.write(`Next step: set ${result.syncEnvVar} locally before your first hosted command.\n`);
+      if (initPlan.initOptions.mode === 'local-primary') {
+        io.stdout.write(`Then run: vibecompass push${rootFlag}\n`);
+        io.stdout.write(`Hosted docs-review: vibecompass docs-review --submit-hosted${rootFlag}\n`);
+      } else if (initPlan.initOptions.mode === 'hosted-only') {
+        io.stdout.write(`Hosted docs-review: vibecompass docs-review --submit-hosted${rootFlag}\n`);
+      }
+    } else if (initPlan.initOptions.mode === 'hosted-only') {
+      io.stdout.write('Hosted-only projects need a hosted sync binding before hosted commands.\n');
+      io.stdout.write('After creating a sync credential, rerun init with --force and --sync-api-url/--sync-project-id/--sync-credential-env-var, or add project.yaml.sync manually.\n');
+    } else if (initPlan.initOptions.mode === 'local-primary') {
+      io.stdout.write('Optional hosted setup later: vibecompass connect-hosted\n');
     }
 
     if (result.contextFilePath) {
@@ -70,6 +90,7 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
       io.stdout.write(`Updated ${sessionResult.claudePath}\n`);
       io.stdout.write(`Created ${sessionResult.wipFilePath}\n`);
       io.stdout.write(`Created ${sessionResult.handoffFilePath}\n`);
+      writeWarnings(io, sessionResult.warnings);
       writeAgentFileSyncResult(io, sessionResult.agentFileSync);
     }
 
@@ -85,10 +106,33 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
     io.stdout.write(`Updated ${result.claudePath}\n`);
     io.stdout.write(`Created ${result.wipFilePath}\n`);
     io.stdout.write(`Created ${result.handoffFilePath}\n`);
+    writeWarnings(io, result.warnings);
     writeAgentFileSyncResult(io, result.agentFileSync);
     return 0;
   }
 
+  if (parsed.command === 'connect-hosted') {
+    const connectPlan = await resolveConnectHostedCliOptions(parsed.options, {
+      cwd: runtime.cwd,
+      io,
+      runtime,
+    });
+    const result = await connectHostedProjectMemory({
+      ...connectPlan,
+      ...(runtime.cwd ? { cwd: runtime.cwd } : {}),
+    });
+    io.stdout.write(`Connected hosted VibeCompass for ${result.mode}\n`);
+    io.stdout.write(`Updated ${result.projectFilePath}\n`);
+    io.stdout.write(`Next step: set ${result.syncEnvVar} locally before your first hosted command.\n`);
+    if (result.mode === 'local-primary') {
+      io.stdout.write('Then run: vibecompass push\n');
+      io.stdout.write('Hosted docs-review: vibecompass docs-review --submit-hosted\n');
+    } else {
+      io.stdout.write('Hosted docs-review: vibecompass docs-review --submit-hosted\n');
+    }
+    return 0;
+  }
+
   if (parsed.command === 'close-session' || parsed.command === 'end-session') {
     const result = await closeProjectSession({
       ...parsed.options,
@@ -144,6 +188,129 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
     return 0;
   }
 
+  if (parsed.command === 'docs-review') {
+    const result = await preflightDocsReview({
+      ...parsed.options,
+      ...(runtime.cwd ? { cwd: runtime.cwd } : {}),
+    }, {
+      io,
+      env: runtime.env,
+      runtime,
+    });
+    io.stdout.write(`Docs-review: ${result.status}\n`);
+    if (result.llm) {
+      io.stdout.write(`LLM: ${result.llm}\n`);
+    }
+    if (result.model) {
+      io.stdout.write(`Model: ${result.model}\n`);
+    }
+    if (result.runtime) {
+      io.stdout.write(`Runtime: ${result.runtime.provider}\n`);
+    }
+    if (result.hosted) {
+      io.stdout.write(`Hosted run: ${result.hosted.run_id}\n`);
+      if (result.hosted.phase) {
+        io.stdout.write(`Hosted phase: ${result.hosted.phase}\n`);
+      }
+    }
+    if (result.localReview) {
+      io.stdout.write(`Local review output: ${result.localReview.output_path}\n`);
+    }
+    if (result.applied) {
+      io.stdout.write(`Applied architecture docs: ${result.applied.architecture_docs.length}\n`);
+      for (const entry of result.applied.architecture_docs) {
+        io.stdout.write(`- ${entry.path} (${entry.status})\n`);
+      }
+    }
+    if (result.appliedDecisionArtifact) {
+      io.stdout.write(`Applied decision artifact: ${result.appliedDecisionArtifact.artifact_id}\n`);
+      io.stdout.write(`Decision: D-${String(result.appliedDecisionArtifact.decision_id).padStart(3, '0')}\n`);
+      io.stdout.write(`Target: ${result.appliedDecisionArtifact.target_path}\n`);
+    }
+    writeWarnings(io, result.warnings);
+    io.stdout.write(`Recorded ${result.statePath}\n`);
+    io.stdout.write(`${result.message}\n`);
+    if (result.reviewPrompt) {
+      io.stdout.write('Architecture review prompt:\n');
+      io.stdout.write(`${result.reviewPrompt}\n`);
+    }
+    return 0;
+  }
+
+  if (parsed.command === 'push') {
+    const result = await pushProjectMemory(parsed.options, {
+      cwd: runtime.cwd,
+      env: runtime.env,
+      runtime,
+    });
+    io.stdout.write(`Push: ${result.status}\n`);
+    io.stdout.write(`Remote revision: ${result.remoteRevisionId}\n`);
+    io.stdout.write(`Run: ${result.runId}\n`);
+    if (result.appliedProposalIds.length > 0) {
+      io.stdout.write(`Applied proposals: ${result.appliedProposalIds.join(', ')}\n`);
+    }
+    if (result.staleProposalIds.length > 0) {
+      io.stdout.write(`Stale proposals: ${result.staleProposalIds.join(', ')}\n`);
+    }
+    io.stdout.write(`Recorded ${result.manifestPath}\n`);
+    io.stdout.write(`${result.message}\n`);
+    return 0;
+  }
+
+  if (parsed.command === 'pull-preview') {
+    const result = await pullPreviewProjectMemory(parsed.options, {
+      cwd: runtime.cwd,
+      env: runtime.env,
+      runtime,
+    });
+    io.stdout.write(`Pull-preview: ${result.status}\n`);
+    io.stdout.write(`Preview token: ${result.previewToken}\n`);
+    io.stdout.write(`Pending proposals: ${result.proposals.length}\n`);
+    for (const proposal of result.proposals) {
+      io.stdout.write(`- ${proposal.proposal_id}: ${proposal.summary}\n`);
+    }
+    if (result.conflicts.length > 0) {
+      io.stdout.write(`Conflicts: ${result.conflicts.length}\n`);
+      for (const conflict of result.conflicts) {
+        io.stdout.write(`- ${conflict.code}: ${conflict.message}\n`);
+      }
+    }
+    writeWarnings(io, result.warnings.map((warning) => `${warning.code}: ${warning.message}`));
+    io.stdout.write(`Recorded ${result.manifestPath}\n`);
+    io.stdout.write(`${result.message}\n`);
+    return 0;
+  }
+
+  if (parsed.command === 'pull-export') {
+    const result = await pullExportProjectMemory(parsed.options, {
+      cwd: runtime.cwd,
+      env: runtime.env,
+      runtime,
+    });
+    io.stdout.write(`Pull-export: ${result.status}\n`);
+    io.stdout.write(`Run: ${result.runId}\n`);
+    io.stdout.write(`Proposal IDs: ${result.proposalIds.join(', ')}\n`);
+    io.stdout.write(`Operations: ${result.operationCount}\n`);
+    io.stdout.write(`Wrote ${result.outputPath}\n`);
+    io.stdout.write(`${result.message}\n`);
+    return 0;
+  }
+
+  if (parsed.command === 'apply-export') {
+    const result = await applyPullExport(parsed.options, {
+      cwd: runtime.cwd,
+      env: runtime.env,
+      runtime,
+    });
+    io.stdout.write(`Apply-export: ${result.status}\n`);
+    for (const entry of result.applied) {
+      io.stdout.write(`- ${entry.path} (${entry.status})\n`);
+    }
+    io.stdout.write(`Recorded ${result.outputPath}\n`);
+    io.stdout.write(`${result.message}\n`);
+    return 0;
+  }
+
   throw new Error(`Unknown command "${parsed.command}".`);
 }
 
@@ -159,6 +326,10 @@ export function parseCliArgs(argv) {
       return parseStartSessionArgs(rest);
     }
 
+    if (command === 'connect-hosted') {
+      return parseConnectHostedArgs(rest);
+    }
+
     if (command === 'close-session' || command === 'end-session') {
       return parseCloseSessionArgs(rest);
     }
@@ -175,6 +346,26 @@ export function parseCliArgs(argv) {
       return parseSyncAgentsArgs(rest);
     }
 
+    if (command === 'docs-review') {
+      return parseDocsReviewArgs(rest);
+    }
+
+    if (command === 'push') {
+      return parsePushArgs(rest);
+    }
+
+    if (command === 'pull-preview') {
+      return parsePullPreviewArgs(rest);
+    }
+
+    if (command === 'pull-export') {
+      return parsePullExportArgs(rest);
+    }
+
+    if (command === 'apply-export') {
+      return parseApplyExportArgs(rest);
+    }
+
     return { command };
   }
 
@@ -400,6 +591,63 @@ function parseStartSessionArgs(argv) {
   };
 }
 
+function parseConnectHostedArgs(argv) {
+  const parsed = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+
+    if (!token.startsWith('--')) {
+      throw new Error(`Unexpected argument "${token}".`);
+    }
+
+    const value = argv[index + 1];
+    if (value === undefined) {
+      throw new Error(`Flag "${token}" requires a value.`);
+    }
+    index += 1;
+
+    switch (token) {
+      case '--root':
+        parsed.rootDir = value;
+        break;
+      case '--sync-api-url':
+        parsed.syncApiUrl = value;
+        break;
+      case '--sync-project-id':
+        parsed.syncProjectId = value;
+        break;
+      case '--sync-credential-env-var':
+        parsed.syncCredentialEnvVar = value;
+        break;
+      default:
+        throw new Error(`Unknown flag "${token}".`);
+    }
+  }
+
+  const syncValues = [
+    parsed.syncApiUrl,
+    parsed.syncProjectId,
+    parsed.syncCredentialEnvVar,
+  ].filter(Boolean);
+
+  return {
+    command: 'connect-hosted',
+    options: {
+      rootDir: parsed.rootDir,
+      ...(syncValues.length > 0
+        ? {
+            sync: {
+              apiUrl: parsed.syncApiUrl,
+              projectId: parsed.syncProjectId,
+              credentialEnvVar: parsed.syncCredentialEnvVar,
+            },
+          }
+        : {}),
+    },
+  };
+}
+
 function parseCloseSessionArgs(argv) {
   const parsed = {
     completed: [],
@@ -587,6 +835,248 @@ function parseSyncAgentsArgs(argv) {
   };
 }
 
+function parseDocsReviewArgs(argv) {
+  const parsed = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+
+    if (token === '--guided') {
+      parsed.guided = true;
+      continue;
+    }
+
+    if (token === '--submit-hosted') {
+      parsed.submitHosted = true;
+      continue;
+    }
+
+    if (token === '--poll-hosted') {
+      parsed.pollHosted = true;
+      continue;
+    }
+
+    if (token === '--complete') {
+      parsed.complete = true;
+      continue;
+    }
+
+    if (token === '--run-local-anthropic') {
+      parsed.runLocalAnthropic = true;
+      continue;
+    }
+
+    if (token === '--run-local') {
+      parsed.runLocal = true;
+      continue;
+    }
+
+    if (token === '--apply-output') {
+      parsed.applyOutput = true;
+      continue;
+    }
+
+    if (token === '--apply-decision-artifact') {
+      parsed.applyDecisionArtifact = true;
+      continue;
+    }
+
+    if (token === '--refresh-index') {
+      parsed.refreshIndex = true;
+      continue;
+    }
+
+    if (!token.startsWith('--')) {
+      throw new Error(`Unexpected argument "${token}".`);
+    }
+
+    const value = argv[index + 1];
+    if (value === undefined) {
+      throw new Error(`Flag "${token}" requires a value.`);
+    }
+    index += 1;
+
+    switch (token) {
+      case '--root':
+        parsed.rootDir = value;
+        break;
+      case '--llm':
+        parsed.llm = value;
+        break;
+      case '--model':
+        parsed.model = value;
+        break;
+      case '--anthropic-env-var':
+        parsed.anthropicEnvVar = value;
+        break;
+      case '--provider':
+        parsed.provider = value;
+        break;
+      case '--output':
+        parsed.outputPath = value;
+        break;
+      case '--artifact':
+        parsed.artifactId = value;
+        break;
+      case '--max-tokens':
+        parsed.maxTokens = value;
+        break;
+      default:
+        throw new Error(`Unknown flag "${token}".`);
+    }
+  }
+
+  return {
+    command: 'docs-review',
+    options: parsed,
+  };
+}
+
+function parsePushArgs(argv) {
+  return {
+    command: 'push',
+    options: parseRootOnlyArgs(argv, 'push'),
+  };
+}
+
+function parsePullPreviewArgs(argv) {
+  const parsed = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === '--no-pending-proposals') {
+      parsed.includePendingProposals = false;
+      continue;
+    }
+
+    if (!token.startsWith('--')) {
+      throw new Error(`Unexpected argument "${token}".`);
+    }
+
+    const value = argv[index + 1];
+    if (value === undefined) {
+      throw new Error(`Flag "${token}" requires a value.`);
+    }
+    index += 1;
+
+    switch (token) {
+      case '--root':
+        parsed.rootDir = value;
+        break;
+      default:
+        throw new Error(`Unknown flag "${token}".`);
+    }
+  }
+
+  return {
+    command: 'pull-preview',
+    options: parsed,
+  };
+}
+
+function parsePullExportArgs(argv) {
+  const parsed = {
+    proposalIds: [],
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+
+    if (!token.startsWith('--')) {
+      throw new Error(`Unexpected argument "${token}".`);
+    }
+
+    const value = argv[index + 1];
+    if (value === undefined) {
+      throw new Error(`Flag "${token}" requires a value.`);
+    }
+    index += 1;
+
+    switch (token) {
+      case '--root':
+        parsed.rootDir = value;
+        break;
+      case '--preview-token':
+        parsed.previewToken = value;
+        break;
+      case '--proposal':
+        parsed.proposalIds.push(value);
+        break;
+      case '--output':
+        parsed.outputPath = value;
+        break;
+      default:
+        throw new Error(`Unknown flag "${token}".`);
+    }
+  }
+
+  return {
+    command: 'pull-export',
+    options: parsed,
+  };
+}
+
+function parseApplyExportArgs(argv) {
+  const parsed = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+
+    if (!token.startsWith('--')) {
+      throw new Error(`Unexpected argument "${token}".`);
+    }
+
+    const value = argv[index + 1];
+    if (value === undefined) {
+      throw new Error(`Flag "${token}" requires a value.`);
+    }
+    index += 1;
+
+    switch (token) {
+      case '--root':
+        parsed.rootDir = value;
+        break;
+      case '--output':
+        parsed.outputPath = value;
+        break;
+      default:
+        throw new Error(`Unknown flag "${token}".`);
+    }
+  }
+
+  return {
+    command: 'apply-export',
+    options: parsed,
+  };
+}
+
+function parseRootOnlyArgs(argv, commandName) {
+  const parsed = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith('--')) {
+      throw new Error(`Unexpected argument "${token}".`);
+    }
+
+    const value = argv[index + 1];
+    if (value === undefined) {
+      throw new Error(`Flag "${token}" requires a value.`);
+    }
+    index += 1;
+
+    switch (token) {
+      case '--root':
+        parsed.rootDir = value;
+        break;
+      default:
+        throw new Error(`Unknown flag "${token}" for ${commandName}.`);
+    }
+  }
+
+  return parsed;
+}
+
 function writeAgentFileSyncResult(io, result) {
   if (!result) {
     return;
@@ -600,6 +1090,12 @@ function writeAgentFileSyncResult(io, result) {
   }
 }
 
+function writeWarnings(io, warnings = []) {
+  for (const warning of warnings) {
+    io.stderr.write(`Warning: ${warning}\n`);
+  }
+}
+
 function splitAssignment(value, flagName) {
   const separatorIndex = value.indexOf('=');
   if (separatorIndex <= 0 || separatorIndex === value.length - 1) {
@@ -613,12 +1109,18 @@ function usageText() {
   return [
     'Usage:',
     '  vibecompass init --name <project-name> --mode <local-only|local-primary|hosted-only> --repo <id=remote> [options]',
+    '  vibecompass connect-hosted [options]',
     '  vibecompass start-session --id <lane-id> --working-on <text> [options]',
     '  vibecompass close-session --title <text> --completed <text> --next-step <text> [options]',
     '  vibecompass end-session --title <text> --completed <text> --next-step <text> [options]  # alias',
     '  vibecompass list-sessions [options]',
     '  vibecompass switch-session <id> [options]',
     '  vibecompass sync-agents [options]',
+    '  vibecompass push [options]',
+    '  vibecompass pull-preview [options]',
+    '  vibecompass pull-export [options]',
+    '  vibecompass apply-export [options]',
+    '  vibecompass docs-review --guided [options]',
     '',
     'Init options:',
     '  --root <path>                        Project-memory root. Defaults to .compass',
@@ -643,6 +1145,13 @@ function usageText() {
     '  --close-session-git-remote <name>    Default Git remote name for that close-session publish step',
     '  --force                              Overwrite an existing project.yaml',
     '',
+    'Connect-hosted options:',
+    '  --root <path>                        Project-memory root. Defaults to .compass',
+    '  --sync-api-url <url>                 Hosted sync api_url',
+    '  --sync-project-id <id>               Hosted sync project_id',
+    '  --sync-credential-env-var <name>     Hosted sync env var reference',
+    '                                        Replaces any existing project.yaml sync binding',
+    '',
     'Start-session options:',
     '  --root <path>                        Project-memory root. Defaults to .compass',
     '  --tooling-root <path>                Tooling root that contains CLAUDE.md. Defaults to cwd',
@@ -679,6 +1188,34 @@ function usageText() {
     '  --tooling-root <path>                Directory where agent files are written. Defaults to cwd',
     '  --format <name>                      Optional format: claude_md, agents_md, cursor_rules, copilot_instructions',
     '  --dry-run                            Show planned writes without changing files',
+    '',
+    'Sync transport options:',
+    '  push --root <path>                   Push canonical local project memory to hosted',
+    '  pull-preview --root <path>           Preview hosted proposals and remote state',
+    '  pull-preview --no-pending-proposals  Exclude pending proposals from preview',
+    '  pull-export --proposal <id>          Export a selected proposal; repeatable',
+    '  pull-export --preview-token <token>  Export from a specific preview token',
+    '  pull-export --output <path>          Output path under root; defaults to state/pull-export.json',
+    '  apply-export --output <path>         Apply exported bundle; defaults to state/pull-export.json',
+    '',
+    'Docs-review options:',
+    '  --root <path>                        Project-memory root. Defaults to .compass',
+    '  --guided                             Accepted for the explicit comprehensive-review workflow',
+    '  --submit-hosted                      Submit the generated review request to hosted sync',
+    '  --poll-hosted                        Poll hosted docs-review run status and update state/docs-review.json',
+    '  --complete                           Mark accepted docs-review changes as completed locally',
+    '  --run-local                          Run the generated review request with a local provider',
+    '  --provider <name>                    Local provider for --run-local. Currently: anthropic',
+    '  --run-local-anthropic                Compatibility alias for --run-local --provider anthropic',
+    '  --apply-output                       Apply accepted architecture doc blocks from review output',
+    '  --output <path>                      Review output path for --apply-output; defaults to state/docs-review-output.md',
+    '  --apply-decision-artifact            Append an accepted hosted decision artifact locally',
+    '  --artifact <id>                      Artifact ID for --apply-decision-artifact',
+    '  --refresh-index                      Also regenerate decisions/INDEX.md after applying a decision artifact',
+    '  --llm <name>                         Preferred LLM/provider to run the external architecture review',
+    '  --model <name>                       Model name to record for the review',
+    '  --anthropic-env-var <name>           Env var to use for local Anthropic docs-review runtime',
+    '  --max-tokens <number>                Local Anthropic max_tokens, 1024-32000. Defaults to 16000',
   ].join('\n');
 }
 
@@ -690,6 +1227,14 @@ function createDefaultIo() {
   };
 }
 
+function formatOptionalRootFlag(rootDir) {
+  if (!rootDir || rootDir === '.compass') {
+    return '';
+  }
+
+  return ` --root ${rootDir}`;
+}
+
 async function main() {
   try {
     const exitCode = await runCli(process.argv.slice(2));