@vibecompass/vibecompass 0.2.1 → 0.3.1

package/src/session.js

@@ -1,5 +1,6 @@
 import { access, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
+import { scanProjectMemory } from './project-memory.js';
 import { parseSimpleYaml } from './simple-yaml.js';
 import { buildCloseSessionGuidance, resolveWorkflowSettings } from './workflow.js';
 import { syncAgentInstructionFiles } from './generators/agent-files/index.js';
@@ -36,6 +37,18 @@ export async function startProjectSession(options) {
   const claude = await readClaudeFile(normalized.claudePath);
   const sessionId = await resolveStartSessionId(normalized, options);
   const lanePaths = getLanePaths(normalized, sessionId);
+  const features = normalizeStringArray(options?.features);
+  const repos = normalizeStringArray(options?.repos);
+  const claims = normalizeStringArray(options?.claims);
+  const existingLanes = await listActiveSessionLanes(normalized);
+  const overlapWarnings = buildOverlapWarnings({
+    sessionId,
+    features,
+    repos,
+    claims,
+    existingLanes,
+  });
+  const highestDecisionId = await readHighestDecisionId(normalized.rootDir);
 
   const nextSessionNumber = await getNextSessionNumber(normalized.sessionsDir, sessionDate);
   const currentSession = parseCurrentSessionBlock(claude.content);
@@ -68,9 +81,10 @@ export async function startProjectSession(options) {
       sessionDate,
       sessionNumber: nextSessionNumber,
       workingOn,
-      features: normalizeStringArray(options?.features),
-      repos: normalizeStringArray(options?.repos),
-      claims: normalizeStringArray(options?.claims),
+      features,
+      repos,
+      claims,
+      highestDecisionId,
     }),
     'utf8',
   );
@@ -99,6 +113,8 @@ export async function startProjectSession(options) {
     status: 'active',
     workingOn,
   }, { current: sessionId });
+  const auditWarnings = await buildDocsReviewWarnings(normalized);
+  const metadataWarnings = collectLaneMetadataWarnings(existingLanes);
   const agentFileSync = await syncAgentInstructionFilesSafely({
     rootDir: normalized.rootDir,
     toolingRootDir: normalized.toolingRootDir,
@@ -114,6 +130,11 @@ export async function startProjectSession(options) {
     handoffFilePath: lanePaths.handoffFilePath,
     sessionDate,
     sessionNumber: nextSessionNumber,
+    warnings: [
+      ...metadataWarnings,
+      ...overlapWarnings,
+      ...auditWarnings,
+    ],
     agentFileSync,
   };
 }
@@ -314,6 +335,26 @@ async function syncAgentInstructionFilesSafely(options) {
   }
 }
 
+async function buildDocsReviewWarnings(normalized) {
+  const markerPath = path.join(normalized.rootDir, 'state', 'docs-review.json');
+  try {
+    const marker = JSON.parse(await readFile(markerPath, 'utf8'));
+    if (marker && marker.status === 'completed') {
+      return [];
+    }
+  } catch (error) {
+    if (!(error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT')) {
+      return [
+        `Docs-review marker at ${markerPath} is unreadable. Starter docs are not a comprehensive architecture review; run "vibecompass docs-review --guided" before risky implementation work.`,
+      ];
+    }
+  }
+
+  return [
+    `No docs-review marker found at ${markerPath}. Starter docs are not a comprehensive architecture review; run "vibecompass docs-review --guided" before risky implementation work.`,
+  ];
+}
+
 function normalizeSessionPaths(options) {
   const cwd = options?.cwd ? path.resolve(options.cwd) : process.cwd();
   const rootDir = path.resolve(cwd, options?.rootDir ?? '.compass');
@@ -511,6 +552,9 @@ async function listActiveSessionLanes(normalized) {
         features: metadata.features,
         repos: metadata.repos,
         claims: metadata.claims,
+        startedAt: metadata.startedAt,
+        decisionSnapshot: metadata.decisionSnapshot,
+        warnings: metadata.warnings,
         sessionDate: metadata.sessionDate ?? wipSession?.sessionDate ?? null,
         sessionNumber: metadata.sessionNumber ?? wipSession?.sessionNumber ?? 0,
       });
@@ -544,18 +588,30 @@ async function readLaneMetadata(sessionFilePath) {
       features: normalizeStringArray(data.feature_slugs),
       repos: normalizeStringArray(data.repos),
       claims: normalizeStringArray(data.claimed_paths),
+      startedAt: normalizeOptionalString(data.started_at),
+      decisionSnapshot: {
+        highestDecisionId: parseNullableNumber(data.decision_snapshot?.highest_decision_id),
+      },
       sessionDate: normalizeOptionalString(data.session_date),
       sessionNumber: typeof data.session_number === 'number' ? data.session_number : Number(data.session_number) || null,
+      warnings: [],
     };
-  } catch {
+  } catch (error) {
     return {
       status: null,
       workingOn: null,
       features: [],
       repos: [],
       claims: [],
+      startedAt: null,
+      decisionSnapshot: {
+        highestDecisionId: null,
+      },
       sessionDate: null,
       sessionNumber: null,
+      warnings: [
+        `Could not parse ${sessionFilePath}: ${error instanceof Error ? error.message : String(error)}`,
+      ],
     };
   }
 }
@@ -778,9 +834,9 @@ function renderLaneMetadata(options) {
     renderYamlArray('feature_slugs', options.features),
     renderYamlArray('repos', options.repos),
     renderYamlArray('claimed_paths', options.claims),
-    `started_at: ${new Date().toISOString()}`,
+    `started_at: ${formatLocalDateTime(new Date())}`,
     'decision_snapshot:',
-    '  highest_decision_id: null',
+    `  highest_decision_id: ${options.highestDecisionId ?? 'null'}`,
     '',
   ].join('\n');
 }
@@ -892,6 +948,124 @@ function normalizeSessionDate(value) {
   ].join('-');
 }
 
+async function readHighestDecisionId(rootDir) {
+  try {
+    const scanResult = await scanProjectMemory(rootDir);
+    const decisionIds = scanResult.documents.flatMap((document) => document.extracted?.decision_ids ?? []);
+    return decisionIds.reduce((max, id) => Math.max(max, id), 0) || null;
+  } catch {
+    return null;
+  }
+}
+
+function buildOverlapWarnings(options) {
+  const warnings = [];
+  for (const lane of options.existingLanes) {
+    const sharedFeatures = intersect(options.features, lane.features ?? []);
+    if (sharedFeatures.length > 0) {
+      warnings.push(
+        `Active session lane "${options.sessionId}" overlaps "${lane.id}" on feature(s): ${sharedFeatures.join(', ')}.`,
+      );
+    }
+
+    const claimOverlaps = findClaimOverlaps(options.claims, lane.claims ?? []);
+    for (const overlap of claimOverlaps) {
+      warnings.push(
+        `Active session lane "${options.sessionId}" overlaps "${lane.id}" on claimed path ${overlap.repo}:${overlap.path}.`,
+      );
+    }
+
+    const sharedRepos = intersect(options.repos, lane.repos ?? []);
+    if (sharedRepos.length > 0 && options.claims.length === 0 && (lane.claims ?? []).length === 0) {
+      warnings.push(
+        `Active session lane "${options.sessionId}" shares repo(s) ${sharedRepos.join(', ')} with "${lane.id}" without path claims; add --claim values to clarify ownership.`,
+      );
+    }
+  }
+
+  return warnings;
+}
+
+function collectLaneMetadataWarnings(lanes) {
+  return lanes.flatMap((lane) => lane.warnings ?? []);
+}
+
+function intersect(left, right) {
+  const rightSet = new Set(right);
+  return left.filter((item) => rightSet.has(item));
+}
+
+function findClaimOverlaps(leftClaims, rightClaims) {
+  const overlaps = [];
+  for (const left of leftClaims.map(parseClaim).filter(Boolean)) {
+    for (const right of rightClaims.map(parseClaim).filter(Boolean)) {
+      if (left.repo !== right.repo) {
+        continue;
+      }
+
+      if (pathPrefixesOverlap(left.path, right.path)) {
+        overlaps.push({
+          repo: left.repo,
+          path: left.path.length <= right.path.length ? left.path : right.path,
+        });
+      }
+    }
+  }
+
+  return overlaps;
+}
+
+function parseClaim(value) {
+  const separatorIndex = value.indexOf(':');
+  if (separatorIndex <= 0 || separatorIndex === value.length - 1) {
+    return null;
+  }
+
+  return {
+    repo: value.slice(0, separatorIndex),
+    path: normalizeClaimPath(value.slice(separatorIndex + 1)),
+  };
+}
+
+function normalizeClaimPath(value) {
+  return value.replace(/^\/+/, '').replace(/\/+$/, '');
+}
+
+function pathPrefixesOverlap(left, right) {
+  return left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
+}
+
+function parseNullableNumber(value) {
+  if (value === null || value === undefined) {
+    return null;
+  }
+
+  const number = typeof value === 'number' ? value : Number(value);
+  return Number.isFinite(number) ? number : null;
+}
+
+function formatLocalDateTime(date) {
+  const offsetMinutes = -date.getTimezoneOffset();
+  const sign = offsetMinutes >= 0 ? '+' : '-';
+  const absOffset = Math.abs(offsetMinutes);
+  const offset = `${sign}${String(Math.floor(absOffset / 60)).padStart(2, '0')}:${String(absOffset % 60).padStart(2, '0')}`;
+
+  return [
+    date.getFullYear(),
+    '-',
+    String(date.getMonth() + 1).padStart(2, '0'),
+    '-',
+    String(date.getDate()).padStart(2, '0'),
+    'T',
+    String(date.getHours()).padStart(2, '0'),
+    ':',
+    String(date.getMinutes()).padStart(2, '0'),
+    ':',
+    String(date.getSeconds()).padStart(2, '0'),
+    offset,
+  ].join('');
+}
+
 function requireNonEmptyString(value, message) {
   const normalized = normalizeOptionalString(value);
   if (!normalized) {

package/src/setup.js

@@ -1,6 +1,10 @@
-import { access } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { access, readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { createInterface } from 'node:readline/promises';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
 
 export const PLACEMENT_PATTERNS = {
   WORKSPACE_ROOT: 'workspace-root',
@@ -73,6 +77,40 @@ export async function resolveInitCliOptions(options, environment = {}) {
   };
 }
 
+export async function resolveConnectHostedCliOptions(options, environment = {}) {
+  const cwd = environment.cwd ? path.resolve(environment.cwd) : process.cwd();
+  let resolved = {
+    ...options,
+    sync: isPlainObject(options?.sync) ? { ...options.sync } : {},
+  };
+
+  if (!resolved.sync.apiUrl || !resolved.sync.projectId || !resolved.sync.credentialEnvVar) {
+    const prompter = createPrompter(environment.io, environment.runtime);
+    try {
+      if (!resolved.sync.apiUrl) {
+        resolved.sync.apiUrl = await askInput(prompter, 'Hosted sync API URL', {
+          defaultValue: 'https://vibecompass.dev',
+        });
+      }
+      if (!resolved.sync.projectId) {
+        resolved.sync.projectId = await askInput(prompter, 'Hosted project id');
+      }
+      if (!resolved.sync.credentialEnvVar) {
+        resolved.sync.credentialEnvVar = await askInput(prompter, 'Credential env var', {
+          defaultValue: 'VIBECOMPASS_SYNC_TOKEN',
+        });
+      }
+    } finally {
+      await prompter.close();
+    }
+  }
+
+  return {
+    rootDir: resolved.rootDir ? toRelativeIfInsideCwd(resolved.rootDir, cwd) : undefined,
+    sync: resolved.sync,
+  };
+}
+
 export function applyPlacementDefaults(options, environment = {}) {
   const cwd = environment.cwd ? path.resolve(environment.cwd) : process.cwd();
   const resolved = cloneInitOptions(options);
@@ -153,7 +191,8 @@ async function completeGuidedInitOptions(options, environment) {
   let resolved = cloneInitOptions(options);
   const cwd = environment.cwd;
   const prompter = environment.prompter;
-  const projectNameDefault = path.basename(cwd);
+  const inferredProject = await inferProjectFromCwd(cwd);
+  const projectNameDefault = inferredProject.projectName ?? path.basename(cwd);
 
   if (!resolved.name) {
     resolved.name = await askInput(prompter, 'Project name', {
@@ -162,63 +201,82 @@ async function completeGuidedInitOptions(options, environment) {
   }
 
   if (!resolved.mode) {
-    resolved.mode = await askChoice(prompter, 'Project mode', [
+    const setupGoal = await askChoice(prompter, 'What should VibeCompass set up?', [
       {
-        value: 'local-only',
-        description: 'Local files only. No hosted dependency.',
+        value: 'share-later',
+        description: 'Recommended. Local notes, with the option to share or collaborate later.',
       },
       {
-        value: 'local-primary',
-        description: 'Local files stay authoritative, with optional hosted sync/projection.',
+        value: 'local-only',
+        description: 'Local files only. No hosted sync or hosted docs-review prompts.',
       },
       {
         value: 'hosted-only',
-        description: 'Compatibility mode when hosted state remains authoritative.',
+        description: 'Hosted VibeCompass is already the source of truth for this project.',
       },
     ], {
-      defaultValue: 'local-only',
+      defaultValue: 'share-later',
     });
+    resolved.mode = setupGoal === 'share-later' ? 'local-primary' : setupGoal;
   }
 
   if (!Array.isArray(resolved.repos) || resolved.repos.length === 0) {
-    resolved.repos = await promptForRepos(prompter, cwd);
+    if (inferredProject.repo) {
+      const useDetectedRepo = await askConfirm(
+        prompter,
+        `Use detected Git repo ${inferredProject.repo.remote}?`,
+        true,
+      );
+      resolved.repos = useDetectedRepo ? [inferredProject.repo] : await promptForRepos(prompter, cwd);
+    } else {
+      resolved.repos = await promptForRepos(prompter, cwd);
+    }
   }
 
   let recommendation = null;
   if (!resolved.placementPattern) {
-    recommendation = await promptForPlacement(prompter, {
-      cwd,
-      repoCount: resolved.repos.length,
-    });
-    resolved.placementPattern = recommendation.pattern;
+    if (inferredProject.repo && resolved.repos.length === 1) {
+      recommendation = recommendPlacementPattern({ repoCount: 1 });
+      resolved.placementPattern = recommendation.pattern;
+    } else {
+      recommendation = await promptForPlacement(prompter, {
+        cwd,
+        repoCount: resolved.repos.length,
+      });
+      resolved.placementPattern = recommendation.pattern;
+    }
   }
 
   if (!resolved.toolingRootDir) {
-    const ownerLabel = describePlacementOwner(resolved.placementPattern);
-    const defaultOwnerDir = await suggestOwnerDirectory({
-      cwd,
-      placementPattern: resolved.placementPattern,
-      repos: resolved.repos,
-    });
-    resolved.toolingRootDir = await askInput(prompter, ownerLabel, {
-      defaultValue: defaultOwnerDir,
-      validate: async (value) => {
-        if (!(await directoryExists(path.resolve(cwd, value)))) {
-          return `${ownerLabel} must already exist relative to the current working directory.`;
-        }
-
-        return null;
-      },
-    });
+    if (inferredProject.repo && resolved.repos.length === 1 && resolved.placementPattern === PLACEMENT_PATTERNS.PRIMARY_REPO) {
+      resolved.toolingRootDir = '.';
+    } else {
+      const ownerLabel = describePlacementOwner(resolved.placementPattern);
+      const defaultOwnerDir = await suggestOwnerDirectory({
+        cwd,
+        placementPattern: resolved.placementPattern,
+        repos: resolved.repos,
+      });
+      resolved.toolingRootDir = await askInput(prompter, ownerLabel, {
+        defaultValue: defaultOwnerDir,
+        validate: async (value) => {
+          if (!(await directoryExists(path.resolve(cwd, value)))) {
+            return `${ownerLabel} must already exist relative to the current working directory.`;
+          }
+
+          return null;
+        },
+      });
+    }
   }
 
   resolved = applyPlacementDefaults(resolved, { cwd });
 
-  if (!resolved.sync && resolved.mode === 'local-primary') {
+  if (!resolved.sync && resolved.mode === 'hosted-only') {
     const configureSync = await askConfirm(
       prompter,
-      'Configure hosted sync binding now?',
-      false,
+      'Connect hosted VibeCompass now?',
+      resolved.mode === 'hosted-only',
     );
 
     if (configureSync) {
@@ -322,6 +380,63 @@ async function completeGuidedInitOptions(options, environment) {
   };
 }
 
+async function inferProjectFromCwd(cwd) {
+  const [packageName, gitInfo] = await Promise.all([
+    readPackageName(cwd),
+    readGitInfo(cwd),
+  ]);
+  const projectName = packageName ?? path.basename(cwd);
+
+  if (!gitInfo?.remote) {
+    return { projectName, repo: null };
+  }
+
+  const remoteSlug = extractRemoteSlug(gitInfo.remote);
+  const repoId = suggestRepoId(remoteSlug ?? packageName ?? path.basename(gitInfo.root ?? cwd));
+
+  return {
+    projectName,
+    repo: {
+      id: repoId,
+      remote: gitInfo.remote,
+      ...(gitInfo.branch ? { defaultBranch: gitInfo.branch } : {}),
+    },
+  };
+}
+
+async function readPackageName(cwd) {
+  try {
+    const packageJson = JSON.parse(await readFile(path.join(cwd, 'package.json'), 'utf8'));
+    return typeof packageJson.name === 'string' && packageJson.name.trim()
+      ? packageJson.name.trim()
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+async function readGitInfo(cwd) {
+  try {
+    const [{ stdout: remote }, { stdout: root }, branchResult] = await Promise.all([
+      execFileAsync('git', ['remote', 'get-url', 'origin'], { cwd }),
+      execFileAsync('git', ['rev-parse', '--show-toplevel'], { cwd }),
+      execFileAsync('git', ['branch', '--show-current'], { cwd }).catch(() => ({ stdout: '' })),
+    ]);
+    const normalizedRemote = remote.trim();
+    if (!normalizedRemote) {
+      return null;
+    }
+
+    return {
+      remote: normalizedRemote,
+      root: root.trim() || null,
+      branch: branchResult.stdout.trim() || null,
+    };
+  } catch {
+    return null;
+  }
+}
+
 async function promptForRepos(prompter, cwd) {
   const repoCount = await askInteger(prompter, 'How many repos belong to this logical project?', {
     defaultValue: 1,