@vibecompass/vibecompass 0.1.0

package/src/generators/agent-files/index.js

@@ -0,0 +1,147 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parseSimpleYaml } from '../../simple-yaml.js';
+import { loadProjectReadModel } from '../../read-model.js';
+import { applyManagedBlock } from './markers.js';
+import { buildAgentContext } from './template.js';
+import { claudeMdFormat } from './claude-md.js';
+import { agentsMdFormat } from './agents-md.js';
+import { cursorRulesFormat } from './cursor-rules.js';
+import { copilotInstructionsFormat } from './copilot-instructions.js';
+
+const FORMATS = [
+  claudeMdFormat,
+  agentsMdFormat,
+  cursorRulesFormat,
+  copilotInstructionsFormat,
+];
+
+const FORMAT_MAP = new Map(FORMATS.map((format) => [format.name, format]));
+
+export async function syncAgentInstructionFiles(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 requestedFormat = normalizeOptionalString(options.format);
+  const dryRun = Boolean(options.dryRun);
+
+  const projectConfig = await readProjectConfig(rootDir);
+  const selection = resolveEnabledFormats(projectConfig, requestedFormat);
+
+  if (selection.disabledFormat) {
+    const outputPath = path.join(toolingRootDir, selection.disabledFormat.path);
+    return {
+      rootDir,
+      toolingRootDir,
+      dryRun,
+      results: [
+        {
+          format: selection.disabledFormat.name,
+          path: outputPath,
+          relativePath: toPosix(path.relative(toolingRootDir, outputPath)),
+          status: 'disabled',
+          warning: `Format "${selection.disabledFormat.name}" is disabled in metadata.agent_files; left untouched.`,
+          changed: false,
+        },
+      ],
+    };
+  }
+
+  const readModel = await loadProjectReadModel(rootDir);
+  const context = buildAgentContext(readModel);
+  const results = [];
+
+  for (const format of selection.formats) {
+    const outputPath = path.join(toolingRootDir, format.path);
+    const existingContent = await readExistingFile(outputPath);
+    const generatedContent = format.render(context);
+    const applied = applyManagedBlock(existingContent, generatedContent);
+
+    if (!dryRun && applied.warning === null && applied.content !== existingContent) {
+      await mkdir(path.dirname(outputPath), { recursive: true });
+      await writeFile(outputPath, applied.content, 'utf8');
+    }
+
+    results.push({
+      format: format.name,
+      path: outputPath,
+      relativePath: toPosix(path.relative(toolingRootDir, outputPath)),
+      status: dryRun && applied.warning === null ? `dry-run-${applied.status}` : applied.status,
+      warning: applied.warning,
+      changed: applied.warning === null && applied.content !== existingContent,
+    });
+  }
+
+  return {
+    rootDir,
+    toolingRootDir,
+    dryRun,
+    results,
+  };
+}
+
+export function getSupportedAgentFormats() {
+  return FORMATS.map((format) => format.name);
+}
+
+async function readProjectConfig(rootDir) {
+  const source = await readFile(path.join(rootDir, 'project.yaml'), 'utf8');
+  return parseSimpleYaml(source, { sourceName: 'project.yaml' });
+}
+
+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 resolveEnabledFormats(projectConfig, requestedFormat) {
+  const configured = projectConfig?.metadata?.agent_files;
+  const enabledNames = FORMATS
+    .filter((format) => configured?.[format.name] !== false)
+    .map((format) => format.name);
+
+  if (requestedFormat) {
+    if (!FORMAT_MAP.has(requestedFormat)) {
+      throw new Error(`Unknown agent file format "${requestedFormat}". Supported formats: ${getSupportedAgentFormats().join(', ')}.`);
+    }
+
+    if (!enabledNames.includes(requestedFormat)) {
+      return {
+        formats: [],
+        disabledFormat: FORMAT_MAP.get(requestedFormat),
+      };
+    }
+
+    return {
+      formats: [FORMAT_MAP.get(requestedFormat)],
+      disabledFormat: null,
+    };
+  }
+
+  return {
+    formats: enabledNames.map((name) => FORMAT_MAP.get(name)),
+    disabledFormat: null,
+  };
+}
+
+function normalizeOptionalString(value) {
+  if (typeof value !== 'string') {
+    return null;
+  }
+
+  const trimmed = value.trim();
+  return trimmed ? trimmed : null;
+}
+
+function toPosix(value) {
+  return value.split(path.sep).join('/');
+}

package/src/generators/agent-files/markers.js

@@ -0,0 +1,49 @@
+export const START_MARKER = '<!-- vibecompass:start - managed by VibeCompass, do not edit -->';
+export const END_MARKER = '<!-- vibecompass:end -->';
+
+export function renderManagedBlock(content) {
+  const trimmed = content.trim();
+  return `${START_MARKER}\n${trimmed}\n${END_MARKER}\n`;
+}
+
+export function applyManagedBlock(existingContent, generatedContent) {
+  const block = renderManagedBlock(generatedContent);
+
+  if (existingContent === null) {
+    return {
+      status: 'create',
+      content: block,
+      warning: null,
+    };
+  }
+
+  const startIndex = existingContent.indexOf(START_MARKER);
+  const endIndex = existingContent.indexOf(END_MARKER);
+
+  if (startIndex === -1 && endIndex === -1) {
+    return {
+      status: 'warning',
+      content: existingContent,
+      warning: 'Existing file has no VibeCompass managed markers; left untouched.',
+    };
+  }
+
+  if (startIndex === -1 || endIndex === -1 || endIndex < startIndex) {
+    return {
+      status: 'warning',
+      content: existingContent,
+      warning: 'Existing file has incomplete VibeCompass managed markers; left untouched.',
+    };
+  }
+
+  const before = existingContent.slice(0, startIndex);
+  const after = existingContent.slice(endIndex + END_MARKER.length);
+  const beforeSeparator = before === '' || before.endsWith('\n') ? '' : '\n';
+  const afterSeparator = after === '' || after.startsWith('\n') ? '' : '\n';
+
+  return {
+    status: 'update',
+    content: `${before}${beforeSeparator}${block}${afterSeparator}${after}`,
+    warning: null,
+  };
+}

package/src/generators/agent-files/template.js

@@ -0,0 +1,75 @@
+export function buildAgentContext(readModel) {
+  return {
+    projectName: readModel.project.name ?? 'Unnamed project',
+    description: readModel.project.description ?? null,
+    mode: readModel.project.mode ?? null,
+    rootDir: readModel.project.root_dir,
+    repos: readModel.project.repos ?? [],
+    domains: readModel.domains ?? [],
+    recentDecisions: readModel.decisions.slice(0, 8),
+    recentSessions: readModel.sessions.slice(0, 3),
+  };
+}
+
+export function renderSharedInstructionBody(context, options = {}) {
+  const heading = options.heading ?? `${context.projectName} Project Instructions`;
+  const intro =
+    options.intro ??
+    'Use VibeCompass project memory as the source of truth before making code changes.';
+
+  return [
+    `# ${heading}`,
+    '',
+    intro,
+    '',
+    '## Read First',
+    `- Project memory root: \`${context.rootDir}\``,
+    '- Read `project.yaml` for project identity, repos, mode, and workflow defaults.',
+    '- Read the latest finalized session note under `sessions/` before resuming work.',
+    '- Read `sessions/wip.md` and `sessions/handoff.md` when they exist; they are the active builder/reviewer scratch files.',
+    '- Read relevant `architecture/` and `decisions/` files before changing implementation.',
+    '',
+    '## Project Shape',
+    ...renderProjectShape(context),
+    '',
+    '## Workflow Rules',
+    '- Use `start session` for builder work and `join as reviewer` for review work.',
+    '- Use `review handoff` to ask a reviewer to inspect the active handoff.',
+    '- Use `address review` to process reviewer feedback from `sessions/wip.md` and `sessions/handoff.md`.',
+    '- Treat generated agent files as views. Update canonical VibeCompass project memory instead of editing managed regions.',
+    '',
+    '## Recent Decisions',
+    ...renderDecisionLines(context.recentDecisions),
+  ].join('\n');
+}
+
+function renderProjectShape(context) {
+  const lines = [];
+
+  if (context.description) {
+    lines.push(`- Description: ${context.description}`);
+  }
+
+  if (context.mode) {
+    lines.push(`- Mode: ${context.mode}`);
+  }
+
+  for (const repo of context.repos) {
+    lines.push(`- Repo \`${repo.id}\`: ${repo.remote}`);
+  }
+
+  for (const domain of context.domains.slice(0, 8)) {
+    const features = domain.features.map((feature) => feature.feature).join(', ');
+    lines.push(`- ${domain.domain}: ${features || 'No features recorded yet.'}`);
+  }
+
+  return lines.length > 0 ? lines : ['- No architecture domains recorded yet.'];
+}
+
+function renderDecisionLines(decisions) {
+  if (!decisions || decisions.length === 0) {
+    return ['- No decisions recorded yet.'];
+  }
+
+  return decisions.map((decision) => `- D-${String(decision.decision_id).padStart(3, '0')} — ${decision.title}`);
+}

package/src/hash.js

@@ -0,0 +1,29 @@
+import { createHash } from 'node:crypto';
+
+export function sha256Text(value) {
+  return `sha256:${createHash('sha256').update(value).digest('hex')}`;
+}
+
+export function stableStringify(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(',')}]`;
+  }
+
+  if (value && typeof value === 'object') {
+    const entries = Object.entries(value)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, entryValue]) => `${JSON.stringify(key)}:${stableStringify(entryValue)}`);
+
+    return `{${entries.join(',')}}`;
+  }
+
+  return JSON.stringify(value);
+}
+
+export function stableHash(value) {
+  return sha256Text(stableStringify(value));
+}
+
+export function localRevisionFromManifestHash(manifestHash) {
+  return `loc_${manifestHash.slice('sha256:'.length, 'sha256:'.length + 24)}`;
+}

package/src/index.js

@@ -0,0 +1,15 @@
+export { STATE_VERSION, generateStateManifest, writeStateManifest } from './manifest.js';
+export { initializeProjectMemory } from './init.js';
+export { scanProjectMemory } from './project-memory.js';
+export { startProjectSession, closeProjectSession } from './session.js';
+export {
+  syncAgentInstructionFiles,
+  getSupportedAgentFormats,
+} from './generators/agent-files/index.js';
+export {
+  loadProjectReadModel,
+  getProjectContext,
+  getFeatureContext,
+  getDecisionLog,
+  getFileContext,
+} from './read-model.js';

package/src/init.js

@@ -0,0 +1,227 @@
+import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { serializeProjectConfig } from './project-yaml.js';
+import { writeStateManifest } from './manifest.js';
+import { scaffoldInitFiles } from './scaffold.js';
+import { applyPlacementDefaults } from './setup.js';
+import { buildWorkflowMetadata } from './workflow.js';
+
+const VALID_MODES = new Set(['local-only', 'local-primary', 'hosted-only']);
+
+export async function initializeProjectMemory(options) {
+  const normalized = normalizeInitOptions(options);
+
+  await mkdir(normalized.rootDir, { recursive: true });
+  await mkdir(path.join(normalized.rootDir, 'architecture'), { recursive: true });
+  await mkdir(path.join(normalized.rootDir, 'decisions'), { recursive: true });
+  await mkdir(path.join(normalized.rootDir, 'sessions'), { recursive: true });
+
+  const projectFilePath = path.join(normalized.rootDir, 'project.yaml');
+  const gitignorePath = path.join(normalized.rootDir, '.gitignore');
+
+  await writeProjectFile(projectFilePath, normalized.projectConfig, normalized.force);
+  const gitignoreUpdated = await ensureStateIgnored(gitignorePath);
+  const manifestResult = await writeStateManifest(normalized.rootDir, {
+    generatedAt: normalized.generatedAt,
+  });
+  const scaffoldResult = await scaffoldInitFiles(normalized.bootstrap);
+
+  return {
+    rootDir: normalized.rootDir,
+    projectFilePath,
+    gitignorePath,
+    gitignoreUpdated,
+    manifestPath: manifestResult.manifestPath,
+    manifest: manifestResult.manifest,
+    scanResult: manifestResult.scanResult,
+    syncEnvVar: normalized.projectConfig.sync?.credential_env_var ?? null,
+    contextFilePath: scaffoldResult.contextFilePath,
+    scaffoldCreatedFiles: scaffoldResult.createdFiles,
+    scaffoldSkippedFiles: scaffoldResult.skippedFiles,
+  };
+}
+
+function normalizeInitOptions(options) {
+  if (!options || typeof options !== 'object') {
+    throw new Error('initializeProjectMemory requires an options object.');
+  }
+
+  const cwd = options.cwd ? path.resolve(options.cwd) : process.cwd();
+  const preparedOptions = applyPlacementDefaults(options, { cwd });
+  const rootDir = path.resolve(cwd, preparedOptions.rootDir ?? '.compass');
+  const toolingRootDir = preparedOptions.toolingRootDir
+    ? path.resolve(cwd, preparedOptions.toolingRootDir)
+    : cwd;
+
+  if (typeof preparedOptions.name !== 'string' || preparedOptions.name.trim() === '') {
+    throw new Error('init requires a non-empty project name.');
+  }
+
+  if (typeof preparedOptions.mode !== 'string' || !VALID_MODES.has(preparedOptions.mode)) {
+    throw new Error('init requires mode to be local-only, local-primary, or hosted-only.');
+  }
+
+  if (!Array.isArray(preparedOptions.repos) || preparedOptions.repos.length === 0) {
+    throw new Error('init requires at least one repo descriptor.');
+  }
+
+  const seenRepoIds = new Set();
+  const repos = preparedOptions.repos.map((repo, index) => {
+    if (!repo || typeof repo !== 'object') {
+      throw new Error(`repo ${index + 1} must be an object.`);
+    }
+
+    if (typeof repo.id !== 'string' || repo.id.trim() === '') {
+      throw new Error(`repo ${index + 1} requires a non-empty id.`);
+    }
+
+    if (seenRepoIds.has(repo.id)) {
+      throw new Error(`repo id "${repo.id}" was provided more than once.`);
+    }
+    seenRepoIds.add(repo.id);
+
+    if (typeof repo.remote !== 'string' || repo.remote.trim() === '') {
+      throw new Error(`repo "${repo.id}" requires a non-empty remote.`);
+    }
+
+    return {
+      id: repo.id,
+      remote: repo.remote,
+      ...(repo.defaultBranch ? { default_branch: repo.defaultBranch } : {}),
+    };
+  });
+
+  const syncOptions = preparedOptions.sync ?? null;
+  let sync = undefined;
+  if (syncOptions) {
+    if (preparedOptions.mode !== 'local-primary') {
+      throw new Error('sync configuration is only supported when mode is local-primary.');
+    }
+
+    const requiredFields = ['apiUrl', 'projectId', 'credentialEnvVar'];
+    const missing = requiredFields.filter((field) => typeof syncOptions[field] !== 'string' || syncOptions[field].trim() === '');
+
+    if (missing.length > 0) {
+      throw new Error(
+        `sync configuration is incomplete. Missing: ${missing.join(', ')}.`,
+      );
+    }
+
+    sync = {
+      provider: 'vibecompass',
+      api_url: syncOptions.apiUrl,
+      project_id: syncOptions.projectId,
+      credential_source: 'env',
+      credential_env_var: syncOptions.credentialEnvVar,
+    };
+  }
+
+  const projectConfig = {
+    format_version: 1,
+    name: preparedOptions.name.trim(),
+    ...(preparedOptions.slug ? { slug: preparedOptions.slug } : {}),
+    ...(preparedOptions.description ? { description: preparedOptions.description } : {}),
+    mode: preparedOptions.mode,
+    repos,
+    ...(sync ? { sync } : {}),
+    metadata: buildAgentFilesMetadata(buildWorkflowMetadata(preparedOptions.metadata, {
+      gitPublish:
+        typeof preparedOptions.closeSessionGitPublish === 'boolean'
+          ? preparedOptions.closeSessionGitPublish
+          : undefined,
+      gitRemote: preparedOptions.closeSessionGitRemote,
+    })),
+  };
+
+  const bootstrapOptions = normalizeBootstrapOptions(preparedOptions.bootstrap, {
+    rootDir,
+    toolingRootDir,
+    projectConfig,
+  });
+
+  return {
+    rootDir,
+    force: Boolean(preparedOptions.force),
+    generatedAt: preparedOptions.generatedAt,
+    projectConfig,
+    bootstrap: bootstrapOptions,
+  };
+}
+
+function buildAgentFilesMetadata(metadata) {
+  const existingAgentFiles = metadata?.agent_files && typeof metadata.agent_files === 'object'
+    ? metadata.agent_files
+    : {};
+
+  return {
+    ...metadata,
+    agent_files: {
+      claude_md: existingAgentFiles.claude_md !== false,
+      agents_md: existingAgentFiles.agents_md !== false,
+      cursor_rules: existingAgentFiles.cursor_rules !== false,
+      copilot_instructions: existingAgentFiles.copilot_instructions !== false,
+      windsurf_rules: existingAgentFiles.windsurf_rules === true,
+      gemini_md: existingAgentFiles.gemini_md === true,
+    },
+  };
+}
+
+function normalizeBootstrapOptions(bootstrap, context) {
+  const requested = bootstrap && typeof bootstrap === 'object' ? bootstrap : {};
+  const workflow = Boolean(requested.workflow || requested.claude || requested.agents);
+  const contextFilePath = path.join(context.rootDir, 'context.md');
+
+  return {
+    workflow,
+    claude: Boolean(requested.claude),
+    agents: Boolean(requested.agents),
+    rootDir: context.rootDir,
+    toolingRootDir: context.toolingRootDir,
+    projectConfig: context.projectConfig,
+    rootRelativePath: toPosix(path.relative(context.toolingRootDir, context.rootDir) || '.'),
+    contextRelativeToToolingRoot: toPosix(
+      path.relative(context.toolingRootDir, contextFilePath) || 'context.md',
+    ),
+  };
+}
+
+async function writeProjectFile(projectFilePath, projectConfig, force) {
+  if (!force && (await fileExists(projectFilePath))) {
+    throw new Error(`project.yaml already exists at ${projectFilePath}. Use --force to overwrite it.`);
+  }
+
+  const source = serializeProjectConfig(projectConfig);
+  await writeFile(projectFilePath, source, 'utf8');
+}
+
+async function ensureStateIgnored(gitignorePath) {
+  const stateEntry = 'state/';
+
+  if (!(await fileExists(gitignorePath))) {
+    await writeFile(gitignorePath, `${stateEntry}\n`, 'utf8');
+    return true;
+  }
+
+  const current = await readFile(gitignorePath, 'utf8');
+  const entries = current.split(/\r?\n/).map((line) => line.trim());
+  if (entries.includes(stateEntry)) {
+    return false;
+  }
+
+  const separator = current.length > 0 && !current.endsWith('\n') ? '\n' : '';
+  await writeFile(gitignorePath, `${current}${separator}${stateEntry}\n`, 'utf8');
+  return true;
+}
+
+async function fileExists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function toPosix(value) {
+  return value.split(path.sep).join('/');
+}

package/src/manifest.js

@@ -0,0 +1,75 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { localRevisionFromManifestHash, stableHash } from './hash.js';
+import { scanProjectMemory } from './project-memory.js';
+
+export const STATE_VERSION = 1;
+
+export function generateStateManifest(scanResult, options = {}) {
+  if (scanResult.errors.length > 0) {
+    const details = scanResult.errors.map((error) => `${error.path}: ${error.message}`).join('\n');
+    throw new Error(`Cannot generate state manifest with canonical parse errors.\n${details}`);
+  }
+
+  const generatedAt = toIsoString(options.generatedAt ?? new Date());
+  const manifestDocuments = {};
+  const manifestInventory = [];
+  let warningCount = 0;
+
+  for (const document of scanResult.documents) {
+    manifestInventory.push({
+      path: document.path,
+      kind: document.kind,
+      content_hash: document.contentHash,
+      byte_length: document.byteLength,
+    });
+
+    warningCount += document.warnings.length;
+
+    manifestDocuments[document.path] = {
+      kind: document.kind,
+      content_hash: document.contentHash,
+      byte_length: document.byteLength,
+      warnings: document.warnings,
+      extracted: document.extracted,
+    };
+  }
+
+  const manifestHash = stableHash(manifestInventory);
+  const projectExtracted = scanResult.project.extracted ?? {};
+
+  return {
+    state_version: STATE_VERSION,
+    generated_at: generatedAt,
+    canonical: {
+      format_version: projectExtracted.format_version,
+      mode: projectExtracted.mode,
+      local_root_revision: localRevisionFromManifestHash(manifestHash),
+      manifest_hash: manifestHash,
+      document_count: manifestInventory.length,
+      warning_count: warningCount,
+    },
+    documents: manifestDocuments,
+    ...(options.sync ? { sync: options.sync } : {}),
+  };
+}
+
+export async function writeStateManifest(rootDir, options = {}) {
+  const scanResult = await scanProjectMemory(rootDir);
+  const manifest = generateStateManifest(scanResult, 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,
+    scanResult,
+  };
+}
+
+function toIsoString(value) {
+  return value instanceof Date ? value.toISOString() : new Date(value).toISOString();
+}