@goliapkg/sentori-cli 0.5.3 → 1.0.0

package/src/issue.ts

@@ -0,0 +1,82 @@
+// `sentori-cli issue list / resolve` — CI triage over the AI
+// surface (`/api/*`, api-scope token; the same loop an agent runs).
+
+type Issue = {
+  id: string
+  kind: string
+  title: string
+  messageSample: string
+  status: string
+  eventCount: number
+  usersCount: number
+  maxPerUser: number
+  lastSeen: string
+  regressed: boolean
+}
+
+export type ApiConfig = {
+  apiUrl: string
+  token: string
+}
+
+async function apiFetch<T>(c: ApiConfig, path: string, init?: RequestInit): Promise<T> {
+  const resp = await fetch(`${c.apiUrl.replace(/\/+$/, '')}${path}`, {
+    ...init,
+    headers: {
+      Authorization: `Bearer ${c.token}`,
+      'Content-Type': 'application/json',
+      ...(init?.headers ?? {}),
+    },
+  })
+  if (!resp.ok) {
+    const detail = await resp.text().catch(() => '')
+    throw new Error(
+      `${resp.status} ${resp.statusText}${detail ? ` — ${detail.slice(0, 300)}` : ''}`,
+    )
+  }
+  return (await resp.json()) as T
+}
+
+export async function listIssues(
+  c: ApiConfig,
+  opts: { status?: string; kind?: string } = {},
+): Promise<Issue[]> {
+  const q = new URLSearchParams()
+  if (opts.status) q.set('status', opts.status)
+  if (opts.kind) q.set('kind', opts.kind)
+  const qs = q.toString()
+  const body = await apiFetch<{ issues: Issue[] }>(c, `/api/issues${qs ? `?${qs}` : ''}`)
+  return body.issues
+}
+
+export async function resolveIssue(
+  c: ApiConfig,
+  issueId: string,
+  release?: string,
+): Promise<void> {
+  await apiFetch(c, `/api/issues/${encodeURIComponent(issueId)}/resolve`, {
+    method: 'POST',
+    body: JSON.stringify(release ? { release } : {}),
+  })
+}
+
+export async function noteIssue(c: ApiConfig, issueId: string, body: string): Promise<void> {
+  await apiFetch(c, `/api/issues/${encodeURIComponent(issueId)}/notes`, {
+    method: 'POST',
+    body: JSON.stringify({ body }),
+  })
+}
+
+export async function fetchBundle(c: ApiConfig, issueId: string): Promise<string> {
+  const resp = await fetch(
+    `${c.apiUrl.replace(/\/+$/, '')}/api/issues/${encodeURIComponent(issueId)}/bundle`,
+    { headers: { Authorization: `Bearer ${c.token}` } },
+  )
+  if (!resp.ok) throw new Error(`${resp.status} ${resp.statusText}`)
+  return resp.text()
+}
+
+export function formatIssueLine(i: Issue): string {
+  const flag = i.regressed ? ' REGRESSED' : ''
+  return `${i.id}  [${i.kind}] ${i.title}  ${i.usersCount}u×${i.maxPerUser}  ${i.eventCount}ev${flag}`
+}

package/src/lenient.ts

@@ -0,0 +1,39 @@
+// The iron rule reaches build-time (design.md §6 dim 3): 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
+// into a real non-zero exit for pipelines that want the hard
+// guarantee.
+
+export type LenientOutcome = {
+  /** What failed, one line. */
+  failure: string
+  /** What it means for the customer, one or two lines. */
+  impact: string
+  /** A copy-pasteable retry command. */
+  retry: string
+}
+
+export const isStrict = (argv: string[]): boolean => argv.includes('--strict')
+
+/** Strip --strict before handing argv to parseArgs. */
+export const stripStrict = (argv: string[]): string[] =>
+  argv.filter((a) => a !== '--strict')
+
+export const lenientFail = (strict: boolean, o: LenientOutcome): number => {
+  console.error(`[sentori] ⚠ ${o.failure}`)
+  if (!strict) {
+    console.error('[sentori]   Your build is NOT blocked by this.')
+  }
+  console.error(`[sentori]   Impact: ${o.impact}`)
+  console.error('[sentori]   Retry anytime:')
+  console.error(`[sentori]     ${o.retry}`)
+  console.error(
+    '[sentori]   Events received in the meantime are re-symbolicated automatically after upload.',
+  )
+  if (strict) {
+    console.error('[sentori]   (--strict: exiting non-zero)')
+    return 1
+  }
+  return 0
+}

package/src/mcp.ts

@@ -0,0 +1,230 @@
+// v1.2 W9 — Sentori MCP server.
+//
+// Stdio JSON-RPC 2.0 transport per the Model Context Protocol spec
+// (https://modelcontextprotocol.io/). LLM clients (Claude Code,
+// custom agents) spawn `sentori-cli mcp serve` as a subprocess and
+// pipe MCP messages over stdin/stdout. Each tool call translates
+// 1:1 to the existing admin API; the MCP layer is pure protocol
+// glue + auth-passthrough.
+//
+// Why CLI-hosted instead of server-hosted MCP:
+//   - The Sentori server exposes admin endpoints over HTTPS already;
+//     spinning up a parallel MCP endpoint would duplicate auth +
+//     route boilerplate.
+//   - LLM clients expect MCP servers to be local stdio subprocesses
+//     (Claude Code config, gptme, etc.). The CLI is the natural
+//     binary to embed it in — the operator already has it installed
+//     and a token configured.
+//   - Easier to ship + version with the rest of the CLI.
+
+import { createInterface } from 'node:readline'
+
+type JsonRpcRequest = {
+  id?: number | string | null
+  jsonrpc: '2.0'
+  method: string
+  params?: Record<string, unknown>
+}
+
+type JsonRpcResponse = {
+  id?: number | string | null
+  jsonrpc: '2.0'
+  result?: unknown
+  error?: { code: number; message: string; data?: unknown }
+}
+
+type ToolHandler = (args: Record<string, unknown>, ctx: McpCtx) => Promise<unknown>
+
+type ToolDef = {
+  name: string
+  description: string
+  inputSchema: Record<string, unknown>
+  handler: ToolHandler
+}
+
+type McpCtx = { apiUrl: string; token: string }
+
+/** Run the MCP server over stdio. Returns when stdin closes. */
+export async function runMcpServer(ctx: McpCtx): Promise<void> {
+  const tools = buildTools()
+  const toolMap = new Map(tools.map((t) => [t.name, t]))
+
+  const rl = createInterface({ input: process.stdin })
+  for await (const line of rl) {
+    const trimmed = line.trim()
+    if (!trimmed) continue
+    let req: JsonRpcRequest
+    try {
+      req = JSON.parse(trimmed)
+    } catch {
+      // Per spec, malformed requests get a parse-error response with
+      // null id.
+      send({
+        error: { code: -32700, message: 'Parse error' },
+        id: null,
+        jsonrpc: '2.0',
+      })
+      continue
+    }
+    // Notifications (no `id`) get no response.
+    const isNotification = req.id === undefined || req.id === null
+    try {
+      const result = await dispatch(req, toolMap, ctx, tools)
+      if (!isNotification) {
+        send({ id: req.id ?? null, jsonrpc: '2.0', result })
+      }
+    } catch (e) {
+      if (!isNotification) {
+        send({
+          error: { code: -32603, message: (e as Error).message },
+          id: req.id ?? null,
+          jsonrpc: '2.0',
+        })
+      }
+    }
+  }
+}
+
+function send(resp: JsonRpcResponse): void {
+  process.stdout.write(JSON.stringify(resp) + '\n')
+}
+
+async function dispatch(
+  req: JsonRpcRequest,
+  toolMap: Map<string, ToolDef>,
+  ctx: McpCtx,
+  tools: ToolDef[],
+): Promise<unknown> {
+  switch (req.method) {
+    case 'initialize':
+      return {
+        capabilities: { tools: {} },
+        protocolVersion: '2024-11-05',
+        serverInfo: { name: 'sentori', version: '1.0' },
+      }
+    case 'notifications/initialized':
+      return {}
+    case 'tools/list':
+      return {
+        tools: tools.map((t) => ({
+          description: t.description,
+          inputSchema: t.inputSchema,
+          name: t.name,
+        })),
+      }
+    case 'tools/call': {
+      const params = (req.params ?? {}) as { arguments?: Record<string, unknown>; name?: string }
+      const name = params.name
+      if (typeof name !== 'string') throw new Error('missing tools/call.name')
+      const tool = toolMap.get(name)
+      if (!tool) throw new Error(`unknown tool: ${name}`)
+      const result = await tool.handler(params.arguments ?? {}, ctx)
+      return {
+        content: [
+          {
+            text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
+            type: 'text',
+          },
+        ],
+      }
+    }
+    default:
+      throw new Error(`method not found: ${req.method}`)
+  }
+}
+
+// ── Tool implementations — the /api closed loop ──────────────────
+//
+// Four tools, mirroring exactly what an agent needs (design.md §9):
+// pick work, pull the evidence, write back, resolve. The bundle is
+// the product; everything else is triage plumbing.
+
+async function apiGet(ctx: McpCtx, path: string, raw = false): Promise<unknown> {
+  const url = `${ctx.apiUrl.replace(/\/+$/, '')}${path}`
+  const resp = await fetch(url, { headers: { Authorization: `Bearer ${ctx.token}` } })
+  if (!resp.ok) throw new Error(`GET ${path} → ${resp.status} ${resp.statusText}`)
+  return raw ? resp.text() : resp.json()
+}
+
+async function apiPost(ctx: McpCtx, path: string, body: unknown): Promise<unknown> {
+  const url = `${ctx.apiUrl.replace(/\/+$/, '')}${path}`
+  const resp = await fetch(url, {
+    body: JSON.stringify(body),
+    headers: {
+      Authorization: `Bearer ${ctx.token}`,
+      'Content-Type': 'application/json',
+    },
+    method: 'POST',
+  })
+  if (!resp.ok) throw new Error(`POST ${path} → ${resp.status} ${resp.statusText}`)
+  return resp.json()
+}
+
+function asString(v: unknown, name: string): string {
+  if (typeof v !== 'string' || v.length === 0) throw new Error(`${name} must be a non-empty string`)
+  return v
+}
+
+export function buildTools(): ToolDef[] {
+  return [
+    {
+      name: 'sentori_issue_list',
+      description:
+        'List issues (default: open, ordered by objective importance — regressed first, then breadth × depth). Filter with status (open|resolved|ignored) and kind (error|warn|trace|assert|probe).',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          status: { type: 'string', enum: ['open', 'resolved', 'ignored'] },
+          kind: { type: 'string', enum: ['assert', 'error', 'probe', 'trace', 'warn'] },
+        },
+      },
+      handler: async (args, ctx) => {
+        const q = new URLSearchParams()
+        if (typeof args.status === 'string') q.set('status', args.status)
+        if (typeof args.kind === 'string') q.set('kind', args.kind)
+        const qs = q.toString()
+        return apiGet(ctx, `/api/issues${qs ? `?${qs}` : ''}`)
+      },
+    },
+    {
+      name: 'sentori_issue_bundle',
+      description:
+        'Fetch the full evidence bundle for one issue as markdown — read it and you have everything needed to fix: stack, user timeline, environment, distribution, guard-probe status.',
+      inputSchema: {
+        type: 'object',
+        properties: { issueId: { type: 'string' } },
+        required: ['issueId'],
+      },
+      handler: async (args, ctx) =>
+        apiGet(ctx, `/api/issues/${encodeURIComponent(asString(args.issueId, 'issueId'))}/bundle`, true),
+    },
+    {
+      name: 'sentori_issue_note',
+      description:
+        'Append a note to an issue — write back what you did ("fixed in abc123, probe SENT-42 planted").',
+      inputSchema: {
+        type: 'object',
+        properties: { issueId: { type: 'string' }, body: { type: 'string' } },
+        required: ['issueId', 'body'],
+      },
+      handler: async (args, ctx) =>
+        apiPost(ctx, `/api/issues/${encodeURIComponent(asString(args.issueId, 'issueId'))}/notes`, {
+          body: asString(args.body, 'body'),
+        }),
+    },
+    {
+      name: 'sentori_issue_resolve',
+      description:
+        'Resolve an issue, anchored on the release that carries the fix — only a recurrence in that release or newer counts as a regression.',
+      inputSchema: {
+        type: 'object',
+        properties: { issueId: { type: 'string' }, release: { type: 'string' } },
+        required: ['issueId'],
+      },
+      handler: async (args, ctx) =>
+        apiPost(ctx, `/api/issues/${encodeURIComponent(asString(args.issueId, 'issueId'))}/resolve`, {
+          release: typeof args.release === 'string' ? args.release : undefined,
+        }),
+    },
+  ]
+}

package/src/native-artifacts.ts

@@ -0,0 +1,175 @@
+// `sentori-cli upload dsym` (iOS) + `sentori-cli upload mapping`
+// (Android). dwarfdump slice discovery stays local; the bytes land
+// on the unified artifacts endpoint (multipart kind + file).
+
+import { spawnSync } from 'node:child_process'
+import { readFile } from 'node:fs/promises'
+import { basename, extname, join } from 'node:path'
+import { statSync, readdirSync } from 'node:fs'
+
+export type AdminUpload = {
+  apiUrl: string
+  release?: string
+  token: string
+}
+
+async function uploadBytes(opts: {
+  apiUrl: string
+  token: string
+  release: string
+  kind: 'dsym' | 'proguard'
+  name: string
+  bytes: Buffer
+}): Promise<void> {
+  const form = new FormData()
+  form.append('kind', opts.kind)
+  form.append('file', new Blob([new Uint8Array(opts.bytes)]), opts.name)
+  const url = `${opts.apiUrl.replace(/\/+$/, '')}/v1/releases/${encodeURIComponent(opts.release)}/artifacts`
+  const resp = await fetch(url, {
+    body: form,
+    headers: { Authorization: `Bearer ${opts.token}` },
+    method: 'POST',
+  })
+  if (!resp.ok) {
+    const detail = await resp.text().catch(() => '')
+    throw new Error(
+      `${resp.status} ${resp.statusText}${detail ? ` — ${detail.slice(0, 300)}` : ''}`,
+    )
+  }
+}
+
+// ── dSYM ──────────────────────────────────────────────────────────
+
+export type DsymSlice = { arch: string; debugId: string; file: string }
+
+const ARCHES = new Set([
+  'arm64',
+  'arm64_32',
+  'arm64e',
+  'armv7',
+  'armv7k',
+  'armv7s',
+  'i386',
+  'x86_64',
+  'x86_64h',
+])
+
+/**
+ * Use `dwarfdump --uuid <path>` to enumerate `(arch, debug_id, file)`
+ * for each Mach-O slice. Returns [] if dwarfdump isn't installed or the
+ * output couldn't be parsed; callers should fall back to explicit
+ * `--debug-id` / `--arch` flags in that case.
+ */
+export function dsymSlicesFromDwarfdump(path: string): DsymSlice[] {
+  const r = spawnSync('dwarfdump', ['--uuid', path])
+  if (r.status !== 0 || !r.stdout) return []
+  const out: DsymSlice[] = []
+  // Output lines look like:
+  //   UUID: 1234ABCD-... (arm64) /path/to/Foo.dSYM/Contents/Resources/DWARF/Foo
+  const re = /^UUID:\s+([0-9A-Fa-f-]{32,36})\s+\(([^)]+)\)\s+(.+)\s*$/m
+  for (const line of r.stdout.toString().split('\n')) {
+    const m = re.exec(line)
+    if (!m) continue
+    const [, debugId, arch, file] = m as unknown as [string, string, string, string]
+    if (!ARCHES.has(arch)) continue
+    out.push({ arch, debugId: debugId.toUpperCase(), file: file.trim() })
+  }
+  return out
+}
+
+/** Walk a `.dSYM` bundle and return the DWARF binary files inside
+ *  `Contents/Resources/DWARF/`. If `path` already points at a binary
+ *  (not a bundle), returns `[path]`. */
+export function dwarfBinariesIn(path: string): string[] {
+  let st
+  try {
+    st = statSync(path)
+  } catch {
+    return []
+  }
+  if (st.isFile()) return [path]
+  const dwarfDir = join(path, 'Contents/Resources/DWARF')
+  try {
+    return readdirSync(dwarfDir)
+      .filter((n) => !n.startsWith('.'))
+      .map((n) => join(dwarfDir, n))
+  } catch {
+    // not a .dSYM bundle layout — try the top-level path
+    return [path]
+  }
+}
+
+export type DsymUploadOptions = AdminUpload & {
+  /** Explicit overrides when dwarfdump isn't available. */
+  arch?: string
+  debugId?: string
+  /** A `Foo.dSYM` bundle or a raw DWARF binary. */
+  path: string
+  objectName?: string
+}
+
+export type DsymUploadResult = { slices: { arch: string; debugId: string }[] }
+
+export async function uploadDsym(opts: DsymUploadOptions): Promise<DsymUploadResult> {
+  const slices: DsymSlice[] = []
+  if (opts.debugId && opts.arch) {
+    // Explicit single-slice upload — no parsing needed.
+    const binaries = dwarfBinariesIn(opts.path)
+    if (binaries.length === 0) throw new Error(`no DWARF binary at: ${opts.path}`)
+    slices.push({ arch: opts.arch, debugId: opts.debugId.toUpperCase(), file: binaries[0]! })
+  } else {
+    // Auto-discover via dwarfdump.
+    const found = dsymSlicesFromDwarfdump(opts.path)
+    if (found.length === 0) {
+      throw new Error(
+        'couldn’t enumerate dSYM slices — install Xcode command-line tools ' +
+          '(for `dwarfdump`), or pass --debug-id and --arch explicitly',
+      )
+    }
+    slices.push(...found)
+  }
+
+  const objectName = opts.objectName ?? basename(opts.path).replace(/\.dSYM$/, '')
+  const uploaded: { arch: string; debugId: string }[] = []
+  for (const s of slices) {
+    const bytes = await readFile(s.file)
+    // One artifact per slice; the name carries the lookup identity
+    // (object-arch-debugId) until the dwarf wiring lands server-side.
+    await uploadBytes({
+      apiUrl: opts.apiUrl,
+      token: opts.token,
+      release: opts.release ?? '',
+      kind: 'dsym',
+      name: `${objectName}-${s.arch}-${s.debugId}`,
+      bytes,
+    })
+    uploaded.push({ arch: s.arch, debugId: s.debugId })
+  }
+  return { slices: uploaded }
+}
+
+// ── ProGuard / R8 mapping ─────────────────────────────────────────
+
+export type MappingUploadOptions = AdminUpload & {
+  debugId?: string
+  path: string
+}
+
+export async function uploadMapping(opts: MappingUploadOptions): Promise<void> {
+  const ext = extname(opts.path).toLowerCase()
+  if (ext && ext !== '.txt' && ext !== '.map') {
+    // R8 emits `mapping.txt` by default; accept anything but warn.
+    console.warn(`[sentori-cli] upload mapping: unexpected extension ${ext} — uploading anyway`)
+  }
+  const body = await readFile(opts.path)
+  if (body.length === 0) throw new Error(`empty mapping file: ${opts.path}`)
+
+  await uploadBytes({
+    apiUrl: opts.apiUrl,
+    token: opts.token,
+    release: opts.release ?? '',
+    kind: 'proguard',
+    name: opts.debugId ? `mapping-${opts.debugId}.txt` : basename(opts.path),
+    bytes: body,
+  })
+}

package/src/probes.ts

@@ -0,0 +1,75 @@
+// `sentori-cli probes sync` — the tripwire registry scan
+// (design.md §2). 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.
+
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+const PROBE_RE = /\bprobe\(\s*['"`]([^'"`]{1,200})['"`]/g
+const SCAN_EXTS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'])
+const SKIP_DIRS = new Set(['node_modules', '.git', 'lib', 'dist', 'build', '.expo'])
+const MAX_FILES = 20_000
+
+export function scanProbes(root: string): string[] {
+  const refs = new Set<string>()
+  let seen = 0
+  const walk = (dir: string): void => {
+    if (seen > MAX_FILES) return
+    let entries: string[]
+    try {
+      entries = readdirSync(dir)
+    } catch {
+      return
+    }
+    for (const name of entries) {
+      if (SKIP_DIRS.has(name)) continue
+      const p = join(dir, name)
+      let st
+      try {
+        st = statSync(p)
+      } catch {
+        continue
+      }
+      if (st.isDirectory()) {
+        walk(p)
+      } else if (st.isFile()) {
+        const dot = name.lastIndexOf('.')
+        if (dot === -1 || !SCAN_EXTS.has(name.slice(dot))) continue
+        seen += 1
+        try {
+          const text = readFileSync(p, 'utf8')
+          for (const m of text.matchAll(PROBE_RE)) {
+            const ref = m[1]
+            if (ref) refs.add(ref)
+          }
+        } catch {
+          // unreadable file — skip
+        }
+      }
+    }
+  }
+  walk(root)
+  return [...refs].sort()
+}
+
+export async function syncProbes(opts: {
+  apiUrl: string
+  token: string
+  release: string
+  refs: string[]
+}): Promise<{ registered: number }> {
+  const resp = await fetch(`${opts.apiUrl.replace(/\/+$/, '')}/api/probes:sync`, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${opts.token}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ release: opts.release, refs: opts.refs }),
+  })
+  if (!resp.ok) {
+    throw new Error(`probes:sync ${resp.status} ${await resp.text().catch(() => '')}`)
+  }
+  return (await resp.json()) as { registered: number }
+}