@goliapkg/sentori-cli 1.5.0 → 1.6.0

package/src/srcbundle.ts

@@ -1,71 +1,160 @@
-// `sentori-cli upload srcbundle` — native source context without
-// repository access.
-//
-// Walks the given directories for native source files, packs them
-// as one JSON object (project-relative path → content), and lands
-// it on the artifacts endpoint as kind `srcbundle`. The server
-// reads it when a dSYM/proguard frame resolves to file+line, so
-// the dashboard shows the failing native code the same way a
-// sourcemap's embedded sourcesContent covers JS. The build owns
-// exactly what goes in — nothing is pulled from git, ever.
-
-import { readFileSync, readdirSync, statSync } from 'node:fs'
-import { join, relative } from 'node:path'
-
-/** Native + shared-code extensions worth carrying. JS/TS ride the
- *  sourcemap already; including them anyway is harmless but bulky,
- *  so they stay out by default. */
-const SOURCE_EXTS = new Set(['.swift', '.kt', '.kts', '.java', '.m', '.mm', '.h', '.c', '.cc', '.cpp', '.hpp'])
-
-const SKIP_DIRS = new Set(['node_modules', '.git', 'build', 'Pods', 'DerivedData', '.gradle', 'dist'])
-
-/** A single source file larger than this is generated, not written. */
-const MAX_FILE_BYTES = 512 * 1024
-/** Total budget before compression; the wire is gzip anyway. */
-const MAX_TOTAL_BYTES = 64 * 1024 * 1024
+// Source archives are build artifacts. Directory mode needs no repository;
+// tag mode reads immutable Git objects without changing the working tree.
+import { execFileSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { lstatSync, readFileSync, readdirSync, realpathSync } from 'node:fs'
+import { extname, isAbsolute, relative, resolve, sep } from 'node:path'
+import { unzipSync, zipSync } from 'fflate'
 
+export const SOURCE_MANIFEST = 'sentori-source-manifest.json'
+export const MAX_SOURCE_FILE_BYTES = 512 * 1024
+export const MAX_SOURCE_BYTES = 64 * 1024 * 1024
+const MAX_FILES = 10000
+const SOURCE_EXTS = new Set(['.swift', '.kt', '.kts', '.java', '.m', '.mm', '.h', '.c', '.cc', '.cpp', '.hpp', '.js', '.jsx', '.ts', '.tsx', '.vue', '.svelte', '.rs', '.go', '.py', '.rb', '.php', '.cs', '.dart'])
+const SKIP_DIRS = new Set(['node_modules', 'build', 'Pods', 'DerivedData', 'dist', 'target', 'vendor', '__pycache__'])
 export type SrcBundleStats = { files: number; bytes: number; skipped: number }
+export type SourceOptions = { root?: string; exclude?: string[]; gitTag?: string }
+export type SourceManifest = {
+  version: 1
+  release: string
+  source: { type: 'directory' | 'git-tag'; tag?: string; commit?: string }
+  files: { path: string; bytes: number; sha256: string }[]
+}
+export type CollectedSources = { bundle: Record<string, string>; stats: SrcBundleStats; source: SourceManifest['source'] }
+const sha256 = (bytes: Uint8Array): string => createHash('sha256').update(bytes).digest('hex')
 
-/** Collect `{ relPath: content }` from the roots. */
-export function collectSources(roots: string[]): { bundle: Record<string, string>; stats: SrcBundleStats } {
-  const bundle: Record<string, string> = {}
-  const stats: SrcBundleStats = { files: 0, bytes: 0, skipped: 0 }
+export function safeSourcePath(path: string): boolean {
+  return path.length > 0 && path.length <= 1024 && !/[\\\x00-\x1f:]/.test(path)
+    && !path.startsWith('/') && path.split('/').every(part => part !== '' && part !== '.' && part !== '..')
+}
+function selected(path: string, includes: string[], excludes: string[]): boolean {
+  const under = (parent: string): boolean => parent === '.' || path === parent || path.startsWith(`${parent}/`)
+  return includes.some(under) && !excludes.some(under)
+}
+function sourcePath(path: string, includes: string[]): boolean {
+  return safeSourcePath(path) && SOURCE_EXTS.has(extname(path).toLowerCase())
+    && !path.split('/').some((part, index, parts) => part.startsWith('.') || SKIP_DIRS.has(part)
+      && !includes.some(include => include === parts.slice(0, index + 1).join('/') || include.startsWith(parts.slice(0, index + 1).join('/') + '/')))
+}
+function readText(bytes: Uint8Array, path: string): string {
+  if (bytes.includes(0)) throw new Error(`source is not UTF-8 text: ${path}`)
+  try { return new TextDecoder('utf-8', { fatal: true }).decode(bytes) }
+  catch { throw new Error(`source is not UTF-8 text: ${path}`) }
+}
+function selectionPath(root: string, path: string): string {
+  const rel = relative(root, resolve(root, path)).split(sep).join('/') || '.'
+  if (rel !== '.' && !safeSourcePath(rel)) throw new Error(`source path is outside --root: ${path}`)
+  return rel
+}
 
-  const walk = (root: string, dir: string): void => {
-    let entries
-    try {
-      entries = readdirSync(dir, { withFileTypes: true })
-    } catch {
-      return
+/** Keep every path relative to ONE root, even with several selected directories. */
+export function collectSources(paths: string[], options: SourceOptions = {}): CollectedSources {
+  if (!paths.length) throw new Error('choose source directories or files (for example: ios android/app/src shared)')
+  const root = realpathSync(resolve(options.root ?? '.'))
+  const includes = paths.map(path => selectionPath(root, path))
+  const excludes = (options.exclude ?? []).map(path => selectionPath(root, path))
+  const bundle: Record<string, string> = Object.create(null)
+  const stats: SrcBundleStats = { files: 0, bytes: 0, skipped: 0 }
+  const add = (path: string, bytes: Uint8Array): void => {
+    if (Object.hasOwn(bundle, path)) return
+    if (bytes.length > MAX_SOURCE_FILE_BYTES) throw new Error(`source exceeds 512 KiB: ${path}; explicitly exclude it if not needed`)
+    if (stats.bytes + bytes.length > MAX_SOURCE_BYTES || stats.files >= MAX_FILES) throw new Error('source bundle exceeds 64 MiB or 10000 files; narrow the selected directories')
+    bundle[path] = readText(bytes, path)
+    stats.files++
+    stats.bytes += bytes.length
+  }
+  let source: SourceManifest['source'] = { type: 'directory' }
+  if (options.gitTag) {
+    const git = (args: string[], limit = MAX_SOURCE_BYTES): Buffer => execFileSync('git', ['-C', root, ...args], { maxBuffer: limit, stdio: ['ignore', 'pipe', 'pipe'] })
+    const top = realpathSync(git(['rev-parse', '--show-toplevel']).toString().trim())
+    if (root !== top) throw new Error('--root must be the repository root when using --git-tag')
+    const tag = options.gitTag
+    git(['check-ref-format', `refs/tags/${tag}`])
+    const commit = git(['rev-parse', '--verify', `refs/tags/${tag}^{commit}`]).toString().trim()
+    if (!/^[0-9a-f]{40,64}$/.test(commit)) throw new Error('tag did not resolve to a commit')
+    source = { type: 'git-tag', tag, commit }
+    const records = git(['ls-tree', '-rlz', '--full-tree', commit]).toString().split('\0').filter(Boolean)
+    const matched = new Set<string>()
+    for (const record of records) {
+      const tab = record.indexOf('\t')
+      const path = record.slice(tab + 1)
+      if (!selected(path, includes, excludes) || !sourcePath(path, includes)) continue
+      const [mode, type, oid, size] = record.slice(0, tab).trim().split(/\s+/)
+      if (type !== 'blob' || !['100644', '100755'].includes(mode!)) { stats.skipped++; continue }
+      if (Number(size) > MAX_SOURCE_FILE_BYTES) throw new Error(`source exceeds 512 KiB: ${path}`)
+      for (const item of includes) if (selected(path, [item], [])) matched.add(item)
+      add(path, git(['cat-file', 'blob', oid!], MAX_SOURCE_FILE_BYTES + 1))
     }
-    for (const e of entries) {
-      if (e.isDirectory()) {
-        if (!SKIP_DIRS.has(e.name) && !e.name.startsWith('.')) walk(root, join(dir, e.name))
-        continue
-      }
-      const dot = e.name.lastIndexOf('.')
-      if (dot < 0 || !SOURCE_EXTS.has(e.name.slice(dot))) continue
-      const full = join(dir, e.name)
-      let size
-      try {
-        size = statSync(full).size
-      } catch {
-        continue
-      }
-      if (size > MAX_FILE_BYTES || stats.bytes + size > MAX_TOTAL_BYTES) {
-        stats.skipped += 1
-        continue
-      }
-      try {
-        bundle[relative(root, full)] = readFileSync(full, 'utf8')
-        stats.files += 1
-        stats.bytes += size
-      } catch {
-        stats.skipped += 1
+    for (const item of includes) if (!matched.has(item)) throw new Error(`no source files at tag ${tag} under ${item}`)
+  } else {
+    const walk = (path: string): void => {
+      const full = resolve(root, path)
+      const stat = lstatSync(full)
+      if (stat.isSymbolicLink()) { stats.skipped++; return }
+      const real = relative(root, realpathSync(full))
+      if (real.startsWith(`..${sep}`) || real === '..' || isAbsolute(real)) throw new Error(`source resolves outside --root: ${path}`)
+      if (stat.isDirectory()) {
+        for (const entry of readdirSync(full).sort()) {
+          if (entry.startsWith('.') || SKIP_DIRS.has(entry)) { stats.skipped++; continue }
+          const child = path === '.' ? entry : `${path}/${entry}`
+          if (excludes.some(x => child === x || child.startsWith(`${x}/`))) continue
+          walk(child)
+        }
+      } else if (stat.isFile() && sourcePath(path, includes) && selected(path, includes, excludes)) {
+        if (stat.size > MAX_SOURCE_FILE_BYTES) throw new Error(`source exceeds 512 KiB: ${path}`)
+        add(path, readFileSync(full))
       }
     }
+    for (const path of includes) walk(path)
   }
+  if (!stats.files) throw new Error('no supported source files selected; choose the application source directories')
+  return { bundle, stats, source }
+}
 
-  for (const root of roots) walk(root, root)
-  return { bundle, stats }
+export function packSources(paths: string[], release: string, options: SourceOptions = {}): { bytes: Uint8Array; manifest: SourceManifest; stats: SrcBundleStats } {
+  if (!release.trim()) throw new Error('release is required and must match the SDK release')
+  const { bundle, stats, source } = collectSources(paths, options)
+  const entries: Record<string, Uint8Array> = Object.create(null)
+  const manifest: SourceManifest = { version: 1, release, source, files: [] }
+  for (const path of Object.keys(bundle).sort()) {
+    const bytes = Buffer.from(bundle[path]!, 'utf8')
+    entries[path] = bytes
+    manifest.files.push({ path, bytes: bytes.length, sha256: sha256(bytes) })
+  }
+  entries[SOURCE_MANIFEST] = Buffer.from(JSON.stringify(manifest, null, 2) + '\n')
+  return { bytes: zipSync(entries, { level: 6, mtime: new Date(2000, 0, 1) }), manifest, stats }
+}
+
+/** Validate in memory; the server independently repeats validation. */
+export function inspectSourceArchive(bytes: Uint8Array, release?: string): { files: string[]; manifest?: SourceManifest } {
+  if (bytes.length > MAX_SOURCE_BYTES + 4 * 1024 * 1024) throw new Error('source archive is too large')
+  const names = new Set<string>()
+  let total = 0
+  const files = unzipSync(bytes, { filter: file => {
+    const path = file.name.replace(/\/$/, '')
+    if (!safeSourcePath(path) || names.has(path)) throw new Error(`unsafe or duplicate ZIP path: ${file.name}`)
+    names.add(path)
+    if (names.size > MAX_FILES + 1) throw new Error('ZIP contains too many entries')
+    const limit = path === SOURCE_MANIFEST ? 4 * 1024 * 1024 : MAX_SOURCE_FILE_BYTES
+    total += file.originalSize
+    if (file.originalSize > limit || total > MAX_SOURCE_BYTES + 4 * 1024 * 1024) throw new Error('ZIP exceeds source size limits')
+    return !file.name.endsWith('/')
+  } })
+  const sources = Object.keys(files).filter(path => path !== SOURCE_MANIFEST)
+  if (!sources.length) throw new Error('source ZIP is empty')
+  for (const path of sources) readText(files[path]!, path)
+  let manifest: SourceManifest | undefined
+  if (files[SOURCE_MANIFEST]) {
+    manifest = JSON.parse(readText(files[SOURCE_MANIFEST]!, SOURCE_MANIFEST)) as SourceManifest
+    if (!manifest || manifest.version !== 1 || typeof manifest.release !== 'string' || !manifest.release.trim() || !Array.isArray(manifest.files)
+      || !manifest.source || !['directory', 'git-tag'].includes(manifest.source.type)
+      || manifest.files.some(file => !file || typeof file.path !== 'string')) throw new Error('invalid source manifest')
+    if (release && manifest.release !== release) throw new Error(`ZIP release ${manifest.release} does not match ${release}`)
+    if (manifest.files.length !== sources.length || new Set(manifest.files.map(file => file.path)).size !== sources.length) throw new Error('source manifest file list does not match ZIP')
+    for (const file of manifest.files) {
+      const body = files[file.path]
+      if (!body || body.length !== file.bytes || sha256(body) !== file.sha256) throw new Error(`source manifest checksum mismatch: ${file.path}`)
+    }
+  }
+  return { files: sources.sort(), manifest }
 }

package/src/upload.ts

@@ -14,7 +14,8 @@
 // (a real RN app's main dSYM runs hundreds of MB) fit as gzip.
 
 import { readFileSync } from 'node:fs'
-import { basename } from 'node:path'
+import { readdirSync, statSync } from 'node:fs'
+import { basename, join, relative, sep } from 'node:path'
 import { gzipSync } from 'node:zlib'
 
 export type UploadOpts = {
@@ -91,6 +92,55 @@ export function warnIfUnusable(name: string, v: UploadVerdict): boolean {
   return true
 }
 
+/**
+ * Turn one path into the source maps under it, each with the name the
+ * server should store.
+ *
+ * A file keeps its basename. A **directory** is walked, and every map
+ * under it keeps its path *relative to that directory* — so
+ * `dist/pages/cart/index.js.map` is stored as
+ * `pages/cart/index.js.map` and not as `index.js.map`.
+ *
+ * That difference is the whole feature. The server matches a frame to
+ * a map by how many trailing path segments they share, precisely
+ * because a WeChat mini program names every page's entry `index.js`
+ * and a web build names every route chunk after its route. Sending
+ * only the basename threw that away on the client, so the matching
+ * could never see more than a filename however carefully it was
+ * written.
+ *
+ * Passing a directory used to read the directory as a file and throw
+ * `EISDIR`, while `docs/getting-started/web.md` told readers to pass
+ * `./dist`.
+ */
+export function expandSourcemapPaths(path: string): { path: string; name: string }[] {
+  let stat
+  try {
+    stat = statSync(path)
+  } catch {
+    // Let the caller's read produce the real error, with the real
+    // path in it.
+    return [{ path, name: basename(path) }]
+  }
+  if (!stat.isDirectory()) return [{ path, name: basename(path) }]
+
+  const out: { path: string; name: string }[] = []
+  const walk = (dir: string): void => {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, e.name)
+      if (e.isDirectory()) walk(full)
+      else if (e.name.endsWith('.map') || e.name.endsWith('.map.gz')) {
+        // POSIX separators on the wire whatever the build machine is:
+        // the server compares these against a frame's `file`, which is
+        // a URL or a module path, and neither uses a backslash.
+        out.push({ path: full, name: relative(path, full).split(sep).join('/') })
+      }
+    }
+  }
+  walk(path)
+  return out
+}
+
 export async function uploadArtifact(opts: UploadOpts): Promise<UploadVerdict> {
   const bytes = readFileSync(opts.path)
   if (bytes.length === 0) throw new Error(`empty file: ${opts.path}`)

package/src/workflow.ts

@@ -0,0 +1,240 @@
+import { createHash } from 'node:crypto'
+import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { basename, dirname, resolve } from 'node:path'
+import { gunzipSync } from 'node:zlib'
+import { parseArgs } from 'node:util'
+import { fetchArtifacts } from './artifacts.js'
+import { checkCompatibility } from './compatibility.js'
+import { dwarfBinariesIn } from './native-artifacts.js'
+import { inspectSourceArchive, packSources, type SourceOptions } from './srcbundle.js'
+import { expandSourcemapPaths, uploadArtifact, type UploadOpts } from './upload.js'
+import { isStrict, lenientFail, stripStrict } from './lenient.js'
+
+export type UploadConfig = {
+  version: 1
+  apiUrl: string
+  tokenEnv: string
+  release?: string
+  artifacts: { sourcemap?: string[]; dsym?: string[]; mapping?: string[] }
+  sources?: { root?: string; include: string[]; exclude?: string[]; gitTag?: string }
+  sourceArchive?: string
+}
+export type UploadPlan = {
+  release: string
+  apiUrl: string
+  tokenEnv: string
+  files: { kind: UploadOpts['kind']; name: string; path: string; hash: string; bytes: number }[]
+  source?: { files: string[]; tag?: string; commit?: string }
+}
+const hash = (bytes: Uint8Array): string => createHash('sha256').update(bytes).digest('hex')
+const commonOptions = {
+  config: { type: 'string' }, release: { type: 'string' }, 'api-url': { type: 'string' },
+  'git-tag': { type: 'string' }, 'dry-run': { type: 'boolean' }, help: { type: 'boolean', short: 'h' },
+} as const
+export const WORKFLOW_HELP = `Release uploads:
+  sentori init --api-url <url> [--release <r>] [--sourcemap <path>] [--dsym <path>]
+               [--mapping <path>] [--sources <dir>] [--git-tag <tag>] [--config <file>]
+  sentori config validate [--config sentori.config.json] [--release <r>]
+  sentori doctor [--config sentori.config.json] [--api-url <url>]
+  sentori upload all [--config sentori.config.json] [--release <r>] [--git-tag <tag>]
+                    [--dry-run] [--strict]
+  sentori verify [--config sentori.config.json] [--release <r>] [--git-tag <tag>]
+  sentori sources pack --release <r> --output sources.zip [--root .] [--git-tag <tag>]
+                       [--exclude <path>] <source-dir-or-file...>
+  sentori upload srcbundle --release <r> [--root .] [--git-tag <tag>] <sources.zip|source-dir...>
+
+Paths in config are relative to that config. Sources keep paths relative to sources.root.
+Set the API-scope token in SENTORI_TOKEN (or the configured tokenEnv); init never stores it.
+Release must match the SDK exactly, including its build number. SENTORI_RELEASE is supported.
+Git mode reads the specified tag's commit, never the working tree or a guessed latest tag.
+Verification checks every planned file's bytes and server validation; it does not claim event matching.
+`
+function object(value: unknown): value is Record<string, unknown> { return !!value && typeof value === 'object' && !Array.isArray(value) }
+function strings(value: unknown, label: string): string[] {
+  if (!Array.isArray(value) || value.some(x => typeof x !== 'string' || !x.trim())) throw new Error(`${label} must be an array of paths`)
+  return value as string[]
+}
+export function loadUploadConfig(path: string): UploadConfig {
+  const value: unknown = JSON.parse(readFileSync(path, 'utf8'))
+  if (!object(value) || value.version !== 1 || typeof value.apiUrl !== 'string' || !object(value.artifacts)) throw new Error('config requires version: 1, apiUrl, and artifacts; run sentori init')
+  if (Object.hasOwn(value, 'token')) throw new Error('store the API token in the environment and set tokenEnv, not token in the config')
+  const allowed = new Set(['version', 'apiUrl', 'tokenEnv', 'release', 'artifacts', 'sources', 'sourceArchive'])
+  for (const key of Object.keys(value)) if (!allowed.has(key)) throw new Error(`unknown config field: ${key}`)
+  for (const [kind, paths] of Object.entries(value.artifacts)) {
+    if (!['sourcemap', 'dsym', 'mapping'].includes(kind)) throw new Error(`unknown artifact kind ${kind}; use sourcemap, dsym, or mapping`)
+    strings(paths, `artifacts.${kind}`)
+  }
+  if (value.release !== undefined && (typeof value.release !== 'string' || !value.release.trim())) throw new Error('release must be a non-empty string')
+  if (value.sourceArchive !== undefined && typeof value.sourceArchive !== 'string') throw new Error('sourceArchive must be a ZIP path')
+  if (value.sources !== undefined) {
+    if (!object(value.sources)) throw new Error('sources must declare include paths')
+    for (const key of Object.keys(value.sources)) if (!['root', 'include', 'exclude', 'gitTag'].includes(key)) throw new Error(`unknown sources field: ${key}`)
+    strings(value.sources.include, 'sources.include')
+    if (value.sources.exclude !== undefined) strings(value.sources.exclude, 'sources.exclude')
+    for (const key of ['root', 'gitTag']) if (value.sources[key] !== undefined && typeof value.sources[key] !== 'string') throw new Error(`sources.${key} must be a string`)
+  }
+  if (value.sources && value.sourceArchive) throw new Error('choose sources or sourceArchive, not both')
+  const tokenEnv = value.tokenEnv ?? 'SENTORI_TOKEN'
+  if (typeof tokenEnv !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(tokenEnv)) throw new Error('tokenEnv must name an environment variable')
+  return { ...value, tokenEnv } as UploadConfig
+}
+function apiUrl(raw: string): string {
+  const url = new URL(raw)
+  if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) throw new Error('apiUrl must be an HTTP(S) instance URL without credentials, query, or fragment')
+  return url.toString().replace(/\/+$/, '')
+}
+function validateArtifact(kind: UploadOpts['kind'], bytes: Buffer, name: string): void {
+  if (!bytes.length) throw new Error(`empty artifact: ${name}`)
+  if (kind === 'sourcemap') {
+    const map = JSON.parse(bytes.toString('utf8'))
+    if (map?.version !== 3 || !(Array.isArray(map.sections) || Array.isArray(map.sources) && typeof map.mappings === 'string')) throw new Error(`not a version 3 source map: ${name}`)
+  }
+  if (kind === 'proguard' && !/^\S.* -> \S+:\s*$/m.test(bytes.toString('utf8'))) throw new Error(`no ProGuard/R8 class mappings in ${name}`)
+  if (kind === 'dsym' && !['feedface', 'cefaedfe', 'feedfacf', 'cffaedfe', 'cafebabe', 'bebafeca', 'cafebabf', 'bfbafeca'].includes(bytes.subarray(0, 4).toString('hex'))) throw new Error(`not a Mach-O DWARF binary: ${name}`)
+}
+export function prepareUploadPlan(configPath: string, overrides: { release?: string; apiUrl?: string; gitTag?: string } = {}): UploadPlan {
+  const config = loadUploadConfig(configPath)
+  const base = dirname(resolve(configPath))
+  const release = overrides.release ?? process.env.SENTORI_RELEASE ?? config.release
+  if (!release?.trim()) throw new Error('set --release, SENTORI_RELEASE, or config.release to the exact SDK release')
+  const plan: UploadPlan = { release, apiUrl: apiUrl(overrides.apiUrl ?? process.env.SENTORI_API_URL ?? config.apiUrl), tokenEnv: config.tokenEnv, files: [] }
+  const add = (kind: UploadOpts['kind'], path: string, name = basename(path)): void => {
+    let bytes = readFileSync(path)
+    if (bytes[0] === 0x1f && bytes[1] === 0x8b) { bytes = gunzipSync(bytes, { maxOutputLength: 512 * 1024 * 1024 }); name = name.replace(/\.gz$/, '') }
+    validateArtifact(kind, bytes, name)
+    const digest = hash(bytes)
+    const collision = plan.files.find(file => file.kind === kind && file.name === name)
+    if (collision) {
+      if (collision.hash !== digest) throw new Error(`two different ${kind} files would overwrite ${name}; choose distinct upload paths`)
+      return
+    }
+    plan.files.push({ kind, path, name, hash: digest, bytes: bytes.length })
+  }
+  for (const path of config.artifacts.sourcemap ?? []) {
+    const maps = expandSourcemapPaths(resolve(base, path))
+    if (!maps.length) throw new Error(`no source maps under ${path}`)
+    for (const file of maps) add('sourcemap', file.path, file.name)
+  }
+  for (const path of config.artifacts.dsym ?? []) {
+    const full = resolve(base, path)
+    const files = dwarfBinariesIn(full)
+    if (!files.length) throw new Error(`no dSYM binaries under ${path}`)
+    for (const file of files) add('dsym', file, lstatSync(full).isDirectory() ? `${basename(full)}-${basename(file)}` : basename(file))
+  }
+  for (const path of config.artifacts.mapping ?? []) add('proguard', resolve(base, path))
+  if (config.sources) {
+    const packed = packSources(config.sources.include, release, {
+      root: resolve(base, config.sources.root ?? '.'), exclude: config.sources.exclude,
+      gitTag: overrides.gitTag ?? config.sources.gitTag,
+    })
+    const dir = resolve(base, '.sentori')
+    mkdirSync(dir, { recursive: true })
+    const archive = resolve(dir, `sources-${hash(packed.bytes)}.zip`)
+    writeFileSync(archive, packed.bytes)
+    add('srcbundle', archive, 'sources.zip')
+    plan.source = { files: packed.manifest.files.map(file => file.path), tag: packed.manifest.source.tag, commit: packed.manifest.source.commit }
+  } else if (overrides.gitTag) throw new Error('--git-tag requires sources in the config')
+  if (config.sourceArchive) {
+    const archive = resolve(base, config.sourceArchive)
+    const source = inspectSourceArchive(readFileSync(archive), release)
+    add('srcbundle', archive)
+    plan.source = { files: source.files, tag: source.manifest?.source.tag, commit: source.manifest?.source.commit }
+  }
+  if (!plan.files.length) throw new Error('config selects no files; declare artifacts or sources')
+  return plan
+}
+export async function verifyUploadPlan(plan: UploadPlan, token: string): Promise<string[]> {
+  const result = await fetchArtifacts({ ...plan, token })
+  if (!result.known || result.release !== plan.release) return [`release not found: ${plan.release}`]
+  const problems: string[] = []
+  for (const file of plan.files) {
+    const matches = result.artifacts.filter(row => row.kind === file.kind && row.contentHash === file.hash
+      && (file.kind === 'dsym' || row.name === file.name))
+    if (!matches.length) problems.push(`missing exact bytes: ${file.kind} ${file.name}`)
+    else if (!matches.some(row => row.usable === true)) problems.push(`${matches.some(row => row.usable === false) ? 'unreadable' : 'not verified by server'}: ${file.kind} ${file.name}`)
+  }
+  return problems
+}
+export async function runWorkflow(command: 'init' | 'validate' | 'upload' | 'verify' | 'doctor', argv: string[]): Promise<number> {
+  const strict = isStrict(argv)
+  try {
+    const parsed = parseArgs({ args: stripStrict(argv), options: { ...commonOptions,
+      ...(command === 'init' ? { sourcemap: { type: 'string', multiple: true }, dsym: { type: 'string', multiple: true }, mapping: { type: 'string', multiple: true }, sources: { type: 'string', multiple: true } } as const : {}),
+    } })
+    if (parsed.values.help) { console.log(WORKFLOW_HELP); return 0 }
+    if (parsed.values['dry-run'] && command !== 'upload') throw new Error('--dry-run is only supported by upload all; doctor and verify must contact the server')
+    const configPath = resolve(parsed.values.config ?? 'sentori.config.json')
+    if (command === 'init') {
+      const v = parsed.values as Record<string, string | string[] | boolean | undefined>
+      const base = dirname(configPath)
+      const config: UploadConfig = {
+        version: 1, apiUrl: apiUrl(parsed.values['api-url'] ?? process.env.SENTORI_API_URL ?? 'https://sentori.golia.jp'),
+        tokenEnv: 'SENTORI_TOKEN', ...(parsed.values.release ? { release: parsed.values.release } : {}),
+        artifacts: { sourcemap: v.sourcemap as string[] ?? [], dsym: v.dsym as string[] ?? [], mapping: v.mapping as string[] ?? [] },
+      }
+      const include = v.sources as string[] ?? ['src', 'Sources', 'ios', 'android/app/src'].filter(path => existsSync(resolve(base, path)))
+      if (include.length) config.sources = { root: '.', include, exclude: [], ...(parsed.values['git-tag'] ? { gitTag: parsed.values['git-tag'] } : {}) }
+      else if (parsed.values['git-tag']) throw new Error('--git-tag requires --sources paths')
+      writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', { flag: 'wx' })
+      console.log(`Created ${configPath}. Review source paths and build artifact paths. Keep .sentori/ out of version control.\nSet SENTORI_TOKEN and the exact SDK release, then run sentori config validate and sentori upload all.`)
+      return 0
+    }
+    if (command === 'doctor') {
+      const config = loadUploadConfig(configPath)
+      const token = process.env[config.tokenEnv]
+      if (!token) throw new Error(`set ${config.tokenEnv} to an API-scope token`)
+      const result = await fetchArtifacts({
+        apiUrl: apiUrl(parsed.values['api-url'] ?? process.env.SENTORI_API_URL ?? config.apiUrl), token,
+        release: parsed.values.release ?? process.env.SENTORI_RELEASE ?? config.release ?? '__sentori_compatibility_check__',
+      })
+      console.log(checkCompatibility(result, !!(config.sources || config.sourceArchive)))
+      console.log(`Node ${process.versions.node}; API token accepted. No files uploaded. Build artifacts and event/build matching were not checked.`)
+      return 0
+    }
+    const plan = prepareUploadPlan(configPath, { release: parsed.values.release, apiUrl: parsed.values['api-url'], gitTag: parsed.values['git-tag'] })
+    console.log(JSON.stringify(plan, null, 2))
+    if (command === 'validate' || parsed.values['dry-run']) { console.log('Local files checked; no upload or server verification performed.'); return 0 }
+    const token = process.env[plan.tokenEnv]
+    if (!token) throw new Error(`set ${plan.tokenEnv} to an API-scope token`)
+    // Check credentials before the first write. An unknown release is allowed.
+    console.log(checkCompatibility(await fetchArtifacts({ ...plan, token }), plan.files.some(file => file.kind === 'srcbundle')))
+    const failures: string[] = []
+    if (command === 'upload') {
+      for (const file of plan.files) {
+        try {
+          // Prevent edits between planning and upload from invalidating the receipt.
+          let body = readFileSync(file.path)
+          if (body[0] === 0x1f && body[1] === 0x8b) body = gunzipSync(body, { maxOutputLength: 512 * 1024 * 1024 })
+          if (hash(body) !== file.hash) throw new Error('file changed after local validation')
+          const verdict = await uploadArtifact({ ...plan, token, ...file })
+          if (verdict.usable !== true) failures.push(`${file.name}: ${verdict.usable === false ? 'unreadable' : 'not verified by server'}`)
+        } catch (error) { failures.push(`${file.name}: ${error instanceof Error ? error.message : String(error)}`) }
+      }
+    }
+    failures.push(...await verifyUploadPlan(plan, token))
+    if (failures.length) throw new Error(failures.join('\n'))
+    console.log(`Verified ${plan.files.length} exact file(s) for ${plan.release}: stored bytes match and format checks passed. Event/build matching is not asserted.`)
+    return 0
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    if (command === 'upload') return lenientFail(strict, { failure: message, impact: 'some planned debug files are missing or unverified', retry: 'sentori upload all --config sentori.config.json; sentori verify --config sentori.config.json' })
+    console.error(`[sentori] ${message}`)
+    return 1
+  }
+}
+export async function runSourcesPack(argv: string[]): Promise<number> {
+  try {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: {
+      release: { type: 'string' }, root: { type: 'string' }, output: { type: 'string' },
+      'git-tag': { type: 'string' }, exclude: { type: 'string', multiple: true }, help: { type: 'boolean', short: 'h' },
+    } })
+    if (parsed.values.help) { console.log(WORKFLOW_HELP); return 0 }
+    const release = parsed.values.release ?? process.env.SENTORI_RELEASE ?? ''
+    if (!parsed.values.output) throw new Error('--output <sources.zip> is required')
+    const options: SourceOptions = { root: parsed.values.root, gitTag: parsed.values['git-tag'], exclude: parsed.values.exclude }
+    const packed = packSources(parsed.positionals, release, options)
+    writeFileSync(parsed.values.output, packed.bytes, { flag: 'wx' })
+    console.log(JSON.stringify({ output: parsed.values.output, ...packed.manifest, stats: packed.stats }, null, 2))
+    return 0
+  } catch (error) { console.error(`[sentori] ${error instanceof Error ? error.message : String(error)}`); return 1 }
+}

package/lib/source-bundle.d.ts

@@ -1,28 +0,0 @@
-import type { AdminUpload } from './native-artifacts.js';
-export type SourceBundleUploadOptions = AdminUpload & {
-    /** v1.4 W26 — optional module label so polyrepo apps (main +
-     *  watch ext + share ext etc.) can upload multiple bundles per
-     *  (release, platform). Empty/undefined → unlabelled single
-     *  bundle (v1.3 W15 behaviour). */
-    module?: string;
-    /** Pre-built tar.gz archive of the project's source tree. */
-    path: string;
-    platform: 'android' | 'ios';
-};
-export type SourceBundleUploadResult = {
-    contentHash: string;
-    kind: string;
-    sizeBytes: number;
-};
-export declare function uploadSourceBundle(opts: SourceBundleUploadOptions): Promise<SourceBundleUploadResult>;
-/** Walk `dir`, pick platform-relevant source files, and tar.gz them
- *  into a temp file. Caller is responsible for invoking `cleanup()`.
- *  Uses the system `tar` binary; that's portable enough on macOS +
- *  Linux + WSL, which covers every realistic CI environment Sentori
- *  ships to. Native Windows CI without WSL would need to gzip the
- *  archive themselves (the pre-built-path mode still works). */
-export declare function buildSourceBundleFromDir(dir: string, platform: 'android' | 'ios'): Promise<{
-    cleanup: () => Promise<void>;
-    path: string;
-}>;
-//# sourceMappingURL=source-bundle.d.ts.map

package/lib/source-bundle.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"source-bundle.d.ts","sourceRoot":"","sources":["../src/source-bundle.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAyBxD,MAAM,MAAM,yBAAyB,GAAG,WAAW,GAAG;IACpD;;;uCAGmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,SAAS,GAAG,KAAK,CAAA;CAC5B,CAAA;AAED,MAAM,MAAM,wBAAwB,GAAG;IACrC,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;CAClB,CAAA;AAED,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,yBAAyB,GAC9B,OAAO,CAAC,wBAAwB,CAAC,CA6BnC;AAuDD;;;;;gEAKgE;AAChE,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,SAAS,GAAG,KAAK,GAC1B,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAuCzD"}