@vibecompass/vibecompass 0.3.3 → 0.4.0

package/src/cli.js

@@ -7,6 +7,9 @@ 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 { getProjectStatus, renderStatusText, toStatusJson } from './status.js';
+import { refreshWorkflow } from './refresh-workflow.js';
+import { inspectProjectCompatibility, formatCompatibilityWarnings } from './compatibility.js';
 import {
   applyPullExport,
   pullExportProjectMemory,
@@ -28,6 +31,10 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
       io,
       runtime,
     });
+    if (initPlan.existingProject) {
+      return writeExistingInitProjectResult(io, initPlan.existingProject);
+    }
+
     const result = await initializeProjectMemory({
       ...initPlan.initOptions,
       ...(runtime.cwd ? { cwd: runtime.cwd } : {}),
@@ -78,6 +85,14 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
       io.stdout.write(`Left existing ${filePath} untouched\n`);
     }
 
+    if (initPlan.agentFileSyncPlan) {
+      const agentFileSync = await syncAgentInstructionFiles({
+        ...initPlan.agentFileSyncPlan,
+        ...(runtime.cwd ? { cwd: runtime.cwd } : {}),
+      });
+      writeAgentFileSyncResult(io, agentFileSync);
+    }
+
     if (initPlan.sessionPlan) {
       const sessionResult = await startProjectSession({
         rootDir: initPlan.initOptions.rootDir,
@@ -98,6 +113,7 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
   }
 
   if (parsed.command === 'start-session') {
+    await writeCompatibilityPreflightWarnings(io, parsed.options, runtime);
     const result = await startProjectSession({
       ...parsed.options,
       ...(runtime.cwd ? { cwd: runtime.cwd } : {}),
@@ -112,6 +128,7 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
   }
 
   if (parsed.command === 'connect-hosted') {
+    await writeCompatibilityPreflightWarnings(io, parsed.options, runtime);
     const connectPlan = await resolveConnectHostedCliOptions(parsed.options, {
       cwd: runtime.cwd,
       io,
@@ -133,7 +150,30 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
     return 0;
   }
 
+  if (parsed.command === 'status') {
+    const result = await getProjectStatus({
+      ...parsed.options,
+      ...(runtime.cwd ? { cwd: runtime.cwd } : {}),
+    });
+    if (parsed.options.json) {
+      io.stdout.write(`${JSON.stringify(toStatusJson(result), null, 2)}\n`);
+    } else {
+      io.stdout.write(renderStatusText(result));
+    }
+    return 0;
+  }
+
+  if (parsed.command === 'refresh-workflow') {
+    const result = await refreshWorkflow({
+      ...parsed.options,
+      ...(runtime.cwd ? { cwd: runtime.cwd } : {}),
+    });
+    writeRefreshWorkflowResult(io, result);
+    return 0;
+  }
+
   if (parsed.command === 'close-session' || parsed.command === 'end-session') {
+    await writeCompatibilityPreflightWarnings(io, parsed.options, runtime);
     const result = await closeProjectSession({
       ...parsed.options,
       ...(runtime.cwd ? { cwd: runtime.cwd } : {}),
@@ -152,6 +192,7 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
   }
 
   if (parsed.command === 'list-sessions') {
+    await writeCompatibilityPreflightWarnings(io, parsed.options, runtime);
     const result = await listProjectSessions({
       ...parsed.options,
       ...(runtime.cwd ? { cwd: runtime.cwd } : {}),
@@ -169,6 +210,7 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
   }
 
   if (parsed.command === 'switch-session') {
+    await writeCompatibilityPreflightWarnings(io, parsed.options, runtime);
     const result = await switchProjectSession({
       ...parsed.options,
       ...(runtime.cwd ? { cwd: runtime.cwd } : {}),
@@ -180,6 +222,7 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
   }
 
   if (parsed.command === 'sync-agents') {
+    await writeCompatibilityPreflightWarnings(io, parsed.options, runtime);
     const result = await syncAgentInstructionFiles({
       ...parsed.options,
       ...(runtime.cwd ? { cwd: runtime.cwd } : {}),
@@ -189,6 +232,7 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
   }
 
   if (parsed.command === 'docs-review') {
+    await writeCompatibilityPreflightWarnings(io, parsed.options, runtime);
     const result = await preflightDocsReview({
       ...parsed.options,
       ...(runtime.cwd ? { cwd: runtime.cwd } : {}),
@@ -238,6 +282,7 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
   }
 
   if (parsed.command === 'push') {
+    await writeCompatibilityPreflightWarnings(io, parsed.options, runtime);
     const result = await pushProjectMemory(parsed.options, {
       cwd: runtime.cwd,
       env: runtime.env,
@@ -258,6 +303,7 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
   }
 
   if (parsed.command === 'pull-preview') {
+    await writeCompatibilityPreflightWarnings(io, parsed.options, runtime);
     const result = await pullPreviewProjectMemory(parsed.options, {
       cwd: runtime.cwd,
       env: runtime.env,
@@ -282,6 +328,7 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
   }
 
   if (parsed.command === 'pull-export') {
+    await writeCompatibilityPreflightWarnings(io, parsed.options, runtime);
     const result = await pullExportProjectMemory(parsed.options, {
       cwd: runtime.cwd,
       env: runtime.env,
@@ -297,6 +344,7 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
   }
 
   if (parsed.command === 'apply-export') {
+    await writeCompatibilityPreflightWarnings(io, parsed.options, runtime);
     const result = await applyPullExport(parsed.options, {
       cwd: runtime.cwd,
       env: runtime.env,
@@ -330,6 +378,14 @@ export function parseCliArgs(argv) {
       return parseConnectHostedArgs(rest);
     }
 
+    if (command === 'status') {
+      return parseStatusArgs(rest);
+    }
+
+    if (command === 'refresh-workflow') {
+      return parseRefreshWorkflowArgs(rest);
+    }
+
     if (command === 'close-session' || command === 'end-session') {
       return parseCloseSessionArgs(rest);
     }
@@ -382,6 +438,11 @@ export function parseCliArgs(argv) {
       continue;
     }
 
+    if (token === '--replace-active-lanes') {
+      parsed.replaceActiveLanes = true;
+      continue;
+    }
+
     if (token === '--guided') {
       parsed.guided = true;
       continue;
@@ -402,6 +463,11 @@ export function parseCliArgs(argv) {
       continue;
     }
 
+    if (token === '--adopt-existing-agent-files') {
+      parsed.adoptExistingAgentFiles = true;
+      continue;
+    }
+
     if (token === '--start-session') {
       parsed.startSession = true;
       continue;
@@ -503,11 +569,13 @@ export function parseCliArgs(argv) {
       mode: parsed.mode,
       repos: parsed.repos,
       force: parsed.force,
+      replaceActiveLanes: parsed.replaceActiveLanes,
       startSession: parsed.startSession,
       sessionWorkingOn: parsed.sessionWorkingOn,
       sessionId: parsed.sessionId,
       closeSessionGitPublish: parsed.closeSessionGitPublish,
       closeSessionGitRemote: parsed.closeSessionGitRemote,
+      adoptExistingAgentFiles: parsed.adoptExistingAgentFiles,
       ...(parsed.withWorkflow || parsed.withClaude || parsed.withAgents
         ? {
             bootstrap: {
@@ -648,6 +716,99 @@ function parseConnectHostedArgs(argv) {
   };
 }
 
+function parseStatusArgs(argv) {
+  const parsed = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+
+    if (token === '--json') {
+      parsed.json = 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 '--tooling-root':
+        parsed.toolingRootDir = value;
+        break;
+      default:
+        throw new Error(`Unknown flag "${token}".`);
+    }
+  }
+
+  return {
+    command: 'status',
+    options: parsed,
+  };
+}
+
+function parseRefreshWorkflowArgs(argv) {
+  const parsed = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+
+    if (token === '--dry-run') {
+      parsed.apply = false;
+      continue;
+    }
+
+    if (token === '--apply') {
+      parsed.apply = true;
+      continue;
+    }
+
+    if (token === '--update-package-stamp') {
+      parsed.updatePackageStamp = true;
+      continue;
+    }
+
+    if (token === '--allow-downgrade-templates') {
+      parsed.allowDowngradeTemplates = 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 '--tooling-root':
+        parsed.toolingRootDir = value;
+        break;
+      default:
+        throw new Error(`Unknown flag "${token}".`);
+    }
+  }
+
+  return {
+    command: 'refresh-workflow',
+    options: parsed,
+  };
+}
+
 function parseCloseSessionArgs(argv) {
   const parsed = {
     completed: [],
@@ -804,6 +965,11 @@ function parseSyncAgentsArgs(argv) {
       continue;
     }
 
+    if (token === '--adopt-existing') {
+      parsed.adoptExisting = true;
+      continue;
+    }
+
     if (!token.startsWith('--')) {
       throw new Error(`Unexpected argument "${token}".`);
     }
@@ -1087,7 +1253,51 @@ function writeAgentFileSyncResult(io, result) {
     const suffix = item.warning ? ` — ${item.warning}` : '';
     const stream = item.warning ? io.stderr : io.stdout;
     stream.write(`- ${item.relativePath}: ${item.status}${suffix}\n`);
+    if (item.conflicts?.length > 0) {
+      const lineNumbers = item.conflicts.map((conflict) => conflict.line).join(', ');
+      io.stderr.write(`  possible workflow overlap on lines ${lineNumbers}; review existing instructions if behavior conflicts.\n`);
+    }
+  }
+}
+
+function writeRefreshWorkflowResult(io, result) {
+  io.stdout.write(`${result.dryRun ? 'Planned' : 'Applied'} workflow refresh for ${result.rootDir}\n`);
+  writeCompatibilityWarnings(io, result.compatibility);
+  io.stdout.write('Project package stamp:\n');
+  const projectSuffix = result.projectFile.warning ? ` — ${result.projectFile.warning}` : '';
+  const projectStatus = result.dryRun && result.projectFile.changed
+    ? `dry-run-${result.projectFile.status}`
+    : result.projectFile.status;
+  io.stdout.write(`- project.yaml: ${projectStatus}${projectSuffix}\n`);
+
+  io.stdout.write('Workflow files:\n');
+  for (const file of result.workflowFiles) {
+    const suffix = file.warning ? ` — ${file.warning}` : '';
+    io.stdout.write(`- ${file.relativePath}: ${result.dryRun && file.changed ? `dry-run-${file.status}` : file.status}${suffix}\n`);
   }
+
+  io.stdout.write('State manifest:\n');
+  io.stdout.write(`- ${result.manifest.path}: ${result.manifest.status} (${result.manifest.documentCount} canonical docs, ${result.manifest.warningCount} warnings)\n`);
+  writeAgentFileSyncResult(io, result.agentFileSync);
+}
+
+async function writeCompatibilityPreflightWarnings(io, options = {}, runtime = {}) {
+  const result = await inspectProjectCompatibility({
+    ...options,
+    ...(runtime.cwd ? { cwd: runtime.cwd } : {}),
+  });
+  writeCompatibilityWarnings(io, result);
+}
+
+function writeCompatibilityWarnings(io, result) {
+  const warnings = formatCompatibilityWarnings(result);
+  if (warnings.length === 0) {
+    return;
+  }
+
+  io.stderr.write('Compatibility warnings:\n');
+  writeWarnings(io, warnings);
+  io.stderr.write('Run `vibecompass status` for detail.\n');
 }
 
 function writeWarnings(io, warnings = []) {
@@ -1110,6 +1320,8 @@ function usageText() {
     'Usage:',
     '  vibecompass init --name <project-name> --mode <local-only|local-primary|hosted-only> --repo <id=remote> [options]',
     '  vibecompass connect-hosted [options]',
+    '  vibecompass status [options]',
+    '  vibecompass refresh-workflow [--dry-run|--apply] [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',
@@ -1138,12 +1350,14 @@ function usageText() {
     '  --with-workflow                      Scaffold context.md and workflow guide files',
     '  --with-claude                        Create a starter CLAUDE.md if missing',
     '  --with-agents                        Create a starter AGENTS.md if missing',
+    '  --adopt-existing-agent-files         Adopt existing unmarked agent files after init',
     '  --start-session                      Open the first builder session after init',
     '  --session-working-on <text>          Required with --start-session outside guided mode',
     '  --session-id <lane-id>                Required with --start-session; names the first builder lane',
     '  --close-session-git-publish          Include a Git publish step in the stored close-session workflow',
     '  --close-session-git-remote <name>    Default Git remote name for that close-session publish step',
     '  --force                              Overwrite an existing project.yaml',
+    '  --replace-active-lanes               Allow --force to replace a root that has active session lanes',
     '',
     'Connect-hosted options:',
     '  --root <path>                        Project-memory root. Defaults to .compass',
@@ -1152,6 +1366,19 @@ function usageText() {
     '  --sync-credential-env-var <name>     Hosted sync env var reference',
     '                                        Replaces any existing project.yaml sync binding',
     '',
+    'Status options:',
+    '  --root <path>                        Project-memory root. Defaults to .compass',
+    '  --tooling-root <path>                Directory where agent files are inspected. Defaults to cwd',
+    '  --json                               Print the typed status model as JSON',
+    '',
+    'Refresh-workflow options:',
+    '  --root <path>                        Project-memory root. Defaults to .compass',
+    '  --tooling-root <path>                Directory where agent files are refreshed. Defaults to cwd',
+    '  --dry-run                            Show planned refresh without changing files (default)',
+    '  --apply                              Apply the planned workflow refresh',
+    '  --update-package-stamp               Update an existing project.yaml package_version stamp',
+    '  --allow-downgrade-templates          Allow applying templates with a CLI older than the root stamp',
+    '',
     'Start-session options:',
     '  --root <path>                        Project-memory root. Defaults to .compass',
     '  --tooling-root <path>                Tooling root that contains CLAUDE.md. Defaults to cwd',
@@ -1187,6 +1414,7 @@ function usageText() {
     '  --root <path>                        Project-memory root. Defaults to .compass',
     '  --tooling-root <path>                Directory where agent files are written. Defaults to cwd',
     '  --format <name>                      Optional format: claude_md, agents_md, cursor_rules, copilot_instructions',
+    '  --adopt-existing                     Append managed blocks to existing unmarked files',
     '  --dry-run                            Show planned writes without changing files',
     '',
     'Sync transport options:',
@@ -1235,6 +1463,66 @@ function formatOptionalRootFlag(rootDir) {
   return ` --root ${rootDir}`;
 }
 
+function writeExistingInitProjectResult(io, existingProject) {
+  const rootFlag = formatOptionalRootFlag(existingProject.displayPath);
+  const active = existingProject.activeSummary ?? { count: 0, current: null };
+
+  if (existingProject.status === 'ambiguous') {
+    (io.stderr ?? process.stderr).write(
+      [
+        'Multiple VibeCompass project memory roots found:',
+        ...existingProject.candidates.map((candidate) => `- ${candidate.displayPath}`),
+        'Pass --root explicitly to choose one.',
+        '',
+      ].join('\n'),
+    );
+    return 1;
+  }
+
+  if (existingProject.status === 'unreadable') {
+    (io.stderr ?? process.stderr).write('VibeCompass project memory already exists, but project.yaml is unreadable.\n');
+    (io.stderr ?? process.stderr).write(`Root: ${existingProject.displayPath}\n`);
+    (io.stderr ?? process.stderr).write(`Project file: ${existingProject.projectFilePath}\n`);
+    (io.stderr ?? process.stderr).write(`Error: ${existingProject.errorMessage}\n`);
+    if (active.count > 0) {
+      (io.stderr ?? process.stderr).write(`Active lanes: ${formatActiveLaneSummary(active)}\n`);
+      (io.stderr ?? process.stderr).write('Close active lanes before replacing this root, or pass --force --replace-active-lanes if replacement is intentional.\n');
+    } else {
+      (io.stderr ?? process.stderr).write('Fix project.yaml manually, or rerun with --force if replacement is intentional.\n');
+    }
+    return 1;
+  }
+
+  const config = existingProject.projectConfig;
+  const repos = Array.isArray(config.repos)
+    ? config.repos.map((repo) => repo.id).filter(Boolean)
+    : [];
+  io.stdout.write('VibeCompass is already initialized — here is how to continue.\n');
+  io.stdout.write(`Project: ${config.name ?? 'Unknown'}\n`);
+  io.stdout.write(`Mode: ${config.mode ?? 'Unknown'}\n`);
+  io.stdout.write(`Root: ${existingProject.displayPath}\n`);
+  io.stdout.write(`Repos: ${repos.length > 0 ? repos.join(', ') : 'None recorded'}\n`);
+  io.stdout.write(`Active lanes: ${formatActiveLaneSummary(active)}\n`);
+  io.stdout.write('Next commands:\n');
+  io.stdout.write(`- vibecompass status${rootFlag}\n`);
+  io.stdout.write(`- vibecompass list-sessions${rootFlag}\n`);
+  io.stdout.write(`- vibecompass start-session${rootFlag} --id LANE_ID --working-on "TASK"\n`);
+  io.stdout.write(`- vibecompass docs-review${rootFlag} --guided\n`);
+  io.stdout.write(`- vibecompass sync-agents${rootFlag}\n`);
+  if (['local-primary', 'hosted-only'].includes(config.mode)) {
+    io.stdout.write(`- vibecompass connect-hosted${rootFlag}\n`);
+  }
+  return 0;
+}
+
+function formatActiveLaneSummary(activeSummary) {
+  if (!activeSummary || activeSummary.count === 0) {
+    return 'none';
+  }
+
+  return `${activeSummary.count}${activeSummary.current ? ` (current: ${activeSummary.current})` : ''}`;
+}
+
 async function main() {
   try {
     const exitCode = await runCli(process.argv.slice(2));