@namzu/sdk 0.1.7 → 0.2.0

package/src/session/migration/__tests__/filesystem.test.ts

@@ -0,0 +1,263 @@
+import { chmod, mkdir, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { UNKNOWN_TENANT_ID } from '../../../types/ids/index.js'
+import { FilesystemMigrationError } from '../errors.js'
+import {
+	DefaultFilesystemMigrator,
+	type FilesystemMigrationEvent,
+	type FilesystemMigrationSink,
+	LEGACY_DEFAULT_PROJECT_PREFIX,
+	LEGACY_DEFAULT_SESSION_ID,
+	MARKER_REL_PATH,
+	MIGRATION_VERSION,
+} from '../filesystem.js'
+import { acquireMigrationLock, writeMarker } from '../marker.js'
+
+function collectingSink(): {
+	events: FilesystemMigrationEvent[]
+	sink: FilesystemMigrationSink
+} {
+	const events: FilesystemMigrationEvent[] = []
+	return {
+		events,
+		sink: {
+			emit(ev) {
+				events.push(ev)
+			},
+		},
+	}
+}
+
+async function seedLegacyThread(root: string, thread: string, runs: string[]): Promise<void> {
+	for (const run of runs) {
+		const dir = join(root, 'threads', thread, 'runs', run)
+		await mkdir(dir, { recursive: true })
+		await writeFile(join(dir, 'run.json'), JSON.stringify({ id: run }), 'utf-8')
+	}
+}
+
+async function pathExists(p: string): Promise<boolean> {
+	try {
+		await stat(p)
+		return true
+	} catch {
+		return false
+	}
+}
+
+describe('DefaultFilesystemMigrator.migrate', () => {
+	let root: string
+
+	beforeEach(async () => {
+		root = await mkdtemp(join(tmpdir(), 'namzu-fsmig-'))
+	})
+
+	afterEach(async () => {
+		// chmod first in case a test left 000 perms on a directory.
+		await chmod(root, 0o755).catch(() => undefined)
+		await rm(root, { recursive: true, force: true })
+	})
+
+	it('cold boot with a single legacy thread: migrates, emits event, writes marker', async () => {
+		await seedLegacyThread(root, 'thd_abc', ['run_xyz'])
+
+		const { events, sink } = collectingSink()
+		const migrator = new DefaultFilesystemMigrator(sink)
+
+		const result = await migrator.migrate(root)
+
+		expect(result.kind).toBe('migrated')
+		expect(result.migratedThreads).toEqual([
+			{ legacyThreadId: 'thd_abc', newProjectId: `${LEGACY_DEFAULT_PROJECT_PREFIX}abc` },
+		])
+
+		// New layout exists.
+		const newRunDir = join(
+			root,
+			'projects',
+			`${LEGACY_DEFAULT_PROJECT_PREFIX}abc`,
+			'sessions',
+			LEGACY_DEFAULT_SESSION_ID,
+			'runs',
+			'run_xyz',
+		)
+		expect(await pathExists(newRunDir)).toBe(true)
+		expect(await pathExists(join(newRunDir, 'run.json'))).toBe(true)
+
+		// Legacy path moved (runs/ sub-tree renamed).
+		expect(await pathExists(join(root, 'threads', 'thd_abc', 'runs'))).toBe(false)
+
+		// Marker landed.
+		const markerRaw = await readFile(join(root, MARKER_REL_PATH), 'utf-8')
+		const markerParsed = JSON.parse(markerRaw)
+		expect(markerParsed.version).toBe(MIGRATION_VERSION)
+		expect(markerParsed.migratedThreads).toHaveLength(1)
+
+		// Event emitted with accurate result.
+		expect(events).toHaveLength(1)
+		expect(events[0]?.type).toBe('filesystem.migrated')
+		expect(events[0]?.result.kind).toBe('migrated')
+	})
+
+	it('warm boot with an existing marker short-circuits to already_migrated', async () => {
+		await writeMarker(join(root, MARKER_REL_PATH), {
+			version: MIGRATION_VERSION,
+			at: new Date(),
+			migratedThreads: [],
+		})
+		await seedLegacyThread(root, 'thd_stillhere', ['run_ignored'])
+
+		const { events, sink } = collectingSink()
+		const migrator = new DefaultFilesystemMigrator(sink)
+
+		const result = await migrator.migrate(root)
+
+		expect(result.kind).toBe('already_migrated')
+		expect(events).toHaveLength(0)
+		// No migration happened — legacy path untouched.
+		expect(await pathExists(join(root, 'threads', 'thd_stillhere', 'runs', 'run_ignored'))).toBe(
+			true,
+		)
+	})
+
+	it('cold boot with neither legacy nor marker writes a marker and returns noop_no_legacy', async () => {
+		const { events, sink } = collectingSink()
+		const migrator = new DefaultFilesystemMigrator(sink)
+
+		const result = await migrator.migrate(root)
+
+		expect(result.kind).toBe('noop_no_legacy')
+		expect(events).toHaveLength(0)
+		expect(await pathExists(join(root, MARKER_REL_PATH))).toBe(true)
+	})
+
+	it('cooperates with a concurrent migrator: main marker lands → already_migrated', async () => {
+		await seedLegacyThread(root, 'thd_abc', ['run_1'])
+
+		// Pre-seed the tmp lock to simulate another boot mid-migration.
+		await acquireMigrationLock(join(root, '.migration', 'v0.2.0.tmp'))
+
+		// Now write the main marker as the "winner" would. The loser must
+		// see this on the re-check after waiting and return already_migrated.
+		await writeMarker(join(root, MARKER_REL_PATH), {
+			version: MIGRATION_VERSION,
+			at: new Date(),
+			migratedThreads: [
+				{ legacyThreadId: 'thd_abc', newProjectId: `${LEGACY_DEFAULT_PROJECT_PREFIX}abc` },
+			],
+		})
+
+		// Because readMarker is checked FIRST (before lock contention), this
+		// actually returns already_migrated on step 1. That is the correct
+		// semantics: the main marker is the single source of truth.
+		const migrator = new DefaultFilesystemMigrator()
+		const result = await migrator.migrate(root)
+		expect(result.kind).toBe('already_migrated')
+	})
+
+	it('migrates multiple legacy threads in one pass with marker listing all', async () => {
+		await seedLegacyThread(root, 'thd_a', ['run_a1', 'run_a2'])
+		await seedLegacyThread(root, 'thd_b', ['run_b1'])
+		await seedLegacyThread(root, 'thd_c', ['run_c1'])
+
+		const migrator = new DefaultFilesystemMigrator()
+		const result = await migrator.migrate(root)
+
+		expect(result.kind).toBe('migrated')
+		expect(result.migratedThreads).toHaveLength(3)
+		const ids = result.migratedThreads.map((m) => m.legacyThreadId).sort()
+		expect(ids).toEqual(['thd_a', 'thd_b', 'thd_c'])
+
+		// Marker content mirrors result.
+		const markerRaw = await readFile(join(root, MARKER_REL_PATH), 'utf-8')
+		const markerParsed = JSON.parse(markerRaw)
+		expect(markerParsed.migratedThreads).toHaveLength(3)
+	})
+
+	it('synthesized project.json has _legacy: true and tenantId: UNKNOWN_TENANT_ID', async () => {
+		await seedLegacyThread(root, 'thd_tenantcheck', ['run_0'])
+		const migrator = new DefaultFilesystemMigrator()
+		await migrator.migrate(root)
+
+		const projectJsonPath = join(
+			root,
+			'projects',
+			`${LEGACY_DEFAULT_PROJECT_PREFIX}tenantcheck`,
+			'project.json',
+		)
+		const parsed = JSON.parse(await readFile(projectJsonPath, 'utf-8'))
+		expect(parsed._legacy).toBe(true)
+		expect(parsed.tenantId).toBe(UNKNOWN_TENANT_ID)
+		expect(parsed.id).toBe(`${LEGACY_DEFAULT_PROJECT_PREFIX}tenantcheck`)
+		expect(parsed.config).toMatchObject({
+			maxDelegationDepth: 4,
+			maxDelegationWidth: 8,
+			maxInterventionDepth: 10,
+		})
+	})
+
+	it('synthesized session.json is idle and flagged _legacy', async () => {
+		await seedLegacyThread(root, 'thd_sescheck', ['run_0'])
+		const migrator = new DefaultFilesystemMigrator()
+		await migrator.migrate(root)
+
+		const sessionJsonPath = join(
+			root,
+			'projects',
+			`${LEGACY_DEFAULT_PROJECT_PREFIX}sescheck`,
+			'sessions',
+			LEGACY_DEFAULT_SESSION_ID,
+			'session.json',
+		)
+		const parsed = JSON.parse(await readFile(sessionJsonPath, 'utf-8'))
+		expect(parsed.id).toBe(LEGACY_DEFAULT_SESSION_ID)
+		expect(parsed.status).toBe('idle')
+		expect(parsed.tenantId).toBe(UNKNOWN_TENANT_ID)
+		expect(parsed._legacy).toBe(true)
+	})
+
+	it('idempotent: two successive migrate() calls produce the same end-state', async () => {
+		await seedLegacyThread(root, 'thd_idem', ['run_1'])
+
+		const migrator = new DefaultFilesystemMigrator()
+		const first = await migrator.migrate(root)
+		const second = await migrator.migrate(root)
+
+		expect(first.kind).toBe('migrated')
+		expect(second.kind).toBe('already_migrated')
+		expect(second.migratedThreads).toHaveLength(0)
+		// End state still valid.
+		const newRunDir = join(
+			root,
+			'projects',
+			`${LEGACY_DEFAULT_PROJECT_PREFIX}idem`,
+			'sessions',
+			LEGACY_DEFAULT_SESSION_ID,
+			'runs',
+			'run_1',
+		)
+		expect(await pathExists(newRunDir)).toBe(true)
+	})
+
+	it('error path: unwritable marker directory surfaces FilesystemMigrationError', async () => {
+		// Make the rootDir read-only so write_marker fails on the noop branch
+		// (simplest repro — no legacy threads needed).
+		await chmod(root, 0o555)
+
+		const migrator = new DefaultFilesystemMigrator()
+		try {
+			await migrator.migrate(root)
+			expect.fail('expected migrate() to throw')
+		} catch (err) {
+			expect(err).toBeInstanceOf(FilesystemMigrationError)
+			const details = (err as FilesystemMigrationError).details
+			expect(details.op).toBe('write_marker')
+			expect(details.path).toContain('v0.2.0')
+		} finally {
+			// restore perms so afterEach can clean up
+			await chmod(root, 0o755).catch(() => undefined)
+		}
+	})
+})

package/src/session/migration/__tests__/id-prefix.test.ts

@@ -0,0 +1,101 @@
+import { beforeEach, describe, expect, it } from 'vitest'
+import type { ProjectId } from '../../../types/session/ids.js'
+import {
+	NOOP_MIGRATION_WARNING_SINK,
+	StalePrefixError,
+	__resetSeenLegacyForTests,
+	acceptLegacyThreadId,
+	rejectLegacyPrefix,
+} from '../id-prefix.js'
+import type { MigrationWarning, MigrationWarningSink } from '../id-prefix.js'
+
+function collectingSink(): { emitted: MigrationWarning[]; sink: MigrationWarningSink } {
+	const emitted: MigrationWarning[] = []
+	return {
+		emitted,
+		sink: {
+			emit(w) {
+				emitted.push(w)
+			},
+		},
+	}
+}
+
+describe('acceptLegacyThreadId', () => {
+	beforeEach(() => {
+		__resetSeenLegacyForTests()
+	})
+
+	it('coerces thd_* to prj_* and emits a warning on first encounter', () => {
+		const { emitted, sink } = collectingSink()
+		const result = acceptLegacyThreadId('thd_abc', sink)
+		expect(result).toBe('prj_abc' as ProjectId)
+		expect(emitted).toHaveLength(1)
+		expect(emitted[0]?.kind).toBe('id_prefix_legacy_read')
+		expect(emitted[0]?.legacyId).toBe('thd_abc')
+		expect(emitted[0]?.normalizedId).toBe('prj_abc')
+		expect(emitted[0]?.emittedOncePerProcess).toBe(true)
+		expect(emitted[0]?.at).toBeInstanceOf(Date)
+	})
+
+	it('does NOT re-emit a warning for the same legacy id on a second call', () => {
+		const { emitted, sink } = collectingSink()
+		acceptLegacyThreadId('thd_abc', sink)
+		acceptLegacyThreadId('thd_abc', sink)
+		acceptLegacyThreadId('thd_abc', sink)
+		expect(emitted).toHaveLength(1)
+	})
+
+	it('emits distinct warnings for distinct legacy ids', () => {
+		const { emitted, sink } = collectingSink()
+		acceptLegacyThreadId('thd_abc', sink)
+		acceptLegacyThreadId('thd_xyz', sink)
+		expect(emitted).toHaveLength(2)
+		expect(emitted.map((w) => w.legacyId).sort()).toEqual(['thd_abc', 'thd_xyz'])
+	})
+
+	it('returns prj_* ids unchanged and emits no warning', () => {
+		const { emitted, sink } = collectingSink()
+		const result = acceptLegacyThreadId('prj_keepme', sink)
+		expect(result).toBe('prj_keepme' as ProjectId)
+		expect(emitted).toHaveLength(0)
+	})
+
+	it('rejects unknown prefixes with StalePrefixError', () => {
+		const { sink } = collectingSink()
+		expect(() => acceptLegacyThreadId('xyz_nope', sink)).toThrowError(StalePrefixError)
+	})
+
+	it('StalePrefixError carries structured details for unknown prefixes', () => {
+		const { sink } = collectingSink()
+		try {
+			acceptLegacyThreadId('xyz_nope', sink)
+			expect.fail('expected throw')
+		} catch (err) {
+			expect(err).toBeInstanceOf(StalePrefixError)
+			expect((err as StalePrefixError).details.rawId).toBe('xyz_nope')
+			expect((err as StalePrefixError).details.kind).toBe('unknown_prefix')
+		}
+	})
+
+	it('NOOP_MIGRATION_WARNING_SINK swallows warnings without error', () => {
+		expect(() => acceptLegacyThreadId('thd_noop', NOOP_MIGRATION_WARNING_SINK)).not.toThrow()
+	})
+})
+
+describe('rejectLegacyPrefix', () => {
+	it('throws StalePrefixError for thd_* input', () => {
+		expect(() => rejectLegacyPrefix('thd_abc')).toThrowError(StalePrefixError)
+	})
+
+	it('accepts prj_* input without throwing', () => {
+		expect(() => rejectLegacyPrefix('prj_abc')).not.toThrow()
+	})
+
+	it('accepts non-thread prefixes without throwing (writer guard is scoped)', () => {
+		// The guard is specifically for thd_* re-emission; unrelated prefixes
+		// are a concern for their own parse functions.
+		expect(() => rejectLegacyPrefix('ses_abc')).not.toThrow()
+		expect(() => rejectLegacyPrefix('run_abc')).not.toThrow()
+	})
+})

package/src/session/migration/__tests__/marker.test.ts

@@ -0,0 +1,84 @@
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import type { ProjectId } from '../../../types/session/ids.js'
+import { acquireMigrationLock, readMarker, releaseMigrationLock, writeMarker } from '../marker.js'
+
+describe('migration marker I/O', () => {
+	let root: string
+
+	beforeEach(async () => {
+		root = await mkdtemp(join(tmpdir(), 'namzu-marker-'))
+	})
+
+	afterEach(async () => {
+		await rm(root, { recursive: true, force: true })
+	})
+
+	it('readMarker returns null when the file is missing', async () => {
+		const result = await readMarker(join(root, 'missing.json'))
+		expect(result).toBeNull()
+	})
+
+	it('readMarker parses a valid JSON marker', async () => {
+		const path = join(root, 'v0.2.0')
+		const at = new Date('2026-04-17T00:00:00.000Z')
+		await writeMarker(path, {
+			version: '0.2.0',
+			at,
+			migratedThreads: [{ legacyThreadId: 'thd_abc', newProjectId: 'prj_legacy_abc' as ProjectId }],
+		})
+		const result = await readMarker(path)
+		expect(result).not.toBeNull()
+		expect(result?.version).toBe('0.2.0')
+		expect(result?.at.toISOString()).toBe('2026-04-17T00:00:00.000Z')
+		expect(result?.migratedThreads).toEqual([
+			{ legacyThreadId: 'thd_abc', newProjectId: 'prj_legacy_abc' },
+		])
+	})
+
+	it('readMarker returns null on corrupt JSON (retry-safe)', async () => {
+		const path = join(root, 'corrupt.json')
+		await writeFile(path, '{ not valid json', 'utf-8')
+		const result = await readMarker(path)
+		expect(result).toBeNull()
+	})
+
+	it('writeMarker atomically writes via tmp-rename (no partial content)', async () => {
+		const path = join(root, 'v0.2.0')
+		await writeMarker(path, {
+			version: '0.2.0',
+			at: new Date(),
+			migratedThreads: [],
+		})
+		const content = await readFile(path, 'utf-8')
+		const parsed = JSON.parse(content)
+		expect(parsed.version).toBe('0.2.0')
+	})
+
+	it('acquireMigrationLock succeeds on first call and throws EEXIST on the second', async () => {
+		const lockPath = join(root, 'v0.2.0.tmp')
+		await acquireMigrationLock(lockPath)
+		let caught: NodeJS.ErrnoException | null = null
+		try {
+			await acquireMigrationLock(lockPath)
+		} catch (err) {
+			caught = err as NodeJS.ErrnoException
+		}
+		expect(caught).not.toBeNull()
+		expect(caught?.code).toBe('EEXIST')
+	})
+
+	it('releaseMigrationLock tolerates a missing file (idempotent)', async () => {
+		const lockPath = join(root, 'never-existed.tmp')
+		await expect(releaseMigrationLock(lockPath)).resolves.toBeUndefined()
+	})
+
+	it('releaseMigrationLock clears the lock so re-acquire succeeds', async () => {
+		const lockPath = join(root, 'v0.2.0.tmp')
+		await acquireMigrationLock(lockPath)
+		await releaseMigrationLock(lockPath)
+		await expect(acquireMigrationLock(lockPath)).resolves.toBeUndefined()
+	})
+})

package/src/session/migration/errors.ts

@@ -0,0 +1,23 @@
+/**
+ * Typed errors for the migration module.
+ *
+ * See session-hierarchy.md §13.4.1. Structured `details` payload lets
+ * consumers route failures without string parsing (Convention #5: fail
+ * fast, surface cause, no silent swallowing).
+ */
+
+/**
+ * Raised when any filesystem step during the boot-time v0.2.0 re-layout
+ * fails (enumerate, rename, synthesize project.json, write marker).
+ * `op` is a short stable tag so consumers can dashboard on failure mode;
+ * `cause` carries the underlying `Error` for stack preservation.
+ */
+export class FilesystemMigrationError extends Error {
+	readonly details: { op: string; path: string; cause?: unknown }
+
+	constructor(details: { op: string; path: string; cause?: unknown }) {
+		super(`Filesystem migration failed at ${details.op} on ${details.path}`)
+		this.name = 'FilesystemMigrationError'
+		this.details = details
+	}
+}