@myelinbridge/cli 0.1.0

package/README.md

@@ -0,0 +1,38 @@
+# @myelinbridge/cli
+
+Push R&D data deliveries into [Myelin](https://myelinbridge.com) from a pipeline —
+preflight against the client's published quality rules, resumable upload, submit,
+and track review outcomes. Full API reference: https://myelinbridge.com/developers.
+
+## Quick start (~10 minutes from key to first submit)
+
+```bash
+export MYELIN_API_KEY=myl_live_…     # created by your bridge owner in Bridge → API
+
+npx @myelinbridge/cli ping                 # verifies auth, prints your projects
+npx @myelinbridge/cli datasets             # what you can deliver to, and whose move it is
+npx @myelinbridge/cli check ./run_042 --dataset onco1-wes    # validate BEFORE uploading a byte
+npx @myelinbridge/cli push  ./run_042 --dataset onco1-wes --submit
+```
+
+- **Resume = re-run.** `push` is idempotent: already-uploaded files are skipped
+  (path + size), interrupted uploads resume mid-file over TUS.
+- **`check` costs nothing.** It evaluates your local manifest against the dataset's
+  quality checks server-side — same engine, same verdicts as submit — without
+  uploading. Exit code 2 means a blocking rule fails.
+- **The fix loop is machine-readable.** On `changes_requested`,
+  `myelin status <batch> --json` returns the failed files, reviewer comments, and
+  rule remediation hints; fix, re-`push --submit`, unchanged files keep their
+  review votes.
+
+## Machine mode
+
+Every command takes `--json`. Exit codes: `0` ok · `1` error · `2` blocked
+(blocking preflight failure, locked delivery, blocked submit).
+
+## Webhooks instead of polling
+
+Register an HTTPS endpoint (portal Bridge → API, or `POST /v1/webhook-endpoints`)
+to receive signed events (`batch.validated`, `batch.changes_requested`,
+`batch.transferred`, …). Verification snippets: https://myelinbridge.com/developers.
+Polling fallback: `GET /v1/events?cursor=…`.

package/bin/myelin.js

@@ -0,0 +1,365 @@
+#!/usr/bin/env node
+// @myelinbridge/cli — Partner Ingestion CLI (Partner API Phase 5, design §3.3).
+//
+//   export MYELIN_API_KEY=myl_live_…
+//   npx @myelinbridge/cli ping
+//   npx @myelinbridge/cli push ./run_042 --dataset onco1-wes --submit
+//
+// Exit codes: 0 ok · 1 error · 2 blocked (failing checks / locked delivery).
+// Every command accepts --json for machine-readable output.
+
+import { readdirSync, statSync, createReadStream, readFileSync } from 'node:fs'
+import { resolve, join, relative, sep, basename } from 'node:path'
+import process from 'node:process'
+import * as tus from 'tus-js-client'
+
+const API_URL = (process.env.MYELIN_API_URL ?? 'https://myelinbridge.com/api/v1').replace(/\/$/, '')
+const KEY = process.env.MYELIN_API_KEY
+
+const argv = process.argv.slice(2)
+const JSON_MODE = argv.includes('--json')
+const args = argv.filter((a) => a !== '--json')
+const command = args[0]
+
+const out = (line) => { if (!JSON_MODE) console.log(line) }
+const emit = (obj) => { if (JSON_MODE) console.log(JSON.stringify(obj, null, 2)) }
+const die = (message, code = 1) => {
+  if (JSON_MODE) console.log(JSON.stringify({ error: message }))
+  else console.error(`✗ ${message}`)
+  process.exit(code)
+}
+
+function flag(name) {
+  return args.includes(`--${name}`)
+}
+function opt(name) {
+  const i = args.indexOf(`--${name}`)
+  return i >= 0 && args[i + 1] && !args[i + 1].startsWith('--') ? args[i + 1] : null
+}
+
+async function api(method, path, body, raw) {
+  const res = await fetch(API_URL + path, {
+    method,
+    headers: {
+      Authorization: `Bearer ${KEY}`,
+      ...(body && !raw ? { 'Content-Type': 'application/json' } : {}),
+    },
+    body: raw ? body : body ? JSON.stringify(body) : undefined,
+  }).catch((err) => die(`Cannot reach ${API_URL}: ${err.message}`))
+  let json = null
+  try { json = await res.json() } catch { /* non-JSON body */ }
+  return { status: res.status, json }
+}
+
+function expectOk(r, context) {
+  if (r.status >= 200 && r.status < 300) return r.json
+  const detail = r.json?.detail ?? `HTTP ${r.status}`
+  const code = r.json?.code ?? 'error'
+  const blocked = ['delivery_locked', 'submit_blocked', 'dataset_not_active', 'api_disabled', 'bridge_paused'].includes(code)
+  die(`${context}: [${code}] ${detail}`, blocked ? 2 : 1)
+}
+
+// ——— dataset resolution (id or slug) ———
+async function resolveDataset(ref) {
+  if (/^[0-9a-f]{8}-[0-9a-f]{4}-/i.test(ref)) {
+    const r = await api('GET', `/datasets/${ref}`)
+    if (r.status === 200) return r.json.dataset
+    die(`Dataset ${ref} not found in this key's scope`)
+  }
+  const me = expectOk(await api('GET', '/me'), 'auth')
+  for (const p of me.projects) {
+    const r = expectOk(await api('GET', `/projects/${p.id}/datasets`), 'datasets')
+    const hit = r.datasets.find((d) => d.slug === ref || d.name === ref)
+    if (hit) return hit
+  }
+  die(`No dataset with slug or name "${ref}" in this key's scope`)
+}
+
+// ——— local manifest ———
+function walkDir(root) {
+  const files = []
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir)) {
+      const full = join(dir, entry)
+      const st = statSync(full)
+      if (st.isDirectory()) walk(full)
+      else files.push({ abs: full, path: '/' + relative(root, full).split(sep).join('/'), size: st.size })
+    }
+  }
+  walk(root)
+  return files
+}
+
+function fmtBytes(n) {
+  if (n >= 1024 ** 3) return (n / 1024 ** 3).toFixed(1) + ' GB'
+  if (n >= 1024 ** 2) return (n / 1024 ** 2).toFixed(1) + ' MB'
+  if (n >= 1024) return (n / 1024).toFixed(1) + ' KB'
+  return n + ' B'
+}
+
+function tusUpload(absPath, size, storagePath, upload) {
+  return new Promise((resolveP, rejectP) => {
+    new tus.Upload(createReadStream(absPath), {
+      endpoint: upload.endpoint,
+      chunkSize: upload.chunk_size_bytes,
+      uploadSize: size,
+      retryDelays: [0, 1000, 5000],
+      headers: { authorization: `Bearer ${upload.token}`, apikey: upload.apikey, ...upload.headers },
+      metadata: {
+        bucketName: upload.bucket,
+        objectName: storagePath,
+        contentType: 'application/octet-stream',
+        cacheControl: '3600',
+      },
+      onError: rejectP,
+      onSuccess: () => resolveP(),
+    }).start()
+  })
+}
+
+// ——— commands ———
+
+async function cmdPing() {
+  const j = expectOk(await api('GET', '/ping'), 'ping')
+  emit(j)
+  out(`✓ key "${j.key.name}" (${j.key.prefix}…) · bridge ${j.bridge.name} · ${j.projects.length} project(s)`)
+}
+
+async function cmdProjects() {
+  const j = expectOk(await api('GET', '/projects'), 'projects')
+  emit(j)
+  for (const p of j.projects) out(`${p.code.padEnd(18)} ${p.status.padEnd(10)} ${p.title}`)
+}
+
+async function cmdDatasets() {
+  const me = expectOk(await api('GET', '/me'), 'auth')
+  const rows = []
+  for (const p of me.projects) {
+    const r = expectOk(await api('GET', `/projects/${p.id}/datasets`), 'datasets')
+    for (const d of r.datasets) {
+      rows.push({
+        project: p.code,
+        dataset: d.slug,
+        status: d.lifecycle_status,
+        quality_version: d.quality_check_version,
+        open_draft: d.open_draft_batch_id,
+        id: d.id,
+      })
+    }
+  }
+  emit({ datasets: rows })
+  if (!JSON_MODE) {
+    out('PROJECT'.padEnd(18) + 'DATASET'.padEnd(22) + 'STATUS'.padEnd(10) + 'YOUR MOVE?')
+    for (const r of rows) {
+      out(
+        r.project.padEnd(18) +
+          r.dataset.padEnd(22) +
+          r.status.padEnd(10) +
+          (r.open_draft ? 'yes — open draft to finish' : '—'),
+      )
+    }
+  }
+}
+
+async function cmdCheck() {
+  const dir = args[1]
+  const dsRef = opt('dataset')
+  if (!dir || !dsRef) die('Usage: myelin check <dir> --dataset <slug|id>')
+  const root = resolve(dir)
+  const files = walkDir(root)
+  if (files.length === 0) die(`No files under ${root}`)
+  const dataset = await resolveDataset(dsRef)
+
+  out(`Evaluating ${files.length} files (${fmtBytes(files.reduce((s, f) => s + f.size, 0))}) against quality checks v${dataset.quality_check_version ?? '—'}…`)
+  const j = expectOk(
+    await api('POST', `/datasets/${dataset.id}/preflight`, {
+      files: files.map((f) => ({ path: f.path, size_bytes: f.size })),
+    }),
+    'preflight',
+  )
+  emit(j)
+  if (!JSON_MODE) {
+    for (const c of j.evaluated) {
+      const mark = c.verdict === 'passed' ? '✓' : c.verdict === 'flagged' ? '⚠' : '✗'
+      out(`${mark} ${c.check_type.padEnd(26)} ${c.verdict}${c.severity === 'blocking' && c.verdict === 'failed' ? ' — BLOCKING' : ''}`)
+      if (c.verdict !== 'passed' && c.remediation) out(`    hint: ${c.remediation}`)
+    }
+    for (const d of j.deferred) out(`… ${d.check_type.padEnd(26)} ${d.reason}`)
+    for (const m of j.manual) out(`○ ${m.name.padEnd(26)} ${m.reason}`)
+  }
+  if (j.blocking_failures > 0) {
+    out(`${j.blocking_failures} blocking issue(s). Fix before pushing to avoid a review round-trip.`)
+    process.exit(2)
+  }
+  out('All manifest-evaluable checks pass.')
+}
+
+async function cmdPush() {
+  const dir = args[1]
+  const dsRef = opt('dataset')
+  if (!dir || !dsRef) die('Usage: myelin push <dir> --dataset <slug|id> [--submit] [--replace]')
+  const root = resolve(dir)
+  const files = walkDir(root)
+  if (files.length === 0) die(`No files under ${root}`)
+  const dataset = await resolveDataset(dsRef)
+
+  // 1. create or resume the draft
+  const created = expectOk(await api('POST', `/datasets/${dataset.id}/batches`), 'create batch')
+  const batchId = created.batch_id
+  out(`Draft ${created.resumed ? 'resumed' : 'created'} (${batchId.slice(0, 8)}…).`)
+
+  // 2. declare in chunks of 500 — idempotent, so re-running skips what's done
+  const declared = []
+  let upload = null
+  for (let i = 0; i < files.length; i += 500) {
+    const slice = files.slice(i, i + 500)
+    const r = await api('POST', `/batches/${batchId}/files`, {
+      files: slice.map((f) => ({ path: f.path, size_bytes: f.size })),
+      replace: flag('replace'),
+    })
+    if (r.status !== 200 && r.status !== 409) expectOk(r, 'declare')
+    const conflicts = r.json.files.filter((f) => f.error)
+    if (conflicts.length > 0) {
+      for (const c of conflicts) out(`✗ ${c.path}: ${c.error}`)
+      die(`${conflicts.length} path conflict(s) — pass --replace to overwrite`, 2)
+    }
+    declared.push(...r.json.files)
+    upload = r.json.upload
+  }
+
+  // 3. upload the delta (anything not already 'uploaded'), 4 in parallel
+  const byPath = new Map(files.map((f) => [f.path, f]))
+  const pending = declared.filter((d) => d.upload_state !== 'uploaded')
+  out(`Uploading ${pending.length}/${declared.length} files (${fmtBytes(pending.reduce((s, d) => s + (byPath.get(d.path)?.size ?? 0), 0))}) · resumable`)
+  let done = 0
+  const queue = [...pending]
+  const workers = Array.from({ length: Math.min(4, queue.length) }, async () => {
+    for (;;) {
+      const d = queue.shift()
+      if (!d) return
+      const local = byPath.get(d.path)
+      await tusUpload(local.abs, local.size, d.storage_path, upload)
+      const c = await api('POST', `/files/${d.file_id}/confirm`)
+      if (c.status !== 200) die(`confirm ${d.path}: [${c.json?.code}] ${c.json?.detail ?? c.status}`)
+      done++
+      out(`  ✓ ${d.path} (${done}/${pending.length})`)
+    }
+  })
+  await Promise.all(workers)
+  out('All files confirmed.')
+
+  // 4. optional submit
+  if (flag('submit')) {
+    const r = await api('POST', `/batches/${batchId}/submit`)
+    if (r.status !== 200) {
+      const code = r.json?.code ?? 'error'
+      die(`submit: [${code}] ${r.json?.detail ?? r.status}`, code === 'submit_blocked' ? 2 : 1)
+    }
+    const a = r.json.auto_checks
+    emit(r.json)
+    out(`Submitting… auto-checks: ${a.passed} passed, ${a.flagged} flagged, ${a.failed} failed.`)
+    out(`✓ Batch submitted for review. Track: myelin status ${batchId} --watch`)
+  } else {
+    emit({ batch_id: batchId, files: declared.length, submitted: false })
+    out(`Draft ready (not submitted). Submit with: myelin push ${dir} --dataset ${dsRef} --submit`)
+  }
+}
+
+async function cmdStatus() {
+  const ref = args[1]
+  if (!ref) die('Usage: myelin status <batch-id|display-name> [--watch]')
+
+  const findBatch = async () => {
+    if (/^[0-9a-f]{8}-[0-9a-f]{4}-/i.test(ref)) {
+      const r = await api('GET', `/batches/${ref}`)
+      if (r.status === 200) return r.json.batch
+      die(`Batch ${ref} not found in this key's scope`)
+    }
+    const list = expectOk(await api('GET', '/batches?limit=100'), 'batches')
+    const hit = list.batches.find((b) => b.display_name === ref)
+    if (!hit) die(`No batch named "${ref}" in this key's scope`)
+    return expectOk(await api('GET', `/batches/${hit.id}`), 'batch').batch
+  }
+
+  const print = async (batch) => {
+    emit({ batch })
+    out(`${batch.display_name}: ${batch.status} — ${batch.court === 'partner' ? 'your move.' : batch.court === 'reviewer' ? "reviewer's move." : batch.court === 'system' ? 'transferring…' : 'done.'}`)
+    if (batch.status === 'changes_requested') {
+      const f = expectOk(await api('GET', `/batches/${batch.id}/findings`), 'findings')
+      if (f.request_changes_comment) out(`  reviewer: "${f.request_changes_comment}"`)
+      for (const fr of f.file_reviews.filter((x) => x.verdict === 'failed')) {
+        out(`  ✗ ${fr.path}  (${fr.reviewer ?? 'reviewer'}: ${fr.comment ?? 'failed'})`)
+      }
+      for (const qf of f.quality_findings.filter((x) => x.verdict === 'failed')) {
+        out(`  ✗ ${qf.name ?? qf.rule_key}${qf.hint ? `: ${qf.hint}` : ''}`)
+      }
+    }
+    return batch
+  }
+
+  let batch = await print(await findBatch())
+  if (flag('watch')) {
+    const terminal = ['transferred', 'rejected', 'changes_requested', 'transfer_failed']
+    while (!terminal.includes(batch.status)) {
+      await new Promise((r) => setTimeout(r, 20_000))
+      const next = await findBatch()
+      if (next.status !== batch.status) batch = await print(next)
+    }
+  }
+}
+
+async function cmdSandbox() {
+  const file = args[1]
+  if (!file) die('Usage: myelin sandbox <file>')
+  const abs = resolve(file)
+  const size = statSync(abs).size
+  if (size > 4 * 1024 * 1024) die('Sandbox files should stay under ~4 MB — this verifies connectivity, not throughput.')
+
+  const me = expectOk(await api('GET', '/me'), 'auth')
+  const form = new FormData()
+  form.set('file', new File([readFileSync(abs)], basename(abs)))
+  const r = await api('POST', `/bridges/${me.bridge.id}/sandbox`, form, true)
+  const j = expectOk(r, 'sandbox')
+  emit(j)
+  out(`✓ Sandbox upload succeeded — the partner-side test transfer checklist item is satisfied for bridge "${me.bridge.name}".`)
+}
+
+function cmdHelp() {
+  console.log(`myelin — Partner Ingestion CLI
+
+Setup:
+  export MYELIN_API_KEY=myl_live_…        (create in Bridge → API)
+  export MYELIN_API_URL=…                 (optional; default https://myelinbridge.com/api/v1)
+
+Commands:
+  ping                                    verify the key; show bridge + projects
+  projects                                list scoped projects
+  datasets                                list datasets with "your move" hints
+  check <dir> --dataset <slug|id>         preflight local files against quality rules (no upload)
+  push <dir> --dataset <slug|id>          create/resume a delivery and upload (resumable; re-run to resume)
+       [--submit] [--replace]
+  status <batch|name> [--watch]           review status + fix-loop findings
+  sandbox <file>                          partner-side test transfer (bridge activation)
+
+Every command accepts --json. Exit codes: 0 ok · 1 error · 2 blocked.`)
+}
+
+// ——— main ———
+if (!command || command === 'help' || command === '--help') {
+  cmdHelp()
+  process.exit(0)
+}
+if (!KEY) die('Set MYELIN_API_KEY (create a key in Bridge → API).')
+
+const commands = {
+  ping: cmdPing,
+  projects: cmdProjects,
+  datasets: cmdDatasets,
+  check: cmdCheck,
+  push: cmdPush,
+  status: cmdStatus,
+  sandbox: cmdSandbox,
+}
+const fn = commands[command]
+if (!fn) die(`Unknown command "${command}" — run: myelin help`)
+await fn()

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@myelinbridge/cli",
+  "version": "0.1.0",
+  "description": "Myelin Partner Ingestion CLI — push R&D data deliveries from a pipeline: preflight against the client's quality rules, resumable upload, submit, track review outcomes.",
+  "type": "module",
+  "bin": {
+    "myelin": "./bin/myelin.js"
+  },
+  "files": [
+    "bin/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "tus-js-client": "^4.1.0"
+  },
+  "keywords": [
+    "myelin",
+    "pharma",
+    "ingestion",
+    "tus"
+  ],
+  "license": "UNLICENSED"
+}