@vibecompass/vibecompass 0.3.3 → 0.4.0

package/src/refresh-workflow.js

@@ -0,0 +1,233 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { inspectProjectCompatibility } from './compatibility.js';
+import { prepareStateManifest, writeStateManifest } from './manifest.js';
+import { serializeProjectConfig } from './project-yaml.js';
+import { buildWorkflowScaffoldFiles } from './scaffold.js';
+import { parseSimpleYaml } from './simple-yaml.js';
+import { syncAgentInstructionFiles } from './generators/agent-files/index.js';
+import { PACKAGE_VERSION } from './version.js';
+
+export async function refreshWorkflow(options = {}) {
+  const cwd = options.cwd ? path.resolve(options.cwd) : process.cwd();
+  const rootDir = path.resolve(cwd, options.rootDir ?? '.compass');
+  const toolingRootDir = options.toolingRootDir
+    ? path.resolve(cwd, options.toolingRootDir)
+    : cwd;
+  const apply = Boolean(options.apply);
+  const dryRun = !apply;
+
+  const compatibility = await inspectProjectCompatibility({ rootDir, cwd });
+  if (apply && compatibility.package.status === 'ahead' && !options.allowDowngradeTemplates) {
+    throw new Error(
+      'This root was refreshed by a newer VibeCompass package. Pass --allow-downgrade-templates to apply older templates with this CLI.',
+    );
+  }
+
+  const projectFilePath = path.join(rootDir, 'project.yaml');
+  const projectConfig = await readProjectConfig(projectFilePath);
+  const rootRelativePath = toPosix(path.relative(toolingRootDir, rootDir) || '.');
+  const contextRelativeToToolingRoot = toPosix(
+    path.relative(toolingRootDir, path.join(rootDir, 'context.md')) || 'context.md',
+  );
+
+  const workflowFiles = await planWorkflowFiles({
+    rootDir,
+    toolingRootDir,
+    projectConfig,
+    rootRelativePath,
+    contextRelativeToToolingRoot,
+  });
+
+  if (apply) {
+    await applyWorkflowFiles(workflowFiles);
+  }
+
+  const projectStamp = planProjectStamp(projectConfig, compatibility, {
+    updatePackageStamp: Boolean(options.updatePackageStamp),
+  });
+  if (apply && projectStamp.changed) {
+    await mkdir(path.dirname(projectFilePath), { recursive: true });
+    await writeFile(projectFilePath, serializeProjectConfig(projectStamp.projectConfig), 'utf8');
+  }
+
+  const manifest = apply
+    ? await writeStateManifest(rootDir)
+    : await prepareStateManifest(rootDir);
+
+  const agentFileSync = await syncAgentInstructionFiles({
+    rootDir,
+    toolingRootDir,
+    dryRun,
+  });
+
+  return {
+    rootDir,
+    toolingRootDir,
+    dryRun,
+    applied: apply,
+    compatibility,
+    projectFile: {
+      path: projectFilePath,
+      status: projectStamp.status,
+      changed: projectStamp.changed,
+      packageVersion: projectStamp.packageVersion,
+      warning: projectStamp.warning,
+    },
+    workflowFiles: workflowFiles.map((file) => ({
+      kind: file.kind,
+      path: file.path,
+      relativePath: toPosix(path.relative(rootDir, file.path)),
+      status: file.status,
+      changed: file.changed,
+      warning: file.warning,
+    })),
+    manifest: {
+      path: manifest.manifestPath,
+      status: apply ? 'updated' : 'planned-update',
+      documentCount: manifest.manifest.canonical.document_count,
+      warningCount: manifest.manifest.canonical.warning_count,
+    },
+    agentFileSync,
+  };
+}
+
+async function readProjectConfig(projectFilePath) {
+  try {
+    return parseSimpleYaml(await readFile(projectFilePath, 'utf8'), {
+      sourceName: projectFilePath,
+    });
+  } catch (error) {
+    if (error && typeof error === 'object' && error.code === 'ENOENT') {
+      throw new Error(`No project.yaml found in ${path.dirname(projectFilePath)}. Run "vibecompass init" first.`);
+    }
+
+    throw error;
+  }
+}
+
+async function planWorkflowFiles(options) {
+  const scaffold = buildWorkflowScaffoldFiles(options);
+  const files = [];
+
+  for (const file of scaffold.files) {
+    const existingContent = await readExistingFile(file.path);
+    const safety = resolveWorkflowFileSafety(file, existingContent);
+    const changed = safety.status !== 'skipped' && existingContent !== file.content;
+    files.push({
+      ...file,
+      existingContent,
+      status: changed ? (existingContent === null ? 'create' : 'update') : safety.status,
+      changed,
+      warning: safety.warning,
+    });
+  }
+
+  return files;
+}
+
+function resolveWorkflowFileSafety(file, existingContent) {
+  if (existingContent === null) {
+    return { status: 'create', warning: null };
+  }
+
+  if (existingContent === file.content) {
+    return { status: 'unchanged', warning: null };
+  }
+
+  if (file.kind === 'context') {
+    return { status: 'update', warning: null };
+  }
+
+  if (isGeneratedWorkflowGuide(file.kind, existingContent)) {
+    return { status: 'update', warning: null };
+  }
+
+  return {
+    status: 'skipped',
+    warning: 'Existing workflow guide does not match a VibeCompass-generated guide shape; left untouched.',
+  };
+}
+
+function isGeneratedWorkflowGuide(kind, content) {
+  // These sentinel strings are the safety boundary for refreshing guide files.
+  // Keep them in lockstep with the scaffold guide templates.
+  if (kind === 'architecture-guide') {
+    return content.includes('Each component doc is canonical. This README is only a convenience guide.');
+  }
+  if (kind === 'decisions-guide') {
+    return content.includes('This README is guidance only; canonical decision content lives in the domain files.');
+  }
+  if (kind === 'sessions-guide') {
+    return content.includes('Those scratch files are session-scoped working artifacts, not finalized history.');
+  }
+
+  return false;
+}
+
+// Refresh writes are intentionally non-atomic, matching init/scaffold behavior.
+async function applyWorkflowFiles(files) {
+  for (const file of files) {
+    if (!file.changed || file.status === 'skipped') {
+      continue;
+    }
+
+    await mkdir(path.dirname(file.path), { recursive: true });
+    await writeFile(file.path, file.content, 'utf8');
+  }
+}
+
+function planProjectStamp(projectConfig, compatibility, options) {
+  const currentMetadata = projectConfig.metadata && typeof projectConfig.metadata === 'object'
+    ? projectConfig.metadata
+    : {};
+  const currentStamp = currentMetadata.package_version;
+  const hasStringStamp = typeof currentStamp === 'string' && currentStamp.trim() !== '';
+  const missingStamp = currentStamp === undefined || currentStamp === null || currentStamp === '';
+  const shouldStamp = missingStamp || Boolean(options.updatePackageStamp);
+
+  if (!shouldStamp) {
+    return {
+      projectConfig,
+      status: 'unchanged',
+      changed: false,
+      packageVersion: hasStringStamp ? currentStamp : null,
+      warning: ['behind', 'invalid'].includes(compatibility.package.status)
+        ? 'Existing package stamp left untouched; pass --update-package-stamp to update it.'
+        : null,
+    };
+  }
+
+  const nextConfig = {
+    ...projectConfig,
+    metadata: {
+      ...currentMetadata,
+      package_version: PACKAGE_VERSION,
+    },
+  };
+  const changed = currentStamp !== PACKAGE_VERSION;
+
+  return {
+    projectConfig: nextConfig,
+    status: changed ? (missingStamp ? 'stamp-create' : 'stamp-update') : 'unchanged',
+    changed,
+    packageVersion: PACKAGE_VERSION,
+    warning: null,
+  };
+}
+
+async function readExistingFile(filePath) {
+  try {
+    return await readFile(filePath, 'utf8');
+  } catch (error) {
+    if (error && typeof error === 'object' && error.code === 'ENOENT') {
+      return null;
+    }
+
+    throw error;
+  }
+}
+
+function toPosix(value) {
+  return value.split(path.sep).join('/');
+}

package/src/scaffold.js

@@ -53,27 +53,13 @@ export async function scaffoldInitFiles(options) {
     };
   }
 
-  const contextFilePath = path.join(options.rootDir, 'context.md');
+  const workflowScaffold = buildWorkflowScaffoldFiles(options);
+  const contextFilePath = workflowScaffold.contextFilePath;
   // context.md is a derived artifact owned by the package; regenerate it on rerun.
-  await writeFile(contextFilePath, generateContextMarkdown(options), 'utf8');
+  await writeFile(contextFilePath, workflowScaffold.context.content, 'utf8');
   createdFiles.push(contextFilePath);
 
-  const workflowFiles = [
-    {
-      path: path.join(options.rootDir, 'architecture', 'README.md'),
-      content: generateArchitectureGuide(options.projectConfig),
-    },
-    {
-      path: path.join(options.rootDir, 'decisions', 'README.md'),
-      content: generateDecisionsGuide(options.projectConfig),
-    },
-    {
-      path: path.join(options.rootDir, 'sessions', 'README.md'),
-      content: generateSessionsGuide(options.projectConfig),
-    },
-  ];
-
-  for (const file of workflowFiles) {
+  for (const file of workflowScaffold.guides) {
     const outcome = await writeIfMissing(file.path, file.content);
     if (outcome.created) {
       createdFiles.push(file.path);
@@ -113,6 +99,40 @@ export async function scaffoldInitFiles(options) {
   };
 }
 
+export function buildWorkflowScaffoldFiles(options) {
+  const contextFilePath = path.join(options.rootDir, 'context.md');
+  const context = {
+    kind: 'context',
+    path: contextFilePath,
+    content: generateContextMarkdown(options),
+  };
+
+  const guides = [
+    {
+      kind: 'architecture-guide',
+      path: path.join(options.rootDir, 'architecture', 'README.md'),
+      content: generateArchitectureGuide(options.projectConfig),
+    },
+    {
+      kind: 'decisions-guide',
+      path: path.join(options.rootDir, 'decisions', 'README.md'),
+      content: generateDecisionsGuide(options.projectConfig),
+    },
+    {
+      kind: 'sessions-guide',
+      path: path.join(options.rootDir, 'sessions', 'README.md'),
+      content: generateSessionsGuide(options.projectConfig),
+    },
+  ];
+
+  return {
+    contextFilePath,
+    context,
+    guides,
+    files: [context, ...guides],
+  };
+}
+
 async function writeIfMissing(filePath, content) {
   if (await fileExists(filePath)) {
     return { created: false };

package/src/setup.js

@@ -1,8 +1,12 @@
 import { execFile } from 'node:child_process';
 import { access, readFile, readdir, realpath } from 'node:fs/promises';
+import os from 'node:os';
 import path from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { promisify } from 'node:util';
+import { getSupportedAgentFilePaths } from './generators/agent-files/index.js';
+import { END_MARKER, START_MARKER } from './generators/agent-files/markers.js';
+import { parseSimpleYaml } from './simple-yaml.js';
 
 const execFileAsync = promisify(execFile);
 
@@ -20,6 +24,24 @@ export async function resolveInitCliOptions(options, environment = {}) {
   let guidedSummary = null;
 
   if (resolved.guided) {
+    if (!resolved.force) {
+      const existingProject = await resolveExistingGuidedProject(resolved, {
+        cwd,
+        io: environment.io,
+        runtime: environment.runtime,
+      });
+      if (existingProject) {
+        return {
+          existingProject,
+          initOptions: null,
+          placementPattern: null,
+          guidedSummary: null,
+          agentFileSyncPlan: null,
+          sessionPlan: null,
+        };
+      }
+    }
+
     const prompter = createPrompter(environment.io, environment.runtime);
     try {
       const guided = await completeGuidedInitOptions(resolved, {
@@ -58,6 +80,7 @@ export async function resolveInitCliOptions(options, environment = {}) {
       mode: resolved.mode,
       repos: resolved.repos,
       force: resolved.force,
+      replaceActiveLanes: resolved.replaceActiveLanes,
       sync: resolved.sync,
       bootstrap: resolved.bootstrap,
       generatedAt: resolved.generatedAt,
@@ -68,6 +91,14 @@ export async function resolveInitCliOptions(options, environment = {}) {
     },
     placementPattern: resolved.placementPattern ?? null,
     guidedSummary,
+    agentFileSyncPlan: resolved.adoptExistingAgentFiles
+      ? {
+          rootDir: resolved.rootDir,
+          toolingRootDir: resolved.toolingRootDir,
+          adoptExisting: true,
+          existingOnly: true,
+        }
+      : null,
     sessionPlan: resolved.startSession
       ? {
           sessionId: resolved.sessionId,
@@ -111,6 +142,212 @@ export async function resolveConnectHostedCliOptions(options, environment = {})
   };
 }
 
+async function resolveExistingGuidedProject(options, environment) {
+  const candidates = await findExistingGuidedProjectRoots(options, environment.cwd);
+  if (candidates.length === 0) {
+    return null;
+  }
+
+  if (candidates.length === 1) {
+    if (candidates[0].discovery === 'ancestor' && canPrompt(environment)) {
+      const prompter = createPrompter(environment.io, environment.runtime);
+      try {
+        const useExistingRoot = await askConfirm(
+          prompter,
+          `Found existing VibeCompass project memory root at ${candidates[0].displayPath}. Show its info instead of initializing a new root here?`,
+          true,
+        );
+        if (!useExistingRoot) {
+          return null;
+        }
+      } finally {
+        await prompter.close();
+      }
+    }
+
+    return readExistingGuidedProject(candidates[0], environment.cwd);
+  }
+
+  return {
+    status: 'ambiguous',
+    candidates,
+  };
+}
+
+async function findExistingGuidedProjectRoots(options, cwd) {
+  const candidateRoots = options.rootDir
+    ? [{
+        rootDir: path.resolve(cwd, options.rootDir),
+        discovery: 'explicit',
+      }]
+    : await buildDefaultExistingRootCandidates(cwd);
+
+  const existing = [];
+  const seen = new Set();
+  for (const candidate of candidateRoots) {
+    const rootDir = candidate.rootDir;
+    if (seen.has(rootDir)) {
+      continue;
+    }
+    seen.add(rootDir);
+
+    if (await fileExists(path.join(rootDir, 'project.yaml'))) {
+      existing.push({
+        rootDir,
+        displayPath: toRelativeIfInsideCwd(rootDir, cwd),
+        discovery: candidate.discovery,
+      });
+    }
+  }
+
+  return existing;
+}
+
+async function buildDefaultExistingRootCandidates(cwd) {
+  const candidates = [
+    {
+      rootDir: path.resolve(cwd, '.compass'),
+      discovery: 'direct',
+    },
+    {
+      rootDir: path.resolve(cwd),
+      discovery: 'direct',
+    },
+  ];
+  const ancestorStopDir = await resolveAncestorSearchStopDir(cwd);
+  if (path.resolve(cwd) === ancestorStopDir) {
+    return candidates;
+  }
+
+  for (const directory of ancestorDirectories(path.dirname(cwd), ancestorStopDir)) {
+    candidates.push(
+      {
+        rootDir: path.join(directory, '.compass'),
+        discovery: 'ancestor',
+      },
+      {
+        rootDir: directory,
+        discovery: 'ancestor',
+      },
+    );
+  }
+
+  return candidates;
+}
+
+async function resolveAncestorSearchStopDir(cwd) {
+  const homeDir = path.resolve(os.homedir());
+  if (path.resolve(cwd) === homeDir) {
+    return homeDir;
+  }
+
+  const gitRoot = await readGitRoot(cwd);
+  if (!gitRoot) {
+    return isPathInside(cwd, homeDir) || path.resolve(cwd) === homeDir
+      ? homeDir
+      : path.parse(cwd).root;
+  }
+
+  const gitRootParent = path.dirname(path.resolve(gitRoot));
+  if (isPathInside(gitRootParent, homeDir) || gitRootParent === homeDir) {
+    return gitRootParent;
+  }
+
+  return isPathInside(cwd, homeDir) || path.resolve(cwd) === homeDir
+    ? homeDir
+    : path.parse(cwd).root;
+}
+
+function ancestorDirectories(startDir, stopDir) {
+  const directories = [];
+  let current = path.resolve(startDir);
+  const stop = path.resolve(stopDir);
+  while (true) {
+    directories.push(current);
+    if (current === stop || current === path.dirname(current)) {
+      break;
+    }
+    current = path.dirname(current);
+  }
+
+  return directories;
+}
+
+async function readExistingGuidedProject(candidate, cwd) {
+  const projectFilePath = path.join(candidate.rootDir, 'project.yaml');
+  const activeSummary = await readActiveLaneSummary(candidate.rootDir);
+  try {
+    const projectConfig = parseSimpleYaml(await readFile(projectFilePath, 'utf8'), {
+      sourceName: projectFilePath,
+    });
+
+    return {
+      status: 'ok',
+      rootDir: candidate.rootDir,
+      displayPath: candidate.displayPath ?? toRelativeIfInsideCwd(candidate.rootDir, cwd),
+      projectFilePath,
+      projectConfig,
+      activeSummary,
+    };
+  } catch (error) {
+    return {
+      status: 'unreadable',
+      rootDir: candidate.rootDir,
+      displayPath: candidate.displayPath ?? toRelativeIfInsideCwd(candidate.rootDir, cwd),
+      projectFilePath,
+      errorMessage: error instanceof Error ? error.message : 'Unable to read project.yaml.',
+      activeSummary,
+    };
+  }
+}
+
+async function readActiveLaneSummary(rootDir) {
+  const activeDir = path.join(rootDir, 'sessions', 'active');
+  let count = 0;
+  try {
+    const entries = await readdir(activeDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+
+      const laneDir = path.join(activeDir, entry.name);
+      if (
+        (await fileExists(path.join(laneDir, 'session.yaml'))) ||
+        (await fileExists(path.join(laneDir, 'wip.md')))
+      ) {
+        count += 1;
+      }
+    }
+  } catch {
+    count = 0;
+  }
+
+  let current = null;
+  try {
+    const indexPath = path.join(activeDir, 'index.yaml');
+    const activeIndex = parseSimpleYaml(await readFile(indexPath, 'utf8'), {
+      sourceName: indexPath,
+    });
+    current = typeof activeIndex.current === 'string' && activeIndex.current !== 'null'
+      ? activeIndex.current
+      : null;
+  } catch {
+    current = null;
+  }
+
+  return { count, current };
+}
+
+function canPrompt(environment) {
+  if (typeof environment.runtime?.prompt === 'function') {
+    return true;
+  }
+
+  const input = environment.runtime?.stdin ?? environment.io?.stdin ?? process.stdin;
+  return Boolean(input?.isTTY);
+}
+
 export function applyPlacementDefaults(options, environment = {}) {
   const cwd = environment.cwd ? path.resolve(environment.cwd) : process.cwd();
   const resolved = cloneInitOptions(options);
@@ -336,6 +573,22 @@ async function completeGuidedInitOptions(options, environment) {
     }
   }
 
+  if (resolved.adoptExistingAgentFiles === undefined) {
+    const adoptionCandidates = await findExistingUnmarkedAgentFiles({
+      cwd,
+      toolingRootDir: resolved.toolingRootDir,
+    });
+
+    if (adoptionCandidates.length > 0) {
+      writeAgentAdoptionPreview(prompter, adoptionCandidates);
+      resolved.adoptExistingAgentFiles = await askConfirm(
+        prompter,
+        'Append VibeCompass managed sections to existing agent instruction files?',
+        false,
+      );
+    }
+  }
+
   if (!resolved.startSession) {
     resolved.startSession = await askConfirm(
       prompter,
@@ -468,6 +721,16 @@ async function readGitInfo(cwd) {
   }
 }
 
+async function readGitRoot(cwd) {
+  try {
+    const { stdout } = await execFileAsync('git', ['rev-parse', '--show-toplevel'], { cwd });
+    const root = stdout.trim();
+    return root ? path.resolve(root) : null;
+  } catch {
+    return null;
+  }
+}
+
 async function discoverChildGitRepos(cwd) {
   let entries = [];
   try {
@@ -558,6 +821,65 @@ function reposMatchDetected(repos, detectedRepos) {
   return repos.every((repo) => detectedKeys.has(`${repo.id}\n${repo.remote}`));
 }
 
+async function findExistingUnmarkedAgentFiles(context) {
+  const toolingRootDir = path.resolve(context.cwd, context.toolingRootDir ?? '.');
+  const candidates = [];
+
+  for (const relativePath of getSupportedAgentFilePaths()) {
+    const filePath = path.join(toolingRootDir, relativePath);
+    let content = null;
+    try {
+      content = await readFile(filePath, 'utf8');
+    } catch {
+      continue;
+    }
+
+    if (content.includes(START_MARKER) || content.includes(END_MARKER)) {
+      continue;
+    }
+
+    candidates.push({
+      relativePath,
+      conflicts: scanPotentialAgentWorkflowConflicts(content),
+    });
+  }
+
+  return candidates;
+}
+
+function writeAgentAdoptionPreview(prompter, candidates) {
+  prompter.write('Existing agent instruction files without VibeCompass markers:\n');
+  for (const candidate of candidates) {
+    prompter.write(`- ${candidate.relativePath}: VibeCompass can append a managed block at the end of this file.\n`);
+    if (candidate.conflicts.length > 0) {
+      prompter.write(`  possible workflow overlap on lines ${candidate.conflicts.map((conflict) => conflict.line).join(', ')}\n`);
+    }
+  }
+  prompter.write('Content outside the managed block stays user-owned and will not be rewritten.\n');
+}
+
+function scanPotentialAgentWorkflowConflicts(content) {
+  const patterns = [
+    'session',
+    'handoff',
+    'decisions',
+    'wip.md',
+    'review handoff',
+    'close-session',
+    'address review',
+    'builder',
+    'reviewer',
+  ];
+
+  return content
+    .split(/\r?\n/)
+    .map((line, index) => ({
+      line: index + 1,
+      normalized: line.toLowerCase(),
+    }))
+    .filter((entry) => patterns.some((pattern) => entry.normalized.includes(pattern)));
+}
+
 async function promptForRepos(prompter, cwd) {
   const repoCount = await askInteger(prompter, 'How many repos belong to this logical project?', {
     defaultValue: 1,
@@ -993,6 +1315,15 @@ async function directoryExists(directoryPath) {
   }
 }
 
+async function fileExists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 async function isSameDirectory(left, right) {
   try {
     const [leftRealPath, rightRealPath] = await Promise.all([
@@ -1019,3 +1350,8 @@ function toRelativeIfInsideCwd(targetPath, cwd) {
 
   return relative;
 }
+
+function isPathInside(candidatePath, parentPath) {
+  const relative = path.relative(path.resolve(parentPath), path.resolve(candidatePath));
+  return Boolean(relative) && !relative.startsWith('..') && !path.isAbsolute(relative);
+}