@gitroll/tacitt-cli 0.0.0-stage → 0.2.0

package/skills/tacitt/scripts/review-stream-client.d.mts

@@ -0,0 +1,22 @@
+import { type ChildProcess, type SpawnOptions } from 'node:child_process'
+
+export const REVIEW_STREAM_REQUEST_TIMEOUT_MS: 75_000
+export const REVIEW_STREAM_SHUTDOWN_STEP_MS: 1_000
+
+export interface ReviewStreamClient {
+  busy(): number
+  readonly retired: boolean
+  readonly unavailable: boolean
+  call(procedure: string, input: unknown): Promise<unknown>
+  close(): Promise<void>
+}
+
+export interface ReviewStreamOptions {
+  spawnChild?: (command: string, args: string[], options: SpawnOptions) => ChildProcess
+  onUnavailable?: () => void
+  onRetired?: (stream: ReviewStreamClient) => void
+  /** Internal deterministic timing seam for transport tests; not a user configuration surface. */
+  timeouts?: { requestMs?: number; shutdownStepMs?: number }
+}
+
+export function startReviewStream(cli: string[], options?: ReviewStreamOptions): ReviewStreamClient

package/skills/tacitt/scripts/review-stream-client.mjs

@@ -0,0 +1,194 @@
+import { spawn } from 'node:child_process'
+
+export const REVIEW_STREAM_REQUEST_TIMEOUT_MS = 75_000
+export const REVIEW_STREAM_SHUTDOWN_STEP_MS = 1_000
+
+/** One paired CLI stream with bounded requests and bounded owned-child shutdown. */
+export function startReviewStream(
+  cli,
+  { spawnChild = spawn, onUnavailable = () => {}, onRetired = () => {}, timeouts = {} } = {},
+) {
+  const requestTimeoutMs = timeouts.requestMs ?? REVIEW_STREAM_REQUEST_TIMEOUT_MS
+  const shutdownStepMs = timeouts.shutdownStepMs ?? REVIEW_STREAM_SHUTDOWN_STEP_MS
+  const [command, ...prefix] = cli
+  const shell = process.platform === 'win32' && !/\.(exe|com)$/iu.test(command)
+  const args = [...prefix, 'review.stream']
+  const child = spawnChild(command, shell ? args.map(windowsArgument) : args, {
+    stdio: ['pipe', 'pipe', 'ignore'],
+    shell,
+  })
+  const pending = new Map()
+  let buffer = ''
+  let next = 0
+  let retired = false
+  let unavailable = false
+  let receivedReply = false
+  let startupFailure = null
+  let closed = false
+  let closePromise
+  let retirementPromise
+
+  const settleAll = (reply) => {
+    for (const [id, request] of pending) {
+      clearTimeout(request.timer)
+      pending.delete(id)
+      request.resolve(reply)
+    }
+  }
+  const markUnavailable = () => {
+    if (unavailable) return
+    unavailable = true
+    onUnavailable()
+  }
+  const retire = (failed) => {
+    if (retirementPromise) return retirementPromise
+    if (!startupFailure && (failed || pending.size > 0)) markUnavailable()
+    retired = true
+    settleAll(startupFailure)
+    retirementPromise = shutdown().finally(() => {
+      child.stdout.off('data', onData)
+      child.stdout.off('error', onStdoutError)
+      child.stdout.on('error', ignoreError)
+      child.stdin.off('error', onStdinError)
+      child.off('close', markClosed)
+      child.off('error', onChildError)
+      child.on('error', ignoreError)
+      if (current) onRetired(current)
+    })
+    return retirementPromise
+  }
+  const markClosed = () => {
+    if (closed) return
+    closed = true
+    void retire(pending.size > 0)
+  }
+
+  const onData = (chunk) => {
+    buffer += chunk
+    for (let index; (index = buffer.indexOf('\n')) >= 0;) {
+      const line = buffer.slice(0, index)
+      buffer = buffer.slice(index + 1)
+      let reply = null
+      try {
+        reply = JSON.parse(line)
+      } catch {
+        continue
+      }
+      if (
+        !receivedReply &&
+        reply?.event === 'review.stream.startup-failed' &&
+        reply.ok === false &&
+        reply.error?.code === 'COORDINATION_BUSY'
+      ) {
+        startupFailure = { ok: false, error: { code: 'COORDINATION_BUSY' } }
+        void retire(false)
+        return
+      }
+      const request = pending.get(reply?.id)
+      if (!request) continue
+      receivedReply = true
+      clearTimeout(request.timer)
+      pending.delete(reply.id)
+      request.resolve(reply)
+    }
+  }
+  const onStdinError = () => {
+    void retire(true)
+  }
+  const onStdoutError = () => void retire(true)
+  const onChildError = () => {
+    if (!Number.isInteger(child.pid)) closed = true
+    void retire(true)
+  }
+  const ignoreError = () => {}
+
+  const current = {
+    busy: () => pending.size,
+    get unavailable() {
+      return unavailable
+    },
+    get retired() {
+      return retired
+    },
+    call(procedure, input, { timeoutMs = requestTimeoutMs } = {}) {
+      if (retired || unavailable) return Promise.resolve(null)
+      const id = next++
+      return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+          // A request may have committed before its reply disappeared. Every waiter on this
+          // sequential transport is therefore unknown; later recovery must reuse durable keys.
+          void retire(true)
+        }, timeoutMs)
+        pending.set(id, { resolve, timer })
+        try {
+          child.stdin.write(JSON.stringify({ id, procedure, input }) + '\n', (error) => {
+            if (error) void retire(true)
+          })
+        } catch {
+          void retire(true)
+        }
+      })
+    },
+    close: () => retire(pending.size > 0),
+  }
+
+  child.stdout.setEncoding('utf8')
+  child.stdout.on('data', onData)
+  child.stdout.on('error', onStdoutError)
+  child.on('close', markClosed)
+  child.on('error', onChildError)
+  child.stdin.on('error', onStdinError)
+
+  function shutdown() {
+    if (closePromise) return closePromise
+    closePromise = (async () => {
+      if (closed) return
+      try {
+        child.stdin.end()
+      } catch {
+        // A closed pipe does not change the unknown-outcome handling above.
+      }
+      if (await waitForClose(child, shutdownStepMs, () => closed)) return
+      signalOwnedChild(child, 'SIGTERM')
+      if (await waitForClose(child, shutdownStepMs, () => closed)) return
+      signalOwnedChild(child, 'SIGKILL')
+      await waitForClose(child, shutdownStepMs, () => closed)
+    })()
+    return closePromise
+  }
+
+  return current
+}
+
+function windowsArgument(value) {
+  return /^[\w./:@=+-]+$/u.test(value) ? value : `"${value.replaceAll('"', '""')}"`
+}
+
+function signalOwnedChild(child, signal) {
+  if (!Number.isInteger(child.pid) || child.pid <= 0) return
+  try {
+    child.kill(signal)
+  } catch {
+    // The bounded close observation handles children that have already exited.
+  }
+}
+
+function waitForClose(child, durationMs, isClosed) {
+  if (isClosed()) return Promise.resolve(true)
+  return new Promise((resolve) => {
+    let settled = false
+    const finish = (closed) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      child.off('close', onClose)
+      child.off('error', onError)
+      resolve(closed)
+    }
+    const onClose = () => finish(true)
+    const onError = () => {}
+    const timer = setTimeout(() => finish(isClosed()), durationMs)
+    child.once('close', onClose)
+    child.once('error', onError)
+  })
+}

package/skills/tacitt/scripts/review.d.mts

@@ -0,0 +1,87 @@
+export function questionsReady(view: unknown): boolean
+export function parseReply(text: string): Record<string, unknown>
+export function estimateTokens(text: string): number
+export function readPlan(text: string, pageTokens?: number): { offset: number; limit: number }[]
+export function renderGuidance(guidance: unknown): string
+export function renderPackTask(
+  packId: string,
+  guidance: unknown,
+  units: readonly { ref: string; unit: unknown }[],
+): string
+export function readAnswer(replies: readonly Record<string, unknown>[]): {
+  units: Map<string, { summary: string; exclude: string | null }>
+  terms: { type: string; value: string; disposition: string; reason: string }[]
+  counts: { ignored: number; retyped: number; clipped: number }
+}
+export function main(argv: string[]): Promise<Record<string, unknown>>
+
+export function workProgress(view: {
+  snapshotId?: string | null
+  phase: string
+  privacy?: { packageApproval: string | null }
+  pendingHideId?: string | null
+  works: readonly {
+    id: string
+    access: string
+    rootSessionIds: readonly string[]
+    status: string
+    emptyReview?: {
+      snapshotId: string
+      inputRevision: number
+      rootSessionIds: readonly string[]
+      scanDigest: string
+    }
+    totalBatches: number
+    completedBatches: number
+    placement: string
+    inputRevision: number
+    revision: number
+    suggestion?: { checkpoint: string; inputRevision: number } | null
+    artifact?: { revision: number } | null
+    staticReview?: unknown
+  }[]
+}): {
+  workId: string
+  readingComplete: boolean
+  needsPlacement: boolean
+  needsDescription: boolean
+  needsRender: boolean
+  previewReady: boolean
+}[]
+
+export interface BlockedWork {
+  workId: string
+  title: string
+  blockedCodes: readonly string[]
+}
+export function blockedWorks(view: {
+  works: readonly {
+    id: string
+    title: string
+    access: string
+    rootSessionIds: readonly string[]
+    status: string
+    blockedCodes?: readonly string[]
+  }[]
+}): BlockedWork[]
+export function settledNext(
+  view: Parameters<typeof blockedWorks>[0] & { readingComplete: boolean },
+  units: readonly { state: string }[],
+): string
+
+export function validatePrivacyAnswer(answer: unknown, unitRefs: readonly string[]): void
+export function writePackTask(
+  task: string,
+  text: string,
+  unitRefs: readonly string[],
+  sourceBatches?: readonly {
+    workId: string
+    chunks: readonly {
+      text: string
+      offset: number
+      core: boolean
+      fieldId: string
+      fieldHash: string
+    }[]
+  }[],
+): Promise<string>