@mycadet/assistant 0.12.11 → 0.13.0

package/src/runtime/migrations/vbundle-import-analyzer.ts

@@ -1,405 +0,0 @@
-/**
- * Analyzes a validated .vbundle archive to produce a dry-run import report.
- *
- * Given a valid .vbundle archive (already validated), this module inspects
- * its manifest and contents to determine what would happen if the bundle
- * were imported. It compares the bundle's files against the current
- * assistant state on disk and reports:
- * - Which files would be written or overwritten
- * - Size changes for each file
- * - Whether existing data would be replaced
- * - Any potential conflicts
- *
- * This is a read-only analysis — no files are written or modified.
- */
-
-import { createHash } from "node:crypto";
-import { existsSync, readFileSync, statSync } from "node:fs";
-import { join, resolve } from "node:path";
-
-import { resolveGuardianPersonaPath } from "../../prompts/persona-resolver.js";
-import { getLogger } from "../../util/logger.js";
-import {
-  isGatewayArchivePath,
-  isRetiredArchivePath,
-} from "./vbundle-import-policy.js";
-import type { ManifestType } from "./vbundle-validator.js";
-
-const log = getLogger("vbundle-import-analyzer");
-
-/**
- * Only these prompt filenames are accepted during import.
- *
- * `USER.md` is retained for backward compatibility with legacy bundles —
- * on import, its content is translated to `users/<slug>.md` at the
- * current guardian's location (see `DefaultPathResolver.resolve`).
- */
-const ALLOWED_PROMPT_FILENAMES = new Set(["IDENTITY.md", "SOUL.md", "USER.md"]);
-
-/** Archive path for the legacy guardian user persona file. */
-const LEGACY_USER_MD_ARCHIVE_PATH = "prompts/USER.md";
-
-// ---------------------------------------------------------------------------
-// Public types
-// ---------------------------------------------------------------------------
-
-type ImportAction = "create" | "overwrite" | "unchanged" | "skip";
-
-interface ImportFileReport {
-  /** Archive path (e.g. "data/db/assistant.db") */
-  path: string;
-  /** What would happen to this file on import */
-  action: ImportAction;
-  /** Size of the file in the bundle (bytes) */
-  bundle_size: number;
-  /** Size of the existing file on disk, or null if it does not exist */
-  current_size: number | null;
-  /** SHA-256 of the file in the bundle */
-  bundle_sha256: string;
-  /** SHA-256 of the existing file on disk, or null if it does not exist */
-  current_sha256: string | null;
-}
-
-interface ImportConflict {
-  code: string;
-  message: string;
-  path?: string;
-}
-
-export interface ImportDryRunReport {
-  /** Whether the import can proceed (bundle is valid and no blocking conflicts) */
-  can_import: boolean;
-  /** Summary of what would happen */
-  summary: {
-    total_files: number;
-    files_to_create: number;
-    files_to_overwrite: number;
-    files_unchanged: number;
-    files_to_skip: number;
-  };
-  /** Per-file analysis of what would change */
-  files: ImportFileReport[];
-  /** Any conflicts or warnings that might block or complicate import */
-  conflicts: ImportConflict[];
-  /** The manifest from the bundle */
-  manifest: ManifestType;
-}
-
-// ---------------------------------------------------------------------------
-// Path mapping
-// ---------------------------------------------------------------------------
-
-/**
- * Maps archive paths to their corresponding locations on disk.
- * This is the canonical mapping used during actual import (PR-5) —
- * dry-run uses the same mapping for consistency.
- */
-export interface PathResolver {
-  resolve(archivePath: string): string | null;
-}
-
-export class DefaultPathResolver implements PathResolver {
-  /**
-   * @param workspaceDir  absolute path to the workspace directory.
-   * @param hooksDir      absolute path to the hooks directory.
-   * @param guardianPersonaPathResolver  function that returns the
-   *   current guardian's persona path (`users/<slug>.md`) or `null`
-   *   when no guardian exists. Defaults to the production
-   *   `resolveGuardianPersonaPath` helper; tests inject a stub so they
-   *   don't need to mock the contact store.
-   */
-  constructor(
-    private workspaceDir?: string,
-    private hooksDir?: string,
-    private guardianPersonaPathResolver: () =>
-      | string
-      | null = resolveGuardianPersonaPath,
-  ) {}
-
-  resolve(archivePath: string): string | null {
-    // Skip credential entries — handled separately by the credential import step
-    if (archivePath.startsWith("credentials/")) {
-      return null;
-    }
-
-    // Retired-feature files (both legacy and workspace-format spellings)
-    // must never resolve to a disk target — resolving would write them
-    // back into the workspace on import. The analyzer and both importers
-    // turn the resulting null into a silent non-blocking skip.
-    if (
-      isRetiredArchivePath(archivePath) ||
-      isGatewayArchivePath(archivePath)
-    ) {
-      return null;
-    }
-
-    // New format: workspace/ prefix — maps directly into the workspace dir
-    if (archivePath.startsWith("workspace/") && this.workspaceDir) {
-      const relPath = archivePath.slice("workspace/".length);
-      if (!relPath) {
-        return null;
-      }
-      const resolved = resolve(this.workspaceDir, relPath);
-      const wsRoot = resolve(this.workspaceDir);
-      // Path traversal containment
-      if (resolved !== wsRoot && !resolved.startsWith(wsRoot + "/")) {
-        return null;
-      }
-      return resolved;
-    }
-
-    // Backward compat: old bundle formats with specific archive paths
-    if (archivePath === "data/db/assistant.db" && this.workspaceDir) {
-      return join(this.workspaceDir, "data", "db", "assistant.db");
-    }
-    if (archivePath === "config/settings.json" && this.workspaceDir) {
-      return join(this.workspaceDir, "config.json");
-    }
-    if (archivePath.startsWith("skills/") && this.workspaceDir) {
-      const resolved = resolve(
-        this.workspaceDir,
-        "skills",
-        archivePath.slice("skills/".length),
-      );
-      const skillsRoot = resolve(this.workspaceDir, "skills");
-      if (resolved !== skillsRoot && !resolved.startsWith(skillsRoot + "/")) {
-        return null;
-      }
-      return resolved;
-    }
-    if (archivePath.startsWith("prompts/") && this.workspaceDir) {
-      // Old bundles stored prompts as prompts/IDENTITY.md etc — these map
-      // to the workspace root (e.g. workspace/IDENTITY.md).
-      // Only accepted prompt filenames resolve — unknown entries are
-      // skipped so they cannot trigger workspace clearing.
-      const filename = archivePath.slice("prompts/".length);
-      if (!ALLOWED_PROMPT_FILENAMES.has(filename)) {
-        return null;
-      }
-
-      // Legacy USER.md translation: rewrite the destination to the
-      // current guardian's per-user persona file `users/<slug>.md`.
-      // Guardian-less workspaces return null → importer skips with a
-      // warning (see vbundle-importer.ts). This lookup runs against
-      // whatever DB state is live at the time of resolve — typically
-      // the pre-import workspace, which is the common upgrade case.
-      if (archivePath === LEGACY_USER_MD_ARCHIVE_PATH) {
-        const guardianPath = this.guardianPersonaPathResolver();
-        if (!guardianPath) {
-          log.warn(
-            { path: archivePath },
-            "Legacy prompts/USER.md has no guardian target — will be skipped on import",
-          );
-          return null;
-        }
-        // Containment check: guardian path must live under the workspace.
-        const wsRoot = resolve(this.workspaceDir);
-        const guardianResolved = resolve(guardianPath);
-        if (
-          guardianResolved !== wsRoot &&
-          !guardianResolved.startsWith(wsRoot + "/")
-        ) {
-          log.warn(
-            { path: archivePath, guardianPath },
-            "Guardian persona path falls outside workspace — refusing to write",
-          );
-          return null;
-        }
-        return guardianResolved;
-      }
-
-      const resolved = resolve(this.workspaceDir, filename);
-      const wsRoot = resolve(this.workspaceDir);
-      if (resolved !== wsRoot && !resolved.startsWith(wsRoot + "/")) {
-        return null;
-      }
-      return resolved;
-    }
-    if (archivePath.startsWith("hooks/") && this.hooksDir) {
-      const resolved = resolve(
-        this.hooksDir,
-        archivePath.slice("hooks/".length),
-      );
-      const hooksRoot = resolve(this.hooksDir);
-      if (resolved !== hooksRoot && !resolved.startsWith(hooksRoot + "/")) {
-        return null;
-      }
-      return resolved;
-    }
-
-    return null;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Hash helper
-// ---------------------------------------------------------------------------
-
-function sha256Hex(data: Uint8Array): string {
-  return createHash("sha256").update(data).digest("hex");
-}
-
-// ---------------------------------------------------------------------------
-// Core analyzer
-// ---------------------------------------------------------------------------
-
-interface AnalyzeImportOptions {
-  /** The parsed and validated manifest from the bundle */
-  manifest: ManifestType;
-  /** Resolves archive paths to disk paths for comparison */
-  pathResolver: PathResolver;
-}
-
-/**
- * Analyze what importing a .vbundle archive would do without modifying
- * any state. Compares bundle contents against current files on disk.
- */
-export function analyzeImport(
-  options: AnalyzeImportOptions,
-): ImportDryRunReport {
-  const { manifest, pathResolver } = options;
-  const files: ImportFileReport[] = [];
-  const conflicts: ImportConflict[] = [];
-
-  for (const fileEntry of manifest.contents) {
-    const diskPath = pathResolver.resolve(fileEntry.path);
-
-    // Credential entries are handled separately by the credential import
-    // step — skip them without flagging as unknown/conflict.
-    if (fileEntry.path.startsWith("credentials/")) {
-      files.push({
-        path: fileEntry.path,
-        action: "skip",
-        bundle_size: fileEntry.size_bytes,
-        bundle_sha256: fileEntry.sha256,
-        current_size: null,
-        current_sha256: null,
-      });
-      continue;
-    }
-
-    if (!diskPath) {
-      // Legacy `prompts/USER.md` in a guardian-less workspace has no
-      // destination to translate to. The commit-time path skips this
-      // entry with a warning rather than failing, so preflight mirrors
-      // that: emit a non-blocking skip so `can_import` stays true and
-      // upgrade paths proceed. No conflict is registered.
-      if (fileEntry.path === LEGACY_USER_MD_ARCHIVE_PATH) {
-        log.warn(
-          { path: fileEntry.path },
-          "Legacy prompts/USER.md has no guardian target — will be skipped on import",
-        );
-        files.push({
-          path: fileEntry.path,
-          action: "skip",
-          bundle_size: fileEntry.size_bytes,
-          bundle_sha256: fileEntry.sha256,
-          current_size: null,
-          current_sha256: null,
-        });
-        continue;
-      }
-
-      // Retired-feature file from a legacy bundle: nothing consumes it
-      // anymore, so drop it silently instead of blocking the restore with
-      // an UNKNOWN_ARCHIVE_PATH conflict.
-      if (
-        isRetiredArchivePath(fileEntry.path) ||
-        isGatewayArchivePath(fileEntry.path)
-      ) {
-        log.info(
-          { path: fileEntry.path },
-          "Archive path is not workspace data — will be skipped on import",
-        );
-        files.push({
-          path: fileEntry.path,
-          action: "skip",
-          bundle_size: fileEntry.size_bytes,
-          bundle_sha256: fileEntry.sha256,
-          current_size: null,
-          current_sha256: null,
-        });
-        continue;
-      }
-
-      // Unknown archive path — would have nowhere to write
-      conflicts.push({
-        code: "UNKNOWN_ARCHIVE_PATH",
-        message: `Archive path "${fileEntry.path}" has no known disk target — it would be skipped during import`,
-        path: fileEntry.path,
-      });
-      files.push({
-        path: fileEntry.path,
-        action: "skip",
-        bundle_size: fileEntry.size_bytes,
-        bundle_sha256: fileEntry.sha256,
-        current_size: null,
-        current_sha256: null,
-      });
-      continue;
-    }
-
-    let currentSize: number | null = null;
-    let currentSha256: string | null = null;
-    let action: ImportAction;
-
-    if (existsSync(diskPath)) {
-      try {
-        const stat = statSync(diskPath);
-        currentSize = stat.size;
-        const diskData = new Uint8Array(readFileSync(diskPath));
-        currentSha256 = sha256Hex(diskData);
-      } catch {
-        // If we cannot read the file, treat it as a conflict
-        conflicts.push({
-          code: "UNREADABLE_EXISTING_FILE",
-          message: `Cannot read existing file at disk path for "${fileEntry.path}" — import would overwrite it`,
-          path: fileEntry.path,
-        });
-        action = "overwrite";
-        files.push({
-          path: fileEntry.path,
-          action,
-          bundle_size: fileEntry.size_bytes,
-          bundle_sha256: fileEntry.sha256,
-          current_size: currentSize,
-          current_sha256: currentSha256,
-        });
-        continue;
-      }
-
-      if (currentSha256 === fileEntry.sha256) {
-        action = "unchanged";
-      } else {
-        action = "overwrite";
-      }
-    } else {
-      action = "create";
-    }
-
-    files.push({
-      path: fileEntry.path,
-      action,
-      bundle_size: fileEntry.size_bytes,
-      bundle_sha256: fileEntry.sha256,
-      current_size: currentSize,
-      current_sha256: currentSha256,
-    });
-  }
-
-  const summary = {
-    total_files: files.length,
-    files_to_create: files.filter((f) => f.action === "create").length,
-    files_to_overwrite: files.filter((f) => f.action === "overwrite").length,
-    files_unchanged: files.filter((f) => f.action === "unchanged").length,
-    files_to_skip: files.filter((f) => f.action === "skip").length,
-  };
-
-  return {
-    can_import: conflicts.length === 0,
-    summary,
-    files,
-    conflicts,
-    manifest,
-  };
-}

package/src/runtime/migrations/vbundle-import-policy.ts

@@ -1,241 +0,0 @@
-/**
- * Shared invariants and predicate functions consumed by both the buffer-
- * based `commitImport` and the streaming `streamCommitImport`. These
- * decisions must stay in lockstep across both importers — moving them
- * here removes the parallel-implementation skew risk that would otherwise
- * grow as either importer evolves.
- *
- * Pure: no `node:fs`, no I/O, no async. Functions over strings + manifest
- * data shapes only.
- */
-
-export const LEGACY_USER_MD_ARCHIVE_PATH = "prompts/USER.md";
-
-export const CONFIG_ARCHIVE_PATHS: ReadonlySet<string> = new Set([
-  "workspace/config.json",
-  "config/settings.json",
-]);
-
-export const CREDENTIAL_METADATA_ARCHIVE_PATH =
-  "workspace/data/credentials/metadata.json";
-
-export const WORKSPACE_PRESERVE_PATHS: readonly string[] = [
-  "embedding-models",
-  "deprecated",
-  "data/db",
-  "data/qdrant",
-];
-
-export function isWorkspaceNamespacedArchivePath(archivePath: string): boolean {
-  return archivePath.startsWith("workspace/");
-}
-
-export function isLegacyPersonaArchivePath(archivePath: string): boolean {
-  return archivePath === LEGACY_USER_MD_ARCHIVE_PATH;
-}
-
-/**
- * Archive paths for retired features. Bundles exported while those features
- * existed still contain these entries; preflight and both importers must
- * treat them as silent non-blocking skips (no conflict, no warning) so old
- * backups stay restorable without noise, and the files are never written
- * back to the workspace.
- *
- * `UPDATES.md` carried the retired update-bulletin release notes. Legacy
- * bundles archived it as `prompts/UPDATES.md`; current-format bundles walk
- * the workspace dir, so it appears as `workspace/UPDATES.md`. Both spellings
- * must be retired — `DefaultPathResolver.resolve()` short-circuits them to
- * `null` before any prefix handling so the workspace-format entry cannot
- * resolve normally and recreate the file on import.
- */
-export const RETIRED_ARCHIVE_PATHS: ReadonlySet<string> = new Set([
-  "prompts/UPDATES.md",
-  "workspace/UPDATES.md",
-]);
-
-export function isRetiredArchivePath(archivePath: string): boolean {
-  return RETIRED_ARCHIVE_PATHS.has(archivePath);
-}
-
-/**
- * `gateway/` holds the gateway's own database and logs, added by the debug
- * export profile for Cadet staff to open on a debug clone. It is never
- * part of a workspace, so preflight and both importers skip it silently,
- * the same way they skip retired paths.
- */
-export function isGatewayArchivePath(archivePath: string): boolean {
-  return archivePath.startsWith("gateway/");
-}
-
-export function isConfigArchivePath(archivePath: string): boolean {
-  return CONFIG_ARCHIVE_PATHS.has(archivePath);
-}
-
-export function isCredentialMetadataArchivePath(archivePath: string): boolean {
-  return archivePath === CREDENTIAL_METADATA_ARCHIVE_PATH;
-}
-
-/**
- * Partition `WORKSPACE_PRESERVE_PATHS` into the two skip sets the buffer
- * importer's selective-clear loop consumes:
- *
- * - `topLevelSkipDirs`: single-segment preserve-paths (e.g. "embedding-models").
- * - `dataSubdirSkipDirs`: second segment of `data/<x>` preserve-paths
- *   (e.g. "db" for "data/db").
- *
- * Stays in sync with WORKSPACE_PRESERVE_PATHS automatically — adding a
- * new entry of either shape doesn't require touching the buffer importer.
- * Multi-segment paths outside the `data/` subtree are intentionally
- * unsupported here; the buffer importer's walk doesn't recurse into
- * arbitrary subdirs. If a future preserve-path needs deeper coverage,
- * widen this helper and the buffer importer's walk together.
- */
-export function partitionWorkspacePreserveSkipDirs(): {
-  topLevelSkipDirs: ReadonlySet<string>;
-  dataSubdirSkipDirs: ReadonlySet<string>;
-} {
-  const topLevelSkipDirs = new Set<string>();
-  const dataSubdirSkipDirs = new Set<string>();
-  for (const rel of WORKSPACE_PRESERVE_PATHS) {
-    const parts = rel.split("/");
-    if (parts.length === 1) {
-      topLevelSkipDirs.add(parts[0]!);
-    } else if (parts.length === 2 && parts[0] === "data") {
-      dataSubdirSkipDirs.add(parts[1]!);
-    }
-  }
-  return { topLevelSkipDirs, dataSubdirSkipDirs };
-}
-
-export const LEGACY_RUNTIME_VERSION_SENTINEL = "0.0.0-legacy";
-
-type SemverTriple = readonly [number, number, number];
-
-function parseSemverTriple(version: string): SemverTriple | null {
-  // Strip optional prerelease/build suffix ("-foo", "+sha"). We treat
-  // "0.7.1-staging.1" as equal-to-release "0.7.1" for gating purposes.
-  // The cloud-side check uses packaging.version.Version, which sorts
-  // prereleases BEFORE the corresponding release; matching that exactly
-  // would require a fuller parser — for runtime-side defense-in-depth
-  // this conservative read is sufficient (matches release of the same
-  // base triple).
-  const base = version.split(/[-+]/)[0] ?? version;
-  const parts = base.split(".");
-  if (parts.length !== 3) {
-    return null;
-  }
-  // Reject components with anything other than ASCII digits to avoid
-  // Number.parseInt's lenient prefix-parse — e.g. "0.8.0foo" would
-  // otherwise coerce to [0, 8, 0] and silently pass the gate, defeating
-  // the parse-failure-fail-open contract in evaluateRuntimeCompatibility.
-  // Leading zeros (e.g. "01.02.03") are intentionally accepted since
-  // they round-trip to the same numeric triple as the un-padded form.
-  if (!parts.every((p) => /^\d+$/.test(p))) {
-    return null;
-  }
-  const [maj, min, pat] = parts.map((p) => Number(p));
-  if (![maj, min, pat].every((n) => Number.isFinite(n) && n >= 0)) {
-    return null;
-  }
-  return [maj!, min!, pat!] as const;
-}
-
-// -1 if a < b, 0 if equal, +1 if a > b. Returns null on parse failure.
-export function compareSemver(a: string, b: string): -1 | 0 | 1 | null {
-  const ta = parseSemverTriple(a);
-  const tb = parseSemverTriple(b);
-  if (!ta || !tb) {
-    return null;
-  }
-  for (let i = 0; i < 3; i++) {
-    if (ta[i]! < tb[i]!) {
-      return -1;
-    }
-    if (ta[i]! > tb[i]!) {
-      return +1;
-    }
-  }
-  return 0;
-}
-
-export interface RuntimeCompatibility {
-  min_runtime_version: string;
-  max_runtime_version: string | null;
-}
-
-export type RuntimeCompatibilityResult =
-  | { ok: true }
-  | {
-      ok: false;
-      reason: "version_incompatible";
-      bundle_compat: RuntimeCompatibility;
-      runtime_version: string;
-    };
-
-export function formatRuntimeCompatibilityMessage(
-  compat: RuntimeCompatibility,
-  runtimeVersion: string,
-): string {
-  const range = compat.max_runtime_version
-    ? `${compat.min_runtime_version}–${compat.max_runtime_version}`
-    : `${compat.min_runtime_version}+`;
-  return `Cannot import: bundle requires runtime ${range}, but this runtime is ${runtimeVersion}. Update your runtime before importing.`;
-}
-
-/**
- * Whether `version` names a runtime built from a source checkout: the
- * `<pkg.version>-local.<timestamp>.<sha>` `APP_VERSION` that the cloud
- * repo's `vel up` stamps on the assistant images it builds for its local
- * minikube cluster. The triple is the checkout's package.json version,
- * which only moves on release cuts, so it says nothing about whether the
- * checkout is newer or older than a release. A CLI hatch from a checkout
- * without an explicit `APP_VERSION` runs as the plain package version and
- * is not covered.
- */
-export function isLocalDevRuntimeVersion(version: string): boolean {
-  return /^\d+\.\d+\.\d+-local\./.test(version);
-}
-
-export function evaluateRuntimeCompatibility(
-  compat: RuntimeCompatibility,
-  runtimeVersion: string,
-): RuntimeCompatibilityResult {
-  if (compat.min_runtime_version === LEGACY_RUNTIME_VERSION_SENTINEL) {
-    return { ok: true };
-  }
-  // A local dev build skips the minimum bound, like an unparsable version
-  // does below: its triple is not comparable to release versions (see
-  // isLocalDevRuntimeVersion), so "runtime older than the bundle" cannot be
-  // decided from it. The maximum bound still applies: it is an explicit
-  // ceiling the bundle's producer recorded, and a local triple above it is
-  // as good a signal as any release's.
-  if (!isLocalDevRuntimeVersion(runtimeVersion)) {
-    const minCmp = compareSemver(runtimeVersion, compat.min_runtime_version);
-    if (minCmp === null) {
-      return { ok: true };
-    }
-    if (minCmp < 0) {
-      return {
-        ok: false,
-        reason: "version_incompatible",
-        bundle_compat: compat,
-        runtime_version: runtimeVersion,
-      };
-    }
-  }
-  if (compat.max_runtime_version !== null) {
-    const maxCmp = compareSemver(runtimeVersion, compat.max_runtime_version);
-    if (maxCmp === null) {
-      return { ok: true };
-    }
-    if (maxCmp > 0) {
-      return {
-        ok: false,
-        reason: "version_incompatible",
-        bundle_compat: compat,
-        runtime_version: runtimeVersion,
-      };
-    }
-  }
-  return { ok: true };
-}