@cleocode/core 2026.4.11 → 2026.4.13

package/src/store/regenerators.ts

@@ -0,0 +1,243 @@
+/**
+ * Dry-run JSON file generators for the three CLEO runtime state files.
+ *
+ * Returns the content that `cleo init` WOULD write on the target machine,
+ * capturing machine-local state (projectRoot, hostname, timestamps) without
+ * touching the filesystem.
+ *
+ * Used by T354's A/B regenerate-and-compare engine (ADR-038 §10): the "A"
+ * side of the comparison is always what a fresh init would produce locally.
+ *
+ * @task T352
+ * @epic T311
+ * @why ADR-038 §10 — A/B regenerate-and-compare needs the "A" side: what the
+ *      JSON files would look like if freshly initialized on the target machine.
+ *      Captures machine-local state (projectRoot, hostname, timestamps).
+ * @what Pure dry-run versions of the cleo init JSON file generators.
+ *
+ * DRIFT WARNING: These generators mirror the logic inside:
+ *   - packages/core/src/scaffold.ts :: createDefaultConfig()           (config.json)
+ *   - packages/core/src/scaffold.ts :: ensureProjectInfo()              (project-info.json)
+ *   - packages/core/src/store/project-detect.ts :: detectProjectType() (project-context.json)
+ *
+ * If any of those functions change the shape or defaults of their generated
+ * files, this module MUST be updated to match. There is no runtime link — the
+ * similarity is maintained manually.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { generateProjectHash } from '../nexus/hash.js';
+import { createDefaultConfig, getCleoVersion } from '../scaffold.js';
+import { getSchemaVersion } from '../schema-management.js';
+import { detectProjectType, type ProjectContext } from './project-detect.js';
+
+/**
+ * Mirror of SQLITE_SCHEMA_VERSION from ./sqlite.ts.
+ *
+ * We do not import sqlite.ts here to avoid its module-level side effects
+ * (node:sqlite bootstrap via createRequire). If the canonical value in
+ * sqlite.ts changes, update this constant to match.
+ *
+ * Canonical source: packages/core/src/store/sqlite.ts :: SQLITE_SCHEMA_VERSION
+ */
+const SQLITE_SCHEMA_VERSION_MIRROR = '2.0.0';
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+/**
+ * The result of a dry-run file generator.
+ *
+ * @typeParam T - The shape of the generated file content. Defaults to
+ *   `Record<string, unknown>` when the exact shape is not statically known.
+ *
+ * @task T352
+ * @epic T311
+ */
+export interface RegeneratedFile<T = Record<string, unknown>> {
+  /** The filename that `cleo init` would write. */
+  filename: 'config.json' | 'project-info.json' | 'project-context.json';
+  /** The parsed content that would be written to disk. */
+  content: T;
+}
+
+// ── Internal helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Detect whether the given `projectRoot` is the CLEO contributor project.
+ * Mirrors the private `isCleoContributorProject()` helper in scaffold.ts.
+ *
+ * Returns `true` only if all three fingerprints match:
+ *   1. `src/dispatch/` directory exists
+ *   2. `src/core/` directory exists
+ *   3. `package.json` identifies as `@cleocode/cleo`
+ */
+function isContributorProject(projectRoot: string): boolean {
+  const at = (p: string) => existsSync(join(projectRoot, p));
+  if (!at('src/dispatch') || !at('src/core')) return false;
+  try {
+    const pkg = JSON.parse(readFileSync(join(projectRoot, 'package.json'), 'utf-8')) as {
+      name?: string;
+    };
+    return pkg.name === '@cleocode/cleo';
+  } catch {
+    return false;
+  }
+}
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Returns the `config.json` content that `cleo init` would write for
+ * `projectRoot` on the current machine.
+ *
+ * PURE — no disk writes. Reads package.json only to detect the contributor
+ * project fingerprint (same as `ensureConfig` in scaffold.ts).
+ *
+ * Mirrors: `packages/core/src/scaffold.ts :: ensureConfig()` and
+ *          `packages/core/src/scaffold.ts :: createDefaultConfig()`.
+ *
+ * DRIFT: if `createDefaultConfig()` adds new keys, regenerateConfigJson must
+ * be updated to reflect the same structure. The coupling is intentional but
+ * manual — see the TSDoc on this file.
+ *
+ * @param projectRoot - Absolute or relative path to the project root.
+ * @returns A `RegeneratedFile` whose `content` matches a freshly written
+ *   `config.json`.
+ */
+export function regenerateConfigJson(projectRoot: string): RegeneratedFile {
+  const resolvedRoot = resolve(projectRoot);
+
+  // createDefaultConfig() is the single source of truth for the config shape.
+  const content = createDefaultConfig() as Record<string, unknown>;
+
+  // Conditionally append the contributor block — mirrors ensureConfig() logic.
+  if (isContributorProject(resolvedRoot)) {
+    content['contributor'] = {
+      isContributorProject: true,
+      devCli: 'cleo-dev',
+      verifiedAt: new Date().toISOString(),
+    };
+  }
+
+  return { filename: 'config.json', content };
+}
+
+/**
+ * Returns the `project-info.json` content that `cleo init` would write for
+ * `projectRoot` on the current machine.
+ *
+ * Captures machine-local fields:
+ *   - `projectHash` — SHA-256 of the resolved absolute path (first 12 chars)
+ *   - `projectId`   — fresh UUID (volatile; each call produces a new value)
+ *   - `lastUpdated` — current ISO timestamp (volatile)
+ *   - `cleoVersion` — read from `@cleocode/core/package.json` at runtime
+ *   - `schemas.*`   — schema version strings from bundled JSON schema files
+ *
+ * PURE — no disk writes.
+ *
+ * Mirrors: `packages/core/src/scaffold.ts :: ensureProjectInfo()`.
+ *
+ * DRIFT: if `ensureProjectInfo` adds, removes, or renames fields in the
+ * written JSON, update this function to match.
+ *
+ * @param projectRoot - Absolute or relative path to the project root.
+ * @returns A `RegeneratedFile` whose `content` matches a freshly written
+ *   `project-info.json`.
+ */
+export function regenerateProjectInfoJson(projectRoot: string): RegeneratedFile {
+  const resolvedRoot = resolve(projectRoot);
+  const projectHash = generateProjectHash(resolvedRoot);
+  const cleoVersion = getCleoVersion();
+  const now = new Date().toISOString();
+
+  // Read schema versions using the synchronous helper — falls back to safe
+  // defaults when schema files are not available (e.g. fresh clone, test env).
+  const configSchemaVersion = getSchemaVersion('config.schema.json') ?? cleoVersion;
+  const projectContextSchemaVersion = getSchemaVersion('project-context.schema.json') ?? '1.0.0';
+
+  const content: Record<string, unknown> = {
+    $schema: './schemas/project-info.schema.json',
+    schemaVersion: '1.0.0',
+    projectId: randomUUID(),
+    projectHash,
+    cleoVersion,
+    lastUpdated: now,
+    schemas: {
+      config: configSchemaVersion,
+      sqlite: SQLITE_SCHEMA_VERSION_MIRROR,
+      projectContext: projectContextSchemaVersion,
+    },
+    injection: {
+      'CLAUDE.md': null,
+      'AGENTS.md': null,
+      'GEMINI.md': null,
+    },
+    health: {
+      status: 'unknown',
+      lastCheck: null,
+      issues: [],
+    },
+    features: {
+      multiSession: false,
+      verification: false,
+      contextAlerts: false,
+    },
+  };
+
+  return { filename: 'project-info.json', content };
+}
+
+/**
+ * Returns the `project-context.json` content that `cleo init` would write for
+ * `projectRoot` on the current machine.
+ *
+ * Runs full project-type detection by inspecting the project directory:
+ * testing framework, build command, primary language, monorepo topology,
+ * file-naming conventions, and LLM hints. DOES NOT spawn child processes.
+ *
+ * PURE — no disk writes.
+ *
+ * Mirrors: `packages/core/src/scaffold.ts :: ensureProjectContext()` and
+ *          `packages/core/src/store/project-detect.ts :: detectProjectType()`.
+ *
+ * DRIFT: if `detectProjectType()` changes its output shape, the downstream
+ * A/B compare engine (T354) will still work because it compares fields by
+ * name — but regenerateProjectContextJson may produce unexpected keys or
+ * miss new ones until updated.
+ *
+ * @param projectRoot - Absolute or relative path to the project root.
+ * @returns A `RegeneratedFile` whose `content` matches a freshly written
+ *   `project-context.json`.
+ */
+export function regenerateProjectContextJson(projectRoot: string): RegeneratedFile<ProjectContext> {
+  const resolvedRoot = resolve(projectRoot);
+  const content = detectProjectType(resolvedRoot);
+  return { filename: 'project-context.json', content };
+}
+
+/**
+ * Convenience wrapper that returns all three regenerated files in one call.
+ *
+ * Each generator runs independently; volatile fields in `project-info.json`
+ * (`projectId`, `lastUpdated`) will differ from a separate call to
+ * `regenerateProjectInfoJson`.
+ *
+ * @param projectRoot - Absolute or relative path to the project root.
+ * @returns Object containing all three `RegeneratedFile` results.
+ *
+ * @task T352
+ * @epic T311
+ */
+export function regenerateAllJson(projectRoot: string): {
+  config: RegeneratedFile;
+  projectInfo: RegeneratedFile;
+  projectContext: RegeneratedFile<ProjectContext>;
+} {
+  return {
+    config: regenerateConfigJson(projectRoot),
+    projectInfo: regenerateProjectInfoJson(projectRoot),
+    projectContext: regenerateProjectContextJson(projectRoot),
+  };
+}

package/src/store/restore-conflict-report.ts

@@ -0,0 +1,317 @@
+/**
+ * Conflict report formatter for the T311 A/B JSON restore engine.
+ *
+ * Reads {@link JsonRestoreReport}[] (from T354) plus optional re-auth and
+ * schema-compatibility warnings, and emits the markdown report format
+ * defined in T311 spec §6.5.
+ *
+ * PURE FORMATTER — the only I/O in this module is inside
+ * {@link writeConflictReport}, which writes a single file via
+ * `fs.writeFileSync`.  Everything else is a pure string transformation.
+ *
+ * @task T357
+ * @epic T311
+ * @why ADR-038 §10 — restore writes a markdown conflict report at
+ *      .cleo/restore-conflicts.md so users (and downstream agents) can
+ *      review classifications + resolve manual-review fields + finalize
+ *      via `cleo restore finalize`.
+ * @what Pure formatter. Reads JsonRestoreReport[] from T354 + extra
+ *       metadata (re-auth warnings, schema warnings) and emits markdown.
+ * @module restore-conflict-report
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import type { JsonRestoreReport } from './restore-json-merge.js';
+
+// ============================================================================
+// Public types
+// ============================================================================
+
+/**
+ * Warning emitted when a signaldock.db agent was encrypted with the
+ * source machine's global-salt and therefore cannot be decrypted on the
+ * target machine.
+ *
+ * @task T357
+ * @epic T311
+ */
+export interface ReauthWarning {
+  /** Canonical agent identifier, e.g. `"cleo-prime"`. */
+  agentId: string;
+  /** Human-readable reason the agent needs re-authentication. */
+  reason: string;
+}
+
+/**
+ * Warning emitted when a bundled database's schema version differs from
+ * the local schema version.
+ *
+ * @task T357
+ * @epic T311
+ */
+export interface SchemaCompatWarning {
+  /** Database name without extension, e.g. `"brain"` or `"conduit"`. */
+  db: string;
+  /** Schema version string found in the bundle. */
+  bundleVersion: string;
+  /** Schema version string found in the local installation. */
+  localVersion: string;
+  /**
+   * Severity of the mismatch:
+   * - `older-bundle` — bundle schema is behind local; forward migration will
+   *   run on first open.
+   * - `newer-bundle` — bundle schema is ahead of local; upgrading cleo is
+   *   recommended before using the restored database.
+   */
+  severity: 'older-bundle' | 'newer-bundle';
+}
+
+/**
+ * All inputs required to build the `.cleo/restore-conflicts.md` report.
+ *
+ * @task T357
+ * @epic T311
+ */
+export interface BuildConflictReportInput {
+  /** Per-file A/B comparison results produced by T354. */
+  reports: JsonRestoreReport[];
+  /** Filesystem path of the bundle file that was imported. */
+  bundlePath: string;
+  /** Machine fingerprint recorded in the bundle manifest (source machine). */
+  sourceMachineFingerprint: string;
+  /** Machine fingerprint of the local machine (target machine). */
+  targetMachineFingerprint: string;
+  /** Cleo version string of the importing installation, e.g. `"2026.4.13"`. */
+  cleoVersion: string;
+  /**
+   * Agent re-authentication warnings for agents whose credentials were
+   * encrypted with the source machine's global-salt.
+   * Omit or pass an empty array when no agents need re-auth.
+   */
+  reauthWarnings?: ReauthWarning[];
+  /**
+   * Schema version mismatch warnings for bundled databases.
+   * Omit or pass an empty array when all schemas match.
+   */
+  schemaWarnings?: SchemaCompatWarning[];
+}
+
+// ============================================================================
+// Value formatting helpers
+// ============================================================================
+
+/**
+ * Formats an arbitrary field value as a compact inline markdown literal.
+ *
+ * - `undefined`  → `_(not present)_`
+ * - `null`       → `` `null` ``
+ * - strings      → `` `"value"` `` with interior double-quotes escaped
+ * - other        → `` `JSON.stringify(value)` ``
+ *
+ * @param val - The value to format.
+ * @returns A markdown-formatted string representation.
+ */
+function formatValue(val: unknown): string {
+  if (val === undefined) return '_(not present)_';
+  if (val === null) return '`null`';
+  if (typeof val === 'string') return '`"' + val.replace(/"/g, '\\"') + '"`';
+  return '`' + JSON.stringify(val) + '`';
+}
+
+// ============================================================================
+// Per-file section renderer
+// ============================================================================
+
+/**
+ * Renders the markdown section for a single {@link JsonRestoreReport}.
+ *
+ * Groups field classifications into three buckets:
+ * - **identical** — skipped (no conflict).
+ * - **resolved** — values differed but auto-resolution produced A or B.
+ * - **manual-review** — no safe auto-resolution; operator must decide.
+ *
+ * @param report - The comparison result for one JSON file.
+ * @returns Markdown string for the file section, without a trailing newline.
+ */
+function renderReportSection(report: JsonRestoreReport): string {
+  const resolved = report.classifications.filter(
+    (c) => c.category !== 'identical' && (c.resolution === 'A' || c.resolution === 'B'),
+  );
+  const manual = report.classifications.filter((c) => c.resolution === 'manual-review');
+  const totalClassified = report.classifications.length;
+  const conflictCount = manual.length;
+
+  const lines: string[] = [];
+
+  lines.push(`## ${report.filename}`);
+  lines.push('');
+  lines.push(
+    `_${totalClassified} fields classified, ${conflictCount} conflict${conflictCount === 1 ? '' : 's'}._`,
+  );
+  lines.push('');
+
+  // Resolved section
+  if (resolved.length === 0) {
+    lines.push('_No resolved conflicts._');
+  } else {
+    lines.push('### Resolved (auto-applied)');
+    lines.push('');
+    for (const c of resolved) {
+      lines.push(`- \`${c.path}\``);
+      lines.push(`  - Local (A): ${formatValue(c.local)}`);
+      lines.push(`  - Imported (B): ${formatValue(c.imported)}`);
+      lines.push(`  - Resolution: **${c.resolution}**`);
+      lines.push(`  - Rationale: ${c.rationale}`);
+    }
+  }
+
+  lines.push('');
+
+  // Manual review section
+  if (manual.length === 0) {
+    lines.push('_No manual review needed._');
+  } else {
+    lines.push('### Manual review needed');
+    lines.push('');
+    for (const c of manual) {
+      lines.push(`- \`${c.path}\``);
+      lines.push(`  - Local (A): ${formatValue(c.local)}`);
+      lines.push(`  - Imported (B): ${formatValue(c.imported)}`);
+      lines.push(`  - Resolution: **manual-review**`);
+      lines.push(`  - Rationale: ${c.rationale}`);
+      lines.push(
+        `  - RESOLVED: (edit this line to set 'A', 'B', or a custom value, then run 'cleo restore finalize')`,
+      );
+    }
+  }
+
+  return lines.join('\n');
+}
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+/**
+ * Builds the complete markdown content for `.cleo/restore-conflicts.md`.
+ *
+ * The output follows the T311 spec §6.5 format:
+ * - Header with bundle metadata and timestamps
+ * - One `##` section per file in `input.reports`
+ * - Agent re-authentication section (or _None_ when empty)
+ * - Schema compatibility warnings section (or _None_ when empty)
+ * - Footer instruction for `cleo restore finalize`
+ *
+ * @task T357
+ * @epic T311
+ * @param input - All data required to render the report.
+ * @returns The full markdown string. Does NOT write to disk.
+ */
+export function buildConflictReport(input: BuildConflictReportInput): string {
+  const {
+    reports,
+    bundlePath,
+    sourceMachineFingerprint,
+    targetMachineFingerprint,
+    cleoVersion,
+    reauthWarnings = [],
+    schemaWarnings = [],
+  } = input;
+
+  const restoredAt = new Date().toISOString();
+
+  const lines: string[] = [];
+
+  // ---- Header ----------------------------------------------------------------
+
+  lines.push('# T311 Import Conflict Report');
+  lines.push('');
+  lines.push(`**Source bundle**: ${bundlePath}`);
+  lines.push(`**Source machine**: ${sourceMachineFingerprint}`);
+  lines.push(`**Target machine**: ${targetMachineFingerprint}`);
+  lines.push(`**Restored at**: ${restoredAt}`);
+  lines.push(`**Cleo version**: ${cleoVersion}`);
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+
+  // ---- Per-file sections -----------------------------------------------------
+
+  for (const report of reports) {
+    lines.push(renderReportSection(report));
+    lines.push('');
+    lines.push('---');
+    lines.push('');
+  }
+
+  // ---- Agent re-authentication section ---------------------------------------
+
+  lines.push('## Agent re-authentication required');
+  lines.push('');
+  if (reauthWarnings.length === 0) {
+    lines.push('_None_');
+  } else {
+    lines.push('The following agents in `signaldock.db` were encrypted with the source');
+    lines.push("machine's `global-salt` and cannot be decrypted on this machine. Run");
+    lines.push('`cleo agent auth <id>` to re-authenticate:');
+    lines.push('');
+    for (const w of reauthWarnings) {
+      lines.push(`- ${w.agentId}: ${w.reason}`);
+    }
+  }
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+
+  // ---- Schema compatibility warnings section ---------------------------------
+
+  lines.push('## Schema compatibility warnings');
+  lines.push('');
+  if (schemaWarnings.length === 0) {
+    lines.push('_None_');
+  } else {
+    for (const w of schemaWarnings) {
+      lines.push(
+        `- \`${w.db}\`: schema version \`${w.bundleVersion}\` (local: \`${w.localVersion}\`)`,
+      );
+      if (w.severity === 'older-bundle') {
+        lines.push('  - Status: **older-bundle: forward migration will run on first open**');
+      } else {
+        lines.push('  - Status: **newer-bundle: upgrade cleo for full support**');
+      }
+    }
+  }
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+
+  // ---- Footer ----------------------------------------------------------------
+
+  lines.push(
+    '_Run `cleo restore finalize` after editing manual-review resolutions above to apply._',
+  );
+
+  return lines.join('\n');
+}
+
+/**
+ * Writes the conflict report markdown to
+ * `<projectRoot>/.cleo/restore-conflicts.md`.
+ *
+ * Creates the `.cleo/` directory if it does not already exist.
+ *
+ * @task T357
+ * @epic T311
+ * @param projectRoot - Absolute path to the project root directory.
+ * @param content     - Markdown string produced by {@link buildConflictReport}.
+ * @returns The absolute path of the written file.
+ */
+export function writeConflictReport(projectRoot: string, content: string): string {
+  const cleoDir = path.join(projectRoot, '.cleo');
+  fs.mkdirSync(cleoDir, { recursive: true });
+  const filePath = path.join(cleoDir, 'restore-conflicts.md');
+  fs.writeFileSync(filePath, content, 'utf-8');
+  return filePath;
+}