@vibecompass/vibecompass 0.3.4 → 0.4.0

package/src/compatibility.js

@@ -0,0 +1,308 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { STATE_VERSION } from './manifest.js';
+import { parseSimpleYaml } from './simple-yaml.js';
+import { PACKAGE_VERSION } from './version.js';
+
+/**
+ * Inspect root compatibility without writing files.
+ * `packageVersion` is a test override; production callers should omit it.
+ */
+export async function inspectProjectCompatibility(options = {}) {
+  const cwd = options.cwd ? path.resolve(options.cwd) : process.cwd();
+  const rootDir = path.resolve(cwd, options.rootDir ?? '.compass');
+  const cliPackageVersion = normalizePackageVersion(options.packageVersion ?? PACKAGE_VERSION);
+  const projectFilePath = path.join(rootDir, 'project.yaml');
+  const manifestPath = path.join(rootDir, 'state', 'manifest.json');
+  const warnings = [];
+
+  const project = await readProjectStamp(projectFilePath);
+  const manifest = await readManifestState(manifestPath);
+  const packageStatus = project.status === 'unreadable'
+    ? {
+        status: 'unknown',
+        rootVersion: null,
+        cliVersion: cliPackageVersion,
+        errorMessage: project.errorMessage,
+      }
+    : buildPackageStatus(project.packageVersion, cliPackageVersion);
+  const stateStatus = buildStateStatus(manifest);
+  // Package and state statuses intentionally use different vocabularies:
+  // canonical package-stamp drift is distinct from derived-state drift.
+
+  if (packageStatus.status === 'unknown') {
+    warnings.push(warning({
+      code: 'project-yaml-unreadable',
+      message: `project.yaml is unreadable. ${packageStatus.errorMessage}`,
+      errorMessage: packageStatus.errorMessage,
+    }));
+  } else if (packageStatus.status === 'legacy') {
+    warnings.push(warning({
+      code: 'package-version-legacy-root',
+      message: 'project.yaml has no metadata.package_version stamp; treating the root as legacy/unknown.',
+      cliVersion: cliPackageVersion,
+    }));
+  } else if (packageStatus.status === 'behind') {
+    warnings.push(warning({
+      code: 'package-version-behind',
+      message: `project.yaml metadata.package_version ${packageStatus.rootVersion} is older than CLI package ${cliPackageVersion}.`,
+      rootVersion: packageStatus.rootVersion,
+      cliVersion: cliPackageVersion,
+    }));
+  } else if (packageStatus.status === 'ahead') {
+    warnings.push(warning({
+      code: 'package-version-ahead',
+      message: `project.yaml metadata.package_version ${packageStatus.rootVersion} is newer than CLI package ${cliPackageVersion}.`,
+      rootVersion: packageStatus.rootVersion,
+      cliVersion: cliPackageVersion,
+    }));
+  } else if (packageStatus.status === 'invalid') {
+    warnings.push(warning({
+      code: 'package-version-invalid',
+      message: 'project.yaml metadata.package_version is present but is not a non-empty semver string.',
+      rootVersion: packageStatus.rootVersion,
+      cliVersion: cliPackageVersion,
+    }));
+  }
+
+  if (stateStatus.status === 'missing') {
+    warnings.push(warning({
+      code: 'state-manifest-missing',
+      message: 'state/manifest.json is missing; commands that need derived state can regenerate it.',
+    }));
+  } else if (stateStatus.status === 'unreadable') {
+    warnings.push(warning({
+      code: 'state-manifest-unreadable',
+      message: `state/manifest.json is unreadable; commands that need derived state can discard and regenerate it. ${stateStatus.errorMessage}`,
+      errorMessage: stateStatus.errorMessage,
+    }));
+  } else if (stateStatus.status === 'unsupported') {
+    warnings.push(warning({
+      code: 'state-version-unsupported',
+      message: `state/manifest.json state_version ${stateStatus.observedVersion} is unsupported by this CLI (expected ${STATE_VERSION}); commands that need derived state can regenerate it.`,
+      observedVersion: stateStatus.observedVersion,
+      expectedVersion: STATE_VERSION,
+      packageObservedVersion: stateStatus.packageObservedVersion,
+    }));
+  }
+
+  return {
+    rootDir,
+    projectFilePath,
+    manifestPath,
+    cliPackageVersion,
+    package: packageStatus,
+    state: stateStatus,
+    warnings,
+  };
+}
+
+export function formatCompatibilityWarnings(result) {
+  return (result?.warnings ?? []).map((warning) => warning.message);
+}
+
+async function readProjectStamp(projectFilePath) {
+  try {
+    const config = parseSimpleYaml(await readFile(projectFilePath, 'utf8'), {
+      sourceName: projectFilePath,
+    });
+    const metadata = isPlainObject(config.metadata) ? config.metadata : {};
+    return {
+      status: 'ok',
+      packageVersion: Object.hasOwn(metadata, 'package_version')
+        ? metadata.package_version
+        : undefined,
+    };
+  } catch (error) {
+    return {
+      status: 'unreadable',
+      packageVersion: undefined,
+      errorMessage: error instanceof Error ? error.message : 'Unable to read project.yaml.',
+    };
+  }
+}
+
+async function readManifestState(manifestPath) {
+  try {
+    return {
+      status: 'ok',
+      manifest: JSON.parse(await readFile(manifestPath, 'utf8')),
+    };
+  } catch (error) {
+    if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+      return { status: 'missing' };
+    }
+
+    return {
+      status: 'unreadable',
+      errorMessage: error instanceof Error ? error.message : 'Unable to read state/manifest.json.',
+    };
+  }
+}
+
+function buildPackageStatus(rootVersion, cliPackageVersion) {
+  if (rootVersion === undefined) {
+    return {
+      status: 'legacy',
+      rootVersion: null,
+      cliVersion: cliPackageVersion,
+    };
+  }
+
+  if (typeof rootVersion !== 'string' || rootVersion.trim() === '') {
+    return {
+      status: 'invalid',
+      rootVersion,
+      cliVersion: cliPackageVersion,
+    };
+  }
+
+  const normalizedRootVersion = normalizePackageVersion(rootVersion);
+  if (!parseSemver(normalizedRootVersion)) {
+    return {
+      status: 'invalid',
+      rootVersion,
+      cliVersion: cliPackageVersion,
+    };
+  }
+
+  const comparison = comparePackageVersions(normalizedRootVersion, cliPackageVersion);
+
+  return {
+    status: comparison === 0 ? 'current' : comparison < 0 ? 'behind' : 'ahead',
+    rootVersion: normalizedRootVersion,
+    cliVersion: cliPackageVersion,
+  };
+}
+
+function buildStateStatus(manifestResult) {
+  if (manifestResult.status === 'missing') {
+    return { status: 'missing' };
+  }
+
+  if (manifestResult.status === 'unreadable') {
+    return {
+      status: 'unreadable',
+      errorMessage: manifestResult.errorMessage,
+    };
+  }
+
+  const manifest = manifestResult.manifest;
+  if (manifest?.state_version !== STATE_VERSION) {
+    return {
+      status: 'unsupported',
+      observedVersion: manifest?.state_version ?? null,
+      expectedVersion: STATE_VERSION,
+      packageObservedVersion:
+        typeof manifest?.package?.observed_version === 'string'
+          ? manifest.package.observed_version
+          : null,
+    };
+  }
+
+  return {
+    status: 'current',
+    observedVersion: manifest.state_version,
+    expectedVersion: STATE_VERSION,
+    packageObservedVersion:
+      typeof manifest?.package?.observed_version === 'string'
+        ? manifest.package.observed_version
+        : null,
+  };
+}
+
+function comparePackageVersions(left, right) {
+  const leftSemver = parseSemver(left);
+  const rightSemver = parseSemver(right);
+  if (!leftSemver || !rightSemver) {
+    return 0;
+  }
+
+  const leftParts = [leftSemver.major, leftSemver.minor, leftSemver.patch];
+  const rightParts = [rightSemver.major, rightSemver.minor, rightSemver.patch];
+  for (let index = 0; index < 3; index += 1) {
+    if (leftParts[index] < rightParts[index]) {
+      return -1;
+    }
+    if (leftParts[index] > rightParts[index]) {
+      return 1;
+    }
+  }
+
+  return comparePrerelease(leftSemver.prerelease, rightSemver.prerelease);
+}
+
+function parseSemver(version) {
+  const match = String(version).match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/);
+  if (!match) {
+    return null;
+  }
+
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] ? match[4].split('.') : [],
+  };
+}
+
+function comparePrerelease(left, right) {
+  if (left.length === 0 && right.length === 0) {
+    return 0;
+  }
+
+  if (left.length === 0) {
+    return 1;
+  }
+
+  if (right.length === 0) {
+    return -1;
+  }
+
+  const length = Math.max(left.length, right.length);
+  for (let index = 0; index < length; index += 1) {
+    const leftPart = left[index];
+    const rightPart = right[index];
+    if (leftPart === undefined) {
+      return -1;
+    }
+    if (rightPart === undefined) {
+      return 1;
+    }
+
+    const leftNumeric = /^\d+$/.test(leftPart);
+    const rightNumeric = /^\d+$/.test(rightPart);
+    if (leftNumeric && rightNumeric) {
+      const difference = Number(leftPart) - Number(rightPart);
+      if (difference !== 0) {
+        return difference < 0 ? -1 : 1;
+      }
+      continue;
+    }
+
+    if (leftNumeric !== rightNumeric) {
+      return leftNumeric ? -1 : 1;
+    }
+
+    const comparison = leftPart.localeCompare(rightPart);
+    if (comparison !== 0) {
+      return comparison < 0 ? -1 : 1;
+    }
+  }
+
+  return 0;
+}
+
+function normalizePackageVersion(version) {
+  return String(version).trim();
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function warning(fields) {
+  return Object.fromEntries(
+    Object.entries(fields).filter(([, value]) => value !== undefined),
+  );
+}

package/src/index.js

@@ -1,4 +1,8 @@
-export { STATE_VERSION, generateStateManifest, writeStateManifest } from './manifest.js';
+export { STATE_VERSION, generateStateManifest, prepareStateManifest, writeStateManifest } from './manifest.js';
+export { inspectProjectCompatibility, formatCompatibilityWarnings } from './compatibility.js';
+export { PACKAGE_VERSION } from './version.js';
+export { refreshWorkflow } from './refresh-workflow.js';
+export { getProjectStatus, renderStatusText, toStatusJson } from './status.js';
 export { initializeProjectMemory } from './init.js';
 export { preflightDocsReview } from './docs-review.js';
 export {

package/src/init.js

@@ -1,4 +1,4 @@
-import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { access, mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { serializeProjectConfig } from './project-yaml.js';
 import { writeStateManifest } from './manifest.js';
@@ -6,12 +6,17 @@ import { scaffoldInitFiles } from './scaffold.js';
 import { applyPlacementDefaults } from './setup.js';
 import { buildWorkflowMetadata } from './workflow.js';
 import { parseSimpleYaml } from './simple-yaml.js';
+import { PACKAGE_VERSION } from './version.js';
 
 const VALID_MODES = new Set(['local-only', 'local-primary', 'hosted-only']);
 
 export async function initializeProjectMemory(options) {
   const normalized = normalizeInitOptions(options);
 
+  if (normalized.force && !normalized.replaceActiveLanes) {
+    await assertNoActiveSessionLanes(normalized.rootDir);
+  }
+
   await mkdir(normalized.rootDir, { recursive: true });
   await mkdir(path.join(normalized.rootDir, 'architecture'), { recursive: true });
   await mkdir(path.join(normalized.rootDir, 'decisions'), { recursive: true });
@@ -137,7 +142,10 @@ function normalizeInitOptions(options) {
     mode: preparedOptions.mode,
     repos,
     ...(sync ? { sync } : {}),
-    metadata: buildAgentFilesMetadata(buildWorkflowMetadata(preparedOptions.metadata, {
+    metadata: buildAgentFilesMetadata(buildWorkflowMetadata({
+      ...(preparedOptions.metadata && typeof preparedOptions.metadata === 'object' ? preparedOptions.metadata : {}),
+      package_version: PACKAGE_VERSION,
+    }, {
       gitPublish:
         typeof preparedOptions.closeSessionGitPublish === 'boolean'
           ? preparedOptions.closeSessionGitPublish
@@ -156,12 +164,44 @@ function normalizeInitOptions(options) {
   return {
     rootDir,
     force: Boolean(preparedOptions.force),
+    replaceActiveLanes: Boolean(preparedOptions.replaceActiveLanes),
     generatedAt: preparedOptions.generatedAt,
     projectConfig,
     bootstrap: bootstrapOptions,
   };
 }
 
+async function assertNoActiveSessionLanes(rootDir) {
+  const activeDir = path.join(rootDir, 'sessions', 'active');
+  let entries = [];
+  try {
+    entries = await readdir(activeDir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  const activeLaneIds = [];
+  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')))
+    ) {
+      activeLaneIds.push(entry.name);
+    }
+  }
+
+  if (activeLaneIds.length > 0) {
+    throw new Error(
+      `Cannot overwrite project memory while active session lanes exist: ${activeLaneIds.join(', ')}. Close the lanes first or pass --replace-active-lanes.`,
+    );
+  }
+}
+
 function normalizeSyncOptions(syncOptions, mode) {
   if (!syncOptions || typeof syncOptions !== 'object') {
     throw new Error('sync configuration must be an object.');

package/src/manifest.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { localRevisionFromManifestHash, stableHash } from './hash.js';
 import { scanProjectMemory } from './project-memory.js';
 import { listProjectSessions } from './session.js';
+import { PACKAGE_VERSION } from './version.js';
 
 export const STATE_VERSION = 1;
 
@@ -50,13 +51,17 @@ export function generateStateManifest(scanResult, options = {}) {
       document_count: manifestInventory.length,
       warning_count: warningCount,
     },
+    package: {
+      observed_version: options.packageVersion ?? PACKAGE_VERSION,
+      observed_at: generatedAt,
+    },
     documents: manifestDocuments,
     ...(options.activeSessions ? { active_sessions: options.activeSessions } : {}),
     ...(options.sync ? { sync: options.sync } : {}),
   };
 }
 
-export async function writeStateManifest(rootDir, options = {}) {
+export async function prepareStateManifest(rootDir, options = {}) {
   const scanResult = await scanProjectMemory(rootDir);
   const activeSessions = await readActiveSessionsForManifest(rootDir);
   const existingSync = Object.hasOwn(options, 'sync')
@@ -70,9 +75,6 @@ export async function writeStateManifest(rootDir, options = {}) {
   const stateDir = path.join(rootDir, 'state');
   const manifestPath = path.join(stateDir, 'manifest.json');
 
-  await mkdir(stateDir, { recursive: true });
-  await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
-
   return {
     manifest,
     manifestPath,
@@ -80,6 +82,16 @@ export async function writeStateManifest(rootDir, options = {}) {
   };
 }
 
+export async function writeStateManifest(rootDir, options = {}) {
+  const prepared = await prepareStateManifest(rootDir, options);
+  const stateDir = path.dirname(prepared.manifestPath);
+
+  await mkdir(stateDir, { recursive: true });
+  await writeFile(prepared.manifestPath, `${JSON.stringify(prepared.manifest, null, 2)}\n`, 'utf8');
+
+  return prepared;
+}
+
 async function readExistingSyncState(rootDir) {
   try {
     const existing = JSON.parse(

package/src/read-model.js

@@ -14,7 +14,7 @@ export async function loadProjectReadModel(rootDir) {
     throw new Error(`Cannot build read model with canonical parse errors.\n${details}`);
   }
 
-  const existingManifest = await readManifestIfPresent(rootDir);
+  const existingManifest = normalizeReadableManifest(await readManifestIfPresent(rootDir));
   const currentManifest = generateStateManifest(scanResult, {
     generatedAt: existingManifest?.generated_at ?? new Date(),
     sync: existingManifest?.sync,
@@ -555,3 +555,19 @@ async function readManifestIfPresent(rootDir) {
     return null;
   }
 }
+
+function normalizeReadableManifest(manifest) {
+  if (!manifest || typeof manifest !== 'object') {
+    return null;
+  }
+
+  if (!manifest.canonical || typeof manifest.canonical !== 'object') {
+    return null;
+  }
+
+  if (typeof manifest.canonical.manifest_hash !== 'string') {
+    return null;
+  }
+
+  return manifest;
+}