@vibecompass/vibecompass 0.7.0 → 0.9.0

package/src/sync-binding.js

@@ -0,0 +1,307 @@
+const TARGET_NAME_PATTERN = /^[a-z0-9][a-z0-9_-]*$/;
+
+function normalizeBindingFields(source) {
+  const apiUrl = typeof source?.api_url === 'string' && source.api_url.trim() !== ''
+    ? source.api_url
+    : null;
+  const projectId = typeof source?.project_id === 'string' && source.project_id.trim() !== ''
+    ? source.project_id
+    : null;
+  const credentialEnvVar = typeof source?.credential_env_var === 'string' && source.credential_env_var.trim() !== ''
+    ? source.credential_env_var
+    : null;
+
+  if (!apiUrl || !projectId || !credentialEnvVar) {
+    return null;
+  }
+
+  return { apiUrl, projectId, credentialEnvVar };
+}
+
+export function assertValidSyncTargetName(name) {
+  if (typeof name !== 'string' || !TARGET_NAME_PATTERN.test(name)) {
+    throw new Error(
+      `Sync target name "${name}" is invalid. Use lowercase letters, digits, hyphens, or underscores (e.g. dev, prod).`,
+    );
+  }
+  return name;
+}
+
+export function readSyncTargets(projectConfig) {
+  const sync = projectConfig?.sync;
+  if (!sync || typeof sync !== 'object') {
+    return null;
+  }
+
+  const targets = sync.targets && typeof sync.targets === 'object' ? sync.targets : null;
+  if (!targets || Object.keys(targets).length === 0) {
+    return null;
+  }
+
+  const defaultTarget = typeof sync.default_target === 'string' && targets[sync.default_target]
+    ? sync.default_target
+    : null;
+
+  return { defaultTarget, targets };
+}
+
+/**
+ * Resolves the effective hosted sync binding for a command (D-236).
+ *
+ * Resolution order: explicit target name -> sync.default_target -> legacy
+ * flat sync fields. Returns null when no complete binding exists. Throws on
+ * an explicitly requested target that is unknown or incomplete, because a
+ * typo must never silently fall back to a different environment.
+ */
+export function resolveSyncBinding(projectConfig, targetName) {
+  const sync = projectConfig?.sync;
+  if (!sync || typeof sync !== 'object') {
+    if (targetName) {
+      throw new Error(
+        `--sync-target ${targetName} requires a sync section in project.yaml. Run "vibecompass connect-hosted --target ${targetName}" first.`,
+      );
+    }
+    return null;
+  }
+
+  const named = readSyncTargets(projectConfig);
+
+  if (targetName) {
+    const target = named?.targets?.[targetName];
+    if (!target || typeof target !== 'object') {
+      const available = named ? Object.keys(named.targets) : [];
+      throw new Error(
+        `Unknown sync target "${targetName}". ${
+          available.length > 0
+            ? `Available targets: ${available.join(', ')}.`
+            : 'No named sync targets are defined in project.yaml; run "vibecompass connect-hosted --target <name>" to add one.'
+        }`,
+      );
+    }
+
+    const fields = normalizeBindingFields(target);
+    if (!fields) {
+      throw new Error(
+        `Sync target "${targetName}" is incomplete. It must define api_url, project_id, and credential_env_var.`,
+      );
+    }
+
+    return { target: targetName, isDefault: targetName === named.defaultTarget, ...fields };
+  }
+
+  if (named?.defaultTarget) {
+    const fields = normalizeBindingFields(named.targets[named.defaultTarget]);
+    if (fields) {
+      return { target: named.defaultTarget, isDefault: true, ...fields };
+    }
+  }
+
+  const flat = normalizeBindingFields(sync);
+  return flat ? { target: null, isDefault: true, ...flat } : null;
+}
+
+const CURSOR_FIELDS = [
+  'last_successful_remote_revision',
+  'last_successful_local_root_revision',
+  'last_successful_manifest_hash',
+  'last_sync_direction',
+  'last_sync_at',
+  'pending_previews',
+];
+
+function pickCursorFields(source) {
+  const cursor = {};
+  for (const field of CURSOR_FIELDS) {
+    if (source?.[field] !== undefined) {
+      cursor[field] = source[field];
+    }
+  }
+  return cursor;
+}
+
+/**
+ * Reads the sync cursor for the resolved binding (D-237). Legacy flat
+ * bindings keep using the flat manifest.sync fields. Named targets read only
+ * their own cursor, and only when its recorded api_url/project_id identity
+ * matches the current binding — otherwise the cursor is treated as absent so
+ * a stale or cross-environment cursor can never become another environment's
+ * baseline.
+ */
+export function readSyncCursor(manifestSync, binding) {
+  if (!manifestSync || typeof manifestSync !== 'object') {
+    return {};
+  }
+
+  if (!binding?.target) {
+    return pickCursorFields(manifestSync);
+  }
+
+  const cursor = manifestSync.targets?.[binding.target];
+  if (
+    !cursor ||
+    typeof cursor !== 'object' ||
+    cursor.api_url !== binding.apiUrl ||
+    cursor.project_id !== binding.projectId
+  ) {
+    return {};
+  }
+
+  return pickCursorFields(cursor);
+}
+
+/**
+ * Builds the next manifest.sync value after a sync operation for the resolved
+ * binding (D-237). Named targets write into manifest.sync.targets.<name>
+ * (stamped with their api_url/project_id identity); when the binding is the
+ * default target, the flat fields mirror the same cursor so ≤0.7.0 CLIs stay
+ * correct on the default environment. Legacy flat bindings keep writing the
+ * flat fields only.
+ */
+export function buildSyncStateWithCursor(manifestSync, binding, cursor) {
+  const existing = manifestSync && typeof manifestSync === 'object' ? manifestSync : {};
+  const cursorFields = pickCursorFields(cursor);
+
+  if (!binding?.target) {
+    return { ...existing, ...cursorFields };
+  }
+
+  const targets = {
+    ...(existing.targets && typeof existing.targets === 'object' ? existing.targets : {}),
+    [binding.target]: {
+      api_url: binding.apiUrl,
+      project_id: binding.projectId,
+      ...cursorFields,
+    },
+  };
+
+  return {
+    ...existing,
+    ...(binding.isDefault ? cursorFields : {}),
+    targets,
+  };
+}
+
+/**
+ * Migrates a legacy flat manifest cursor into a named target's cursor slot
+ * (D-237). Only applies when the new target's binding values match the flat
+ * binding the cursor was written against, the target has no cursor yet, and
+ * a flat cursor actually exists. Returns the next manifest.sync value, or
+ * null when nothing should change.
+ */
+export function migrateFlatCursorToTarget(manifestSync, targetName, bindingFields) {
+  const existing = manifestSync && typeof manifestSync === 'object' ? manifestSync : {};
+  const targets = existing.targets && typeof existing.targets === 'object' ? existing.targets : {};
+  const flatCursor = pickCursorFields(existing);
+
+  if (targets[targetName] || Object.keys(flatCursor).length === 0) {
+    return null;
+  }
+
+  return {
+    ...existing,
+    targets: {
+      ...targets,
+      [targetName]: {
+        api_url: bindingFields.apiUrl,
+        project_id: bindingFields.projectId,
+        ...flatCursor,
+      },
+    },
+  };
+}
+
+/**
+ * Reconciles manifest cursor state after connect-hosted (re)binds a named
+ * target (D-237). Handles, in order:
+ * 1. first flat→named conversion with matching values: migrate the flat
+ *    cursor into the target's slot;
+ * 2. rebinding an existing target to a different api_url/project_id: drop its
+ *    now-wrong cursor;
+ * 3. when the (re)bound target is the default: re-mirror the flat cursor from
+ *    the target's identity-matching cursor, or clear it — so an older CLI can
+ *    never combine the new flat binding with a previous environment's cursor.
+ * Returns the next manifest.sync value, or null when nothing changes.
+ */
+export function reconcileCursorsAfterConnect(manifestSync, targetName, bindingFields, options = {}) {
+  const existing = manifestSync && typeof manifestSync === 'object' ? manifestSync : {};
+  let next = existing;
+  let changed = false;
+
+  if (options.isFirstConversion && options.flatBindingMatches) {
+    const migrated = migrateFlatCursorToTarget(next, targetName, bindingFields);
+    if (migrated) {
+      next = migrated;
+      changed = true;
+    }
+  }
+
+  const targetCursor = next.targets?.[targetName];
+  if (
+    targetCursor &&
+    typeof targetCursor === 'object' &&
+    (targetCursor.api_url !== bindingFields.apiUrl ||
+      targetCursor.project_id !== bindingFields.projectId)
+  ) {
+    const targets = { ...next.targets };
+    delete targets[targetName];
+    next = { ...next, targets };
+    changed = true;
+  }
+
+  if (options.isDefault) {
+    const mirrored = mirrorTargetCursorToFlat(next, targetName, bindingFields);
+    if (JSON.stringify(mirrored) !== JSON.stringify(next)) {
+      next = mirrored;
+      changed = true;
+    }
+  }
+
+  return changed ? next : null;
+}
+
+/**
+ * Re-mirrors the flat manifest cursor from a (new default) target's cursor
+ * (D-237). When the target has no identity-matching cursor, the flat cursor
+ * fields are cleared so an older CLI cannot reuse the previous default's
+ * cursor against the new default environment.
+ */
+export function mirrorTargetCursorToFlat(manifestSync, targetName, bindingFields) {
+  const existing = manifestSync && typeof manifestSync === 'object' ? manifestSync : {};
+  const base = {};
+  for (const [key, value] of Object.entries(existing)) {
+    if (!CURSOR_FIELDS.includes(key)) {
+      base[key] = value;
+    }
+  }
+
+  const target = existing.targets?.[targetName];
+  const identityMatches =
+    target &&
+    typeof target === 'object' &&
+    target.api_url === bindingFields.apiUrl &&
+    target.project_id === bindingFields.projectId;
+
+  return identityMatches ? { ...base, ...pickCursorFields(target) } : base;
+}
+
+/**
+ * Builds the project.yaml sync section for a set of named targets. The flat
+ * fields always mirror the default target so older CLIs that only read the
+ * flat binding keep working against the default environment.
+ */
+export function buildSyncSectionWithTargets(targets, defaultTarget) {
+  const defaultFields = normalizeBindingFields(targets[defaultTarget]);
+  if (!defaultFields) {
+    throw new Error(`Default sync target "${defaultTarget}" is incomplete.`);
+  }
+
+  return {
+    provider: 'vibecompass',
+    api_url: defaultFields.apiUrl,
+    project_id: defaultFields.projectId,
+    credential_source: 'env',
+    credential_env_var: defaultFields.credentialEnvVar,
+    default_target: defaultTarget,
+    targets,
+  };
+}

package/src/sync.js

@@ -3,6 +3,11 @@ import path from 'node:path';
 import { sha256Text } from './hash.js';
 import { writeStateManifest } from './manifest.js';
 import { parseSimpleYaml } from './simple-yaml.js';
+import {
+  buildSyncStateWithCursor,
+  readSyncCursor,
+  resolveSyncBinding,
+} from './sync-binding.js';
 
 const DEFAULT_EXPORT_PATH = 'state/pull-export.json';
 
@@ -14,7 +19,8 @@ export async function pushProjectMemory(options = {}, environment = {}) {
   });
   const manifest = manifestResult.manifest;
   const documents = await readPushDocuments(context.rootDir, manifest.documents);
-  const baseRemoteRevisionId = normalizeUuid(manifest.sync?.last_successful_remote_revision);
+  const cursor = readSyncCursor(manifest.sync, context.binding);
+  const baseRemoteRevisionId = normalizeUuid(cursor.last_successful_remote_revision);
   const body = {
     ...(baseRemoteRevisionId ? { base_remote_revision_id: baseRemoteRevisionId } : {}),
     local_root_revision: manifest.canonical.local_root_revision,
@@ -25,15 +31,15 @@ export async function pushProjectMemory(options = {}, environment = {}) {
 
   const response = await postJson(context, 'push', body);
   const now = new Date().toISOString();
-  const sync = {
-    ...(manifest.sync ?? {}),
+  const sync = buildSyncStateWithCursor(manifest.sync, context.binding, {
+    ...cursor,
     last_successful_remote_revision: response.remote_revision_id,
     last_successful_local_root_revision: manifest.canonical.local_root_revision,
     last_successful_manifest_hash: manifest.canonical.manifest_hash,
     last_sync_direction: 'push',
     last_sync_at: now,
     pending_previews: [],
-  };
+  });
   const updatedManifest = await writeStateManifest(context.rootDir, { sync });
 
   return {
@@ -55,10 +61,11 @@ export async function pullPreviewProjectMemory(options = {}, environment = {}) {
     sync: existingManifest?.sync,
   });
   const manifest = manifestResult.manifest;
+  const cursor = readSyncCursor(manifest.sync, context.binding);
 
   const response = await postJson(context, 'pull-preview', {
     state_version: manifest.state_version,
-    base_remote_revision_id: normalizeUuid(manifest.sync?.last_successful_remote_revision),
+    base_remote_revision_id: normalizeUuid(cursor.last_successful_remote_revision),
     local_root_revision: manifest.canonical.local_root_revision,
     local_manifest_hash: manifest.canonical.manifest_hash,
     local_documents: buildLocalDocumentSummaries(manifest.documents),
@@ -81,13 +88,13 @@ export async function pullPreviewProjectMemory(options = {}, environment = {}) {
     created_at: response.created_at ?? new Date().toISOString(),
     expires_at: response.expires_at,
   };
-  const sync = {
-    ...(manifest.sync ?? {}),
+  const sync = buildSyncStateWithCursor(manifest.sync, context.binding, {
+    ...cursor,
     pending_previews: [
-      ...(Array.isArray(manifest.sync?.pending_previews) ? manifest.sync.pending_previews : []),
+      ...(Array.isArray(cursor.pending_previews) ? cursor.pending_previews : []),
       previewRecord,
     ].slice(-5),
-  };
+  });
   const updatedManifest = await writeStateManifest(context.rootDir, { sync });
 
   return {
@@ -105,7 +112,7 @@ export async function pullPreviewProjectMemory(options = {}, environment = {}) {
 export async function pullExportProjectMemory(options = {}, environment = {}) {
   const context = await loadSyncContext(options, environment);
   const manifest = await readRequiredManifest(context.manifestPath);
-  const preview = resolvePreview(manifest, options.previewToken);
+  const preview = resolvePreview(manifest, options.previewToken, context.binding);
   const proposalIds = options.proposalIds?.length
     ? options.proposalIds
     : preview.available_proposal_ids ?? [];
@@ -200,18 +207,15 @@ async function loadSyncContext(options, environment) {
   if (project.mode !== 'local-primary') {
     throw new Error('Hosted sync commands require project.yaml mode: local-primary.');
   }
-  if (
-    !project.sync ||
-    typeof project.sync.api_url !== 'string' ||
-    typeof project.sync.project_id !== 'string' ||
-    typeof project.sync.credential_env_var !== 'string'
-  ) {
-    throw new Error('Hosted sync commands require sync.api_url, sync.project_id, and sync.credential_env_var in project.yaml.');
+
+  const binding = resolveSyncBinding(project, options.syncTarget ?? null);
+  if (!binding) {
+    throw new Error('Hosted sync commands require sync.api_url, sync.project_id, and sync.credential_env_var in project.yaml (or a named target under sync.targets).');
   }
 
-  const credential = normalizeOptionalString((environment.env ?? process.env)[project.sync.credential_env_var]);
+  const credential = normalizeOptionalString((environment.env ?? process.env)[binding.credentialEnvVar]);
   if (!credential) {
-    throw new Error(`Hosted sync command requires ${project.sync.credential_env_var}.`);
+    throw new Error(`Hosted sync command requires ${binding.credentialEnvVar}.`);
   }
 
   const fetchImpl = environment.runtime?.fetch ?? globalThis.fetch;
@@ -225,8 +229,10 @@ async function loadSyncContext(options, environment) {
     manifestPath,
     fetch: fetchImpl,
     credential,
-    apiUrl: project.sync.api_url,
-    projectId: project.sync.project_id,
+    apiUrl: binding.apiUrl,
+    projectId: binding.projectId,
+    syncTarget: binding.target,
+    binding,
   };
 }
 
@@ -308,9 +314,10 @@ function buildLocalDocumentExtractedSummary(kind, extracted = {}) {
   return {};
 }
 
-function resolvePreview(manifest, previewToken) {
-  const previews = Array.isArray(manifest.sync?.pending_previews)
-    ? manifest.sync.pending_previews
+function resolvePreview(manifest, previewToken, binding) {
+  const cursor = readSyncCursor(manifest.sync, binding);
+  const previews = Array.isArray(cursor.pending_previews)
+    ? cursor.pending_previews
     : [];
   if (previewToken) {
     const match = previews.find((preview) => preview.preview_token === previewToken);

package/src/workflows/registry.js

@@ -99,7 +99,7 @@ When the user says \`docs review\`, run this workflow inside the current Claude
 
 ## Goal
 
-Turn starter project memory into evidence-backed architecture docs under \`architecture/<domain>/<feature>/<component>.md\`, a projected coverage plan, and optional accepted decision recommendations.
+Turn starter project memory into evidence-backed architecture docs under \`architecture/<domain>/<feature>/<component>.md\`, a projected coverage plan, a journey-aware project map, and optional accepted decision recommendations.
 
 ## Steps
 
@@ -109,8 +109,8 @@ Turn starter project memory into evidence-backed architecture docs under \`archi
    - produce a coverage plan before reading broad source bodies
    - read targeted source files only when the coverage plan needs evidence
 3. Run \`vibecompass docs-review --guided --llm <tool-name> --model <model-name>\` to record the review marker and print the canonical docs-review contract. Use the current AI tool name and model when known.
-4. Present the evidence inventory, coverage plan, proposed architecture docs, blindspots, token-budget risks, and any decision candidates before generating accepted output.
-5. Draft only output the user accepts. The accepted plan must be fenced as \`vibecompass-coverage-plan version=1\`. Accepted architecture docs must be fenced as \`vibecompass-architecture-doc path=architecture/domain/feature/component.md\` blocks and must include required frontmatter: \`domain\`, \`feature\`, \`component\`, and \`status\`. Accepted local decisions may be fenced as \`vibecompass-decision-recommendation target=decisions/domain.md\` blocks without D-numbers.
+4. Present the evidence inventory, coverage plan, user journey, project/system map, proposed architecture docs, blindspots, token-budget risks, and any decision candidates before generating accepted output.
+5. Draft only output the user accepts. The accepted plan must be fenced as \`vibecompass-coverage-plan version=1\`. Accepted architecture docs must be fenced as \`vibecompass-architecture-doc path=architecture/domain/feature/component.md\` blocks and must include required frontmatter: \`domain\`, \`feature\`, \`component\`, and \`status\`. The accepted \`architecture/overview/project-shape.md\` doc should include exactly one \`vibecompass-project-map version=1\` JSON block with journey-facing features, entry points, and evidence-backed relationships. Accepted local decisions may be fenced as \`vibecompass-decision-recommendation target=decisions/domain.md\` blocks without D-numbers.
 6. Keep each generated architecture doc focused and retrieval-oriented. Soft budget: under 12000 bytes per doc unless the extra detail is necessary and called out in review metadata or retrieval guidance.
 7. Write the accepted fenced blocks to \`${outputPath}\`.
 8. Run \`vibecompass docs-review --apply-output\` to validate and apply the accepted blocks. If accepted docs were written manually outside the output file, run \`vibecompass docs-review --complete\` after confirming the marker should be completed.