@myelinbridge/cli 0.10.0 → 0.12.0

package/README.md

@@ -13,6 +13,8 @@ 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 contract --dataset onco1-wes            # what is expected of your delivery
 npx @myelinbridge/cli sample-depth 1 --dataset onco1-wes      # once, before your first submit
+npx @myelinbridge/cli roles --dataset onco1-wes               # which file plays which role
+npx @myelinbridge/cli roles set samplesheet /metadata/samplesheet.csv --dataset onco1-wes
 npx @myelinbridge/cli check ./run_042 --dataset onco1-wes    # validate BEFORE uploading a byte
 npx @myelinbridge/cli push  ./run_042 --dataset onco1-wes --submit
 ```
@@ -27,6 +29,40 @@ npx @myelinbridge/cli push  ./run_042 --dataset onco1-wes --submit
   deliveries — after that, re-asserting the current value still succeeds and only a
   *change* exits `2`. This is the only dataset field you can write.
 
+- **Declare which file plays which role — whenever you like (0.11.0).** Quality
+  checks read files by ROLE (`samplesheet`, `checksum_manifest`, `qc_report`,
+  `subject_roster`, `capture_bed`), not by a filing convention you never agreed
+  to. `roles` shows what is declared and what Myelin detected in your
+  deliveries; `roles set <role> <path>` confirms a file; `roles none <role>`
+  states your dataset has no such file (a statement, not a gap). Nothing is
+  ever required to deliver — an undeclared role just means the checks that read
+  it report *"could not check"* instead of running, so declaring is how you
+  activate more checks before upload and catch problems before review does.
+  Unlike `sample-depth` it **never locks**, and it is idempotent, so a pipeline
+  can assert it on every run. The samplesheet is **sticky**: send it once and
+  every later delivery reconciles against it — a partial delivery (93 of 96) is
+  reported as a state, never as a failure.
+
+- **Your client's own fields show up, read-only (0.12.0).** Clients can define
+  their own metadata fields on datasets (a sponsor study code, a work order, a
+  therapeutic area). `contract` prints them under CLIENT FIELDS, and `check`
+  tells you when required ones are not filled in yet — informational only:
+  their team fills them in Myelin, there is nothing to change in your delivery,
+  and metadata never moves the exit code. In `--json`, datasets carry a
+  `metadata` object (`{key: {label, type, value}}`) and preflight carries
+  `metadata.missing_required`.
+
+- **A missing path in `roles set` is refused, not guessed (0.11.1).** Flags are
+  not positional arguments: `roles set samplesheet --dataset onco1-wes` (path
+  omitted) used to declare the samplesheet at the literal path `--dataset` and
+  print a tick. Every samplesheet check then reported *"could not check — the
+  declared file is not in the delivery"* on a delivery that was fine. The
+  command now exits with its usage line instead.
+
+- **`--dataset` takes the slug in any case (0.11.0).** Slugs are matched
+  case-insensitively (`onco1-wes` and `ONCO1-WES` name the same dataset); an id
+  or an exact name works too.
+
 - **Resume = re-run.** `push` is idempotent: already-uploaded files are skipped
   (path + size), and within a large file, parts that already landed are skipped
   too (S3 multipart). Uploads go direct to storage over short-lived presigned

package/bin/myelin.js

@@ -17,6 +17,12 @@
 // cannot validate either without deciding by hand, and hearing "all checks
 // pass" before uploading is the green-before-sending / red-after trap this
 // release exists to close.
+//
+// 0.12.0 — clients can define their own fields on datasets (sprint 22).
+// `contract` shows them read-only, and `check` reports the required ones the
+// client has not filled in yet — informational ONLY: metadata never moves the
+// exit code (the client fills these in Myelin; nothing for a partner to fix,
+// and a pipeline must never halt on it).
 
 import { readdirSync, statSync, createReadStream, readFileSync } from 'node:fs'
 import { resolve, join, relative, sep, basename } from 'node:path'
@@ -102,6 +108,11 @@ const VERDICT_LABEL = {
 const verdictMark = (v) => VERDICT_MARK[v] ?? '?'
 const verdictLabel = (v) => VERDICT_LABEL[v] ?? v
 
+// A client field value in human mode (0.12.0). Arrays joined, booleans said
+// in words, everything else printed as-is — never JSON punctuation.
+const fmtFieldValue = (v) =>
+  Array.isArray(v) ? v.join(', ') : v === true ? 'yes' : v === false ? 'no' : String(v ?? '—')
+
 // Column widths come from the content. padEnd() alone silently ran a long
 // value into the next column — a 28-character dataset slug swallowed the
 // STATUS header's gutter. Pass headers = null for an unheadered list.
@@ -191,9 +202,15 @@ async function resolveDataset(ref) {
     die(`Dataset ${ref} not found in this key's scope`)
   }
   const me = expectOk(await api('GET', '/me'), 'auth')
+  // Slugs are matched case-insensitively: seeded datasets carry lowercase slugs
+  // while the portal generates uppercase ones, and the slug is a handle a human
+  // types — the case of the fleet should never be their problem.
+  const want = ref.toLowerCase()
   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)
+    const hit = r.datasets.find(
+      (d) => (typeof d.slug === 'string' && d.slug.toLowerCase() === want) || d.name === ref,
+    )
     if (hit) return hit
   }
   die(`No dataset with slug or name "${ref}" in this key's scope`)
@@ -559,6 +576,15 @@ async function cmdContract() {
     for (const c of manual) out(`  · ${c.name}`)
     out('')
   }
+  // 0.12.0 — the client's own fields on this dataset, read-only (their team
+  // writes them in Myelin; the API never accepts them from a partner key).
+  const meta = dataset.metadata ?? {}
+  const metaKeys = Object.keys(meta)
+  if (metaKeys.length > 0) {
+    out('CLIENT FIELDS — how your client describes this dataset (read-only)')
+    for (const k of metaKeys) out(`  · ${meta[k].label}: ${fmtFieldValue(meta[k].value)}`)
+    out('')
+  }
   out(`Run "myelin check <dir> --dataset ${dsRef}" to test ${s.checkable_before_upload} of these locally.`)
 }
 
@@ -656,6 +682,16 @@ async function cmdCheck() {
   if (j.must_acknowledge_failures > 0) {
     out(`${j.must_acknowledge_failures} check(s) your client asked to be told about — nothing to fix; their reviewer records a decision. Not a blocker.`)
   }
+  // 0.12.0 — required client fields not filled in yet. Informational ONLY:
+  // their team fills these in Myelin, nothing changes in the delivery, and
+  // metadata never moves the exit code (warn, never block — by design).
+  const gaps = j.metadata?.missing_required ?? []
+  if (gaps.length > 0) {
+    out(
+      `${gaps.length} field(s) your client asks for on this dataset ${gaps.length === 1 ? 'is' : 'are'} ` +
+        `not filled in yet: ${gaps.map((g) => g.label).join(', ')}. Their team fills these in Myelin — not a blocker.`,
+    )
+  }
 
   const k = j.counts
   // "All checks that run before upload pass" was written when every check
@@ -896,6 +932,69 @@ async function cmdSampleDepth() {
   }
 }
 
+// Which delivered file plays each role (sprint 19). Checks read files by ROLE
+// — declaring one activates every check that was waiting on it, and nothing
+// here is ever required to deliver. Unlike sample-depth this never locks:
+// declarations apply forward, and re-declaring is allowed for the life of the
+// dataset (idempotent — assert it on every run).
+async function cmdRoles() {
+  const dsRef = opt('dataset')
+  if (!dsRef) die('Usage: myelin roles [set <role> <path> | none <role> | clear <role>] --dataset <slug|id>')
+  const dataset = await resolveDataset(dsRef)
+  const sub = args[1]
+
+  if (sub === 'set' || sub === 'none' || sub === 'clear') {
+    const role = args[2]
+    if (!role) die(`Usage: myelin roles ${sub} <role>${sub === 'set' ? ' <path>' : ''} --dataset <slug|id>`)
+    const body = { role }
+    if (sub === 'set') {
+      const path = args[3]
+      // ⚠ `args` only strips --json, so an omitted path lets the NEXT FLAG slide
+      // into its place: `roles set samplesheet --dataset onco1-wes` used to
+      // declare the samplesheet at `/--dataset`. The API accepts it (printable,
+      // under 255 chars), the CLI printed a tick, and every samplesheet check
+      // then answered role_file_missing on a delivery that was fine.
+      if (!path || path.startsWith('--')) {
+        die('Usage: myelin roles set <role> <path> --dataset <slug|id>')
+      }
+      body.path = path
+    } else if (sub === 'none') {
+      body.none = true
+    } else {
+      body.clear = true
+    }
+    const j = expectOk(await api('PUT', `/datasets/${dataset.id}/file-roles`, body), 'file-roles')
+    emit(j)
+    if (!JSON_MODE) {
+      out(
+        j.changed
+          ? `✓ ${role} ${sub === 'set' ? `→ ${body.path}` : sub === 'none' ? 'declared: no such file in this dataset' : 'declaration cleared'} for ${dataset.name}.`
+          : `${role} already declared that way for ${dataset.name} — nothing to change.`,
+      )
+    }
+    return
+  }
+
+  const j = expectOk(await api('GET', `/datasets/${dataset.id}/file-roles`), 'file-roles')
+  emit(j)
+  if (JSON_MODE) return
+  out(`${dataset.name} — delivery file roles`)
+  const declaredBy = new Map(j.declarations.map((d) => [d.role, d]))
+  for (const role of ['samplesheet', 'checksum_manifest', 'qc_report', 'subject_roster', 'capture_bed']) {
+    const d = declaredBy.get(role)
+    if (d) {
+      out(`  ${role.padEnd(18)} ${d.declared_none ? '(no such file in this dataset — declared)' : d.path}`)
+    } else {
+      const cands = j.candidates.filter((c) => c.role === role)
+      out(`  ${role.padEnd(18)} not declared${cands.length ? ` — looks like: ${cands.map((c) => c.path).join(', ')}` : ''}`)
+    }
+  }
+  const undeclared = 5 - j.declarations.length
+  if (undeclared > 0) {
+    out(`\nDeclaring a role activates the checks that read it — run: myelin roles set <role> <path> --dataset ${dsRef}`)
+  }
+}
+
 function cmdHelp() {
   console.log(`myelin — Partner Ingestion CLI
 
@@ -910,6 +1009,8 @@ Commands:
   projects                                list scoped projects
   datasets                                list datasets with "your move" hints
   sample-depth <0-5> --dataset <slug|id>  declare the folder depth a sample sits at (locks after 1st submit)
+  roles [set|none|clear …] --dataset <…>  which file plays each role (samplesheet, checksum list, …) —
+                                          declaring one activates the checks that read it; never locks
   contract --dataset <slug|id>            what this dataset expects of your delivery
   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)
@@ -1008,6 +1109,7 @@ const commands = {
   projects: cmdProjects,
   datasets: cmdDatasets,
   'sample-depth': cmdSampleDepth,
+  roles: cmdRoles,
   contract: cmdContract,
   check: cmdCheck,
   push: cmdPush,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myelinbridge/cli",
-  "version": "0.10.0",
+  "version": "0.12.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": {