@ddtcorex/dsh-maestro-memory 1.0.1

package/src/host/migration/cli.ts

@@ -0,0 +1,139 @@
+/**
+ * migration/cli.ts — operations CLI requiring explicit --apply; default is read-only
+ */
+
+import { inspect, dryRun, run, verify } from './service.ts'
+import { resolveMemoryRoot } from '../storage/layout.ts'
+
+export interface ParsedArgs {
+  root: string | null
+  apply: boolean
+  command: 'inspect' | 'dryRun' | 'run' | 'verify'
+  runId?: string
+  help: boolean
+}
+
+export function parseArgs(argv: string[]): ParsedArgs {
+  const args = argv.slice(2)
+  let root: string | null = null
+  let apply = false
+  let command: ParsedArgs['command'] = 'inspect'
+  let runId: string | undefined
+  let help = false
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (a === '--help' || a === '-h') help = true
+    else if (a === '--apply') apply = true
+    else if (a === '--inspect') command = 'inspect'
+    else if (a === '--dry-run' || a === '--dryRun') command = 'dryRun'
+    else if (a === '--verify') command = 'verify'
+    else if (a === '--run') command = 'run'
+    else if (a === '--root' && i + 1 < args.length) {
+      root = args[++i]
+    } else if (a.startsWith('--root=')) {
+      root = a.slice('--root='.length)
+    } else if (a === '--run-id' && i + 1 < args.length) {
+      runId = args[++i]
+    } else if (a.startsWith('--run-id=')) {
+      runId = a.slice('--run-id='.length)
+    }
+  }
+  // explicit --apply forces run command unless verify explicitly requested
+  if (apply && command === 'inspect') command = 'run'
+  // if user asked --verify, keep verify even with --apply? But verify is separate
+  // parse loyalty: --verify overrides apply's run conversion
+  if (args.includes('--verify')) command = 'verify'
+  return { root, apply, command, runId, help }
+}
+
+export function helpText(): string {
+  return `
+dsh-maestro-memory migration CLI
+
+Default is read-only (inspect). Requires explicit --apply to perform backup+adoption.
+
+Usage:
+  node migrate.mjs [--root <path>] [--inspect|--dry-run|--verify] [--apply] [--run-id <id>]
+
+Commands (read-only by default):
+  --inspect       Read-only inventory, parse, warnings for malformed JSONL/locks/noncanonical (default)
+  --dry-run       Same as inspect, explicitly read-only (no side effects)
+  --verify        Verify current files against latest backup manifest (or --run-id); blocks writes on mismatch
+
+Write operation (requires --apply):
+  --apply         Perform migration: byte-preserving backup manifest + schema.json + journal
+                  Without --apply, run is NOT executed (stays read-only)
+
+Options:
+  --root <path>   Memory root (default: ~/.dsh/memories)
+  --run-id <id>   For verify: specific backup runId (default: latest / schema.json)
+
+Examples:
+  node scripts/migrate.mjs --root /tmp/memories            # inspect only
+  node scripts/migrate.mjs --root /tmp/memories --dry-run  # dry-run
+  node scripts/migrate.mjs --root /tmp/memories --apply    # backup + adopt
+  node scripts/migrate.mjs --root /tmp/memories --verify   # verify
+
+`.trim()
+}
+
+export async function main(parsed: ParsedArgs): Promise<{ ok: boolean; command: string; output?: any }> {
+  if (parsed.help) {
+    console.log(helpText())
+    return { ok: true, command: 'help' }
+  }
+  const root = parsed.root ? resolveMemoryRoot(parsed.root) : resolveMemoryRoot(null)
+
+  if (parsed.command === 'verify') {
+    const res = await verify(root, parsed.runId)
+    if (res.ok) {
+      console.log(`verify ok: runId=${res.runId} (${res.manifestPath})`)
+    } else {
+      console.error(`verify failed: runId=${res.runId}`)
+      for (const m of res.mismatches) console.error(`  - ${m}`)
+      console.error('writes are now blocked until mismatch is resolved (see .maestro-memory/write-block.json)')
+    }
+    return { ok: res.ok, command: 'verify', output: res }
+  }
+
+  if (parsed.command === 'run') {
+    if (!parsed.apply) {
+      // Safety: default is read-only, require explicit --apply
+      const insp = await inspect(root)
+      console.log('read-only inspect (dry-run): use --apply to perform migration')
+      console.log(`files: ${insp.files.filter((f) => f.exists).length} existing, warnings: ${insp.warnings.length}`)
+      for (const w of insp.warnings) console.log(`  warn: ${w}`)
+      console.log(`inventory: memoryEntries=${insp.inventory.memoryEntries}, todos=${insp.inventory.todoIdsCount}, queue valid=${insp.inventory.queueValid} malformed=${insp.inventory.queueMalformed}`)
+      return { ok: true, command: 'inspect', output: insp }
+    }
+    const res = await run(root)
+    if (res.ok) {
+      console.log(`run ok: runId=${res.runId}`)
+      console.log(`manifest: ${res.manifestPath}`)
+      console.log(`backup: ${res.backupFilesDir}`)
+      if (res.warnings.length) {
+        console.log('warnings:')
+        for (const w of res.warnings) console.log(`  - ${w}`)
+      }
+    } else {
+      console.error(`run failed: ${res.errors.join('; ')}`)
+      for (const w of res.warnings) console.error(`  warn: ${w}`)
+    }
+    return { ok: res.ok, command: 'run', output: res }
+  }
+
+  if (parsed.command === 'dryRun') {
+    const res = await dryRun(root)
+    console.log(`dryRun: ok=${res.ok}, warnings=${res.warnings.length}`)
+    for (const w of res.warnings) console.log(`  warn: ${w}`)
+    console.log(`inventory: memoryEntries=${res.inventory.memoryEntries}, todos=${res.inventory.todoIdsCount}`)
+    return { ok: res.ok, command: 'dryRun', output: res }
+  }
+
+  // default inspect
+  const res = await inspect(root)
+  console.log(`inspect: ok=${res.ok}, files=${res.files.filter((f) => f.exists).length}, warnings=${res.warnings.length}`)
+  for (const w of res.warnings) console.log(`  warn: ${w}`)
+  console.log(`inventory: memoryEntries=${res.inventory.memoryEntries}, todos=${res.inventory.todoIdsCount}, queue valid=${res.inventory.queueValid} malformed=${res.inventory.queueMalformed}`)
+  return { ok: res.ok, command: 'inspect', output: res }
+}

package/src/host/migration/fixture.ts

@@ -0,0 +1,218 @@
+/**
+ * fixture.ts — helpers for M4-PR-A rehearsal: fixture profile with link: package/patch,
+ * one-owner per compatibility tool, and copied-schema population (not live home).
+ *
+ * Pure helpers + minimal FS. No Cordis import, no network, no live home mutation.
+ */
+
+import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { createHash } from 'node:crypto'
+
+const COMPAT_TOOLS = ['memory', 'dtodo', 'skill_manage', 'memory_suggest', 'memory_review_status'] as const
+type CompatTool = typeof COMPAT_TOOLS[number]
+
+/**
+ * Known tool ownership map for rehearsal.
+ * Currently only @ddtcorex/dsh-maestro-memory provides compatibility tools.
+ * Future: if DSH core adds an owner, this gate must surface it.
+ */
+const KNOWN_OWNERS: Record<string, string[]> = {
+  memory: ['@ddtcorex/dsh-maestro-memory'],
+  dtodo: ['@ddtcorex/dsh-maestro-memory'],
+  skill_manage: [], // optional module, not owned by default
+  memory_suggest: ['@ddtcorex/dsh-maestro-memory'],
+  memory_review_status: ['@ddtcorex/dsh-maestro-memory'],
+}
+
+export interface CreateFixtureProfileOpts {
+  profileDir: string
+  packageDir: string
+  profileName?: string
+}
+
+export interface FixtureProfileResult {
+  profileDir: string
+  packageJsonPath: string
+}
+
+/**
+ * Build a fixture profile with link: package/patch and prove one owner per tool.
+ * - Creates <profileDir>/package.json with link: dependency to the local package checkout.
+ * - Bundles list contains exactly one owner for each compat tool.
+ * - Does NOT duplicate the cordis.patch.yml row (patch is owned by the package itself).
+ */
+export async function createFixtureProfile(opts: CreateFixtureProfileOpts): Promise<FixtureProfileResult> {
+  const { profileDir, packageDir } = opts
+  if (!profileDir) throw new Error('createFixtureProfile: profileDir is required')
+  if (!packageDir) throw new Error('createFixtureProfile: packageDir is required')
+  mkdirSync(profileDir, { recursive: true })
+  const packageJsonPath = join(profileDir, 'package.json')
+  const pkg = {
+    name: opts.profileName ?? 'dsh-profile-fixture',
+    private: true,
+    dsh: {
+      profile: {
+        bundles: ['@ddtcorex/dsh-maestro-memory'],
+      },
+    },
+    dependencies: {
+      '@ddtcorex/dsh-maestro-memory': `link:${packageDir}`,
+    },
+  }
+  writeFileSync(packageJsonPath, JSON.stringify(pkg, null, 2), 'utf8')
+  // Intentionally do NOT create cordis.patch.yml with duplicate maestro-memory row.
+  // The package's own cordis.patch.yml provides it; duplicates crash loader.
+  return { profileDir, packageJsonPath }
+}
+
+export interface AssertSingleOwnerOpts {
+  toolOwners?: Record<string, string[]>
+}
+
+export interface AssertSingleOwnerResult {
+  ok: boolean
+  owners: Record<string, string>
+  errors: string[]
+}
+
+/**
+ * Prove one owner per compatibility tool for a fixture profile.
+ * - By default derives owners from the profile's bundles (known mapping).
+ * - If opts.toolOwners provided, uses that mapping to simulate duplicate detection (for tests).
+ */
+export async function assertSingleOwner(
+  profileDir: string,
+  opts?: AssertSingleOwnerOpts,
+): Promise<AssertSingleOwnerResult> {
+  const owners: Record<string, string> = {}
+  const errors: string[] = []
+
+  // If caller supplies explicit toolOwners mapping, use it for validation
+  if (opts?.toolOwners) {
+    for (const [tool, list] of Object.entries(opts.toolOwners)) {
+      if (list.length === 0) continue
+      if (list.length > 1) {
+        errors.push(`tool "${tool}" has multiple owners: ${list.join(', ')} (duplicate owner)`)
+      } else {
+        owners[tool] = list[0]
+      }
+    }
+    return { ok: errors.length === 0, owners, errors }
+  }
+
+  // Derive from profile package.json bundles
+  const pkgPath = join(profileDir, 'package.json')
+  if (!existsSync(pkgPath)) {
+    return { ok: false, owners, errors: [`profile package.json not found: ${pkgPath}`] }
+  }
+  let pkg: any
+  try {
+    pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+  } catch (e: any) {
+    return { ok: false, owners, errors: [`failed to parse package.json: ${e?.message}`] }
+  }
+  const bundles: string[] = pkg?.dsh?.profile?.bundles ?? []
+  const deps: Record<string, string> = pkg?.dependencies ?? {}
+
+  // For each compat tool, collect owners from bundles that claim it
+  for (const tool of COMPAT_TOOLS) {
+    const claimed = bundles.filter((b: string) => {
+      const known = KNOWN_OWNERS[tool] ?? []
+      return known.includes(b)
+    })
+    // Also check dependencies that are link: but not in bundles? Bundles is source of truth for loader.
+    if (claimed.length === 0) {
+      // tool not owned in this fixture — skip (skill_manage may be absent)
+      continue
+    }
+    if (claimed.length > 1) {
+      errors.push(`tool "${tool}" has multiple owners: ${claimed.join(', ')}`)
+    } else {
+      owners[tool] = claimed[0]
+      // Verify dependency is link:
+      const depVal = deps[claimed[0]]
+      if (depVal && !depVal.startsWith('link:')) {
+        errors.push(`tool "${tool}" owner ${claimed[0]} dependency is not link: (got ${depVal})`)
+      }
+    }
+  }
+
+  // Additional check: ensure profile does not contain duplicate patch row
+  const patchPath = join(profileDir, 'cordis.patch.yml')
+  if (existsSync(patchPath)) {
+    const text = readFileSync(patchPath, 'utf8')
+    if (text.includes('maestro-memory')) {
+      errors.push('profile cordis.patch.yml must not duplicate package patch id maestro-memory')
+    }
+  }
+
+  // Check that our package link exists
+  const ourDep = deps['@ddtcorex/dsh-maestro-memory']
+  if (!ourDep) {
+    errors.push('profile missing dependency @ddtcorex/dsh-maestro-memory')
+  } else if (!ourDep.startsWith('link:')) {
+    errors.push(`expected link: dependency for @ddtcorex/dsh-maestro-memory, got ${ourDep}`)
+  }
+
+  return { ok: errors.length === 0, owners, errors }
+}
+
+// ---------------------------------------------------------------------------
+// Copied schema fixture (not live home)
+// ---------------------------------------------------------------------------
+
+function writeLegacyMemory(file: string, entries: string[]) {
+  const content = entries.length === 0 ? '' : entries.join('\n§\n') + '\n'
+  mkdirSync(dirname(file), { recursive: true })
+  writeFileSync(file, content, 'utf8')
+}
+
+function writeTodoFile(file: string, entriesRaw: string[]) {
+  const header = `<!--\nTodo entry format (auto-maintained by the program, do not edit the structure manually):\n- Entries are delimited by §; the comment block before the first § is the format note, not a todo\n- The first line of each todo is the metadata tag line (fixed order, optional parts may be omitted):\n  [created time] auto-stamped by the program (e.g. [2026-08-06 21:30])\n  [id: 8-hex] unique identifier for the entry, operated by the dtodo tool\n  [q1] important & urgent  [q2] important not urgent  [q3] urgent not important  [q4] not important not urgent (default = unclassified)\n  [due: YYYY-MM-DD] due date (default = none)\n  [status: pending|doing|done|blocked|cancelled] status (default pending)\n  [done: YYYY-MM-DD HH:MM] completion time (auto-stamped, only for done status)\n  [cat: category] optional (life/work/study...)\n- Todo content follows the first tag line and may span multiple lines\n-->\n`
+  const body = entriesRaw.join('\n§\n')
+  const text = `${header}${body.length > 0 ? `\n§\n${body}\n` : ''}`
+  mkdirSync(dirname(file), { recursive: true })
+  writeFileSync(file, text, 'utf8')
+}
+
+/**
+ * Populate a temp memory root with synthetic legacy files for rehearsal,
+ * mirroring migration.spec's fixture but centralized for reuse.
+ * This root is a *copy*, never the live ~/.dsh/memories.
+ */
+export async function createCopiedMemoryRoot(root: string, opts?: { cwd?: string }) {
+  const cwd = opts?.cwd ?? '/tmp/proj-a'
+  const hash = createHash('sha1').update(cwd).digest('hex').slice(0, 12)
+
+  // global memory
+  writeLegacyMemory(join(root, 'MEMORY.md'), ['[2026-08-10] global one', '[2026-08-11] global two'])
+  writeLegacyMemory(join(root, 'USER.md'), ['[2026-08-10] user one'])
+  writeLegacyMemory(join(root, 'MEMORY-archive.md'), ['[2026-08-09] archived global'])
+  writeLegacyMemory(join(root, 'USER-archive.md'), ['[2026-08-09] archived user'])
+  // queue
+  const suggestion = { target: 'memory', content: 'suggest 1', reason: 'r', time: new Date().toISOString() }
+  mkdirSync(root, { recursive: true })
+  writeFileSync(join(root, 'SUGGESTIONS.jsonl'), JSON.stringify(suggestion) + '\n', 'utf8')
+  // project
+  writeLegacyMemory(join(root, 'projects', hash, 'MEMORY.md'), ['[2026-08-10 10:00] project log'])
+  writeLegacyMemory(join(root, 'projects', hash, 'KEY.md'), ['[2026-08-10] [branch:main] key entry', '[2026-08-10] key two'])
+  writeLegacyMemory(join(root, 'projects', hash, 'KEY-archive.md'), ['[2026-08-08] old key'])
+  writeFileSync(
+    join(root, 'projects', hash, 'TODOS.md'),
+    '<!-- header -->\n§\n[2026-08-10 10:00] [id: aabbccdd] [status: pending]\nproj todo\n',
+    'utf8',
+  )
+  // daily
+  mkdirSync(join(root, 'daily'), { recursive: true })
+  writeFileSync(join(root, 'daily', '2026-08-10.md'), '[08:30] daily entry\n', 'utf8')
+  writeFileSync(
+    join(root, 'daily', '2026-08-10.todo.md'),
+    '<!-- header -->\n§\n[2026-08-10 10:00] [id: deadbeef] [status: pending]\ndaily todo\n',
+    'utf8',
+  )
+  // todos life/work
+  writeTodoFile(join(root, 'TODOS-life.md'), ['[2026-08-10 10:00] [id: 11111111] [status: pending]\nlife todo'])
+  writeTodoFile(join(root, 'TODOS-work.md'), ['[2026-08-10 10:00] [id: 22222222] [status: doing]\nwork todo'])
+  writeFileSync(join(root, 'TODO-archive.md'), 'archived todo\n', 'utf8')
+}