@iceinvein/agent-skills 0.1.39 → 0.2.0

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

@@ -0,0 +1,183 @@
+import { afterEach, expect, test } from 'bun:test'
+import { mkdir, mkdtemp, realpath, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { errorMessage } from '../../bin/migrate.ts'
+
+const CLI = join(import.meta.dir, '..', '..', 'bin', 'migrate.ts')
+
+async function run(
+  args: string[],
+  opts: { cwd?: string } = {},
+): Promise<{ code: number; out: string; err: string }> {
+  const proc = Bun.spawn(['bun', CLI, ...args], {
+    stdout: 'pipe',
+    stderr: 'pipe',
+    ...(opts.cwd ? { cwd: opts.cwd } : {}),
+  })
+  const [out, err] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ])
+  await proc.exited
+  return { code: proc.exitCode ?? -1, out, err }
+}
+
+test('--help exits 0 and lists the subcommands', async () => {
+  const { code, out } = await run(['--help'])
+  expect(code).toBe(0)
+  for (const verb of ['init', 'import', 'census', 'queue', 'check', 'status', 'reset', 'report']) {
+    expect(out).toContain(verb)
+  }
+})
+
+test('no subcommand is a usage error', async () => {
+  const { code, err } = await run([])
+  expect(code).toBe(2)
+  expect(err).toContain('Usage')
+})
+
+test('unknown subcommand is a usage error naming the input', async () => {
+  const { code, err } = await run(['frobnicate'])
+  expect(code).toBe(2)
+  expect(err).toContain('frobnicate')
+})
+
+test('--version prints the package version', async () => {
+  const { code, out } = await run(['--version'])
+  expect(code).toBe(0)
+  expect(out.trim()).toMatch(/^migrate \d+\.\d+\.\d+$/)
+})
+
+// The central guard in main() (bin/migrate.ts): every handler calls
+// loadConfig without a try/catch of its own, so a missing or malformed
+// config.toml throws an Error that none of them classifies. Before the
+// guard, that Error escaped as a raw Bun stack trace (source snippet, "at
+// ..." frames, a non-deliberate exit code). The guard must turn that into
+// the same one-line, no-stack-trace diagnostic every handler already
+// produces for its own recognized failures, with a deliberate exit code:
+// 2, because the request could not be serviced at all (same class as "no
+// .migrate store found above the cwd"), not 1 (a well-formed request with
+// a bad answer).
+
+let guardRoot: string | undefined
+
+afterEach(async () => {
+  if (guardRoot) await rm(guardRoot, { recursive: true, force: true })
+  guardRoot = undefined
+})
+
+function looksLikeStackTrace(text: string): boolean {
+  return /\bat\s+\S+\s*\(?.*:\d+:\d+/.test(text) || text.includes('Bun v') || text.includes('^')
+}
+
+test('a missing config.toml is a clean diagnostic and exit 2, not a stack trace', async () => {
+  guardRoot = await realpath(await mkdtemp(join(tmpdir(), 'migrate-cli-guard-')))
+  await mkdir(join(guardRoot, '.migrate'), { recursive: true })
+  const { code, out, err } = await run(['check'], { cwd: guardRoot })
+  expect(code).toBe(2)
+  expect(out).toBe('')
+  expect(err).toBe(
+    `check: config.toml not found at ${join(guardRoot, '.migrate', 'config.toml')}; run 'migrate init' first\n`,
+  )
+  expect(looksLikeStackTrace(err)).toBe(false)
+})
+
+test('a malformed config.toml is a clean diagnostic and exit 2, not a stack trace', async () => {
+  guardRoot = await realpath(await mkdtemp(join(tmpdir(), 'migrate-cli-guard-')))
+  await mkdir(join(guardRoot, '.migrate'), { recursive: true })
+  await writeFile(join(guardRoot, '.migrate', 'config.toml'), '[source]\npath = "/tmp/legacy"\n')
+  const { code, err } = await run(['check'], { cwd: guardRoot })
+  expect(code).toBe(2)
+  expect(err).toBe('check: config.toml: missing or empty source.scope\n')
+  expect(looksLikeStackTrace(err)).toBe(false)
+})
+
+test('the guard is central: it also catches a bad config.toml for queue, not just check', async () => {
+  guardRoot = await realpath(await mkdtemp(join(tmpdir(), 'migrate-cli-guard-')))
+  await mkdir(join(guardRoot, '.migrate'), { recursive: true })
+  const { code, err } = await run(['queue', 'list'], { cwd: guardRoot })
+  expect(code).toBe(2)
+  expect(err).toContain('queue: config.toml not found')
+  expect(looksLikeStackTrace(err)).toBe(false)
+})
+
+test("the guard does not mask a well-formed request's own classified failure", async () => {
+  guardRoot = await realpath(await mkdtemp(join(tmpdir(), 'migrate-cli-guard-')))
+  const { code, err } = await run(['import', 'elements', 'nope.json'], { cwd: guardRoot })
+  // No .migrate store at all: findStoreRoot's own usage error fires before
+  // loadConfig is ever reached, so this exercises the pre-existing guard
+  // (findStoreRoot), not the new one, confirming the new guard did not
+  // change behaviour for a case already handled.
+  expect(code).toBe(2)
+  expect(err).toContain('import: no .migrate store found above the cwd')
+})
+
+// Minor finding 5: init, report and reset each parse a `--flag <value>`
+// pair, and used to disagree on what happens when the value slot is empty
+// or is itself another flag. `init --scope --name newapp` used to read
+// scope as the literal string '--name' and exit 0; `report --out` with
+// nothing after it used to fall back to the default directory in silence;
+// only `reset --phase` with no value at all was already a usage error. All
+// three now share one rule, reset's own shape: either shape of a bad value
+// is a usage error (2) naming the flag.
+
+test('init treats a flag value that is itself another flag as a usage error, not a swallowed value', async () => {
+  guardRoot = await realpath(await mkdtemp(join(tmpdir(), 'migrate-cli-flags-')))
+  const { code, err } = await run(['init', '--source', guardRoot, '--scope', '--name', 'newapp'], {
+    cwd: guardRoot,
+  })
+  expect(code).toBe(2)
+  expect(err).toContain('--scope needs a value')
+})
+
+test('report --out with no value is a usage error, not a silent fallback to the default directory', async () => {
+  guardRoot = await realpath(await mkdtemp(join(tmpdir(), 'migrate-cli-flags-')))
+  const { code, err } = await run(['report', '--out'], { cwd: guardRoot })
+  expect(code).toBe(2)
+  expect(err).toContain('--out needs a value')
+})
+
+test('reset --phase whose value is itself another flag is a usage error, matching a missing value', async () => {
+  guardRoot = await realpath(await mkdtemp(join(tmpdir(), 'migrate-cli-flags-')))
+  const { code, err } = await run(['reset', '--phase', '--out'], { cwd: guardRoot })
+  expect(code).toBe(2)
+  expect(err).toContain('--phase needs a value')
+})
+
+test('reset --phase with no value at all is still a usage error (unchanged)', async () => {
+  guardRoot = await realpath(await mkdtemp(join(tmpdir(), 'migrate-cli-flags-')))
+  const { code, err } = await run(['reset', '--phase'], { cwd: guardRoot })
+  expect(code).toBe(2)
+  expect(err).toContain('--phase needs a value')
+})
+
+test('reset with no --phase flag at all is a usage error naming the missing flag', async () => {
+  guardRoot = await realpath(await mkdtemp(join(tmpdir(), 'migrate-cli-flags-')))
+  const { code, err } = await run(['reset'], { cwd: guardRoot })
+  expect(code).toBe(2)
+  expect(err).toContain('missing --phase')
+})
+
+// Minor finding 6: the central guard's `(e as Error).message` printed the
+// useless "sub: undefined" for a non-Error rejection, and would have thrown
+// a TypeError from inside the catch itself for a rejected `null` or
+// `undefined` -- the one shape that would still have escaped uncaught.
+// `errorMessage` is the exact expression the guard now calls; exercised
+// directly here since nothing in this CLI's own handlers currently rejects
+// with anything but a real Error, so the failure mode this closes cannot
+// be reproduced by driving the CLI end-to-end.
+
+test('errorMessage returns the message of an Error instance', () => {
+  expect(errorMessage(new Error('boom'))).toBe('boom')
+})
+
+test('errorMessage converts a non-Error rejection to a string instead of printing undefined', () => {
+  expect(errorMessage('boom')).toBe('boom')
+  expect(errorMessage({ code: 'EBOOM' })).toBe('[object Object]')
+})
+
+test('errorMessage converts a null or undefined rejection without throwing a second error', () => {
+  expect(errorMessage(null)).toBe('null')
+  expect(errorMessage(undefined)).toBe('undefined')
+})

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

@@ -0,0 +1,164 @@
+import { afterEach, beforeEach, expect, test } from 'bun:test'
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+const CLI = join(import.meta.dir, '..', '..', 'bin', 'migrate.ts')
+
+const SURFACES = [
+  'routes',
+  'tables',
+  'jobs',
+  'reports',
+  'screens',
+  'integrations',
+  'workflows',
+  'settings',
+]
+
+let target: string
+let source: string
+
+async function migrate(args: string[]): Promise<{ code: number; out: string; err: string }> {
+  const proc = Bun.spawn(['bun', CLI, ...args], { cwd: target, stdout: 'pipe', stderr: 'pipe' })
+  const [out, err] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ])
+  await proc.exited
+  return { code: proc.exitCode ?? -1, out, err }
+}
+
+beforeEach(async () => {
+  target = await mkdtemp(join(tmpdir(), 'migrate-conc-'))
+  source = join(target, 'legacy')
+  await Bun.write(join(source, 'app.js'), '// legacy\n')
+  const init = await migrate([
+    'init',
+    '--source',
+    source,
+    '--scope',
+    'concurrency fixture',
+    '--name',
+    'target',
+  ])
+  expect(init.code).toBe(0)
+})
+
+afterEach(async () => {
+  await rm(target, { recursive: true, force: true })
+})
+
+// Eight concurrent importers, one per default surface type, because
+// (surface x lens) is exactly the fan-out unit the orchestration rules
+// mandate for phase 1. Before the store lock, each importer read the same
+// base elements.jsonl and whichever renamed last discarded every other
+// writer's rows, and each recordBatch clobbered the batch list the same way.
+test('eight concurrent imports lose no rows and no batch entries', async () => {
+  const files = await Promise.all(
+    SURFACES.map(async (surface, i) => {
+      const batch = `b-${surface}-code-00${i + 1}`
+      const path = join(target, `${batch}.json`)
+      await writeFile(
+        path,
+        JSON.stringify({
+          batch,
+          phase: 'enumerate',
+          rows: [
+            {
+              id: `${surface.replace(/s$/, '')}-one`,
+              surface,
+              element: `${surface} one`,
+              found_by: ['code'],
+              disposition: { kind: 'unaccounted' },
+              refs: [{ kind: 'src', path: 'app.js' }],
+              lens: 'code',
+              notes: '',
+            },
+            {
+              id: `${surface.replace(/s$/, '')}-two`,
+              surface,
+              element: `${surface} two`,
+              found_by: ['code'],
+              disposition: { kind: 'unaccounted' },
+              refs: [{ kind: 'src', path: 'app.js' }],
+              lens: 'code',
+              notes: '',
+            },
+          ],
+        }),
+      )
+      return { batch, path }
+    }),
+  )
+
+  const results = await Promise.all(files.map((f) => migrate(['import', 'elements', f.path])))
+  for (const r of results) expect(r.code).toBe(0)
+
+  const elements = (await readFile(join(target, '.migrate', 'elements.jsonl'), 'utf8'))
+    .split('\n')
+    .filter((l) => l.trim().length > 0)
+  expect(elements.length).toBe(SURFACES.length * 2)
+
+  const phases = JSON.parse(await readFile(join(target, '.migrate', 'phases.json'), 'utf8'))
+  const recorded = new Set((phases.phases.enumerate.batches as { id: string }[]).map((b) => b.id))
+  for (const f of files) expect(recorded.has(f.batch)).toBe(true)
+})
+
+test('a dead holder is refused with exit 3 and cleared by --force-unlock', async () => {
+  await writeFile(
+    join(target, '.migrate', '.lock'),
+    JSON.stringify({ pid: 999999, startedAt: '2026-08-07T02:58:03.000Z', cmd: 'import' }),
+  )
+  const batchPath = join(target, 'b-routes-code-001.json')
+  await writeFile(
+    batchPath,
+    JSON.stringify({
+      batch: 'b-routes-code-001',
+      phase: 'enumerate',
+      rows: [
+        {
+          id: 'route-one',
+          surface: 'routes',
+          element: 'GET /one',
+          found_by: ['code'],
+          disposition: { kind: 'unaccounted' },
+          refs: [{ kind: 'src', path: 'app.js' }],
+          lens: 'code',
+          notes: '',
+        },
+      ],
+    }),
+  )
+
+  const blocked = await migrate(['import', 'elements', batchPath])
+  expect(blocked.code).toBe(3)
+  expect(blocked.err).toContain('999999')
+  expect(blocked.err).toContain('--force-unlock')
+
+  const forced = await migrate(['import', 'elements', batchPath, '--force-unlock'])
+  expect(forced.code).toBe(0)
+})
+
+// Final-review finding, Important 3: `reset` does the same read-modify-write
+// over whole store files that import and census do -- it rewrites
+// elements.jsonl, census.jsonl and phases.json from what it read -- and was
+// the one such command with no lock and no lock.ts import at all. A command
+// that does not take the lock cannot report that it could not get it, so exit
+// 3 here is the whole assertion: before the fix both invocations below exited
+// 0 and cleared the store out from under whatever held the lock.
+test('reset refuses a dead holder with exit 3 and clears it with --force-unlock', async () => {
+  await writeFile(
+    join(target, '.migrate', '.lock'),
+    JSON.stringify({ pid: 999999, startedAt: '2026-08-07T02:58:03.000Z', cmd: 'import' }),
+  )
+
+  const blocked = await migrate(['reset', '--phase', 'enumerate'])
+  expect(blocked.code).toBe(3)
+  expect(blocked.err).toContain('999999')
+  expect(blocked.err).toContain('--force-unlock')
+
+  const forced = await migrate(['reset', '--phase', 'enumerate', '--force-unlock'])
+  expect(forced.code).toBe(0)
+  expect(forced.out).toContain('reset enumerate')
+})

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

@@ -0,0 +1,112 @@
+import { afterEach, beforeEach, expect, test } from 'bun:test'
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { DEFAULT_CLOSERS, DEFAULT_SURFACES, loadConfig, writeConfig } from '../config.ts'
+import { storePaths } from '../paths.ts'
+
+let root: string
+
+beforeEach(async () => {
+  root = await mkdtemp(join(tmpdir(), 'migrate-config-'))
+  await mkdir(join(root, '.migrate'), { recursive: true })
+})
+
+afterEach(async () => {
+  await rm(root, { recursive: true, force: true })
+})
+
+const MINIMAL = `[source]
+path = "/tmp/legacy"
+scope = "the whole thing"
+stack = "unknown"
+vcs = "none"
+basis = "source-only"
+
+[target]
+name = "newapp"
+stack = "bun + react"
+parity_test_path = "tests/parity/{capability}/{fr_slug}.test.ts"
+`
+
+test('loadConfig fills the default surface and closer sets', async () => {
+  await writeFile(storePaths(root).config, MINIMAL)
+  const cfg = await loadConfig(root)
+  expect(cfg.surfaces).toEqual([...DEFAULT_SURFACES])
+  expect(cfg.closers).toEqual([...DEFAULT_CLOSERS])
+  expect(cfg.source.path).toBe('/tmp/legacy')
+  expect(cfg.source.basis).toBe('source-only')
+})
+
+test('loadConfig honours a declared surface set', async () => {
+  await writeFile(
+    storePaths(root).config,
+    `${MINIMAL}\n[surfaces]\ntypes = ["programs", "copybooks"]\nsingular = { copybooks = "copybook" }\n`,
+  )
+  const cfg = await loadConfig(root)
+  expect(cfg.surfaces).toEqual(['programs', 'copybooks'])
+  expect(cfg.surfaceSingular.copybooks).toBe('copybook')
+})
+
+test('loadConfig fails with a diagnostic when a required key is missing', async () => {
+  await writeFile(storePaths(root).config, '[source]\npath = "/tmp/legacy"\n')
+  await expect(loadConfig(root)).rejects.toThrow(/source.scope/)
+})
+
+test('loadConfig fails with a diagnostic when the file is absent', async () => {
+  await expect(loadConfig(root)).rejects.toThrow(/config.toml/)
+})
+
+test('writeConfig then loadConfig round-trips', async () => {
+  await writeConfig(root, {
+    sourcePath: '/tmp/legacy',
+    scope: 'billing only',
+    targetName: 'newapp',
+  })
+  const cfg = await loadConfig(root)
+  expect(cfg.source.scope).toBe('billing only')
+  expect(cfg.target.name).toBe('newapp')
+  expect(cfg.source.stack).toBe('unknown')
+  expect(cfg.handoff.adapter).toBe('markdown')
+})
+
+// A hostile scope is operator-typed free text, not TOML syntax: writeConfig
+// must escape it so loadConfig reads back the exact bytes that were passed in,
+// rather than truncating the value, injecting a key, or leaving config.toml
+// unparseable for every later command.
+const HOSTILE_SCOPES: Array<[string, string]> = [
+  ['a quote that would otherwise close the string and inject a key', 'billing" evil = true #'],
+  ['a backslash that would otherwise start a TOML escape', 'billing\\team'],
+  ['a newline that would otherwise leave the string unterminated', 'billing\nrogue'],
+  ['a tab', 'billing\trogue'],
+  ['several hostile characters combined', 'billing" \\evil\t\n#more'],
+]
+
+for (const [label, scope] of HOSTILE_SCOPES) {
+  test(`writeConfig then loadConfig round-trips ${label} byte-identically`, async () => {
+    await writeConfig(root, { sourcePath: '/tmp/legacy', scope, targetName: 'newapp' })
+    const cfg = await loadConfig(root)
+    expect(cfg.source.scope).toBe(scope)
+  })
+}
+
+test('writeConfig round-trips a value containing backspace, form feed and delete', async () => {
+  const scope = `billing${String.fromCharCode(0x08)}${String.fromCharCode(0x0c)}${String.fromCharCode(0x7f)}rogue`
+  await writeConfig(root, { sourcePath: '/tmp/legacy', scope, targetName: 'newapp' })
+  const cfg = await loadConfig(root)
+  expect(cfg.source.scope).toBe(scope)
+})
+
+test('writeConfig refuses a value containing a control character it cannot represent', async () => {
+  const scope = `billing${String.fromCharCode(0x1b)}esc`
+  await expect(
+    writeConfig(root, { sourcePath: '/tmp/legacy', scope, targetName: 'newapp' }),
+  ).rejects.toThrow(/U\+001b/)
+})
+
+test('writeConfig does not fall prey to $-pattern replacement corruption', async () => {
+  const scope = 'cost$&$$center'
+  await writeConfig(root, { sourcePath: '/tmp/legacy', scope, targetName: 'newapp' })
+  const cfg = await loadConfig(root)
+  expect(cfg.source.scope).toBe(scope)
+})