@cleocode/core 2026.3.44 → 2026.3.45

package/src/nexus/transfer-types.ts

@@ -0,0 +1,129 @@
+/**
+ * Types for cross-project task transfer via NEXUS.
+ *
+ * @task T046, T047
+ * @epic T4540
+ */
+
+import type { Task } from '@cleocode/contracts';
+
+/** Transfer mode: copy keeps source tasks, move archives them. */
+export type TransferMode = 'copy' | 'move';
+
+/** Transfer scope: single task or full subtree. */
+export type TransferScope = 'single' | 'subtree';
+
+/** Conflict resolution when target has tasks with duplicate titles. */
+export type TransferOnConflict = 'duplicate' | 'rename' | 'skip' | 'fail';
+
+/** How to handle missing dependencies in the target project. */
+export type TransferOnMissingDep = 'strip' | 'fail';
+
+/** Parameters for a cross-project transfer operation. */
+export interface TransferParams {
+  /** Task IDs to transfer from the source project. */
+  taskIds: string[];
+  /** Source project name or hash. */
+  sourceProject: string;
+  /** Target project name or hash. */
+  targetProject: string;
+  /** Copy (default) keeps source tasks; move archives them. */
+  mode?: TransferMode;
+  /** Single transfers individual tasks; subtree transfers tasks + all descendants. */
+  scope?: TransferScope;
+  /** How to handle title conflicts in the target. */
+  onConflict?: TransferOnConflict;
+  /** How to handle missing deps in the target. */
+  onMissingDep?: TransferOnMissingDep;
+  /** Whether to add provenance notes to transferred tasks. */
+  provenance?: boolean;
+  /** Override parent ID in target project. */
+  targetParent?: string;
+  /** Whether to transfer brain observations linked to source tasks. */
+  transferBrain?: boolean;
+  /** Dry run: preview without writing. */
+  dryRun?: boolean;
+}
+
+/** A single task entry in the transfer manifest. */
+export interface TransferManifestEntry {
+  /** Original task ID in source project. */
+  sourceId: string;
+  /** New task ID in target project. */
+  targetId: string;
+  /** Task title. */
+  title: string;
+  /** Task type (task, epic, milestone, etc.). */
+  type: string;
+}
+
+/** Manifest describing what was (or would be) transferred. */
+export interface TransferManifest {
+  /** Source project name. */
+  sourceProject: string;
+  /** Target project name. */
+  targetProject: string;
+  /** Transfer mode used. */
+  mode: TransferMode;
+  /** Transfer scope used. */
+  scope: TransferScope;
+  /** Tasks included in the transfer. */
+  entries: TransferManifestEntry[];
+  /** ID remap table: sourceId -> targetId. */
+  idRemap: Record<string, string>;
+  /** Number of brain observations transferred. */
+  brainObservationsTransferred: number;
+}
+
+/** Result of a transfer operation. */
+export interface TransferResult {
+  /** Whether this was a dry run. */
+  dryRun: boolean;
+  /** Number of tasks transferred. */
+  transferred: number;
+  /** Number of tasks skipped (conflict resolution). */
+  skipped: number;
+  /** Number of source tasks archived (move mode only). */
+  archived: number;
+  /** Number of external links created. */
+  linksCreated: number;
+  /** Number of brain observations transferred. */
+  brainObservationsTransferred: number;
+  /** Transfer manifest with full details. */
+  manifest: TransferManifest;
+}
+
+/** Options passed to importFromPackage (extracted from importTasksPackage). */
+export interface ImportFromPackageOptions {
+  /** Working directory for the target project. */
+  cwd?: string;
+  /** Dry run: preview without writing. */
+  dryRun?: boolean;
+  /** Parent task ID in target. */
+  parent?: string;
+  /** Phase override. */
+  phase?: string;
+  /** Label to add to imported tasks. */
+  addLabel?: string;
+  /** Whether to add provenance notes. */
+  provenance?: boolean;
+  /** Status to reset imported tasks to. */
+  resetStatus?: Task['status'];
+  /** Conflict resolution strategy. */
+  onConflict?: TransferOnConflict;
+  /** Missing dependency strategy. */
+  onMissingDep?: TransferOnMissingDep;
+  /** Force import (skip duplicate checks). */
+  force?: boolean;
+}
+
+/** Result from importFromPackage. */
+export interface ImportFromPackageResult {
+  imported: number;
+  skipped: number;
+  idRemap: Record<string, string>;
+  dryRun?: boolean;
+  preview?: {
+    tasks: Array<{ id: string; title: string; type: string }>;
+  };
+}

package/src/nexus/transfer.ts

@@ -0,0 +1,314 @@
+/**
+ * Cross-project task transfer engine for NEXUS.
+ *
+ * Provides executeTransfer() and previewTransfer() for moving/copying
+ * tasks between registered NEXUS projects with full provenance tracking.
+ *
+ * @task T046, T049, T050, T051, T052, T053
+ * @epic T4540
+ */
+
+import { randomUUID } from 'node:crypto';
+import { importFromPackage } from '../admin/import-tasks.js';
+import { getLogger } from '../logger.js';
+import { createLink } from '../reconciliation/link-store.js';
+import { BrainDataAccessor } from '../store/brain-accessor.js';
+import { getBrainDb } from '../store/brain-sqlite.js';
+import { getAccessor } from '../store/data-accessor.js';
+import { exportSingle, exportSubtree } from '../store/export.js';
+import { requirePermission } from './permissions.js';
+import { nexusGetProject } from './registry.js';
+import type {
+  TransferManifest,
+  TransferManifestEntry,
+  TransferParams,
+  TransferResult,
+} from './transfer-types.js';
+
+const log = getLogger('nexus:transfer');
+
+/**
+ * Preview a transfer without writing any data.
+ * Validates projects, permissions, and builds the manifest.
+ */
+export async function previewTransfer(params: TransferParams): Promise<TransferResult> {
+  return executeTransferInternal({ ...params, dryRun: true });
+}
+
+/**
+ * Execute a cross-project task transfer.
+ *
+ * Pipeline:
+ *   1. Validate source/target projects via nexusGetProject()
+ *   2. Check permissions: read on source, write on target
+ *   3. Read source tasks
+ *   4. Build ExportPackage via exportSubtree/exportSingle
+ *   5. Import into target via importFromPackage()
+ *   6. Create bidirectional external_task_links
+ *   7. Write nexus_audit_log entry
+ *   8. If move mode: archive source tasks
+ *   9. If transferBrain: copy brain observations
+ */
+export async function executeTransfer(params: TransferParams): Promise<TransferResult> {
+  return executeTransferInternal(params);
+}
+
+async function executeTransferInternal(params: TransferParams): Promise<TransferResult> {
+  const {
+    taskIds,
+    sourceProject: sourceProjectRef,
+    targetProject: targetProjectRef,
+    mode = 'copy',
+    scope = 'subtree',
+    onConflict = 'rename',
+    onMissingDep = 'strip',
+    provenance = true,
+    targetParent,
+    transferBrain = false,
+    dryRun = false,
+  } = params;
+
+  if (!taskIds.length) {
+    throw new Error('No task IDs specified for transfer');
+  }
+
+  // Step 1: Validate projects
+  const sourceProject = await nexusGetProject(sourceProjectRef);
+  if (!sourceProject) {
+    throw new Error(`Source project not found: ${sourceProjectRef}`);
+  }
+
+  const targetProject = await nexusGetProject(targetProjectRef);
+  if (!targetProject) {
+    throw new Error(`Target project not found: ${targetProjectRef}`);
+  }
+
+  if (sourceProject.hash === targetProject.hash) {
+    throw new Error('Source and target projects must be different');
+  }
+
+  // Step 2: Check permissions
+  await requirePermission(sourceProject.hash, 'read', 'nexus.transfer');
+  await requirePermission(targetProject.hash, 'write', 'nexus.transfer');
+
+  // Step 3: Read source tasks
+  const sourceAccessor = await getAccessor(sourceProject.path);
+  const { tasks: allSourceTasks } = await sourceAccessor.queryTasks({});
+
+  // Step 4: Build ExportPackage for each task
+  const exportPackages = [];
+  for (const taskId of taskIds) {
+    const pkg =
+      scope === 'subtree'
+        ? exportSubtree(taskId, allSourceTasks, sourceProject.name)
+        : exportSingle(taskId, allSourceTasks, sourceProject.name);
+
+    if (!pkg) {
+      throw new Error(`Task not found in source project: ${taskId}`);
+    }
+    exportPackages.push(pkg);
+  }
+
+  // Merge all packages into one (dedup by task ID)
+  const seenIds = new Set<string>();
+  const mergedTasks = [];
+  for (const pkg of exportPackages) {
+    for (const task of pkg.tasks) {
+      if (!seenIds.has(task.id)) {
+        seenIds.add(task.id);
+        mergedTasks.push(task);
+      }
+    }
+  }
+
+  // Use the first package as base and replace tasks
+  const mergedPkg = { ...exportPackages[0]! };
+  mergedPkg.tasks = mergedTasks;
+  mergedPkg._meta = { ...mergedPkg._meta, taskCount: mergedTasks.length };
+
+  // Step 5: Import into target
+  const importResult = await importFromPackage(mergedPkg, {
+    cwd: targetProject.path,
+    dryRun,
+    parent: targetParent,
+    provenance,
+    onConflict,
+    onMissingDep,
+  });
+
+  // Build manifest
+  const entries: TransferManifestEntry[] = mergedTasks.map((t) => ({
+    sourceId: t.id,
+    targetId: importResult.idRemap[t.id] ?? t.id,
+    title: t.title,
+    type: t.type ?? 'task',
+  }));
+
+  const manifest: TransferManifest = {
+    sourceProject: sourceProject.name,
+    targetProject: targetProject.name,
+    mode,
+    scope,
+    entries,
+    idRemap: importResult.idRemap,
+    brainObservationsTransferred: 0,
+  };
+
+  const result: TransferResult = {
+    dryRun,
+    transferred: importResult.imported,
+    skipped: importResult.skipped,
+    archived: 0,
+    linksCreated: 0,
+    brainObservationsTransferred: 0,
+    manifest,
+  };
+
+  if (dryRun) {
+    return result;
+  }
+
+  // Step 6: Create bidirectional external_task_links
+  // Only create links for tasks that were actually imported (verify they exist in target)
+  let linksCreated = 0;
+  const targetAccessor = await getAccessor(targetProject.path);
+  const { tasks: targetTasks } = await targetAccessor.queryTasks({});
+  const targetTaskIds = new Set(targetTasks.map((t) => t.id));
+
+  for (const entry of entries) {
+    if (importResult.idRemap[entry.sourceId] && targetTaskIds.has(entry.targetId)) {
+      // Link in target: points back to source
+      await createLink(
+        {
+          taskId: entry.targetId,
+          providerId: `nexus:${sourceProject.name}`,
+          externalId: entry.sourceId,
+          externalTitle: entry.title,
+          linkType: 'transferred',
+          syncDirection: 'inbound',
+          metadata: {
+            transferMode: mode,
+            transferScope: scope,
+            sourceProject: sourceProject.name,
+            transferredAt: new Date().toISOString(),
+          },
+        },
+        targetProject.path,
+      );
+      linksCreated++;
+
+      // Link in source: points to target
+      await createLink(
+        {
+          taskId: entry.sourceId,
+          providerId: `nexus:${targetProject.name}`,
+          externalId: entry.targetId,
+          externalTitle: entry.title,
+          linkType: 'transferred',
+          syncDirection: 'outbound',
+          metadata: {
+            transferMode: mode,
+            transferScope: scope,
+            targetProject: targetProject.name,
+            transferredAt: new Date().toISOString(),
+          },
+        },
+        sourceProject.path,
+      );
+      linksCreated++;
+    }
+  }
+  result.linksCreated = linksCreated;
+
+  // Step 7: Write audit log
+  try {
+    const { getNexusDb } = await import('../store/nexus-sqlite.js');
+    const { nexusAuditLog } = await import('../store/nexus-schema.js');
+    const db = await getNexusDb();
+    await db.insert(nexusAuditLog).values({
+      id: randomUUID(),
+      action: 'transfer',
+      projectHash: sourceProject.hash,
+      projectId: sourceProject.projectId,
+      domain: 'nexus',
+      operation: 'transfer',
+      success: 1,
+      detailsJson: JSON.stringify({
+        sourceProject: sourceProject.name,
+        targetProject: targetProject.name,
+        mode,
+        scope,
+        taskCount: result.transferred,
+        idRemap: importResult.idRemap,
+      }),
+    });
+  } catch (err) {
+    log.warn({ err }, 'nexus transfer audit write failed');
+  }
+
+  // Step 8: Move mode — archive source tasks
+  if (mode === 'move') {
+    let archived = 0;
+    for (const entry of entries) {
+      if (importResult.idRemap[entry.sourceId]) {
+        try {
+          await sourceAccessor.archiveSingleTask(entry.sourceId, {
+            archivedAt: new Date().toISOString(),
+            archiveReason: `Transferred to ${targetProject.name} as ${entry.targetId}`,
+          });
+          archived++;
+        } catch (err) {
+          log.warn({ err, taskId: entry.sourceId }, 'failed to archive source task after transfer');
+        }
+      }
+    }
+    result.archived = archived;
+  }
+
+  // Step 9: Brain observation transfer
+  if (transferBrain) {
+    let brainTransferred = 0;
+    try {
+      const sourceBrainDb = await getBrainDb(sourceProject.path);
+      const targetBrainDb = await getBrainDb(targetProject.path);
+      const sourceBrain = new BrainDataAccessor(sourceBrainDb);
+      const targetBrain = new BrainDataAccessor(targetBrainDb);
+
+      for (const entry of entries) {
+        if (!importResult.idRemap[entry.sourceId]) continue;
+
+        const links = await sourceBrain.getLinksForTask(entry.sourceId);
+        for (const link of links) {
+          if (link.memoryType !== 'observation') continue;
+
+          const observation = await sourceBrain.getObservation(link.memoryId);
+          if (!observation) continue;
+
+          const newObsId = `O-${randomUUID().slice(0, 8)}`;
+          await targetBrain.addObservation({
+            ...observation,
+            id: newObsId,
+            createdAt: observation.createdAt,
+            updatedAt: new Date().toISOString().replace('T', ' ').slice(0, 19),
+          });
+
+          await targetBrain.addLink({
+            memoryType: 'observation',
+            memoryId: newObsId,
+            taskId: entry.targetId,
+            linkType: 'applies_to',
+            createdAt: new Date().toISOString().replace('T', ' ').slice(0, 19),
+          });
+
+          brainTransferred++;
+        }
+      }
+    } catch (err) {
+      log.warn({ err }, 'brain observation transfer failed');
+    }
+    result.brainObservationsTransferred = brainTransferred;
+    result.manifest.brainObservationsTransferred = brainTransferred;
+  }
+
+  return result;
+}

package/src/store/brain-sqlite.ts

@@ -50,13 +50,17 @@ export function getBrainDbPath(cwd?: string): string {
 
 /**
  * Resolve the path to the drizzle-brain migrations folder.
- * Works from both src/ (dev via tsx) and dist/ (compiled).
+ * Works from both src/ (dev via tsx) and dist/ (compiled via esbuild bundle).
+ *
+ * - Source layout: __dirname = src/store/ → need ../../migrations/drizzle-brain
+ * - Bundled layout: __dirname = dist/     → need ../migrations/drizzle-brain
  */
 export function resolveBrainMigrationsFolder(): string {
   const __filename = fileURLToPath(import.meta.url);
   const __dirname = dirname(__filename);
-  // Both src/store/ and dist/store/ are 2 levels deep from package root
-  return join(__dirname, '..', '..', 'migrations', 'drizzle-brain');
+  const isBundled = __dirname.endsWith('/dist') || __dirname.endsWith('\\dist');
+  const pkgRoot = isBundled ? join(__dirname, '..') : join(__dirname, '..', '..');
+  return join(pkgRoot, 'migrations', 'drizzle-brain');
 }
 
 /**

package/src/store/nexus-sqlite.ts

@@ -46,13 +46,17 @@ export function getNexusDbPath(): string {
 
 /**
  * Resolve the path to the drizzle-nexus migrations folder.
- * Works from both src/ (dev via tsx) and dist/ (compiled).
+ * Works from both src/ (dev via tsx) and dist/ (compiled via esbuild bundle).
+ *
+ * - Source layout: __dirname = src/store/ → need ../../migrations/drizzle-nexus
+ * - Bundled layout: __dirname = dist/     → need ../migrations/drizzle-nexus
  */
 export function resolveNexusMigrationsFolder(): string {
   const __filename = fileURLToPath(import.meta.url);
   const __dirname = dirname(__filename);
-  // Both src/store/ and dist/store/ are 2 levels deep from package root
-  return join(__dirname, '..', '..', 'migrations', 'drizzle-nexus');
+  const isBundled = __dirname.endsWith('/dist') || __dirname.endsWith('\\dist');
+  const pkgRoot = isBundled ? join(__dirname, '..') : join(__dirname, '..', '..');
+  return join(pkgRoot, 'migrations', 'drizzle-nexus');
 }
 
 /**

package/src/store/sqlite.ts

@@ -357,13 +357,19 @@ export async function getDb(cwd?: string): Promise<NodeSQLiteDatabase<typeof sch
 
 /**
  * Resolve the path to the drizzle migrations folder.
- * Works from both src/ (dev via tsx) and dist/ (compiled).
+ * Works from both src/ (dev via tsx) and dist/ (compiled via esbuild bundle).
+ *
+ * - Source layout: __dirname = src/store/ → need ../../migrations/drizzle-tasks
+ * - Bundled layout: __dirname = dist/     → need ../migrations/drizzle-tasks
  */
 export function resolveMigrationsFolder(): string {
   const __filename = fileURLToPath(import.meta.url);
   const __dirname = dirname(__filename);
-  // Both src/store/ and dist/store/ are 2 levels deep from package root
-  return join(__dirname, '..', '..', 'migrations', 'drizzle-tasks');
+  // When esbuild bundles into dist/index.js, __dirname is dist/ (1 level deep).
+  // When running from source via tsx, __dirname is src/store/ (2 levels deep).
+  const isBundled = __dirname.endsWith('/dist') || __dirname.endsWith('\\dist');
+  const pkgRoot = isBundled ? join(__dirname, '..') : join(__dirname, '..', '..');
+  return join(pkgRoot, 'migrations', 'drizzle-tasks');
 }
 
 /**

package/src/store/tasks-schema.ts

@@ -127,7 +127,7 @@ export const TASK_RELATION_TYPES = [
 export const LIFECYCLE_TRANSITION_TYPES = ['automatic', 'manual', 'forced'] as const;
 
 /** External task link types matching DB constraint on external_task_links.link_type. */
-export const EXTERNAL_LINK_TYPES = ['created', 'matched', 'manual'] as const;
+export const EXTERNAL_LINK_TYPES = ['created', 'matched', 'manual', 'transferred'] as const;
 
 /** Sync direction types matching DB constraint on external_task_links.sync_direction. */
 export const SYNC_DIRECTIONS = ['inbound', 'outbound', 'bidirectional'] as const;