@iceinvein/agent-skills 0.1.39 → 0.2.0

package/skills/migrate/scripts/config.ts

@@ -0,0 +1,237 @@
+import { readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { storePaths } from './paths.ts'
+
+export const DEFAULT_SURFACES: readonly string[] = [
+  'routes',
+  'tables',
+  'jobs',
+  'reports',
+  'screens',
+  'integrations',
+  'workflows',
+  'settings',
+]
+
+export const DEFAULT_CLOSERS: readonly string[] = [
+  'cross-capability-workflow',
+  'scope-injection',
+  'read-write-symmetry',
+]
+
+export type Config = {
+  source: {
+    path: string
+    scope: string
+    stack: string
+    vcs: string
+    basis: 'runnable' | 'source-only'
+  }
+  target: {
+    name: string
+    stack: string
+    parity_test_path: string
+    layout: Record<string, string>
+    commands: Record<string, string>
+  }
+  surfaces: string[]
+  surfaceSingular: Record<string, string>
+  closers: string[]
+  handoff: { adapter: string }
+}
+
+export type ConfigInit = {
+  sourcePath: string
+  scope: string
+  targetName: string
+  sourceStack?: string
+  targetStack?: string
+  vcs?: string
+  basis?: 'runnable' | 'source-only'
+}
+
+// Values substituted into the TOML template come from operator-typed free text
+// (--scope, --name, and friends), not from anything shaped like TOML syntax. A
+// quote, a backslash, a newline, or a control character must round-trip through
+// loadConfig byte-identical, not be interpreted as TOML escape/string syntax.
+//
+// Bun.TOML.parse (verified directly against Bun 1.3.14) has two quirks that
+// shape this function:
+//   1. The named escapes for tab and form feed decode swapped: writing the
+//      tab escape reads back as the form feed code point, and vice versa.
+//      Tab is therefore emitted as a literal character rather than escaped
+//      (the TOML spec permits a raw, unescaped tab inside a basic string, and
+//      Bun reads that back correctly), and form feed is emitted via a
+//      four-hex-digit unicode escape instead of its named escape.
+//   2. A four-hex-digit unicode escape only decodes correctly for the C0
+//      control codes that coincide with a named escape (backspace, tab,
+//      newline, form feed, carriage return) and for the delete character;
+//      every other C0 control fails to parse back at all, named or
+//      unicode-escaped, so a config.toml written with one of those bytes
+//      could never be read again. Those bytes cannot occur from real CLI
+//      text (a NUL byte cannot even survive in argv), so rather than
+//      silently write a store loadConfig can never reopen, this rejects
+//      them with a clear diagnostic instead.
+const TOML_NAMED_ESCAPES: Record<string, string> = {
+  '\\': '\\\\',
+  '"': '\\"',
+  '\b': '\\b',
+  '\n': '\\n',
+  '\r': '\\r',
+}
+
+const FORM_FEED = String.fromCharCode(0x0c)
+const DEL = String.fromCharCode(0x7f)
+
+// Every C0 control other than tab (code point 9) must be escaped in a TOML
+// basic string. Tab, newline, carriage return and backspace are excluded from
+// this set because they are handled above; form feed and delete are excluded
+// because they are handled via a working unicode escape just below. What
+// remains is what Bun's TOML reader cannot represent by any means. Built from
+// explicit code points, rather than a literal character class, so no raw
+// control bytes sit in this source file.
+const UNREPRESENTABLE_CODES = [
+  0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x0b, 0x0e, 0x0f, 0x10, 0x11, 0x12, 0x13, 0x14,
+  0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
+]
+const UNREPRESENTABLE = new Set(UNREPRESENTABLE_CODES)
+
+function escapeTomlString(value: string, where: string): string {
+  let out = ''
+  for (const ch of value) {
+    const code = ch.codePointAt(0) ?? 0
+    if (UNREPRESENTABLE.has(code)) {
+      throw new Error(
+        `config.toml: ${where} contains U+${code.toString(16).padStart(4, '0')}, ` +
+          'a control character this store cannot represent in config.toml',
+      )
+    }
+    if (ch === '\t') {
+      // Literal tab: legal unescaped in a TOML basic string, and the one
+      // representation Bun's reader decodes correctly (see note above).
+      out += ch
+      continue
+    }
+    if (ch === FORM_FEED) {
+      out += '\\u000c'
+      continue
+    }
+    if (ch === DEL) {
+      out += '\\u007f'
+      continue
+    }
+    out += TOML_NAMED_ESCAPES[ch] ?? ch
+  }
+  return out
+}
+
+// A plain replaceAll(placeholder, replacement) treats a $-pattern inside the
+// replacement string as a substitution directive (`$&`, `$$`, `$'`, ...), even
+// though the placeholder is a literal string, not a regex. A callback
+// replacement is used verbatim instead, so an escaped value that happens to
+// contain a dollar sign cannot reintroduce corruption after escaping removed
+// the TOML-specific risk.
+function substitute(text: string, placeholder: string, value: string): string {
+  return text.replaceAll(placeholder, () => value)
+}
+
+function req(obj: Record<string, unknown> | undefined, key: string, where: string): string {
+  const value = obj?.[key]
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`config.toml: missing or empty ${where}.${key}`)
+  }
+  return value
+}
+
+export async function loadConfig(root: string): Promise<Config> {
+  const path = storePaths(root).config
+  let text: string
+  try {
+    text = await readFile(path, 'utf8')
+  } catch {
+    throw new Error(`config.toml not found at ${path}; run 'migrate init' first`)
+  }
+  const raw = Bun.TOML.parse(text) as Record<string, Record<string, unknown> | undefined>
+  const source = raw.source
+  const target = raw.target
+  const sourcePath = req(source, 'path', 'source')
+  const sourceScope = req(source, 'scope', 'source')
+  const sourceStack = req(source, 'stack', 'source')
+  const sourceVcs = req(source, 'vcs', 'source')
+  const basis = req(source, 'basis', 'source')
+  if (basis !== 'runnable' && basis !== 'source-only') {
+    throw new Error(`config.toml: source.basis must be runnable or source-only, got ${basis}`)
+  }
+  const surfacesTable = raw.surfaces
+  const declared = surfacesTable?.types
+  const singular = (surfacesTable?.singular ?? {}) as Record<string, string>
+  const closersTable = raw.closers
+  const declaredClosers = closersTable?.set
+  const handoffTable = raw.handoff
+
+  return {
+    source: {
+      path: sourcePath,
+      scope: sourceScope,
+      stack: sourceStack,
+      vcs: sourceVcs,
+      basis,
+    },
+    target: {
+      name: req(target, 'name', 'target'),
+      stack: req(target, 'stack', 'target'),
+      parity_test_path: req(target, 'parity_test_path', 'target'),
+      layout: (target?.layout ?? {}) as Record<string, string>,
+      commands: (target?.commands ?? {}) as Record<string, string>,
+    },
+    surfaces: Array.isArray(declared) ? (declared as string[]) : [...DEFAULT_SURFACES],
+    surfaceSingular: singular,
+    closers: Array.isArray(declaredClosers) ? (declaredClosers as string[]) : [...DEFAULT_CLOSERS],
+    handoff: { adapter: (handoffTable?.adapter as string | undefined) ?? 'markdown' },
+  }
+}
+
+export async function writeConfig(root: string, init: ConfigInit): Promise<void> {
+  const templatePath = join(import.meta.dir, '..', 'templates', 'config.toml')
+  const template = await readFile(templatePath, 'utf8')
+  let rendered = template
+  rendered = substitute(
+    rendered,
+    '{{SOURCE_PATH}}',
+    escapeTomlString(init.sourcePath, 'source.path'),
+  )
+  rendered = substitute(rendered, '{{SCOPE}}', escapeTomlString(init.scope, 'source.scope'))
+  rendered = substitute(
+    rendered,
+    '{{SOURCE_STACK}}',
+    escapeTomlString(init.sourceStack ?? 'unknown', 'source.stack'),
+  )
+  rendered = substitute(rendered, '{{VCS}}', escapeTomlString(init.vcs ?? 'none', 'source.vcs'))
+  rendered = substitute(
+    rendered,
+    '{{BASIS}}',
+    escapeTomlString(init.basis ?? 'source-only', 'source.basis'),
+  )
+  rendered = substitute(
+    rendered,
+    '{{TARGET_NAME}}',
+    escapeTomlString(init.targetName, 'target.name'),
+  )
+  rendered = substitute(
+    rendered,
+    '{{TARGET_STACK}}',
+    escapeTomlString(init.targetStack ?? 'unknown', 'target.stack'),
+  )
+  // Deliberately a plain writeFile, not writeAtomically. Routing it through
+  // that helper would make writeConfig itself refuse to render a config whose
+  // declared source.path contains the store, which sounds right but is the
+  // wrong layer for the decision: this function renders a declaration, and
+  // whether the declaration is usable is init-cmd.ts's call, made there
+  // against all three of init's write targets before anything is created.
+  // Putting the refusal here as well would also make the one state those
+  // downstream guards exist for -- a config.toml hand-edited after the fact to
+  // point at a source containing its own store -- unconstructible through this
+  // API, and it is that hand-edit, not init, that reaches them in practice.
+  // The containment invariant still holds: init-cmd.ts guards this path.
+  await writeFile(storePaths(root).config, rendered)
+}

package/skills/migrate/scripts/ids.ts

@@ -0,0 +1,31 @@
+const SLUG = /^[a-z0-9]+(-[a-z0-9]+)*$/
+
+export function singularOf(surface: string, overrides: Record<string, string>): string {
+  const override = overrides[surface]
+  if (override) return override
+  return surface.endsWith('s') ? surface.slice(0, -1) : surface
+}
+
+export function idPrefixFor(surface: string, overrides: Record<string, string>): string {
+  return `${singularOf(surface, overrides)}-`
+}
+
+export function isValidSlug(s: string): boolean {
+  return SLUG.test(s)
+}
+
+export function validateElementId(
+  id: string,
+  surface: string,
+  overrides: Record<string, string>,
+): string | null {
+  const prefix = idPrefixFor(surface, overrides)
+  if (!id.startsWith(prefix)) {
+    return `id ${id} does not start with ${prefix} (surface ${surface})`
+  }
+  const slug = id.slice(prefix.length)
+  if (!isValidSlug(slug)) {
+    return `id ${id} has an invalid slug after ${prefix}: want lowercase kebab-case`
+  }
+  return null
+}

package/skills/migrate/scripts/import-cmd.ts

@@ -0,0 +1,141 @@
+import { loadConfig } from './config.ts'
+import { LockError, withStoreLock } from './lock.ts'
+import { assertNotUnderSource, storePaths } from './paths.ts'
+import { isPhase, recordBatch } from './phases.ts'
+import { readJsonFile, readRows, upsertRows, writeRows } from './store.ts'
+import type { Delta, Element, Requirement } from './types.ts'
+import { validateDelta, validateElement, validateRequirement } from './validate.ts'
+
+export type ImportKind = 'elements' | 'reqs' | 'deltas'
+
+type BatchFile = { batch?: string; phase?: string; rows?: unknown[] }
+
+export async function runImport(opts: {
+  root: string
+  kind: ImportKind
+  batchFile: string
+  forceUnlock?: boolean
+}): Promise<number> {
+  const cfg = await loadConfig(opts.root)
+  let raw: unknown
+  try {
+    raw = await readJsonFile(opts.batchFile)
+  } catch (e) {
+    // Not shaped like a batch file at all (missing, or not valid JSON): a
+    // malformed request, same class as the missing-field check just below.
+    process.stderr.write(`import: ${(e as Error).message}\n`)
+    return 2
+  }
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+    process.stderr.write('import: batch file needs {"batch": id, "phase": name, "rows": [...]}\n')
+    return 2
+  }
+  const parsed = raw as BatchFile
+  const batchId = parsed.batch
+  const phase = parsed.phase
+  if (!batchId || !phase || !Array.isArray(parsed.rows)) {
+    process.stderr.write('import: batch file needs {"batch": id, "phase": name, "rows": [...]}\n')
+    return 2
+  }
+  if (!isPhase(phase)) {
+    process.stderr.write(`import: unknown phase ${phase}\n`)
+    return 2
+  }
+
+  const errors: string[] = []
+  const validated: ({ id: string; batch: string } & Record<string, unknown>)[] = []
+  for (const row of parsed.rows) {
+    const result =
+      opts.kind === 'elements'
+        ? validateElement(row, cfg)
+        : opts.kind === 'reqs'
+          ? validateRequirement(row, cfg)
+          : validateDelta(row, cfg)
+    if (result.ok) {
+      validated.push({ ...(result.value as object), batch: batchId } as never)
+    } else {
+      errors.push(...result.errors)
+    }
+  }
+
+  // A repeated id within one batch is an authoring error: keeping the last one
+  // silently would discard a row nobody was told about. Name every id that
+  // recurs so the whole batch is refused under the all-or-nothing rule below.
+  const idCounts = new Map<string, number>()
+  for (const row of validated) {
+    idCounts.set(row.id, (idCounts.get(row.id) ?? 0) + 1)
+  }
+  for (const [id, count] of idCounts) {
+    if (count > 1) errors.push(`batch: id ${id} appears ${count} times in this batch`)
+  }
+
+  // All or nothing. A partially-written batch is a store an agent cannot reason
+  // about on resume: the batch id would claim rows that are not all there.
+  if (errors.length > 0) {
+    for (const e of errors) process.stderr.write(`import: ${e}\n`)
+    process.stderr.write(`import: ${errors.length} error(s), nothing written\n`)
+    return 1
+  }
+
+  const paths = storePaths(opts.root)
+  const target =
+    opts.kind === 'elements'
+      ? paths.elements
+      : opts.kind === 'reqs'
+        ? paths.requirements
+        : paths.deltas
+  try {
+    await assertNotUnderSource(target, cfg.source.path)
+  } catch (e) {
+    // A store whose configured source.path resolves to include its own
+    // target path (e.g. source.path: '.') can never be written to, for any
+    // batch content whatsoever: an environment/config problem, invariant
+    // across every possible row, not a property of this batch's data. Same
+    // usage-error class as "no .migrate store found above the cwd" and
+    // "config.toml not found" elsewhere in this CLI, not a batch-content
+    // failure (1).
+    process.stderr.write(`import: ${(e as Error).message}\n`)
+    return 2
+  }
+
+  // The read, the upsert, the rewrite, and the batch record are one critical
+  // section. Splitting them lets a second importer read this one's base,
+  // rewrite the file from it, and silently drop every row written in between.
+  let merged: { added: number; updated: number }
+  try {
+    merged = await withStoreLock(
+      opts.root,
+      async () => {
+        const existing = await readRows<Element | Requirement | Delta>(target)
+        const result = upsertRows(existing as { id: string }[], validated)
+        await writeRows(target, result.rows, cfg.source.path)
+        await recordBatch(
+          opts.root,
+          phase,
+          { id: batchId, count: validated.length },
+          cfg.source.path,
+        )
+        return { added: result.added, updated: result.updated }
+      },
+      {
+        cmd: 'import',
+        ...(opts.forceUnlock ? { force: true } : {}),
+        onWait: (m) => process.stderr.write(`import: ${m}\n`),
+      },
+    )
+  } catch (e) {
+    // A lock failure is neither bad batch content (1) nor a malformed request
+    // (2): the request is fine and would succeed on retry, so it gets its own
+    // class a caller can branch on.
+    if (e instanceof LockError) {
+      process.stderr.write(`import: ${e.message}\n`)
+      return 3
+    }
+    throw e
+  }
+
+  process.stdout.write(
+    `import ${opts.kind}: ${merged.added} added, ${merged.updated} updated, batch ${batchId}\n`,
+  )
+  return 0
+}

package/skills/migrate/scripts/init-cmd.ts

@@ -0,0 +1,118 @@
+import { existsSync, statSync } from 'node:fs'
+import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises'
+import { isAbsolute, join, resolve } from 'node:path'
+import { writeConfig } from './config.ts'
+import { assertNotUnderSource, storePaths } from './paths.ts'
+
+const ENV_IGNORE = '.migrate/.env'
+
+// A real ignore entry is a whole line, not any line containing the string as a
+// substring: a comment mentioning the path, or an unrelated deeper path such as
+// foo/.migrate/.env, must not be mistaken for the real entry.
+function gitignoreListsEnvFile(text: string): boolean {
+  return text.split('\n').some((line) => {
+    const trimmed = line.trim()
+    return trimmed.length > 0 && !trimmed.startsWith('#') && trimmed === ENV_IGNORE
+  })
+}
+
+export async function runInit(opts: {
+  root: string
+  sourcePath: string
+  scope: string
+  targetName: string
+  sourceStack?: string
+  targetStack?: string
+  vcs?: string
+  basis?: string
+}): Promise<number> {
+  const sourcePath = isAbsolute(opts.sourcePath) ? opts.sourcePath : resolve(opts.sourcePath)
+  if (!existsSync(sourcePath)) {
+    process.stderr.write(`init: source path does not exist: ${sourcePath}\n`)
+    return 2
+  }
+  if (!statSync(sourcePath).isDirectory()) {
+    process.stderr.write(`init: source path is not a directory: ${sourcePath}\n`)
+    return 2
+  }
+  const basis = opts.basis ?? 'source-only'
+  if (basis !== 'runnable' && basis !== 'source-only') {
+    process.stderr.write(`init: --basis must be runnable or source-only, got ${basis}\n`)
+    return 2
+  }
+
+  const paths = storePaths(opts.root)
+  const gitignore = join(opts.root, '.gitignore')
+
+  // Every other command reaches the source path through a store that already
+  // exists, so its writers inherit the containment guard from the helper they
+  // write through. `init` is the command that creates that store, and it had
+  // no guard at all: pointing --source at a directory containing the target
+  // produced a config.toml, a queue directory and a .gitignore edit inside the
+  // read-only source tree, after which every later command exited 2 on the
+  // guard those writers do have. The user was left with a store nothing could
+  // write to, three shipped documents having promised this was impossible.
+  //
+  // All three write targets are checked here, before anything is created, so a
+  // refusal leaves the tree exactly as it was found rather than half-built.
+  // Reported and returned rather than thrown, matching how import-cmd.ts and
+  // census-cmd.ts already classify this same refusal: a request that could
+  // never be serviced as posed is a usage error (2), not a content failure.
+  // The check runs ahead of the existing-config check below because a config
+  // already sitting inside the source tree is itself the wreckage of this bug,
+  // and "that store can never work" is the more useful thing to say about it
+  // than "that file is already there".
+  for (const target of [paths.config, paths.queueDir, gitignore]) {
+    try {
+      await assertNotUnderSource(target, sourcePath)
+    } catch (e) {
+      process.stderr.write(`init: ${(e as Error).message}\n`)
+      return 2
+    }
+  }
+
+  if (existsSync(paths.config)) {
+    process.stderr.write(`init: ${paths.config} already exists; edit it or remove it first\n`)
+    return 1
+  }
+
+  await mkdir(paths.queueDir, { recursive: true })
+  await writeConfig(opts.root, {
+    sourcePath,
+    scope: opts.scope,
+    targetName: opts.targetName,
+    ...(opts.sourceStack ? { sourceStack: opts.sourceStack } : {}),
+    ...(opts.targetStack ? { targetStack: opts.targetStack } : {}),
+    vcs: opts.vcs ?? (existsSync(join(sourcePath, '.git')) ? 'git' : 'none'),
+    basis,
+  })
+
+  process.stdout.write(`init: wrote ${paths.config}\n`)
+
+  // The append branch used to be the whole of this: a target repo with no
+  // .gitignore of its own got no ignore entry, so the first `git add -A` of
+  // the run staged .migrate/.env -- the one file in the store most likely to
+  // hold credentials, in the one place (a fresh target, first commit) where
+  // nobody has looked at the ignore rules yet. The `leaks` gate that would
+  // catch the committed result is opt-in, so nothing else stands behind this.
+  // Creating the file closes that.
+  //
+  // Both branches say what they did on stdout. init writing or editing a file
+  // outside .migrate/ that the caller did not name is worth one line either
+  // way; a silent edit to a .gitignore the caller already maintains is no more
+  // discoverable than a silent creation.
+  if (existsSync(gitignore)) {
+    const text = await readFile(gitignore, 'utf8')
+    if (!gitignoreListsEnvFile(text)) {
+      const prefix = text.endsWith('\n') || text.length === 0 ? '' : '\n'
+      await appendFile(gitignore, `${prefix}${ENV_IGNORE}\n`)
+      process.stdout.write(`init: appended ${ENV_IGNORE} to ${gitignore}\n`)
+    }
+  } else {
+    await writeFile(gitignore, `${ENV_IGNORE}\n`)
+    process.stdout.write(`init: created ${gitignore} with ${ENV_IGNORE}\n`)
+  }
+
+  process.stdout.write('next: run the enumerate phase, then `migrate check`\n')
+  return 0
+}