@goliapkg/sentori-cli 1.4.1 → 1.6.0

package/src/__tests__/upload-verdict.test.ts

@@ -0,0 +1,77 @@
+// The server has answered `usable: false` since 2.15.0, and its own
+// comment in `artifacts_upload.rs` says "the response says so". It
+// did. Nothing read it — both upload paths threw the body away and
+// returned `{ id }` — so a Hermes bundle uploaded as a source map
+// stored, printed nothing, and sat under a green light on the release
+// page until somebody expanded the row months later.
+//
+// These pin the two halves that were missing: it warns, and it does
+// not throw.
+
+import { describe, expect, mock, test } from 'bun:test'
+
+import { warnIfUnusable } from '../upload.js'
+
+/** Capture what the CLI prints, without printing it. */
+function captured(fn: () => void): { warn: string[] } {
+  const warn: string[] = []
+  const orig = console.warn
+  console.warn = mock((...a: unknown[]) => void warn.push(a.join(' ')))
+  try {
+    fn()
+  } finally {
+    console.warn = orig
+  }
+  return { warn }
+}
+
+describe('what the server said about the file it stored', () => {
+  test('an unreadable artifact is named, with what to upload instead', () => {
+    const { warn } = captured(() => {
+      const said = warnIfUnusable('index.android.bundle', {
+        id: 'a',
+        usable: false,
+        hint: 'React Native: upload the generated .map, not the bundle.',
+      })
+      expect(said).toBe(true)
+    })
+    expect(warn).toHaveLength(1)
+    // The file, so somebody with eight artifacts knows which one.
+    expect(warn[0]).toContain('index.android.bundle')
+    // And the server's own instruction, rather than our paraphrase.
+    expect(warn[0]).toContain('upload the generated .map')
+  })
+
+  test('it warns rather than throwing — an upload may not fail a build', () => {
+    // The zero-cost rule: sentori cannot break a customer's release.
+    // The file did store; only its usefulness is in question.
+    expect(() =>
+      captured(() => warnIfUnusable('main.jsbundle', { id: 'a', usable: false })),
+    ).not.toThrow()
+  })
+
+  test('a readable artifact says nothing', () => {
+    const { warn } = captured(() => {
+      expect(warnIfUnusable('app.map', { id: 'a', usable: true })).toBe(false)
+    })
+    expect(warn).toHaveLength(0)
+  })
+
+  test('"we did not look" is not "we looked and it is broken"', () => {
+    // `srcbundle` and anything uploaded before the check existed come
+    // back `null`. Warning on those would train people to ignore the
+    // warning that matters.
+    for (const usable of [null, undefined]) {
+      const { warn } = captured(() => {
+        expect(warnIfUnusable('srcbundle.json', { id: 'a', usable })).toBe(false)
+      })
+      expect(warn).toHaveLength(0)
+    }
+  })
+
+  test('a hint-less refusal still names the file', () => {
+    const { warn } = captured(() => warnIfUnusable('Insight.app-arm64', { id: 'a', usable: false }))
+    expect(warn[0]).toContain('Insight.app-arm64')
+    expect(warn[0]).toContain('cannot read')
+  })
+})

package/src/__tests__/workflow.test.ts

@@ -0,0 +1,102 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { createHash } from 'node:crypto'
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { gunzipSync } from 'node:zlib'
+import { loadUploadConfig, prepareUploadPlan, runWorkflow, verifyUploadPlan } from '../workflow.js'
+import { inspectSourceArchive } from '../srcbundle.js'
+
+let root: string
+const realFetch = globalThis.fetch
+const oldToken = process.env.SENTORI_TEST_UPLOAD_TOKEN
+beforeEach(() => { root = mkdtempSync(join(tmpdir(), 'sentori-upload-test-')); process.env.SENTORI_TEST_UPLOAD_TOKEN = 'api-test' })
+afterEach(() => { globalThis.fetch = realFetch; rmSync(root, { recursive: true, force: true }); if (oldToken === undefined) delete process.env.SENTORI_TEST_UPLOAD_TOKEN; else process.env.SENTORI_TEST_UPLOAD_TOKEN = oldToken })
+function config(artifacts: object = {}, sources?: object) {
+  const path = join(root, 'sentori.config.json')
+  writeFileSync(path, JSON.stringify({ version: 1, apiUrl: 'https://upload.test', tokenEnv: 'SENTORI_TEST_UPLOAD_TOKEN', release: 'app@1+7', artifacts, ...(sources ? { sources } : {}) }))
+  return path
+}
+function reply(body: unknown, status = 200) { return new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } }) }
+
+describe('unified release upload', () => {
+  test('configuration paths are relative to config, and init never overwrites a config', async () => {
+    writeFileSync(join(root, 'mapping.txt'), 'com.example.A -> a:\n    void run() -> a\n')
+    const path = config({ mapping: ['mapping.txt'] })
+    expect(prepareUploadPlan(path).files[0]?.path).toBe(join(root, 'mapping.txt'))
+    expect(await runWorkflow('init', ['--config', path])).toBe(1)
+    expect(loadUploadConfig(path).tokenEnv).toBe('SENTORI_TEST_UPLOAD_TOKEN')
+  })
+  test('checks every source map, DWARF binary, mapping and source archive after upload', async () => {
+    writeFileSync(join(root, 'index.map'), JSON.stringify({ version: 3, sources: ['src/a.ts'], names: [], mappings: 'AAAA' }))
+    writeFileSync(join(root, 'mapping.txt'), 'com.example.A -> a:\n    void run() -> a\n')
+    writeFileSync(join(root, 'dwarf'), Buffer.from('cffaedfe00000000', 'hex'))
+    mkdirSync(join(root, 'src')); writeFileSync(join(root, 'src/a.ts'), 'export const a = 1')
+    const path = config({ sourcemap: ['index.map'], dsym: ['dwarf'], mapping: ['mapping.txt'] }, { include: ['src'] })
+    const uploaded: any[] = []
+    globalThis.fetch = (async (url, init) => {
+      expect(String(url)).toContain('/v1/releases/app%401%2B7/artifacts')
+      expect((init?.headers as any).Authorization).toBe('Bearer api-test')
+      if (init?.method === 'POST') {
+        const form = init.body as FormData; const file = form.get('file') as File
+        const bytes = gunzipSync(Buffer.from(await file.arrayBuffer()))
+        const kind = String(form.get('kind'))
+        if (kind === 'srcbundle') expect(inspectSourceArchive(bytes, 'app@1+7').files).toEqual(['src/a.ts'])
+        uploaded.push({ kind, name: file.name.replace(/\.gz$/, ''), usable: true, contentHash: createHash('sha256').update(bytes).digest('hex') })
+        return reply({ id: String(uploaded.length), usable: true }, 201)
+      }
+      return reply({ release: 'app@1+7', known: uploaded.length > 0, artifacts: uploaded,
+        compatibility: { serverVersion: '5.1.12', artifactProtocol: 1, sourceBundleFormats: ['zip', 'json'], verification: ['sha256', 'format'] } })
+    }) as typeof fetch
+    expect(await runWorkflow('upload', ['--config', path, '--strict'])).toBe(0)
+    expect(uploaded.map(x => x.kind)).toEqual(['sourcemap', 'dsym', 'proguard', 'srcbundle'])
+    expect(await runWorkflow('verify', ['--config', path])).toBe(0)
+  })
+  test('a readable old artifact of the same kind cannot satisfy verification', async () => {
+    writeFileSync(join(root, 'mapping.txt'), 'A -> a:\n')
+    const plan = prepareUploadPlan(config({ mapping: ['mapping.txt'] }))
+    globalThis.fetch = (async () => reply({ known: true, release: plan.release, artifacts: [{ kind: 'proguard', usable: true, contentHash: 'old' }] })) as typeof fetch
+    expect(await verifyUploadPlan(plan, 't')).toEqual(['missing exact bytes: proguard mapping.txt'])
+    globalThis.fetch = (async () => reply({ known: true, release: plan.release, artifacts: [{ kind: 'proguard', name: 'mapping.txt', usable: null, contentHash: plan.files[0]!.hash }] })) as typeof fetch
+    expect((await verifyUploadPlan(plan, 't'))[0]).toContain('not verified')
+    globalThis.fetch = (async () => reply({ known: true, release: plan.release, artifacts: [{ kind: 'proguard', name: 'another.txt', usable: true, contentHash: plan.files[0]!.hash }] })) as typeof fetch
+    expect((await verifyUploadPlan(plan, 't'))[0]).toContain('missing exact bytes')
+  })
+  test('dry-run needs no token or network; failures are lenient only for uploads', async () => {
+    writeFileSync(join(root, 'mapping.txt'), 'A -> a:\n')
+    const path = config({ mapping: ['mapping.txt'] })
+    globalThis.fetch = (async () => { throw new Error('offline') }) as typeof fetch
+    delete process.env.SENTORI_TEST_UPLOAD_TOKEN
+    expect(await runWorkflow('upload', ['--config', path, '--dry-run'])).toBe(0)
+    expect(await runWorkflow('upload', ['--config', path])).toBe(0)
+    expect(await runWorkflow('upload', ['--config', path, '--strict'])).toBe(1)
+    expect(await runWorkflow('verify', ['--config', path])).toBe(1)
+  })
+  test('invalid local files prevent any upload', async () => {
+    writeFileSync(join(root, 'a.map'), 'not a map')
+    const path = config({ sourcemap: ['a.map'] })
+    globalThis.fetch = (async () => { throw new Error('network must not be called') }) as typeof fetch
+    expect(await runWorkflow('validate', ['--config', path])).toBe(1)
+  })
+  test('partial remote failure still uploads remaining files and fails strict verification', async () => {
+    writeFileSync(join(root, 'a.map'), JSON.stringify({ version: 3, sources: ['a.ts'], names: [], mappings: 'AAAA' }))
+    writeFileSync(join(root, 'mapping.txt'), 'A -> a:\n')
+    const path = config({ sourcemap: ['a.map'], mapping: ['mapping.txt'] })
+    const attempted: string[] = [], uploaded: any[] = []
+    globalThis.fetch = (async (_url, init) => {
+      if (init?.method === 'POST') {
+        const form = init.body as FormData, kind = String(form.get('kind'))
+        attempted.push(kind)
+        if (kind === 'sourcemap') return reply({ error: 'injected rejection' }, 400)
+        const file = form.get('file') as File
+        uploaded.push({ kind, usable: true, contentHash: createHash('sha256').update(gunzipSync(Buffer.from(await file.arrayBuffer()))).digest('hex') })
+        return reply({ id: '1', usable: true }, 201)
+      }
+      return reply({ known: uploaded.length > 0, release: 'app@1+7', artifacts: uploaded })
+    }) as typeof fetch
+    expect(await runWorkflow('upload', ['--config', path, '--strict'])).toBe(1)
+    expect(attempted).toEqual(['sourcemap', 'proguard'])
+    expect(uploaded).toHaveLength(1)
+  })
+
+})

package/src/artifacts.ts

@@ -34,6 +34,13 @@ export type ArtifactRow = {
 }
 
 export type ArtifactsResponse = {
+  /** Additive capability advertisement. Absent on older servers. */
+  compatibility?: {
+    serverVersion: string
+    artifactProtocol: number
+    sourceBundleFormats: string[]
+    verification: string[]
+  }
   release: string
   /** False when the server has never heard this release name at all
    *  — a typo in `--release` and an un-uploaded release look the
@@ -61,5 +68,9 @@ export async function fetchArtifacts(opts: {
       `${resp.status} ${resp.statusText}${detail ? ` — ${detail.slice(0, 200)}` : ''}`,
     )
   }
-  return (await resp.json()) as ArtifactsResponse
+  const result = await resp.json() as ArtifactsResponse
+  if (!result || result.release !== opts.release || typeof result.known !== 'boolean' || !Array.isArray(result.artifacts)) {
+    throw new Error('Unsupported artifact inventory response; check --api-url and upgrade the Sentori server or CLI together.')
+  }
+  return result
 }

package/src/compatibility.ts

@@ -0,0 +1,21 @@
+import { readFileSync } from 'node:fs'
+import type { ArtifactsResponse } from './artifacts.js'
+
+/** Read the installed package, so a release bump cannot leave a stale constant. */
+export const CLI_VERSION: string = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version
+
+/** Capabilities, not a server version comparison: backports may share versions. */
+export function checkCompatibility(result: ArtifactsResponse, sourceZip: boolean): string {
+  const info = result.compatibility
+  if (info === undefined) {
+    if (sourceZip) throw new Error('This server does not advertise source ZIP support. No files were uploaded. Upgrade the Sentori server to a build advertising artifact protocol 1 and sourceBundleFormats: ["zip"], then run sentori doctor. Existing CLI 1.5 pipelines may continue using legacy JSON sources.')
+    return 'Legacy artifact API: server capabilities are not advertised. Source maps, dSYM and mapping uploads remain available; verification still requires matching SHA-256 bytes and usable: true.'
+  }
+  if (!info || typeof info.serverVersion !== 'string' || info.artifactProtocol !== 1
+    || !Array.isArray(info.sourceBundleFormats) || !Array.isArray(info.verification)
+    || !info.verification.includes('sha256') || !info.verification.includes('format')) {
+    throw new Error('Unsupported server artifact protocol or verification capabilities. No files were uploaded. Install a compatible CLI/server pair; use sentori --version and sentori doctor to inspect it.')
+  }
+  if (sourceZip && !info.sourceBundleFormats.includes('zip')) throw new Error(`Sentori server ${info.serverVersion} does not support source ZIPs. No files were uploaded. Upgrade the server before uploading sources.`)
+  return `Sentori CLI ${CLI_VERSION}; server ${info.serverVersion}; artifact protocol 1; source ZIP ${info.sourceBundleFormats.includes('zip') ? 'supported' : 'unavailable'}.`
+}

package/src/index.ts

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 import { parseArgs } from 'node:util'
+import { runWorkflow, runSourcesPack, WORKFLOW_HELP } from './workflow.js'
+import { checkCompatibility, CLI_VERSION } from './compatibility.js'
 
 import {
   fetchBundle,
@@ -22,24 +24,23 @@ import {
 } from './push.js'
 import { reactNativeUpload } from './react-native.js'
 import { fetchArtifacts } from './artifacts.js'
-import { uploadArtifact } from './upload.js'
+import { expandSourcemapPaths, uploadArtifact } from './upload.js'
 
-const HELP = `sentori-cli — Sentori command-line interface
+const HELP = `${WORKFLOW_HELP}\n\nsentori — Sentori command-line interface
 
 Symbolication artifacts (api-scope token; failures NEVER block your
 build — exit 0 with a friendly note unless --strict):
-  sentori-cli upload sourcemap --release <r> --token <t> <path...>
-  sentori-cli upload dsym      --release <r> --token <t> <path.dSYM>
-  sentori-cli upload mapping   --release <r> --token <t> mapping.txt
+  sentori upload sourcemap --release <r> --token <t> <path...>
+  sentori upload dsym      --release <r> --token <t> <path.dSYM>
+  sentori upload mapping   --release <r> --token <t> mapping.txt
                                (mapping = the R8/proguard map; stored as kind "proguard")
-  sentori-cli upload srcbundle --release <r> --token <t> <src-dir...>
-                               (native source files so dSYM/proguard frames
-                                show the failing line; nothing touches git)
-  sentori-cli react-native upload --release <r> --token <t> \\
+  sentori upload srcbundle --release <r> --token <t> <src-dir...>
+                               (ZIP or selected source directories; optional --git-tag pins a tag)
+  sentori react-native upload --release <r> --token <t> \\
       --metro-map <m> --hermes-map <h> [--bundle <b>]
 
-Release gate (the ONE command here that is allowed to fail):
-  sentori-cli artifacts check --release <r> --token <t> [--expect dsym,sourcemap]
+Legacy kind-presence gate (use verify for exact planned files):
+  sentori artifacts check --release <r> --token <t> [--expect dsym,sourcemap]
       Asks the server what actually landed for this release. With
       --expect, exits 1 when one of those kinds is missing. Uploads
       never block your build; this is the step that does, and it
@@ -47,23 +48,24 @@ Release gate (the ONE command here that is allowed to fail):
       the upload step that stopped being called at all.
 
 Regression tripwires (design: probes):
-  sentori-cli probes sync --release <r> --token <t> [--dir .]
+  sentori probes sync --release <r> --token <t> [--dir .]
       Statically scans source for sentori.probe('REF') call sites and
       registers them, so a silent probe is visibly alive.
 
 CI triage (the same /api surface an AI agent uses):
-  sentori-cli issue list [--status open] [--kind error]
-  sentori-cli issue resolve <issue-id> [--in-release <r>]
-  sentori-cli issue note <issue-id> --body "fixed in abc123"
-  sentori-cli issue bundle <issue-id>
+  sentori issue list [--status open] [--kind error]
+  sentori issue resolve <issue-id> [--in-release <r>]
+  sentori issue note <issue-id> --body "fixed in abc123"
+  sentori issue bundle <issue-id>
 
 MCP (for Claude Code and friends):
-  sentori-cli mcp serve --token <api-token> [--api-url <url>]
+  sentori mcp serve --token <api-token> [--api-url <url>]
 
 Push (carried):
-  sentori-cli push send / receipt / creds ...
+  sentori push send / receipt / creds ...
 
 Common options:
+  --version     installed CLI package version
   --token       api-scope token (or $SENTORI_TOKEN)
   --api-url     instance URL (or $SENTORI_API_URL; default https://sentori.golia.jp)
   --strict      upload commands: exit non-zero on failure
@@ -139,47 +141,42 @@ const UPLOAD_OPTS = {
 
 async function cmdUploadSrcbundle(argv: string[]): Promise<number> {
   const strict = isStrict(argv)
-  let parsed
   try {
-    parsed = parseArgs({ allowPositionals: true, args: stripStrict(argv), options: UPLOAD_OPTS })
-  } catch (e) {
-    console.error(`error: ${(e as Error).message}\n${HELP}`)
-    return 2
-  }
-  if (parsed.values.help) {
-    console.log(HELP)
-    return 0
-  }
-  const c = parseCommon(parsed.values)
-  if (!c) return 2
-  if (parsed.positionals.length === 0) {
-    console.error('error: at least one source directory is required')
-    return 2
-  }
-  try {
-    const { collectSources } = await import('./srcbundle.js')
-    const { bundle, stats } = collectSources(parsed.positionals)
-    if (stats.files === 0) {
-      console.error('error: no native source files found under the given directories')
-      return 2
-    }
-    const { writeFileSync, mkdtempSync } = await import('node:fs')
+    const parsed = parseArgs({ allowPositionals: true, args: stripStrict(argv), options: {
+      ...UPLOAD_OPTS, root: { type: 'string' }, 'git-tag': { type: 'string' }, exclude: { type: 'string', multiple: true },
+    } })
+    if (parsed.values.help) { console.log(HELP); return 0 }
+    const c = parseCommon({ ...parsed.values, release: parsed.values.release ?? process.env.SENTORI_RELEASE })
+    if (!c) throw new Error('upload configuration is incomplete')
+    const { inspectSourceArchive, packSources } = await import('./srcbundle.js')
+    const { readFileSync, writeFileSync, mkdtempSync, rmSync } = await import('node:fs')
     const { tmpdir } = await import('node:os')
     const { join } = await import('node:path')
-    const tmp = join(mkdtempSync(join(tmpdir(), 'sentori-srcbundle-')), 'srcbundle.json')
-    writeFileSync(tmp, JSON.stringify(bundle))
-    await uploadArtifact({ ...c, kind: 'srcbundle', path: tmp, name: 'srcbundle.json' })
-    console.log(
-      `uploaded a source bundle for "${c.release}" — ${stats.files} file(s)` +
-        `${stats.skipped ? ` (${stats.skipped} skipped as oversized/unreadable)` : ''}; ` +
-        `native frames on this release now show their source window.`,
-    )
-    return 0
-  } catch (e) {
+    let temporary: string | undefined
+    try {
+      let path = parsed.positionals[0]
+      if (parsed.positionals.length === 1 && path?.toLowerCase().endsWith('.zip')) {
+        if (parsed.values['git-tag']) throw new Error('--git-tag applies to source directories, not an existing ZIP')
+        const archive = inspectSourceArchive(readFileSync(path), c.release)
+        console.log(`Checked ${archive.files.length} source files in ${path}`)
+      } else {
+        const packed = packSources(parsed.positionals, c.release, { root: parsed.values.root, exclude: parsed.values.exclude, gitTag: parsed.values['git-tag'] })
+        temporary = mkdtempSync(join(tmpdir(), 'sentori-sources-'))
+        path = join(temporary, 'sources.zip')
+        writeFileSync(path, packed.bytes)
+        console.log(JSON.stringify(packed.manifest, null, 2))
+      }
+      console.log(checkCompatibility(await fetchArtifacts(c), true))
+      const verdict = await uploadArtifact({ ...c, kind: 'srcbundle', path: path!, name: 'sources.zip' })
+      if (verdict.usable !== true) throw new Error('source bundle was stored but not verified by the server')
+      console.log(`Source bundle stored and validated for ${c.release}; source context requires matching file paths and line numbers.`)
+      return 0
+    } finally { if (temporary) rmSync(temporary, { recursive: true, force: true }) }
+  } catch (error) {
     return lenientFail(strict, {
-      failure: `srcbundle upload failed (${(e as Error).message})`,
-      impact: `native frames from ${c.release} will show file:line without the code window until uploaded.`,
-      retry: `sentori-cli upload srcbundle --release "${c.release}" --token <t> ${parsed.positionals.join(' ')}`,
+      failure: `source upload failed (${error instanceof Error ? error.message : String(error)})`,
+      impact: 'source context may be unavailable for this release',
+      retry: 'sentori upload srcbundle --release <exact-sdk-release> sources.zip',
     })
   }
 }
@@ -204,18 +201,28 @@ async function cmdUploadSourcemap(argv: string[]): Promise<number> {
     return 2
   }
   try {
-    for (const p of parsed.positionals) {
-      await uploadArtifact({ ...c, kind: 'sourcemap', path: p })
+    // A directory expands to the maps under it, each keeping its path
+    // relative to that directory. Passing one used to throw EISDIR
+    // while the docs told people to pass `./dist`.
+    const targets = parsed.positionals.flatMap((p) => expandSourcemapPaths(p))
+    if (targets.length === 0) {
+      console.error(
+        `error: no .map files under ${parsed.positionals.join(', ')}`,
+      )
+      return 2
+    }
+    for (const t of targets) {
+      await uploadArtifact({ ...c, kind: 'sourcemap', path: t.path, name: t.name })
     }
     console.log(
-      `uploaded ${parsed.positionals.length} sourcemap(s) for "${c.release}" — minified stacks on this release now resolve to source.`,
+      `uploaded ${targets.length} sourcemap(s) for "${c.release}" — minified stacks on this release now resolve to source.`,
     )
     return 0
   } catch (e) {
     return lenientFail(strict, {
       failure: `sourcemap upload failed (${(e as Error).message})`,
       impact: `crashes from ${c.release} will show minified stacks until the map is uploaded.`,
-      retry: `sentori-cli upload sourcemap --release "${c.release}" --token <t> ${parsed.positionals.join(' ')}`,
+      retry: `sentori upload sourcemap --release "${c.release}" --token <t> ${parsed.positionals.join(' ')}`,
     })
   }
 }
@@ -275,7 +282,7 @@ async function cmdUploadDsym(argv: string[]): Promise<number> {
     return lenientFail(strict, {
       failure: `dSYM upload failed (${(e as Error).message})`,
       impact: `native iOS stacks from ${c.release} stay unsymbolicated until the dSYM lands.`,
-      retry: `sentori-cli upload dsym --release "${c.release}" --token <t> ${path}`,
+      retry: `sentori upload dsym --release "${c.release}" --token <t> ${path}`,
     })
   }
 }
@@ -319,7 +326,7 @@ async function cmdUploadMapping(argv: string[]): Promise<number> {
     return lenientFail(strict, {
       failure: `mapping upload failed (${(e as Error).message})`,
       impact: `Android stacks from ${c.release} stay R8-obfuscated until the mapping lands.`,
-      retry: `sentori-cli upload mapping --release "${c.release}" --token <t> ${path}`,
+      retry: `sentori upload mapping --release "${c.release}" --token <t> ${path}`,
     })
   }
 }
@@ -370,7 +377,7 @@ async function cmdReactNativeUpload(argv: string[]): Promise<number> {
     return lenientFail(strict, {
       failure: `react-native upload failed (${(e as Error).message})`,
       impact: `Hermes stacks from ${c.release} stay unsymbolicated until the composed map lands.`,
-      retry: `sentori-cli react-native upload --release "${c.release}" --token <t> --metro-map ${metroMap} --hermes-map ${hermesMap}`,
+      retry: `sentori react-native upload --release "${c.release}" --token <t> --metro-map ${metroMap} --hermes-map ${hermesMap}`,
     })
   }
 }
@@ -409,7 +416,7 @@ async function cmdProbesSync(argv: string[]): Promise<number> {
     return lenientFail(strict, {
       failure: `probes sync failed (${(e as Error).message})`,
       impact: `silent probes on ${c.release} can't be told apart from deleted code until registered.`,
-      retry: `sentori-cli probes sync --release "${c.release}" --token <t> --dir ${dir}`,
+      retry: `sentori probes sync --release "${c.release}" --token <t> --dir ${dir}`,
     })
   }
 }
@@ -585,12 +592,12 @@ async function cmdMcpServe(argv: string[]): Promise<number> {
 const UNREADABLE_HINT: Record<string, string> = {
   dsym:
     'Upload the binary inside the .dSYM bundle ' +
-    '(Contents/Resources/DWARF/<name>), or point `sentori-cli upload dsym` ' +
+    '(Contents/Resources/DWARF/<name>), or point `sentori upload dsym` ' +
     'at the .dSYM and let it find the slices.',
   proguard: 'Upload build/outputs/mapping/<variant>/mapping.txt.',
   sourcemap:
     'For React Native upload the composed map — ' +
-    '`sentori-cli react-native upload --metro-map <m> --hermes-map <h>` — not the bundle.',
+    '`sentori react-native upload --metro-map <m> --hermes-map <h>` — not the bundle.',
 }
 
 async function cmdArtifactsCheck(argv: string[]): Promise<number> {
@@ -670,15 +677,25 @@ async function cmdArtifactsCheck(argv: string[]): Promise<number> {
 }
 
 async function main(argv: string[]): Promise<number> {
+  if (argv.length === 1 && (argv[0] === '--version' || argv[0] === '-V')) {
+    console.log(`sentori ${CLI_VERSION}`)
+    return 0
+  }
   if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
     console.log(HELP)
     return 0
   }
   const [a, b, ...rest] = argv
+  if (a === 'init') return runWorkflow('init', argv.slice(1))
+  if (a === 'doctor') return runWorkflow('doctor', argv.slice(1))
+  if (a === 'verify') return runWorkflow('verify', argv.slice(1))
+  if (a === 'config' && b === 'validate') return runWorkflow('validate', rest)
+  if (a === 'upload' && b === 'all') return runWorkflow('upload', rest)
+  if (a === 'sources' && b === 'pack') return runSourcesPack(rest)
   if (a === 'upload' && b === 'sourcemap') return cmdUploadSourcemap(rest)
   if (a === 'upload' && b === 'dsym') return cmdUploadDsym(rest)
   if (a === 'upload' && b === 'mapping') return cmdUploadMapping(rest)
-  if (a === 'upload' && b === 'srcbundle') return cmdUploadSrcbundle(rest)
+  if (a === 'upload' && (b === 'srcbundle' || b === 'source-bundle')) return cmdUploadSrcbundle(rest)
   if (a === 'react-native' && b === 'upload') return cmdReactNativeUpload(rest)
   if (a === 'artifacts' && b === 'check') return cmdArtifactsCheck(rest)
   if (a === 'probes' && b === 'sync') return cmdProbesSync(rest)

package/src/lenient.ts

@@ -1,4 +1,4 @@
-// The iron rule reaches build-time (design.md §6 dim 3): an upload
+// The iron rule reaches build-time: an upload
 // failure must never break the customer's build or release. Every
 // upload-family command runs through this wrapper — on failure it
 // prints a friendly, actionable note and exits 0. `--strict` opts

package/src/mcp.ts

@@ -135,7 +135,7 @@ async function dispatch(
 
 // ── Tool implementations — the /api closed loop ──────────────────
 //
-// Four tools, mirroring exactly what an agent needs (design.md §9):
+// Four tools, mirroring exactly what an agent needs:
 // pick work, pull the evidence, write back, resolve. The bundle is
 // the product; everything else is triage plumbing.
 

package/src/native-artifacts.ts

@@ -8,6 +8,7 @@ import { basename, extname, join } from 'node:path'
 import { statSync, readdirSync } from 'node:fs'
 
 import { gzipForWire, wireArrayBuffer } from './upload.js'
+import { type UploadVerdict, warnIfUnusable } from './upload.js'
 
 export type AdminUpload = {
   apiUrl: string
@@ -41,6 +42,10 @@ async function uploadBytes(opts: {
       `${resp.status} ${resp.statusText}${detail ? ` — ${detail.slice(0, 300)}` : ''}`,
     )
   }
+  // The dSYM path posts its own request rather than going through
+  // `uploadArtifact`, so it needs the same read — this is the half
+  // that would have gone quiet again.
+  warnIfUnusable(opts.name, (await resp.json().catch(() => ({}))) as UploadVerdict)
 }
 
 // ── dSYM ──────────────────────────────────────────────────────────

package/src/probes.ts

@@ -1,5 +1,5 @@
 // `sentori-cli probes sync` — the tripwire registry scan
-// (design.md §2). Statically scans source for `sentori.probe('REF')`
+// Statically scans source for `sentori.probe('REF')`
 // / `probe("REF")` call sites and registers the refs against a
 // release, so the server can tell a silent probe (fix holding) from
 // deleted code.