@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/engineering/resolve-release/scripts/npm-version-absence.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+// Read-only observation, not a reservation or publication authorization.
+import { spawnSync } from 'node:child_process'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+import { parseYamlMapping } from '../../engineering-runtime/scripts/yaml-mapping.mjs'
+
+const TIMEOUT_MS = 30_000
+const OUTPUT_LIMIT = 1024 * 1024
+const INVALID_ARGUMENTS = 'npm-version-absence: invalid arguments'
+
+function validate({ packageName, version, registry, cwd }) {
+  const namePattern = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/
+  if (typeof packageName !== 'string' || packageName.length > 214
+    || /\s/.test(packageName) || !namePattern.test(packageName)
+    || ['node_modules', 'favicon.ico'].includes(packageName)) throw new Error(INVALID_ARGUMENTS)
+  if (typeof version !== 'string' || /\s/.test(version)
+    || !/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(version)
+    || !version.split('.').every((part) => Number.isSafeInteger(Number(part)))) throw new Error(INVALID_ARGUMENTS)
+  if (typeof registry !== 'string' || /[\s\x00-\x20\x7f]/.test(registry)
+    || !/^https:\/\/[^/?#@\\]+(?:\/[^?#\\]*)?$/i.test(registry)) throw new Error(INVALID_ARGUMENTS)
+  try {
+    const url = new URL(registry)
+    if (url.protocol !== 'https:' || !url.hostname || url.username || url.password || url.search || url.hash) {
+      throw new Error(INVALID_ARGUMENTS)
+    }
+  } catch {
+    throw new Error(INVALID_ARGUMENTS)
+  }
+  if (typeof cwd !== 'string' || !cwd || cwd.includes('\0')) throw new Error(INVALID_ARGUMENTS)
+}
+
+export function probeNpmVersionAbsence(options = {}) {
+  if (!options || typeof options !== 'object' || Array.isArray(options)) throw new Error(INVALID_ARGUMENTS)
+  const { packageName, version, registry, cwd = process.cwd() } = options
+  validate({ packageName, version, registry, cwd })
+  const observation = (status, reason) => ({
+    status, packageName, version, registry, observedAt: new Date().toISOString(), reason,
+  })
+  let result
+  try {
+    result = spawnSync('npm', ['view', `${packageName}@${version}`, 'version', `--registry=${registry}`, '--json'], {
+      cwd,
+      timeout: TIMEOUT_MS,
+      maxBuffer: OUTPUT_LIMIT,
+      killSignal: 'SIGKILL',
+      shell: false,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+  } catch {
+    return observation('inconclusive', 'process-error')
+  }
+  if (result.error || result.signal || result.status === null
+    || Buffer.byteLength(result.stdout || '') + Buffer.byteLength(result.stderr || '') > OUTPUT_LIMIT) {
+    return observation('inconclusive', 'process-error')
+  }
+  let stdout, stderr
+  try {
+    const decoder = new TextDecoder('utf-8', { fatal: true })
+    stdout = decoder.decode(result.stdout || new Uint8Array()).trim()
+    stderr = decoder.decode(result.stderr || new Uint8Array())
+  } catch {
+    return observation('inconclusive', 'unexpected-response')
+  }
+  const codes = []
+  let affirmativeE404 = false
+  for (const channel of [stdout, stderr]) {
+    let value = channel.trim()
+    const structured = /^(?:\{|\[|")/.test(value)
+    if (structured) {
+      try {
+        value = JSON.parse(value)
+      } catch {
+        return observation('inconclusive', 'unexpected-response')
+      }
+      try {
+        // JSON owns syntax; the strict mapping parser refuses duplicate keys at any depth.
+        // Wrapping permits string and array documents without a second parsing implementation.
+        parseYamlMapping(`{"document":${channel.trim()}}`)
+      } catch {
+        return observation('inconclusive', result.status === 0 ? 'unexpected-response' : 'npm-error')
+      }
+    } else if (/[{}\[\]"]/.test(value)) {
+      // Never salvage JSON fragments from a text-prefixed or otherwise mixed channel.
+      return observation('inconclusive', 'unexpected-response')
+    }
+    if (structured && result.status !== 0) {
+      if (!value || typeof value !== 'object' || Array.isArray(value)
+        || !value.error || typeof value.error !== 'object' || Array.isArray(value.error)
+        || !Object.hasOwn(value.error, 'code')) return observation('inconclusive', 'npm-error')
+      affirmativeE404 ||= value.error.code === 'E404'
+    } else if (!structured) {
+      affirmativeE404 ||= value === 'E404'
+        || /^npm[ \t]+(?:error|ERR!)[ \t]+code[ \t]+E404[ \t]*$/m.test(value)
+    }
+    const pending = [value]
+    while (pending.length) {
+      const item = pending.pop()
+      if (item && typeof item === 'object') {
+        for (const [key, child] of Object.entries(item)) {
+          if (key === 'code') codes.push(child)
+          pending.push(key, child)
+        }
+      } else if (typeof item === 'string') {
+        // ERR! is npm's legacy log prefix, not an error code.
+        codes.push(...(item.replace(/\bnpm\s+ERR!/g, '').match(/\bE[A-Z0-9_]+\b/g) || []))
+        for (const match of item.matchAll(/\bnpm[ \t]+(?:error|ERR!)[ \t]+code\b([^\r\n]*)/g)) codes.push(match[1].trim())
+      }
+    }
+  }
+  if (result.status === 1 && affirmativeE404 && codes.includes('E404') && codes.every((code) => code === 'E404')) {
+    return observation('absent', 'version-absent')
+  }
+  if (result.status !== 0) return observation('inconclusive', 'npm-error')
+  let observedVersion = stdout
+  try { observedVersion = JSON.parse(stdout) } catch { /* npm also supports a bare version. */ }
+  if (observedVersion === version && codes.length === 0) return observation('present', 'version-present')
+  return observation('inconclusive', 'unexpected-response')
+}
+
+export function main(argv = process.argv.slice(2)) {
+  try {
+    const fields = new Map([['--package', 'packageName'], ['--version', 'version'], ['--registry', 'registry']])
+    const options = {}
+    for (let i = 0; i < argv.length; i += 2) {
+      const field = fields.get(argv[i])
+      if (!field || Object.hasOwn(options, field) || typeof argv[i + 1] !== 'string') throw new Error(INVALID_ARGUMENTS)
+      options[field] = argv[i + 1]
+    }
+    const result = probeNpmVersionAbsence(options)
+    process.stdout.write(`${JSON.stringify(result)}\n`)
+    return result.status === 'absent' ? 0 : result.status === 'present' ? 1 : 2
+  } catch {
+    process.stderr.write(`${INVALID_ARGUMENTS}\n`)
+    return 2
+  }
+}
+
+if (isMainModule(import.meta.url)) process.exitCode = main()

package/skills/engineering/resolve-release/scripts/npm-version-absence.test.mjs

@@ -0,0 +1,426 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { spawnSync } from 'node:child_process'
+import { mkdtempSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { probeNpmVersionAbsence } from './npm-version-absence.mjs'
+
+const script = fileURLToPath(new URL('./npm-version-absence.mjs', import.meta.url))
+const request = { packageName: '@example/widget', version: '1.2.3', registry: 'https://registry.example.test/custom/npm/' }
+const leakMarker = 'PRIVATE_CREDENTIAL_PAYLOAD_DO_NOT_FORWARD'
+
+function fixture(t) {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), 'npm-version-absence-')))
+  const bin = join(root, 'bin')
+  const cwd = join(root, 'work')
+  const calls = join(root, 'calls.jsonl')
+  mkdirSync(bin)
+  mkdirSync(cwd)
+  const savedEnv = { ...process.env }
+  t.after(() => {
+    process.env = savedEnv
+    rmSync(root, { recursive: true, force: true })
+  })
+  process.env.PATH = bin
+  process.env.FAKE_NPM_CALLS = calls
+  process.env.FAKE_NPM_REPLY = JSON.stringify({ stderr: 'npm error code E404', exitCode: 1 })
+  process.env.npm_config_registry = 'https://ambient-registry.example.test/ignored/'
+  const executable = `#!${process.execPath}
+const fs = require('node:fs')
+fs.appendFileSync(process.env.FAKE_NPM_CALLS, JSON.stringify({ argv: process.argv.slice(2), cwd: process.cwd() }) + '\\n')
+const reply = JSON.parse(process.env.FAKE_NPM_REPLY)
+fs.writeSync(1, reply.stdout || '')
+fs.writeSync(2, reply.stderr || '')
+if (reply.stdoutHex) fs.writeSync(1, Buffer.from(reply.stdoutHex, 'hex'))
+if (reply.stderrHex) fs.writeSync(2, Buffer.from(reply.stderrHex, 'hex'))
+for (const [fd, size] of [[1, reply.stdoutBytes], [2, reply.stderrBytes]]) {
+  let remaining = size || 0
+  while (remaining > 0) {
+    const chunk = Buffer.alloc(Math.min(8192, remaining), ' ')
+    remaining -= fs.writeSync(fd, chunk)
+  }
+}
+if (reply.signal) process.kill(process.pid, reply.signal)
+process.exit(reply.exitCode ?? 0)
+`
+  writeFileSync(join(bin, 'npm'), executable, { mode: 0o755 })
+  for (const command of ['git', 'gh', 'gcloud', 'curl', 'wget', 'touch']) {
+    writeFileSync(join(bin, command), `#!${process.execPath}
+require('node:fs').appendFileSync(process.env.FAKE_NPM_CALLS, JSON.stringify({ forbiddenCommand: ${JSON.stringify(command)}, argv: process.argv.slice(2) }) + '\\n')
+process.exit(91)
+`, { mode: 0o755 })
+  }
+  t.mock.timers.enable({ apis: ['Date'], now: Date.UTC(2030, 0, 2) })
+  return {
+    root, bin, cwd,
+    reply(value) { process.env.FAKE_NPM_REPLY = JSON.stringify(value) },
+    calls() {
+      try { return readFileSync(calls, 'utf8').trim().split('\n').map((line) => JSON.parse(line)) }
+      catch (error) { if (error.code === 'ENOENT') return []; throw error }
+    },
+    probe(overrides = {}) { return probeNpmVersionAbsence({ ...request, cwd, ...overrides }) },
+    cli(args = ['--package', request.packageName, '--version', request.version, '--registry', request.registry]) {
+      return spawnSync(process.execPath, [script, ...args], { cwd, env: process.env, encoding: 'utf8', timeout: 40_000 })
+    },
+  }
+}
+
+function checkResult(result, status, reason, input = request) {
+  assert.deepEqual(Object.keys(result).sort(), ['status', 'packageName', 'version', 'registry', 'observedAt', 'reason'].sort())
+  assert.equal(result.status, status)
+  assert.equal(result.reason, reason)
+  assert.equal(result.packageName, input.packageName)
+  assert.equal(result.version, input.version)
+  assert.equal(result.registry, input.registry)
+  assert.equal(new Date(result.observedAt).toISOString(), result.observedAt)
+  assert.equal(JSON.stringify(result).includes(leakMarker), false)
+}
+
+test('clean E404 observes absence through one read-only npm argv with explicit scoped registry', (t) => {
+  const f = fixture(t)
+  checkResult(f.probe(), 'absent', 'version-absent')
+  assert.deepEqual(f.calls(), [{
+    argv: ['view', '@example/widget@1.2.3', 'version', '--registry=https://registry.example.test/custom/npm/', '--json'],
+    cwd: f.cwd,
+  }])
+  assert.deepEqual(readdirSync(f.cwd), [])
+})
+
+const responses = [
+  ['plain E404 on stdout', { stdout: 'npm ERR! code E404\n', exitCode: 1 }, 'absent', 'version-absent'],
+  ['JSON E404', { stdout: '{"error":{"code":"E404","summary":"Not found","detail":""}}', exitCode: 1 }, 'absent', 'version-absent'],
+  ['JSON E404 with matching stderr', { stdout: '{"error":{"code":"E404"}}', stderr: 'npm error code E404', exitCode: 1 }, 'absent', 'version-absent'],
+  ['bare E404 on stderr', { stderr: 'E404', exitCode: 1 }, 'absent', 'version-absent'],
+  ['JSON E404 on stderr', { stderr: '{"error":{"code":"E404"}}', exitCode: 1 }, 'absent', 'version-absent'],
+  ['escaped JSON E404 code', { stdout: '{"error":{"co\\u0064e":"E\\u0034\\u0030\\u0034"}}', exitCode: 1 }, 'absent', 'version-absent'],
+  ['E404 with exit 2', { stderr: 'npm error code E404', exitCode: 2 }, 'inconclusive', 'npm-error'],
+  ['E404 with exit 7', { stderr: 'npm error code E404', exitCode: 7 }, 'inconclusive', 'npm-error'],
+  ['empty nonzero', { exitCode: 1 }, 'inconclusive', 'npm-error'],
+  ['unknown nonzero', { stderr: 'Something failed', exitCode: 42 }, 'inconclusive', 'npm-error'],
+  ['non-code E404 substring', { stderr: 'NOT_E404 or E404suffix', exitCode: 1 }, 'inconclusive', 'npm-error'],
+  ['E404 with unknown named code', { stderr: 'npm error code E404\nnpm error code UNKNOWN', exitCode: 1 }, 'inconclusive', 'npm-error'],
+  ['E404 mixed within JSON', { stdout: '{"error":{"code":"E404","detail":"E403"}}', exitCode: 1 }, 'inconclusive', 'npm-error'],
+  ['escaped mixed JSON code', { stdout: '{"error":{"code":"E404","detail":"E\\u0034\\u0030\\u0033"}}', exitCode: 1 }, 'inconclusive', 'npm-error'],
+  ['duplicate JSON keys cannot hide mixed codes', { stdout: '{"error":{"code":"E403","code":"E404"}}', exitCode: 1 }, 'inconclusive', 'npm-error'],
+  ['malformed UTF-8 stdout cannot clear absence', { stdout: 'E404 ', stdoutHex: 'ff', exitCode: 1 }, 'inconclusive', 'unexpected-response'],
+  ['malformed UTF-8 stderr cannot clear absence', { stdout: 'E404 ', stderrHex: 'ff', exitCode: 1 }, 'inconclusive', 'unexpected-response'],
+  ['malformed JSON error', { stdout: '{"error":{"code":"E404"', exitCode: 1 }, 'inconclusive', 'unexpected-response'],
+  ['malformed JSON stderr', { stderr: '["E404",', exitCode: 1 }, 'inconclusive', 'unexpected-response'],
+  ['successful JSON version', { stdout: '"1.2.3"\n' }, 'present', 'version-present'],
+  ['successful bare version', { stdout: ' \n1.2.3\t\n' }, 'present', 'version-present'],
+  ['successful version with warning', { stdout: '"1.2.3"', stderr: 'npm warn using cached metadata' }, 'present', 'version-present'],
+  ['successful empty output', {}, 'inconclusive', 'unexpected-response'],
+  ['successful wrong version', { stdout: '"1.2.4"' }, 'inconclusive', 'unexpected-response'],
+  ['successful bare wrong version', { stdout: '2.0.0' }, 'inconclusive', 'unexpected-response'],
+  ['successful malformed JSON', { stdout: '"1.2.3' }, 'inconclusive', 'unexpected-response'],
+  ['successful version object', { stdout: '{"version":"1.2.3"}' }, 'inconclusive', 'unexpected-response'],
+  ['successful version array', { stdout: '["1.2.3"]' }, 'inconclusive', 'unexpected-response'],
+  ['successful extra output', { stdout: '1.2.3\n1.2.3' }, 'inconclusive', 'unexpected-response'],
+  ['successful E404', { stdout: 'E404' }, 'inconclusive', 'unexpected-response'],
+  ['successful version with error', { stdout: '"1.2.3"', stderr: 'npm error code E404' }, 'inconclusive', 'unexpected-response'],
+  ['process killed after E404', { stdout: 'E404', signal: 'SIGKILL' }, 'inconclusive', 'process-error'],
+]
+for (const code of ['E403', 'ENOTFOUND', 'E500', 'ETARGET', 'ENEEDAUTH', 'ECONNRESET']) {
+  responses.push(
+    [code, { stderr: `npm error code ${code}`, exitCode: 1 }, 'inconclusive', 'npm-error'],
+    [`E404 mixed with ${code}`, { stdout: '{"error":{"code":"E404"}}', stderr: `npm error code ${code}`, exitCode: 1 }, 'inconclusive', 'npm-error'],
+  )
+}
+for (const [name, reply, status, reason] of responses) {
+  test(name, (t) => {
+    const f = fixture(t)
+    f.reply(reply)
+    checkResult(f.probe(), status, reason)
+    assert.equal(f.calls().length, 1)
+  })
+}
+
+const incidentalJsonRefusals = [
+  '{"note":"E404"}',
+  '{"E404":"diagnostic only"}',
+  '{"error":{"detail":"previous E404; request failed"}}',
+  '{"note":"E\\u0034\\u0030\\u0034"}',
+  '"E404"',
+  '["E404"]',
+  '{"code":"E404"}',
+  '{"causes":[{"code":"E404"}]}',
+]
+for (const output of incidentalJsonRefusals) {
+  for (const channel of ['stdout', 'stderr']) {
+    for (const otherError of [false, true]) {
+      test(`incidental JSON cannot prove absence on ${channel}: ${output}; other error ${otherError}`, (t) => {
+        const f = fixture(t)
+        f.reply({
+          [channel]: output,
+          ...(otherError ? { [channel === 'stdout' ? 'stderr' : 'stdout']: 'npm error code E404' } : {}),
+          exitCode: 1,
+        })
+        const result = f.cli()
+        assert.equal(result.status, 2)
+        checkResult(JSON.parse(result.stdout), 'inconclusive', 'npm-error')
+      })
+    }
+  }
+}
+
+const structuredRefusals = [
+  ['unknown code with E404 detail', '{"error":{"code":"UNKNOWN","detail":"upstream E404"}}'],
+  ['numeric code', '{"error":{"code":404}}'],
+  ['null code', '{"error":{"code":null}}'],
+  ['boolean code', '{"error":{"code":false}}'],
+  ['array code', '{"error":{"code":["E404"]}}'],
+  ['object code', '{"error":{"code":{"value":"E404"}}}'],
+  ['empty code', '{"error":{"code":""}}'],
+  ['mixed code value', '{"error":{"code":"E404 UNKNOWN"}}'],
+  ['nested unknown code', '{"error":{"code":"E404","causes":[{"code":"UNKNOWN"}]}}'],
+  ['escaped unknown code key', '{"error":{"co\\u0064e":"UNKNOWN","detail":"E404"}}'],
+  ['duplicate unknown then E404', '{"error":{"code":"UNKNOWN","code":"E404"}}'],
+  ['duplicate E404 then unknown', '{"error":{"code":"E404","code":"UNKNOWN"}}'],
+  ['escaped duplicate code key', '{"error":{"code":"UNKNOWN","co\\u0064e":"E404"}}'],
+  ['duplicate error object', '{"error":{"code":"UNKNOWN"},"error":{"code":"E404"}}'],
+  ['duplicate nested unrelated key', '{"error":{"code":"E404","causes":[{"note":"first","note":"second"}]}}'],
+]
+for (const [name, output] of structuredRefusals) {
+  for (const channel of ['stdout', 'stderr']) {
+    test(`CLI refuses ${name} on ${channel}`, (t) => {
+      const f = fixture(t)
+      f.reply({
+        [channel]: output,
+        [channel === 'stdout' ? 'stderr' : 'stdout']: `npm error code E404\n${leakMarker}`,
+        exitCode: 1,
+      })
+      const result = f.cli()
+      assert.equal(result.error, undefined)
+      assert.equal(result.status, 2)
+      assert.equal(result.stderr, '')
+      checkResult(JSON.parse(result.stdout), 'inconclusive', 'npm-error')
+      assert.equal(f.calls().length, 1)
+      assert.deepEqual(readdirSync(f.cwd), [])
+    })
+  }
+}
+
+test('CLI refuses an exact successful version with an unknown structured stderr code', (t) => {
+  const f = fixture(t)
+  f.reply({ stdout: '"1.2.3"', stderr: JSON.stringify({ error: { code: 'UNKNOWN', detail: leakMarker } }) })
+  const result = f.cli()
+  assert.equal(result.error, undefined)
+  assert.equal(result.status, 2)
+  assert.equal(result.stderr, '')
+  checkResult(JSON.parse(result.stdout), 'inconclusive', 'unexpected-response')
+  assert.equal(f.calls().length, 1)
+})
+
+const framingRefusals = [
+  ['warning then malformed JSON', 'npm warn diagnostic\n{"error":{"code":"E404"', 'unexpected-response'],
+  ['warning then one JSON object', 'npm warn diagnostic\n{"error":{"code":"E404"}}', 'unexpected-response'],
+  ['warning then two JSON documents', 'npm warn diagnostic\n{"error":{"code":"E404"}}\n{"error":{"code":"UNKNOWN"}}', 'unexpected-response'],
+  ['two JSON documents', '{"error":{"code":"E404"}}\n{"error":{"code":"UNKNOWN"}}', 'unexpected-response'],
+  ['plain E404 then truncated JSON', 'npm error code E404\n{"error":', 'unexpected-response'],
+  ['warning then JSON string', 'npm warn diagnostic\n"E404"', 'unexpected-response'],
+  ['warning then JSON array', 'npm warn diagnostic\n[{"code":"E404"},{"code":"UNKNOWN"}]', 'unexpected-response'],
+  ['YAML instead of JSON syntax', '{error: {code: E404}}', 'unexpected-response'],
+  ['missing plain code value', 'npm error code', 'npm-error'],
+  ['mixed plain code value', 'npm ERR! code E404 UNKNOWN', 'npm-error'],
+]
+for (const [name, output, reason] of framingRefusals) {
+  for (const channel of ['stdout', 'stderr']) {
+    test(`CLI refuses ${name} on ${channel}`, (t) => {
+      const f = fixture(t)
+      f.reply({
+        [channel]: output,
+        [channel === 'stdout' ? 'stderr' : 'stdout']: `npm error code E404\n${leakMarker}`,
+        exitCode: 1,
+      })
+      const result = f.cli()
+      assert.equal(result.error, undefined)
+      assert.equal(result.status, 2)
+      assert.equal(result.stderr, '')
+      checkResult(JSON.parse(result.stdout), 'inconclusive', reason)
+      assert.equal(f.calls().length, 1)
+      assert.deepEqual(readdirSync(f.cwd), [])
+    })
+  }
+}
+
+const invalidNames = [
+  '', '@scope', '@scope/', '@/widget', '@scope/widget/extra', 'one/two', '@scope/@widget',
+  'Widget', '@Scope/widget', '@scope/Widget', '.widget', '_widget', '-widget', '@.scope/widget',
+  ' widget', 'widget ', 'widget\n', 'widget\r', 'wid\tget', 'wid\0get',
+  'widget@1.2.3', 'widget;touch injected', 'widget$(touch injected)', 'widget%2fother',
+  'https://example.test/widget.tgz', '../widget', 'caf\u00e9', 'node_modules', 'favicon.ico',
+  'a'.repeat(215), `@a/${'b'.repeat(212)}`, null, 3, {}, ['widget'],
+]
+const invalidVersions = [
+  '', 'v1.2.3', 'V1.2.3', '01.2.3', '1.02.3', '1.2.03', '1.2', '1.2.3.4',
+  '1.2.3-rc.1', '1.2.3+build', '^1.2.3', 'latest', '*', ' 1.2.3', '1.2.3\n',
+  '1.2.3;touch injected', '9007199254740992.0.0', null, 123, {},
+]
+const invalidRegistries = [
+  '', 'http://registry.example.test', 'ftp://registry.example.test', '//registry.example.test',
+  'https:', 'https://', 'https://user:password@registry.example.test', 'https://user@registry.example.test',
+  'https://@registry.example.test', 'https://registry.example.test?token=private',
+  'https://registry.example.test/#fragment', 'https://registry.example.test/?', 'https://registry.example.test/#',
+  ' https://registry.example.test', 'https://registry.example.test ',
+  'https://registry.example.test/\npath', 'https://registry.example.test/\rpath',
+  'https://registry.example.test/\u2028path', 'https://registry.example.test/\u2029path',
+  'https://registry.example.test/\tpath', 'https://registry.example.test/\0path',
+  'https://registry.example.test\\@other.test', 'https://registry.example.test:bad',
+  null, 42, {},
+]
+
+test('bad API parameters fail with a fixed message before spawning any process', (t) => {
+  const f = fixture(t)
+  for (const [field, values] of [['packageName', invalidNames], ['version', invalidVersions], ['registry', invalidRegistries], ['cwd', ['', 2, null, 'bad\0directory']]]) {
+    for (const value of field === 'cwd' ? values : [...values, undefined]) {
+      assert.throws(() => f.probe({ [field]: value }), { message: 'npm-version-absence: invalid arguments' })
+    }
+  }
+  for (const value of [undefined, null, 'bad', [], 1, {}]) {
+    assert.throws(() => probeNpmVersionAbsence(value), { message: 'npm-version-absence: invalid arguments' })
+  }
+  assert.deepEqual(f.calls(), [])
+  assert.deepEqual(readdirSync(f.cwd), [])
+})
+
+test('canonical safe names up to 214 characters and stable versions are accepted', (t) => {
+  const f = fixture(t)
+  for (const packageName of ['widget', 'widget.js_v2-extra', '@scope-name/widget.js_v2', 'a'.repeat(214), `@a/${'b'.repeat(211)}`]) {
+    for (const version of ['0.0.0', '10.20.30']) {
+      checkResult(f.probe({ packageName, version }), 'absent', 'version-absent', { ...request, packageName, version })
+    }
+  }
+})
+
+test('explicit HTTPS registries support custom paths, ports and case-insensitive schemes', (t) => {
+  const f = fixture(t)
+  for (const registry of ['https://registry.example.test', 'HTTPS://REGISTRY.EXAMPLE.TEST/npm/', 'https://registry.example.test:8443/custom/npm/', 'https://[::1]:8443/custom/']) {
+    checkResult(f.probe({ registry }), 'absent', 'version-absent', { ...request, registry })
+    assert.equal(f.calls().at(-1).argv[3], `--registry=${registry}`)
+  }
+})
+
+test('the API defaults cwd to the calling directory', (t) => {
+  const f = fixture(t)
+  const previous = process.cwd()
+  try {
+    process.chdir(f.cwd)
+    checkResult(probeNpmVersionAbsence(request), 'absent', 'version-absent')
+  } finally {
+    process.chdir(previous)
+  }
+  assert.equal(f.calls()[0].cwd, f.cwd)
+})
+
+for (const failure of ['missing executable', 'missing cwd']) {
+  test(`real spawn failure: ${failure}`, (t) => {
+    const f = fixture(t)
+    if (failure === 'missing executable') rmSync(join(f.bin, 'npm'))
+    const cwd = failure === 'missing cwd' ? join(f.root, leakMarker) : f.cwd
+    checkResult(f.probe({ cwd }), 'inconclusive', 'process-error')
+    assert.deepEqual(f.calls(), [])
+  })
+}
+
+for (const [name, reply, status, reason] of [
+  ['exact 1 MiB', { stdout: 'E404\n', stdoutBytes: 1024 * 1024 - 5, exitCode: 1 }, 'absent', 'version-absent'],
+  ['over 1 MiB stdout', { stdout: 'E404\n', stdoutBytes: 1024 * 1024, exitCode: 1 }, 'inconclusive', 'process-error'],
+  ['over 1 MiB stderr', { stderr: 'E404\n', stderrBytes: 1024 * 1024, exitCode: 1 }, 'inconclusive', 'process-error'],
+  ['over 1 MiB combined', { stdout: 'E404\n', stdoutBytes: 600 * 1024, stderrBytes: 600 * 1024, exitCode: 1 }, 'inconclusive', 'process-error'],
+]) {
+  test(`bounded output: ${name}`, (t) => {
+    const f = fixture(t)
+    f.reply(reply)
+    checkResult(f.probe(), status, reason)
+  })
+}
+
+for (const [name, reply, status, reason, exitCode] of [
+  ['absence', { stdout: '{"error":{"code":"E404"}}', stderr: leakMarker, exitCode: 1 }, 'absent', 'version-absent', 0],
+  ['presence', { stdout: '"1.2.3"', stderr: leakMarker }, 'present', 'version-present', 1],
+  ['inconclusive', { stdout: leakMarker, stderr: 'npm error code E403', exitCode: 1 }, 'inconclusive', 'npm-error', 2],
+  ['signal death', { stdout: `E404 ${leakMarker}`, signal: 'SIGKILL' }, 'inconclusive', 'process-error', 2],
+]) {
+  test(`CLI maps ${name} to exit ${exitCode} without forwarding child output`, (t) => {
+    const f = fixture(t)
+    f.reply(reply)
+    const result = f.cli()
+    assert.equal(result.error, undefined)
+    assert.equal(result.status, exitCode)
+    assert.equal(result.stderr, '')
+    checkResult(JSON.parse(result.stdout), status, reason)
+    assert.equal(result.stdout.includes(leakMarker), false)
+    assert.deepEqual(f.calls(), [{
+      argv: ['view', '@example/widget@1.2.3', 'version', `--registry=${request.registry}`, '--json'], cwd: f.cwd,
+    }])
+    assert.deepEqual(readdirSync(f.cwd), [])
+  })
+}
+
+test('CLI rejects missing, duplicate, unknown and unsafe arguments without registry discovery or raw errors', (t) => {
+  const f = fixture(t)
+  const valid = ['--package', request.packageName, '--version', request.version, '--registry', request.registry]
+  const invalidArgs = [
+    [], valid.slice(0, 4), valid.slice(2), [...valid.slice(0, 2), ...valid.slice(4)],
+    [...valid, '--registry', request.registry], [...valid, '--package', request.packageName],
+    [...valid, '--version', request.version], [...valid, '--timeout', '1'],
+    [...valid, '--help'], [...valid, `--unknown-${leakMarker}`],
+    [...valid, '--registry'], ['--package', leakMarker, ...valid.slice(2)],
+    ['--package', request.packageName, '--version', '1.2.3', '--registry', `https://user:${leakMarker}@registry.example.test`],
+  ]
+  for (const args of invalidArgs) {
+    const result = f.cli(args)
+    assert.equal(result.error, undefined)
+    assert.equal(result.status, 2)
+    assert.equal(result.stdout, '')
+    assert.equal(result.stderr, 'npm-version-absence: invalid arguments\n')
+  }
+  assert.deepEqual(f.calls(), [])
+  assert.deepEqual(readdirSync(f.cwd), [])
+})
+
+test('probing preserves files and tags and invokes no publisher or provider even with shell metacharacters', (t) => {
+  const f = fixture(t)
+  mkdirSync(join(f.cwd, '.git', 'refs', 'tags'), { recursive: true })
+  writeFileSync(join(f.cwd, '.git', 'refs', 'tags', 'existing'), 'historical-tag-sha\n')
+  writeFileSync(join(f.cwd, 'unchanged'), leakMarker)
+  const registry = 'https://registry.example.test/custom/npm/;git'
+  f.reply({ stdout: JSON.stringify({ error: { code: 'E404', detail: leakMarker } }), exitCode: 1 })
+  checkResult(f.probe({ registry }), 'absent', 'version-absent', { ...request, registry })
+  assert.deepEqual(f.calls(), [{
+    argv: ['view', '@example/widget@1.2.3', 'version', `--registry=${registry}`, '--json'], cwd: f.cwd,
+  }])
+  assert.deepEqual(readdirSync(f.cwd).sort(), ['.git', 'unchanged'])
+  assert.deepEqual(readdirSync(join(f.cwd, '.git'), { recursive: true }).sort(), ['refs', 'refs/tags', 'refs/tags/existing'])
+  assert.equal(readFileSync(join(f.cwd, '.git', 'refs', 'tags', 'existing'), 'utf8'), 'historical-tag-sha\n')
+  assert.equal(readFileSync(join(f.cwd, 'unchanged'), 'utf8'), leakMarker)
+})
+
+test('importing the module does not run npm or the CLI', (t) => {
+  const f = fixture(t)
+  const result = spawnSync(process.execPath, ['--input-type=module', '-e', `await import(${JSON.stringify(new URL('./npm-version-absence.mjs', import.meta.url).href)})`], {
+    cwd: f.cwd, env: process.env, encoding: 'utf8', timeout: 10_000,
+  })
+  assert.equal(result.error, undefined)
+  assert.equal(result.status, 0)
+  assert.equal(result.stdout, '')
+  assert.equal(result.stderr, '')
+  assert.deepEqual(f.calls(), [])
+})
+
+test('the CLI still blocks a present version when launched through a symlink', (t) => {
+  const f = fixture(t)
+  const link = join(f.root, 'installed-helper.mjs')
+  symlinkSync(script, link)
+  f.reply({ stdout: '"1.2.3"' })
+  const result = spawnSync(process.execPath, [link, '--package', request.packageName, '--version', request.version, '--registry', request.registry], {
+    cwd: f.cwd, env: process.env, encoding: 'utf8', timeout: 10_000,
+  })
+  assert.equal(result.error, undefined)
+  assert.equal(result.status, 1)
+  assert.equal(result.stderr, '')
+  checkResult(JSON.parse(result.stdout), 'present', 'version-present')
+  assert.equal(f.calls().length, 1)
+})