@gitroll/tacitt-cli 0.0.0-stage → 0.2.0

package/skills/tacitt/scripts/journey.mjs

@@ -0,0 +1,592 @@
+import { randomUUID } from 'node:crypto'
+import { mkdir, realpath, rm } from 'node:fs/promises'
+import { join, resolve, isAbsolute } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { parseArgs } from 'node:util'
+import { main as review, withJourneyCli } from './review.mjs'
+import {
+  read,
+  optional,
+  save,
+  phaseOf,
+  activeTerms,
+  stageFingerprint,
+  procedureFor,
+  recoverWrites,
+  definiteWriteRejection,
+  resolutionAuthority,
+  resolutionEvidence,
+  planResolutions,
+  assertResolutionFresh,
+  uncoveredPending,
+} from './journey-state.mjs'
+import { classificationTasks } from './journey-classification-tasks.mjs'
+import { classificationEvidence, classificationFormat } from './journey-classification.mjs'
+import {
+  consolidateClassification,
+  classificationSubmission,
+  partialClassificationSubmission,
+} from './journey-consolidation.mjs'
+import { consolidateCards, cardSubmission } from './journey-card-consolidation.mjs'
+import {
+  classificationProgress,
+  publishClassificationProgress,
+  publishFailedClassificationProgress,
+} from './journey-classification-progress.mjs'
+import { answers, createTasks } from './journey-tasks.mjs'
+import { scanTiming } from './journey-scan-timing.mjs'
+export { phaseOf, stageFingerprint } from './journey-state.mjs'
+
+async function publishCompleteClassification(manifest, view, call, proposalRevision) {
+  const baselineRevision = manifest.classification?.baselineRevision
+  if (
+    !Number.isSafeInteger(baselineRevision) ||
+    view.classificationRevision !== view.revision ||
+    view.classificationRevision <= baselineRevision
+  )
+    throw new Error('CLASSIFICATION_PROGRESS_COMPLETION_UNCONFIRMED')
+  if (proposalRevision !== view.revision)
+    throw new Error('CLASSIFICATION_PROGRESS_COMPLETION_UNCONFIRMED')
+  await publishClassificationProgress(manifest, view, call, {
+    status: 'complete',
+    stage: 'proposal',
+    proposalRevision,
+  })
+}
+
+// Longer than the default request bound, still inside a 2-minute tool timeout.
+const FREEZE_REQUEST_MS = 100_000
+
+async function prepareInitialFreeze(run, journeyId, call, view) {
+  const path = join(run, 'initial-freeze-timing.json')
+  const timing = await optional(path)
+  if (!view.consent || view.phase === 'paused' || view.scope?.status === 'confirmed')
+    throw new Error('INITIAL_FREEZE_NOT_ALLOWED')
+  if (timing?.completedAt && timing.snapshotId !== view.snapshotId)
+    throw new Error('INITIAL_FREEZE_SNAPSHOT_CHANGED')
+  if (timing?.completedAt && timing.snapshotId === view.snapshotId)
+    return {
+      stage: 'freeze',
+      status: 'complete',
+      ...timing,
+      elapsedMs: Date.parse(timing.completedAt) - Date.parse(timing.startedAt),
+    }
+  if (view.snapshotId && (!timing?.startedAt || view.classificationRevision !== null))
+    throw new Error('INITIAL_FREEZE_NOT_STARTED_HERE')
+  const startedAt = timing?.startedAt ?? new Date().toISOString()
+  if (!timing) await save(path, { startedAt, completedAt: null })
+  // Safe on retry while scope remains pending; journey.prepare resumes the frozen capture.
+  try {
+    await call('journey.prepare', { journeyId }, { timeoutMs: FREEZE_REQUEST_MS })
+  } catch (error) {
+    // A large first freeze can outlast one helper command; captured roots persist for the rerun.
+    if (error?.code === 'CLI_UNAVAILABLE') return { stage: 'freeze', status: 'running', startedAt }
+    throw error
+  }
+  const completed = await call('journey.get', { journeyId })
+  if (
+    !completed.snapshotId ||
+    completed.scope?.status === 'confirmed' ||
+    completed.classificationRevision !== null
+  )
+    throw new Error('INITIAL_FREEZE_NOT_CONFIRMED')
+  const completedAt = new Date().toISOString()
+  const saved = { startedAt, completedAt, snapshotId: completed.snapshotId }
+  await save(path, saved)
+  return {
+    stage: 'freeze',
+    status: 'complete',
+    ...saved,
+    elapsedMs: Date.parse(completedAt) - Date.parse(startedAt),
+  }
+}
+
+/**
+ * Scan timing is an internal diagnostic (BL-180): a receipt that no longer matches the journey
+ * marks timing stale or unavailable and never hides the rest of the helper's report.
+ */
+async function observeScanTiming(run, journeyId, view, start, call) {
+  try {
+    return await scanTiming(run, journeyId, view, start, call)
+  } catch (error) {
+    const code = error instanceof Error ? error.message : ''
+    if (!code.startsWith('SCAN_TIMING_')) throw error
+    process.stderr.write(code + '\n')
+    return { status: code === 'SCAN_TIMING_SCOPE_CHANGED' ? 'stale' : 'unavailable', code }
+  }
+}
+
+/** Locked by withJourneyCli in production; injected transport permits deterministic crash tests. */
+/** A running journey render (panel or CLI) with packaged/selected Work counts (BL-185). */
+function packagingProgress(view) {
+  if (!view.packaging) return {}
+  const selected = view.works.filter((work) => work.access !== 'drop' && work.rootSessionIds.length)
+  return {
+    packaging: {
+      ...view.packaging,
+      selected: selected.length,
+      packaged: selected.filter(
+        (work) => work.status === 'ready' && work.artifact?.revision === work.revision,
+      ).length,
+    },
+  }
+}
+
+/** One await call's bound: inside a 10-minute tool timeout; the Skill repeats it to 30 minutes. */
+export const maxAwaitMs = 540_000
+const awaitPollMs = 1000
+
+/**
+ * D0: the agent waits inside its turn for the person's next panel decision. Returns once the
+ * helper phase changes (consent recorded, the last card answered, a Work moved out of Drop
+ * needing a read) or a new card batch is due, else after `waitMs` with `changed: false`.
+ */
+async function awaitDecision(journeyId, waitMs, call, sleep) {
+  if (!Number.isSafeInteger(waitMs) || waitMs < 0 || waitMs > maxAwaitMs)
+    throw new Error('INVALID_ARGUMENTS')
+  const started = Date.now()
+  let view = await call('journey.get', { journeyId })
+  const from = phaseOf(view)
+  for (;;) {
+    const phase = phaseOf(view)
+    const batchDue = phase === 'browser-answers' && uncoveredPending(view).length > 0
+    if (phase !== from || batchDue || Date.now() - started >= waitMs)
+      return {
+        command: 'await',
+        from,
+        phase,
+        changed: phase !== from || batchDue,
+        waitedMs: Date.now() - started,
+        revision: view.revision,
+      }
+    await sleep(Math.min(awaitPollMs, Math.max(0, waitMs - (Date.now() - started))))
+    view = await call('journey.get', { journeyId })
+  }
+}
+
+async function runPhaseCore(
+  { run, journeyId, command, stage, refresh = false, limit = 3, waitMs = 0, sleep },
+  call,
+) {
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > 16) throw new Error('INVALID_ARGUMENTS')
+  if (command === 'await')
+    return awaitDecision(
+      journeyId,
+      waitMs,
+      call,
+      sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
+    )
+  let view = await call('journey.get', { journeyId })
+  if (command === 'scan-start')
+    return {
+      scan: await observeScanTiming(run, journeyId, view, true, call),
+      next: 'journey.prepare',
+    }
+  if (command === 'status') {
+    const active = await optional(join(run, 'classification-active.json'))
+    const manifest = active ? await optional(join(active.directory, 'manifest.json')) : null
+    const freeze = await optional(join(run, 'initial-freeze-timing.json'))
+    const proposalAt =
+      view.classificationProgress?.status === 'complete'
+        ? view.classificationProgress.updatedAt
+        : null
+    const coldElapsedMs =
+      freeze?.completedAt && freeze.snapshotId === view.snapshotId && proposalAt
+        ? Math.max(0, Date.parse(proposalAt) - Date.parse(freeze.startedAt))
+        : null
+    return {
+      ...(manifest?.classification
+        ? { classification: await classificationProgress(manifest) }
+        : {}),
+      phase: phaseOf(view),
+      revision: view.revision,
+      readingComplete: view.readingComplete,
+      pending: activeTerms(view).filter((term) => term.disposition === 'pending').length,
+      answersRevision: view.privacy.answersRevision,
+      ...packagingProgress(view),
+      coldElapsedMs,
+      scan: await observeScanTiming(run, journeyId, view, false, call),
+    }
+  }
+  if (command === 'prepare') return prepareInitialFreeze(run, journeyId, call, view)
+  if (
+    !['classification', 'cards', 'resolution'].includes(stage) ||
+    !['tasks', 'evidence', 'consolidate', 'ingest'].includes(command)
+  )
+    throw new Error('INVALID_ARGUMENTS')
+  const activePath = join(run, `${stage}-active.json`)
+  const active = await optional(activePath)
+  let manifest = active ? await optional(join(active.directory, 'manifest.json')) : null
+  if (active && !manifest) throw new Error('CORRUPTED_STATE')
+  if (manifest && manifest.format !== classificationFormat)
+    throw new Error('INCOMPATIBLE_JOURNEY_TASKS')
+  if (manifest) {
+    const recovery = await recoverWrites(active.directory, manifest, call)
+    // A failed transport leaves the exact pending request intact and never reaches refresh.
+    if (recovery.recovered) view = await call('journey.get', { journeyId })
+    if (recovery.stale && (!refresh || command !== 'tasks')) throw new Error('REVISION_CONFLICT')
+    if (recovery.rejected && !(refresh && command === 'tasks')) {
+      const error = new Error(recovery.rejected)
+      error.code = recovery.rejected
+      throw error
+    }
+    if (recovery.completed === recovery.total && !recovery.stale && command === 'ingest') {
+      if (stage === 'classification' && manifest.consolidation)
+        await publishCompleteClassification(
+          manifest,
+          view,
+          call,
+          (await optional(join(active.directory, 'receipt.json')))?.revision,
+        )
+      return { stage, ...recovery }
+    }
+  }
+  const consolidationRefresh = refresh && command === 'consolidate' && stage === 'classification'
+  if (
+    consolidationRefresh &&
+    !['classification', 'classification-confirmation'].includes(phaseOf(view)) &&
+    !grouping(view)
+  )
+    throw new Error('STAGE_NOT_READY')
+  if (consolidationRefresh && (await optional(join(active?.directory ?? run, 'receipt.json'))))
+    throw new Error('CLASSIFICATION_ALREADY_SUBMITTED')
+  // A card batch (D3) whose append was accepted is finished: the next `tasks` starts another.
+  const batchDone =
+    stage === 'cards' &&
+    manifest?.batch &&
+    ['applied', 'replayed'].includes(
+      (await optional(join(active.directory, 'receipt.json')))?.status,
+    )
+  if (batchDone && command !== 'tasks') return { stage, status: 'applied', batchDone: true }
+  if (batchDone) manifest = null
+  const fingerprint = stageFingerprint(view, stage)
+  if (manifest?.resolutionBatches && !refresh)
+    await assertResolutionFresh(active.directory, manifest, view)
+  // A batch names its own open values; the CLI refuses them once they are no longer open.
+  // Known Works this helper published (E2) changed the Works it fingerprinted.
+  else if (
+    manifest &&
+    !manifest.batch &&
+    !manifest.partial &&
+    manifest.fingerprint !== fingerprint &&
+    (!refresh || consolidationRefresh)
+  )
+    throw new Error('STALE_TASKS')
+  if (refresh && command !== 'tasks' && !consolidationRefresh) throw new Error('INVALID_ARGUMENTS')
+  if (command === 'tasks') {
+    const phase = phaseOf(view)
+    const revisingCards =
+      stage === 'cards' && refresh && ['browser-answers', 'answers-confirmation'].includes(phase)
+    // Batches start while reading continues and after earlier batches (D3).
+    const cardBatch =
+      stage === 'cards' &&
+      !refresh &&
+      view.scope.status === 'confirmed' &&
+      !['paused', 'sending', 'completed'].includes(phase) &&
+      uncoveredPending(view).length > 0
+    if (cardBatch && !manifest) {
+      const directory = join(run, stage, `batch-${randomUUID()}`)
+      await mkdir(directory, { recursive: true, mode: 0o700 })
+      manifest = {
+        format: classificationFormat,
+        stage,
+        batch: true,
+        fingerprint,
+        existingCards: view.privacy.cards.map((card) => ({
+          id: card.id,
+          question: card.question,
+          options: card.options.map(({ id, label }) => ({ id, label })),
+          answer: card.answer?.optionId ?? null,
+          termCount: card.termKeys.length,
+        })),
+        tasks: await createTasks(directory, stage, view, call, { batch: true }),
+        answersRevision: view.privacy.answersRevision,
+      }
+      await save(join(directory, 'manifest.json'), manifest)
+      await save(activePath, { directory })
+      return { stage, tasks: manifest.tasks, batch: true }
+    }
+    if (
+      phase !== stage &&
+      !revisingCards &&
+      !(cardBatch && manifest) &&
+      !(stage === 'classification' && (phase === 'classification-confirmation' || grouping(view)))
+    )
+      throw new Error('STAGE_NOT_READY')
+    if (manifest && !refresh && stage === 'classification') {
+      if (!manifest.classification && manifest.format === classificationFormat)
+        throw new Error('INCOMPATIBLE_CLASSIFICATION_TASKS')
+      const result = await classificationTasks(active.directory, manifest, view, call, limit)
+      await publishClassificationProgress(manifest, view, call)
+      return result
+    }
+    if (manifest && !refresh)
+      return {
+        stage,
+        tasks: manifest.tasks,
+        consolidation: manifest.consolidation ?? null,
+        reused: true,
+      }
+    const directory = join(run, stage, `${fingerprint}-${randomUUID()}`)
+    await mkdir(directory, { recursive: true, mode: 0o700 })
+    manifest = {
+      format: classificationFormat,
+      stage,
+      fingerprint,
+      tasks: stage === 'classification' ? [] : await createTasks(directory, stage, view, call),
+      answersRevision: view.privacy.answersRevision,
+    }
+    await save(join(directory, 'manifest.json'), manifest)
+    await save(activePath, { directory })
+    if (stage === 'classification') {
+      const result = await classificationTasks(directory, manifest, view, call, limit)
+      await publishClassificationProgress(manifest, view, call)
+      return result
+    }
+    return { stage, tasks: manifest.tasks }
+  }
+  if (!manifest || !active) throw new Error('TASKS_REQUIRED')
+  const directory = active.directory
+  if (command === 'evidence') {
+    if (stage !== 'classification') throw new Error('INVALID_ARGUMENTS')
+    const result = await classificationEvidence(directory, manifest, view, call, limit)
+    await publishClassificationProgress(manifest, view, call)
+    return result
+  }
+  if (command === 'consolidate') {
+    if (stage === 'cards') return consolidateCards(directory, manifest)
+    if (stage !== 'classification') throw new Error('INVALID_ARGUMENTS')
+    if (!manifest.classification?.complete) throw new Error('CLASSIFICATION_READS_INCOMPLETE')
+    let pendingRootAnswers = false
+    for (const item of manifest.tasks)
+      if (!item.projectKeys && !(await optional(item.answer))) pendingRootAnswers = true
+    if (pendingRootAnswers) throw new Error('CLASSIFICATION_ANSWERS_INCOMPLETE')
+    const evidence = await classificationEvidence(directory, manifest, view, call, limit)
+    await publishClassificationProgress(manifest, view, call)
+    if (!evidence.evidenceComplete || evidence.tasks.length)
+      return { ...evidence, consolidationReady: false }
+    const result = await consolidateClassification(directory, manifest, {
+      refresh: consolidationRefresh,
+    })
+    await publishClassificationProgress(manifest, view, call, {
+      stage: 'proposal',
+    })
+    return result
+  }
+  if (stage === 'resolution') {
+    if (!manifest.resolutionBatches) {
+      manifest.resolutionBatches = planResolutions(
+        view,
+        await answers(manifest.tasks, 'resolutions'),
+      )
+      manifest.resolutionAuthority = resolutionAuthority(view)
+      manifest.resolutionEvidence = resolutionEvidence(view)
+      await save(join(directory, 'manifest.json'), manifest)
+    }
+    let recorded = 0
+    for (const batch of manifest.resolutionBatches) {
+      const requestPath = join(directory, `${batch.id}.request.json`),
+        receiptPath = join(directory, `${batch.id}.receipt.json`)
+      if (await optional(receiptPath)) continue
+      const latest = await call('journey.get', { journeyId })
+      await assertResolutionFresh(directory, manifest, latest)
+      const request = {
+        journeyId,
+        expectedRevision: latest.revision,
+        idempotencyKey: randomUUID(),
+        answersRevision: manifest.answersRevision,
+        resolutions: batch.resolutions,
+      }
+      await save(requestPath, request)
+      const result = await call(procedureFor(stage), request)
+      await save(receiptPath, {
+        status: result.status,
+        revision: result.state?.revision,
+      })
+      if (result.status === 'stale') throw new Error('REVISION_CONFLICT')
+      recorded++
+    }
+    return {
+      stage,
+      recorded,
+      completed: manifest.resolutionBatches.length,
+      total: manifest.resolutionBatches.length,
+    }
+  }
+  if (stage === 'classification' && command === 'ingest' && !manifest.partial) {
+    const readiness = manifest.consolidation
+      ? await consolidateClassification(directory, manifest)
+      : { readyForIngest: false }
+    if (!readiness.readyForIngest) {
+      const partial = await partialClassificationSubmission(manifest)
+      if (partial) return ingestKnownWorks(directory, manifest, view, call, partial)
+    }
+  }
+  if (stage === 'classification' && !manifest.consolidation)
+    throw new Error('CONSOLIDATION_REQUIRED')
+  if (stage === 'classification') {
+    const readiness = await consolidateClassification(directory, manifest)
+    if (!readiness.readyForIngest) return readiness
+  }
+  if (stage === 'cards') {
+    const readiness = await consolidateCards(directory, manifest)
+    if (!readiness.readyForIngest) return readiness
+  }
+  const key = stage === 'classification' ? 'items' : stage === 'cards' ? 'cards' : 'resolutions'
+  const tasks = stage === 'classification' ? [manifest.consolidation] : manifest.tasks
+  const request = {
+    journeyId,
+    expectedRevision: view.revision,
+    idempotencyKey: randomUUID(),
+    // After the known Works, scans keep moving the revision: bind to the classification (E2).
+    ...(stage === 'classification' && manifest.partial
+      ? { expectedClassificationRevision: manifest.partial.revision }
+      : {}),
+    ...(stage === 'classification'
+      ? { [key]: await classificationSubmission(manifest, view) }
+      : stage === 'cards'
+        ? await cardSubmission(manifest)
+        : { [key]: await answers(tasks, key) }),
+    ...(stage === 'resolution' ? { answersRevision: manifest.answersRevision } : {}),
+  }
+  await save(join(directory, 'request.json'), request)
+  let result
+  try {
+    result = await call(procedureFor(stage), request)
+    await save(join(directory, 'receipt.json'), {
+      status: result.status,
+      revision: result.state?.revision,
+    })
+  } catch (error) {
+    if (definiteWriteRejection(error))
+      await save(join(directory, 'receipt.json'), {
+        status: 'rejected',
+        code: error.code,
+      })
+    throw error
+  }
+  if (result.status === 'stale') throw new Error('REVISION_CONFLICT')
+  if (stage === 'classification' && !manifest.partial) {
+    const latest = await call('journey.get', { journeyId })
+    await publishCompleteClassification(manifest, latest, call, result.state?.revision)
+  }
+  return { stage, status: result.status, revision: result.state?.revision }
+}
+
+/** Classification published known Works and is still grouping the remaining roots (E2). */
+const grouping = (view) => view.works.some((work) => work.placement === 'classifying')
+
+/**
+ * E2: publishes known-project Works while unresolved roots are still being grouped, so their
+ * scan can start. Its request and receipt are kept apart from the final proposal's.
+ */
+async function ingestKnownWorks(directory, manifest, view, call, partial) {
+  const requestPath = join(directory, 'partial.request.json')
+  const request = (await optional(requestPath)) ?? {
+    journeyId: view.journeyId,
+    expectedRevision: view.revision,
+    idempotencyKey: randomUUID(),
+    ...partial,
+  }
+  await save(requestPath, request)
+  const result = await call(procedureFor('classification'), request)
+  if (result.status === 'stale') {
+    await rm(requestPath, { force: true })
+    throw new Error('REVISION_CONFLICT')
+  }
+  manifest.partial = { status: result.status, revision: result.state?.revision }
+  await save(join(directory, 'manifest.json'), manifest)
+  return {
+    stage: 'classification',
+    status: result.status,
+    partial: true,
+    pendingRoots: partial.pendingRootSessionIds.length,
+    revision: result.state?.revision,
+  }
+}
+
+const terminalClassificationErrors = new Set([
+  'INVALID_SELECTION',
+  'CLASSIFICATION_PROJECT_NAME_CONFLICT',
+  'CLASSIFICATION_ROOT_COVERAGE_INVALID',
+  'CLASSIFICATION_THEME_TOO_SMALL',
+  'CLASSIFICATION_UNSORTED_DUPLICATE',
+  'INVALID_CLASSIFICATION_GROUP_KIND',
+  'INVALID_CLASSIFICATION_ITEM',
+])
+
+/** Preserve the original error; publish failure only against a still-current running checkpoint. */
+export async function runPhase(args, call) {
+  try {
+    return await runPhaseCore(args, call)
+  } catch (error) {
+    const code = error?.code ?? error?.message
+    if (args.stage === 'classification' && terminalClassificationErrors.has(code)) {
+      try {
+        const active = await optional(join(args.run, 'classification-active.json'))
+        const manifest = active ? await optional(join(active.directory, 'manifest.json')) : null
+        if (manifest?.format === classificationFormat && manifest.classification) {
+          const latest = await call('journey.get', {
+            journeyId: args.journeyId,
+          })
+          await publishFailedClassificationProgress(manifest, latest, call)
+        }
+      } catch {
+        // Progress is advisory; never mask the classification error that caused this path.
+      }
+    }
+    throw error
+  }
+}
+
+export async function main(argv) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      run: { type: 'string' },
+      journey: { type: 'string' },
+      stage: { type: 'string' },
+      refresh: { type: 'boolean', default: false },
+      limit: { type: 'string' },
+      'wait-ms': { type: 'string' },
+      model: { type: 'string' },
+      effort: { type: 'string' },
+    },
+  })
+  const [command] = positionals
+  if (!values.run) throw new Error('INVALID_ARGUMENTS')
+  if (command === 'init') {
+    const cli = positionals.slice(1)
+    const scopes = cli.flatMap((value, index) => (value === '--state-dir' ? [cli[index + 1]] : []))
+    if (scopes.length !== 1 || typeof scopes[0] !== 'string' || !isAbsolute(scopes[0]))
+      throw new Error('EXPLICIT_CLI_STATE_DIRECTORY_REQUIRED')
+    return review(argv)
+  }
+  const run = resolve(values.run),
+    config = await read(join(run, 'config.json'))
+  return withJourneyCli(run, (call) =>
+    runPhase(
+      {
+        run,
+        journeyId: config.journeyId,
+        command,
+        stage: values.stage,
+        refresh: values.refresh,
+        limit: values.limit === undefined ? 3 : Number(values.limit),
+        waitMs: values['wait-ms'] === undefined ? 300_000 : Number(values['wait-ms']),
+      },
+      call,
+    ),
+  )
+}
+const entry = process.argv[1]
+if (entry && (await realpath(entry)) === fileURLToPath(import.meta.url))
+  main(process.argv.slice(2)).then(
+    (result) => process.stdout.write(JSON.stringify({ ok: true, ...result }) + '\n'),
+    (error) => {
+      const code = /^[A-Z_]{3,80}$/u.test(error.message) ? error.message : 'JOURNEY_HELPER_FAILED'
+      process.stderr.write(code + '\n')
+      process.exitCode = 1
+    },
+  )

package/skills/tacitt/scripts/local-cli.d.mts

@@ -0,0 +1,18 @@
+export interface LocalCliBinding {
+  schemaVersion: 1
+  package: '@gitroll/tacitt-cli'
+  version: string
+  nodePath: string
+  cliPath: string
+  artifactSha256: string
+}
+
+export function readLocalCliBinding(
+  cliPath: string,
+  expected: { name: string; version: string },
+): Promise<LocalCliBinding>
+
+export function verifyLocalCliBinding(
+  receiptPath: string,
+  expectedReceiptSha256: string,
+): Promise<LocalCliBinding>