@iceinvein/agent-skills 0.1.39 → 0.2.0

package/skills/migrate/scripts/__tests__/init.test.ts

@@ -0,0 +1,192 @@
+import { afterEach, beforeEach, expect, test } from 'bun:test'
+import { existsSync } from 'node:fs'
+import { mkdir, mkdtemp, readFile, rm, symlink, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { loadConfig } from '../config.ts'
+import { runInit } from '../init-cmd.ts'
+import { storePaths } from '../paths.ts'
+
+async function captureStdout(fn: () => Promise<number>): Promise<{ code: number; text: string }> {
+  const out: string[] = []
+  const original = process.stdout.write.bind(process.stdout)
+  process.stdout.write = ((s: string) => {
+    out.push(s)
+    return true
+  }) as typeof process.stdout.write
+  try {
+    const code = await fn()
+    return { code, text: out.join('') }
+  } finally {
+    process.stdout.write = original
+  }
+}
+
+let root: string
+let source: string
+
+beforeEach(async () => {
+  root = await mkdtemp(join(tmpdir(), 'migrate-init-'))
+  source = join(root, 'legacy')
+  await mkdir(source, { recursive: true })
+})
+
+afterEach(async () => {
+  await rm(root, { recursive: true, force: true })
+})
+
+const BASE = () => ({ root, sourcePath: source, scope: 'billing', targetName: 'newapp' })
+
+test('init creates the store and a loadable config', async () => {
+  expect(await runInit(BASE())).toBe(0)
+  expect(existsSync(storePaths(root).queueDir)).toBe(true)
+  const cfg = await loadConfig(root)
+  expect(cfg.source.scope).toBe('billing')
+  expect(cfg.target.name).toBe('newapp')
+})
+
+test('init refuses to overwrite an existing config', async () => {
+  await runInit(BASE())
+  expect(await runInit(BASE())).toBe(1)
+})
+
+test('init refuses a source path that does not exist', async () => {
+  expect(await runInit({ ...BASE(), sourcePath: join(root, 'nope') })).toBe(2)
+})
+
+test('init appends the env file to an existing .gitignore exactly once', async () => {
+  await writeFile(join(root, '.gitignore'), 'node_modules/\n')
+  await runInit(BASE())
+  const text = await readFile(join(root, '.gitignore'), 'utf8')
+  expect(text).toContain('.migrate/.env')
+  expect(text.match(/\.migrate\/\.env/g)).toHaveLength(1)
+})
+
+test('init records an explicit basis', async () => {
+  await runInit({ ...BASE(), basis: 'runnable' })
+  expect((await loadConfig(root)).source.basis).toBe('runnable')
+})
+
+test('init appends the env file to a .gitignore that lacks a trailing newline', async () => {
+  await writeFile(join(root, '.gitignore'), 'node_modules/')
+  await runInit(BASE())
+  const text = await readFile(join(root, '.gitignore'), 'utf8')
+  expect(text).toBe('node_modules/\n.migrate/.env\n')
+})
+
+test('init detects vcs as git when the source path contains a .git directory', async () => {
+  await mkdir(join(source, '.git'), { recursive: true })
+  await runInit(BASE())
+  expect((await loadConfig(root)).source.vcs).toBe('git')
+})
+
+test('init detects vcs as none when the source path has no .git directory', async () => {
+  await runInit(BASE())
+  expect((await loadConfig(root)).source.vcs).toBe('none')
+})
+
+test('init refuses a source path that is a file, not a directory', async () => {
+  const filePath = join(root, 'not-a-dir.txt')
+  await writeFile(filePath, 'hi')
+  expect(await runInit({ ...BASE(), sourcePath: filePath })).toBe(2)
+})
+
+test('init does not mistake an unrelated deeper path for a real .gitignore entry', async () => {
+  await writeFile(join(root, '.gitignore'), 'node_modules/\nfoo/.migrate/.env\n')
+  await runInit(BASE())
+  const text = await readFile(join(root, '.gitignore'), 'utf8')
+  const lines = text.split('\n').map((l) => l.trim())
+  expect(lines).toContain('.migrate/.env')
+  expect(lines.filter((l) => l === '.migrate/.env')).toHaveLength(1)
+})
+
+test('init does not mistake a commented-out mention for a real .gitignore entry', async () => {
+  await writeFile(join(root, '.gitignore'), 'node_modules/\n# .migrate/.env (handled elsewhere)\n')
+  await runInit(BASE())
+  const text = await readFile(join(root, '.gitignore'), 'utf8')
+  const lines = text.split('\n').map((l) => l.trim())
+  expect(lines).toContain('.migrate/.env')
+  expect(lines.filter((l) => l === '.migrate/.env')).toHaveLength(1)
+})
+
+// Final-review finding, Important 1: init was the one writer with no
+// containment guard. `migrate init --source .` inside a source tree created
+// config.toml, made queue/, and appended to the source's own .gitignore; every
+// later command then exited 2 on the guard those writers do have, leaving a
+// store nothing could write to. SKILL.md, docs/reference.md and
+// docs/architecture.md all claimed this was impossible.
+
+test('init refuses to build a store inside the read-only source tree, writing nothing', async () => {
+  const result = await runInit({ ...BASE(), sourcePath: root })
+  expect(result).toBe(2)
+  expect(existsSync(storePaths(root).dir)).toBe(false)
+  expect(existsSync(join(root, '.gitignore'))).toBe(false)
+})
+
+// The three write targets init checks share a parent for an ordinary target
+// root, so a plain path comparison can never tell them apart. A symlink can:
+// here .migrate resolves into the source tree while the target root itself is
+// nowhere near it, so only the store-path legs of the check fire. The guard
+// resolves real paths, which is what makes this reachable at all.
+test('init refuses when only the store directory resolves into the source tree', async () => {
+  const stash = join(source, 'stash')
+  await mkdir(stash, { recursive: true })
+  await symlink(stash, storePaths(root).dir)
+  expect(await runInit(BASE())).toBe(2)
+  expect(existsSync(join(stash, 'config.toml'))).toBe(false)
+  expect(existsSync(join(stash, 'queue'))).toBe(false)
+})
+
+// The mirror image, and the leg the store-path checks alone would miss: the
+// store is fine, but the target's .gitignore is a symlink into the source, so
+// the append would edit a file in the read-only checkout. Refused before
+// anything is created, so the planted file is byte-identical afterwards.
+test('init refuses when only the .gitignore resolves into the source tree', async () => {
+  const planted = join(source, '.gitignore')
+  await writeFile(planted, 'node_modules/\n')
+  await symlink(planted, join(root, '.gitignore'))
+  expect(await runInit(BASE())).toBe(2)
+  expect(await readFile(planted, 'utf8')).toBe('node_modules/\n')
+  expect(existsSync(storePaths(root).dir)).toBe(false)
+})
+
+// Final-review finding, Important 2: the append was guarded by
+// `if (existsSync(gitignore))`, so a target repo with no .gitignore of its own
+// got no ignore entry at all and `git add -A` staged .migrate/.env on the
+// first commit of the run. The `leaks` gate that would catch the committed
+// result is opt-in, so nothing else stood behind this.
+
+test('init creates a .gitignore listing the env file when the target has none, and says so', async () => {
+  const { code, text } = await captureStdout(() => runInit(BASE()))
+  expect(code).toBe(0)
+  const gitignore = join(root, '.gitignore')
+  expect(await readFile(gitignore, 'utf8')).toBe('.migrate/.env\n')
+  expect(text).toContain(`init: created ${gitignore} with .migrate/.env`)
+})
+
+test('init reports the append when the target already has a .gitignore', async () => {
+  const gitignore = join(root, '.gitignore')
+  await writeFile(gitignore, 'node_modules/\n')
+  const { code, text } = await captureStdout(() => runInit(BASE()))
+  expect(code).toBe(0)
+  expect(text).toContain(`init: appended .migrate/.env to ${gitignore}`)
+})
+
+// The claim the two tests above exist to make is not really about file
+// content, it is that git will not stage the env file. Asserted against real
+// git rather than by reading the ignore text, since the ignore text being
+// right and git still staging the file is precisely the failure that shipped.
+test('git does not stage .migrate/.env after init, on a target that had no .gitignore', async () => {
+  await Bun.spawn(['git', 'init', '-q'], { cwd: root, stdout: 'ignore', stderr: 'ignore' }).exited
+  expect(await runInit(BASE())).toBe(0)
+  await writeFile(storePaths(root).env, 'API_TOKEN=super-secret\n')
+  const proc = Bun.spawn(['git', 'check-ignore', '.migrate/.env'], {
+    cwd: root,
+    stdout: 'pipe',
+    stderr: 'ignore',
+  })
+  const listed = await new Response(proc.stdout).text()
+  await proc.exited
+  expect(proc.exitCode).toBe(0)
+  expect(listed.trim()).toBe('.migrate/.env')
+})

package/skills/migrate/scripts/__tests__/leaks.test.ts

@@ -0,0 +1,176 @@
+import { afterEach, beforeEach, expect, test } from 'bun:test'
+import { chmod, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { parseEnv, scanLeaks, secretValues } from '../leaks.ts'
+
+let root: string
+
+beforeEach(async () => {
+  root = await mkdtemp(join(tmpdir(), 'migrate-leaks-'))
+  await mkdir(join(root, '.migrate', 'queue'), { recursive: true })
+})
+
+afterEach(async () => {
+  await rm(root, { recursive: true, force: true })
+})
+
+async function git(args: string[], cwd: string): Promise<void> {
+  const proc = Bun.spawn(['git', ...args], { cwd, stdout: 'ignore', stderr: 'ignore' })
+  const code = await proc.exited
+  if (code !== 0) throw new Error(`git ${args.join(' ')} failed with exit code ${code}`)
+}
+
+async function initRepo(cwd: string): Promise<void> {
+  await git(['init', '-q'], cwd)
+  await git(['config', 'user.email', 'test@example.com'], cwd)
+  await git(['config', 'user.name', 'Test'], cwd)
+  await git(['config', 'commit.gpgsign', 'false'], cwd)
+}
+
+test('parseEnv handles quotes, export and comments', () => {
+  const env = parseEnv('# a comment\nexport A="one two"\nB=plain\nC=\n')
+  expect(env.A).toBe('one two')
+  expect(env.B).toBe('plain')
+  expect(env.C).toBe('')
+})
+
+test('secretValues drops empties, short values and urls', () => {
+  const values = secretValues({
+    MIGRATE_SOURCE_URL: 'https://legacy.example.com',
+    MIGRATE_SOURCE_PASSWORD: 'hunter2-longer-secret',
+    MIGRATE_SOURCE_READONLY: 'true',
+    SHORT: 'abc',
+    EMPTY: '',
+  })
+  expect(values).toEqual(['hunter2-longer-secret'])
+})
+
+test('scanLeaks finds a secret pasted into an artifact and names the variable', async () => {
+  await writeFile(join(root, '.migrate', '.env'), 'MIGRATE_SOURCE_PASSWORD=hunter2-longer-secret\n')
+  await writeFile(
+    join(root, '.migrate', 'queue', 'q-a.md'),
+    'logged in with hunter2-longer-secret\n',
+  )
+  const violations = await scanLeaks({ root })
+  expect(violations).toHaveLength(1)
+  expect(violations[0]?.message).toContain('MIGRATE_SOURCE_PASSWORD')
+  expect(violations[0]?.message).toContain('q-a.md')
+  expect(violations[0]?.message).not.toContain('hunter2-longer-secret')
+})
+
+test('scanLeaks passes on a clean store', async () => {
+  await writeFile(join(root, '.migrate', '.env'), 'MIGRATE_SOURCE_PASSWORD=hunter2-longer-secret\n')
+  await writeFile(join(root, '.migrate', 'queue', 'q-a.md'), 'observed at legacy.example.com\n')
+  expect(await scanLeaks({ root })).toEqual([])
+})
+
+test('scanLeaks is a no-op with no .env file', async () => {
+  expect(await scanLeaks({ root })).toEqual([])
+})
+
+test('scanLeaks reports an unreadable artifact as a violation instead of skipping it', async () => {
+  await writeFile(join(root, '.migrate', '.env'), 'MIGRATE_SOURCE_PASSWORD=hunter2-longer-secret\n')
+  const target = join(root, '.migrate', 'queue', 'q-a.md')
+  await writeFile(target, 'nothing secret here\n')
+  await chmod(target, 0o000)
+  const violations = await scanLeaks({ root })
+  expect(violations).toHaveLength(1)
+  expect(violations[0]?.gate).toBe('leaks')
+  expect(violations[0]?.message).toContain('q-a.md')
+  expect(violations[0]?.message).not.toContain('hunter2-longer-secret')
+})
+
+test('scanLeaks reports one violation per file for a value shared by two variables, naming both', async () => {
+  await writeFile(
+    join(root, '.migrate', '.env'),
+    'MIGRATE_SOURCE_PASSWORD=hunter2-longer-secret\nMIGRATE_SOURCE_PASSWORD_RO=hunter2-longer-secret\n',
+  )
+  await writeFile(
+    join(root, '.migrate', 'queue', 'q-a.md'),
+    'logged in with hunter2-longer-secret\n',
+  )
+  const violations = await scanLeaks({ root })
+  expect(violations).toHaveLength(1)
+  expect(violations[0]?.message).toContain('MIGRATE_SOURCE_PASSWORD_RO')
+  expect(violations[0]?.message).toContain('MIGRATE_SOURCE_PASSWORD')
+  expect(violations[0]?.message).not.toContain('hunter2-longer-secret')
+})
+
+test('scanLeaks never puts a secret value on the git subprocess argument list', async () => {
+  await writeFile(join(root, '.migrate', '.env'), 'MIGRATE_SOURCE_PASSWORD=hunter2-longer-secret\n')
+  await mkdir(join(root, '.git'))
+  const capturePath = join(root, 'argv-capture.log')
+  const stubPath = join(root, 'git-stub.sh')
+  await writeFile(stubPath, `#!/bin/sh\necho "$@" >> ${JSON.stringify(capturePath)}\n`)
+  await chmod(stubPath, 0o755)
+
+  await scanLeaks({ root, gitBin: stubPath })
+
+  const captured = await readFile(capturePath, 'utf8').catch(() => '')
+  expect(captured.length).toBeGreaterThan(0)
+  expect(captured).not.toContain('hunter2-longer-secret')
+})
+
+test('scanLeaks finds a secret spanning a chunk boundary in the git stub output', async () => {
+  // The stub writes the secret in two separate stdout writes with a pause in
+  // between, so the parent's stream reads them as two separate chunks with
+  // the secret split across the boundary. This exercises the carry-over
+  // logic in findInStream rather than relying on how a real git process
+  // happens to buffer its output.
+  const secret = 'hunter2-longer-secret'
+  await writeFile(join(root, '.migrate', '.env'), `MIGRATE_SOURCE_PASSWORD=${secret}\n`)
+  await mkdir(join(root, '.git'))
+  const stubPath = join(root, 'git-stub-split.ts')
+  const mid = Math.floor(secret.length / 2)
+  await writeFile(
+    stubPath,
+    [
+      '#!/usr/bin/env bun',
+      `process.stdout.write(${JSON.stringify(secret.slice(0, mid))})`,
+      'await new Promise((resolve) => setTimeout(resolve, 50))',
+      `process.stdout.write(${JSON.stringify(secret.slice(mid))})`,
+      '',
+    ].join('\n'),
+  )
+  await chmod(stubPath, 0o755)
+
+  const violations = await scanLeaks({ root, gitBin: stubPath })
+  expect(violations).toHaveLength(1)
+  expect(violations[0]?.message).toContain('MIGRATE_SOURCE_PASSWORD')
+  expect(violations[0]?.message).toContain('git history')
+})
+
+test('scanLeaks finds a secret that exists only in git history, not in the working tree', async () => {
+  await writeFile(join(root, '.migrate', '.env'), 'MIGRATE_SOURCE_PASSWORD=hunter2-longer-secret\n')
+  await initRepo(root)
+  const notes = join(root, 'notes.txt')
+  await writeFile(notes, 'logged in with hunter2-longer-secret\n')
+  await git(['add', 'notes.txt'], root)
+  await git(['commit', '-q', '-m', 'add notes'], root)
+  await writeFile(notes, 'logged in fine\n')
+  await git(['add', 'notes.txt'], root)
+  await git(['commit', '-q', '-m', 'redact notes'], root)
+
+  const violations = await scanLeaks({ root })
+  expect(violations).toHaveLength(1)
+  expect(violations[0]?.gate).toBe('leaks')
+  expect(violations[0]?.message).toContain('MIGRATE_SOURCE_PASSWORD')
+  expect(violations[0]?.message).toContain('git history')
+  expect(violations[0]?.message).not.toContain('hunter2-longer-secret')
+})
+
+test('scanLeaks does not attempt to run git when there is no .git directory', async () => {
+  await writeFile(join(root, '.migrate', '.env'), 'MIGRATE_SOURCE_PASSWORD=hunter2-longer-secret\n')
+  const violations = await scanLeaks({ root, gitBin: join(root, 'no-such-git-binary') })
+  expect(violations).toEqual([])
+})
+
+test('scanLeaks reports a violation when git cannot be run, instead of crashing', async () => {
+  await writeFile(join(root, '.migrate', '.env'), 'MIGRATE_SOURCE_PASSWORD=hunter2-longer-secret\n')
+  await mkdir(join(root, '.git'))
+  const violations = await scanLeaks({ root, gitBin: join(root, 'no-such-git-binary') })
+  expect(violations).toHaveLength(1)
+  expect(violations[0]?.gate).toBe('leaks')
+  expect(violations[0]?.message).not.toContain('hunter2-longer-secret')
+})

package/skills/migrate/scripts/__tests__/lock.test.ts

@@ -0,0 +1,183 @@
+import { afterEach, beforeEach, expect, test } from 'bun:test'
+import { existsSync, unlinkSync } from 'node:fs'
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { LockError, lockPath, processIsAlive, withStoreLock } from '../lock.ts'
+
+let root: string
+
+beforeEach(async () => {
+  root = await mkdtemp(join(tmpdir(), 'migrate-lock-'))
+  await mkdir(join(root, '.migrate'), { recursive: true })
+})
+
+afterEach(async () => {
+  await rm(root, { recursive: true, force: true })
+})
+
+test('runs the body, returns its value, and removes the lock afterwards', async () => {
+  const result = await withStoreLock(root, async () => 'done', { cmd: 'import' })
+  expect(result).toBe('done')
+  expect(existsSync(lockPath(root))).toBe(false)
+})
+
+test('the lock file names the holder while the body runs', async () => {
+  let holder: { pid: number; cmd: string; startedAt: string } | null = null
+  await withStoreLock(
+    root,
+    async () => {
+      holder = JSON.parse(await readFile(lockPath(root), 'utf8'))
+    },
+    { cmd: 'census' },
+  )
+  expect(holder).not.toBeNull()
+  expect((holder as unknown as { pid: number }).pid).toBe(process.pid)
+  expect((holder as unknown as { cmd: string }).cmd).toBe('census')
+})
+
+test('releases the lock when the body throws, and propagates the error', async () => {
+  const boom = withStoreLock(
+    root,
+    async () => {
+      throw new Error('body failed')
+    },
+    { cmd: 'import' },
+  )
+  await expect(boom).rejects.toThrow('body failed')
+  expect(existsSync(lockPath(root))).toBe(false)
+})
+
+test('refuses immediately when the holder pid is not running, naming --force-unlock', async () => {
+  await writeFile(
+    lockPath(root),
+    JSON.stringify({ pid: 999999, startedAt: '2026-08-07T02:58:03.000Z', cmd: 'import' }),
+  )
+  const attempt = withStoreLock(root, async () => 'unreachable', {
+    cmd: 'import',
+    alive: () => false,
+    timeoutMs: 30_000,
+  })
+  await expect(attempt).rejects.toThrow(/--force-unlock/)
+  await attempt.catch((e) => {
+    expect(e).toBeInstanceOf(LockError)
+    expect((e as LockError).kind).toBe('stale')
+  })
+})
+
+// Regression: readHolder and alive() are separated by an await boundary, so
+// a holder that finishes, unlinks the lock, and exits in that gap used to
+// make alive() return false for a pid that no longer matters, reported as a
+// stale lock even though the lock was actually free. The alive hook's own
+// side effect stands in for that race deterministically: it removes the lock
+// file at the exact moment withStoreLock asks whether the holder it just read
+// is still alive, so the confirming re-read must see the lock gone and retry
+// rather than concluding pid 4242 is a dead holder.
+test('a holder that releases the lock in the gap between the read and the liveness check is retried, not reported stale', async () => {
+  await writeFile(
+    lockPath(root),
+    JSON.stringify({ pid: 4242, startedAt: '2026-08-07T02:58:03.000Z', cmd: 'import' }),
+  )
+  let calls = 0
+  const result = await withStoreLock(root, async () => 'ran', {
+    cmd: 'import',
+    alive: (pid) => {
+      calls += 1
+      if (pid === 4242) unlinkSync(lockPath(root))
+      return false
+    },
+  })
+  expect(result).toBe('ran')
+  // Called exactly once: the confirming re-read found the lock gone and the
+  // retry went straight to acquiring it, never asking alive() about a second
+  // holder.
+  expect(calls).toBe(1)
+})
+
+test('times out while a live holder keeps the lock, naming the holder', async () => {
+  await writeFile(
+    lockPath(root),
+    JSON.stringify({ pid: 4412, startedAt: '2026-08-07T02:58:03.000Z', cmd: 'import' }),
+  )
+  const waits: string[] = []
+  const attempt = withStoreLock(root, async () => 'unreachable', {
+    cmd: 'import',
+    alive: () => true,
+    timeoutMs: 120,
+    onWait: (m) => waits.push(m),
+  })
+  await attempt.catch((e) => {
+    expect(e).toBeInstanceOf(LockError)
+    expect((e as LockError).kind).toBe('timeout')
+    expect((e as LockError).message).toContain('4412')
+  })
+  expect(waits.length).toBe(1)
+  expect(waits[0]).toContain('4412')
+  expect(waits[0]).toContain('2026-08-07T02:58:03.000Z')
+})
+
+test('force breaks a lock held by a live holder and runs the body', async () => {
+  await writeFile(
+    lockPath(root),
+    JSON.stringify({ pid: 4412, startedAt: '2026-08-07T02:58:03.000Z', cmd: 'import' }),
+  )
+  const result = await withStoreLock(root, async () => 'ran', {
+    cmd: 'import',
+    alive: () => true,
+    force: true,
+  })
+  expect(result).toBe('ran')
+  expect(existsSync(lockPath(root))).toBe(false)
+})
+
+test('a lock file that never becomes readable is reported as stale, not waited out', async () => {
+  await writeFile(lockPath(root), 'not json at all')
+  const attempt = withStoreLock(root, async () => 'unreachable', {
+    cmd: 'import',
+    timeoutMs: 30_000,
+  })
+  await attempt.catch((e) => {
+    expect(e).toBeInstanceOf(LockError)
+    expect((e as LockError).kind).toBe('stale')
+    expect((e as LockError).message).toContain('unreadable')
+  })
+})
+
+// A lock file left empty forever (its creator crashed after the O_EXCL
+// create but before it ever wrote a holder record) must not hang: an empty
+// read is deliberately excluded from UNREADABLE_TOLERANCE (see readHolder),
+// since counting it there is what caused real contention to misreport a
+// live handoff as corruption, so the only remaining backstop is the overall
+// deadline. This confirms that backstop actually fires instead of looping.
+test('a lock file that stays empty forever times out rather than looping', async () => {
+  await writeFile(lockPath(root), '')
+  const attempt = withStoreLock(root, async () => 'unreachable', {
+    cmd: 'import',
+    timeoutMs: 120,
+  })
+  await attempt.catch((e) => {
+    expect(e).toBeInstanceOf(LockError)
+    expect((e as LockError).kind).toBe('timeout')
+  })
+})
+
+test('two concurrent bodies in one process do not overlap', async () => {
+  const events: string[] = []
+  const body = (name: string) => async () => {
+    events.push(`${name}:enter`)
+    await Bun.sleep(20)
+    events.push(`${name}:exit`)
+  }
+  await Promise.all([
+    withStoreLock(root, body('a'), { cmd: 'import' }),
+    withStoreLock(root, body('b'), { cmd: 'import' }),
+  ])
+  expect(events.length).toBe(4)
+  expect(events[1]).toBe(events[0]?.replace(':enter', ':exit'))
+  expect(events[3]).toBe(events[2]?.replace(':enter', ':exit'))
+})
+
+test('processIsAlive is true for this process and false for an unused pid', () => {
+  expect(processIsAlive(process.pid)).toBe(true)
+  expect(processIsAlive(999999)).toBe(false)
+})

package/skills/migrate/scripts/__tests__/paths.test.ts

@@ -0,0 +1,129 @@
+import { afterEach, beforeEach, expect, test } from 'bun:test'
+import { existsSync, mkdirSync, mkdtempSync, rmSync, symlinkSync } from 'node:fs'
+import { mkdir, mkdtemp, rm, symlink } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { assertNotUnderSource, findStoreRoot, storePaths } from '../paths.ts'
+
+let root: string
+
+beforeEach(async () => {
+  root = await mkdtemp(join(tmpdir(), 'migrate-paths-'))
+})
+
+afterEach(async () => {
+  await rm(root, { recursive: true, force: true })
+})
+
+// Platform support is detected once, synchronously, at module load, so
+// test.skipIf's condition is known before any test runs rather than
+// discovered mid-test.
+
+function detectSymlinkSupport(): boolean {
+  const dir = mkdtempSync(join(tmpdir(), 'migrate-symlink-check-'))
+  try {
+    symlinkSync(join(dir, 'target'), join(dir, 'link'))
+    return true
+  } catch {
+    return false
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+}
+
+function detectCaseInsensitiveFs(): boolean {
+  const dir = mkdtempSync(join(tmpdir(), 'migrate-case-check-'))
+  try {
+    mkdirSync(join(dir, 'src'))
+    return existsSync(join(dir, 'SRC'))
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+}
+
+const SYMLINKS_SUPPORTED = detectSymlinkSupport()
+const CASE_INSENSITIVE_FS = detectCaseInsensitiveFs()
+
+test('findStoreRoot walks up to the directory holding .migrate', async () => {
+  await mkdir(join(root, '.migrate'), { recursive: true })
+  await mkdir(join(root, 'a', 'b'), { recursive: true })
+  expect(await findStoreRoot(join(root, 'a', 'b'))).toBe(root)
+})
+
+test('findStoreRoot returns null when there is no store', async () => {
+  await mkdir(join(root, 'a'), { recursive: true })
+  expect(await findStoreRoot(join(root, 'a'))).toBeNull()
+})
+
+test('storePaths puts every artifact under .migrate', () => {
+  const p = storePaths(root)
+  expect(p.config).toBe(join(root, '.migrate', 'config.toml'))
+  expect(p.elements).toBe(join(root, '.migrate', 'elements.jsonl'))
+  expect(p.queueDir).toBe(join(root, '.migrate', 'queue'))
+  expect(p.phases).toBe(join(root, '.migrate', 'phases.json'))
+})
+
+test('assertNotUnderSource rejects a path inside the source tree', async () => {
+  const source = join(root, 'legacy')
+  await expect(assertNotUnderSource(join(source, 'x.md'), source)).rejects.toThrow(/source/)
+  await expect(assertNotUnderSource(join(source, '..', 'out.md'), source)).resolves.toBeUndefined()
+})
+
+test('assertNotUnderSource is not fooled by a sibling with a shared prefix', async () => {
+  const source = join(root, 'legacy')
+  await expect(
+    assertNotUnderSource(join(root, 'legacy-notes', 'x.md'), source),
+  ).resolves.toBeUndefined()
+})
+
+test('assertNotUnderSource allows writes to the source parent directory', async () => {
+  const source = join(root, 'legacy')
+  await expect(assertNotUnderSource(root, source)).resolves.toBeUndefined()
+})
+
+// Important finding 1, bypass 1: a lexical-only comparison never resolves
+// symlinks, so a target reached only through a symlinked directory can
+// really land inside the source tree while comparing as "outside" on raw
+// path text. Here `.migrate` itself -- the exact shape named in the report
+// -- is a symlink into the source tree; storePaths' own path construction
+// (`join(root, '.migrate', 'elements.jsonl')`) is used verbatim so this
+// reproduces the real write path, not a synthetic one.
+test.skipIf(!SYMLINKS_SUPPORTED)(
+  'assertNotUnderSource follows a .migrate directory symlinked into the source tree',
+  async () => {
+    const source = join(root, 'legacy')
+    const insideSource = join(source, 'landing-zone')
+    await mkdir(insideSource, { recursive: true })
+    await symlink(insideSource, join(root, '.migrate'))
+    const target = storePaths(root).elements
+    await expect(assertNotUnderSource(target, source)).rejects.toThrow(/source/)
+  },
+)
+
+// Important finding 1, bypass 2: on a case-insensitive volume, a config
+// declaring the source at one case spelling and a store computed from a
+// project root spelled with a different case name the same physical
+// directory, but plain string comparison sees two unrelated paths. Skipped
+// cleanly (not failed) on a case-sensitive filesystem, where this scenario
+// cannot arise at all.
+test.skipIf(!CASE_INSENSITIVE_FS)(
+  'assertNotUnderSource is not fooled by a case-variant spelling of the source root',
+  async () => {
+    const declaredSource = join(root, 'ci', 'src')
+    await mkdir(declaredSource, { recursive: true })
+    const target = join(root, 'ci', 'SRC', '.migrate', 'elements.jsonl')
+    await expect(assertNotUnderSource(target, declaredSource)).rejects.toThrow(/source/)
+  },
+)
+
+// A write target need not exist yet -- that is the normal case for a store
+// file about to be created for the first time -- so the fix must resolve
+// containment from the nearest existing ancestor rather than requiring the
+// target itself to exist.
+test('assertNotUnderSource resolves containment even when the target does not exist yet', async () => {
+  const source = join(root, 'legacy')
+  await mkdir(source, { recursive: true })
+  const target = join(root, 'project', '.migrate', 'elements.jsonl')
+  await mkdir(join(root, 'project'), { recursive: true })
+  await expect(assertNotUnderSource(target, source)).resolves.toBeUndefined()
+})