@gitroll/tacitt-cli 0.0.0-stage → 0.1.0

package/skills/tacitt/scripts/journey.mjs

@@ -0,0 +1,451 @@
+import { randomUUID } from 'node:crypto'
+import { mkdir, realpath } 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,
+} from './journey-state.mjs'
+import { classificationTasks } from './journey-classification-tasks.mjs'
+import { classificationEvidence, classificationFormat } from './journey-classification.mjs'
+import { consolidateClassification, classificationSubmission } 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,
+    },
+  }
+}
+
+async function runPhaseCore({ run, journeyId, command, stage, refresh = false, limit = 3 }, call) {
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > 16) throw new Error('INVALID_ARGUMENTS')
+  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))
+  )
+    throw new Error('STAGE_NOT_READY')
+  if (consolidationRefresh && (await optional(join(active?.directory ?? run, 'receipt.json'))))
+    throw new Error('CLASSIFICATION_ALREADY_SUBMITTED')
+  const fingerprint = stageFingerprint(view, stage)
+  if (manifest?.resolutionBatches && !refresh)
+    await assertResolutionFresh(active.directory, manifest, view)
+  else if (manifest && 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)
+    if (
+      phase !== stage &&
+      !revisingCards &&
+      !(stage === 'classification' && phase === 'classification-confirmation')
+    )
+      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' && !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(),
+    [key]:
+      stage === 'classification'
+        ? await classificationSubmission(manifest, view)
+        : stage === 'cards'
+          ? await cardSubmission(manifest)
+          : 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') {
+    const latest = await call('journey.get', { journeyId })
+    await publishCompleteClassification(manifest, latest, call, result.state?.revision)
+  }
+  return { stage, status: result.status, 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' },
+      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),
+      },
+      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>

package/skills/tacitt/scripts/local-cli.mjs

@@ -0,0 +1,116 @@
+import { createHash } from 'node:crypto'
+import { lstat, open, readdir, realpath } from 'node:fs/promises'
+import { dirname, isAbsolute, join } from 'node:path'
+
+const fail = () => {
+  throw new Error('LOCAL_CLI_BINDING_INVALID')
+}
+const object = (value) => typeof value === 'object' && value !== null && !Array.isArray(value)
+const versionPattern = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/
+const digestPattern = /^[a-f0-9]{64}$/
+const digest = (bytes) => createHash('sha256').update(bytes).digest('hex')
+
+async function regularFile(path, limit) {
+  const before = await lstat(path)
+  if (!before.isFile() || before.isSymbolicLink() || before.size > limit) fail()
+  const handle = await open(path, 'r')
+  try {
+    const opened = await handle.stat()
+    if (opened.dev !== before.dev || opened.ino !== before.ino) fail()
+    const bytes = await handle.readFile()
+    const after = await lstat(path)
+    if (
+      !after.isFile() ||
+      after.isSymbolicLink() ||
+      after.dev !== before.dev ||
+      after.ino !== before.ino ||
+      after.size !== before.size ||
+      after.mtimeMs !== before.mtimeMs ||
+      bytes.length !== before.size
+    )
+      fail()
+    return bytes
+  } finally {
+    await handle.close()
+  }
+}
+
+async function packageFiles(root) {
+  const files = []
+  let bytes = 0
+  const visit = async (name, depth = 0) => {
+    if (depth > 16 || files.length >= 10000) fail()
+    const path = join(root, name)
+    const info = await lstat(path)
+    if (info.isSymbolicLink()) fail()
+    if (info.isDirectory()) {
+      for (const child of (await readdir(path)).sort()) await visit(`${name}/${child}`, depth + 1)
+    } else if (info.isFile()) {
+      const content = await regularFile(path, 512 * 1024 * 1024 - bytes)
+      bytes += content.length
+      files.push([name, content.length, digest(content)])
+    } else fail()
+  }
+  for (const name of ['package.json', 'bin', 'dist', 'skills']) await visit(name)
+  return files
+}
+
+/** Reads only the selected installed package; it never downloads or opens application state. */
+export async function readLocalCliBinding(cliPath, expected) {
+  if (
+    typeof cliPath !== 'string' ||
+    !isAbsolute(cliPath) ||
+    cliPath
+      .split('')
+      .some((character) => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127) ||
+    !object(expected) ||
+    expected.name !== '@gitroll/tacitt-cli' ||
+    typeof expected.version !== 'string' ||
+    !versionPattern.test(expected.version)
+  )
+    fail()
+  const requested = await lstat(cliPath)
+  if (!requested.isFile() || requested.isSymbolicLink()) fail()
+  const executable = await realpath(cliPath)
+  const root = dirname(dirname(executable))
+  if (executable !== join(root, 'bin', 'tacitt.cjs')) fail()
+  const metadataBytes = await regularFile(join(root, 'package.json'), 1024 * 1024)
+  const metadata = JSON.parse(metadataBytes.toString('utf8'))
+  if (
+    !object(metadata) ||
+    metadata.name !== expected.name ||
+    metadata.version !== expected.version ||
+    !object(metadata.bin) ||
+    metadata.bin['tacitt'] !== 'bin/tacitt.cjs'
+  )
+    fail()
+  const files = await packageFiles(root)
+  if (
+    !files.some(([name]) => name === 'dist/cli.mjs') ||
+    !files.some(([name, , sha256]) => name === 'package.json' && sha256 === digest(metadataBytes))
+  )
+    fail()
+  return {
+    schemaVersion: 1,
+    package: expected.name,
+    version: expected.version,
+    nodePath: await realpath(process.execPath),
+    cliPath: executable,
+    artifactSha256: digest(JSON.stringify(files)),
+  }
+}
+
+/** A receipt hash comes from the managed entry, independently of the local receipt bytes. */
+export async function verifyLocalCliBinding(receiptPath, expectedReceiptSha256) {
+  if (!isAbsolute(receiptPath) || !digestPattern.test(expectedReceiptSha256)) fail()
+  const bytes = await regularFile(receiptPath, 8192)
+  if (digest(bytes) !== expectedReceiptSha256) fail()
+  const receipt = JSON.parse(bytes.toString('utf8'))
+  if (!object(receipt) || receipt.schemaVersion !== 1) fail()
+  const actual = await readLocalCliBinding(receipt.cliPath, {
+    name: receipt.package,
+    version: receipt.version,
+  })
+  if (JSON.stringify(actual) !== JSON.stringify(receipt)) fail()
+  return actual
+}