@kamishibai/sdk 0.1.1

package/src/delivery/read.js

@@ -0,0 +1,109 @@
+import { existsSync, readFileSync, readSync } from 'node:fs'
+import { basename, extname, resolve } from 'node:path'
+import { CODES, EXIT, KsbError } from '../core/errors.js'
+
+export const STDIN_SPEC = '-'
+
+const CHUNK_SIZE = 65536
+/** Per-stall budget: MAX_EAGAIN_RETRIES × RETRY_PAUSE_MS ≈ 10s of writer silence. */
+const MAX_EAGAIN_RETRIES = 5000
+const RETRY_PAUSE_MS = 2
+
+/** Block the thread briefly without spinning the CPU. */
+const pause = (ms) => {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
+}
+
+/**
+ * Read stdin synchronously. A shell pipe hands us a non-blocking fd, so EAGAIN
+ * simply means "the writer has not produced data yet" and must be retried —
+ * `readFileSync(0)` gives up on it and breaks `example doc | render -`.
+ *
+ * The retry budget is per stall, not per read: it resets whenever bytes arrive,
+ * so a slow writer that pauses repeatedly (an upstream agent streaming Markdown,
+ * say) is only cut off after a genuine ~10s silence rather than accumulating
+ * earlier waits until an arbitrary cap truncates a still-live stream.
+ */
+const readStdin = () => {
+  const buffer = Buffer.alloc(CHUNK_SIZE)
+  const chunks = []
+  let retries = 0
+
+  for (;;) {
+    let read
+    try {
+      read = readSync(0, buffer, 0, CHUNK_SIZE, null)
+    } catch (cause) {
+      if (cause.code === 'EOF') break
+      if (cause.code === 'EAGAIN' && retries < MAX_EAGAIN_RETRIES) {
+        retries += 1
+        pause(RETRY_PAUSE_MS)
+        continue
+      }
+      throw new KsbError({
+        code: CODES.INPUT_EMPTY,
+        message: `could not read stdin: ${cause.message}`,
+        exitCode: EXIT.USAGE,
+      })
+    }
+    if (read === 0) break
+    retries = 0
+    chunks.push(Buffer.from(buffer.subarray(0, read)))
+  }
+
+  return Buffer.concat(chunks).toString('utf8')
+}
+
+/**
+ * Read a source document from a path or from stdin (`-`).
+ * @returns {{source: string, origin: string, format: 'markdown'|'json', slug: string}}
+ */
+export function readSource(spec) {
+  if (spec === STDIN_SPEC) {
+    const source = readStdin()
+    return { source, origin: 'stdin', format: sniffFormat(source, ''), slug: 'document' }
+  }
+
+  const absolute = resolve(spec)
+  if (!existsSync(absolute)) {
+    throw new KsbError({
+      code: CODES.INPUT_NOT_FOUND,
+      message: `input not found: ${spec}`,
+      exitCode: EXIT.USAGE,
+    })
+  }
+  const source = readFileSync(absolute, 'utf8')
+  const ext = extname(absolute)
+  return {
+    source,
+    origin: absolute,
+    format: sniffFormat(source, ext),
+    slug: basename(absolute, ext) || 'document',
+  }
+}
+
+/** Read an existing artifact (or any text file) for inspection. */
+export function readArtifact(spec) {
+  const absolute = resolve(spec)
+  if (!existsSync(absolute)) {
+    throw new KsbError({
+      code: CODES.INPUT_NOT_FOUND,
+      message: `artifact not found: ${spec}`,
+      exitCode: EXIT.USAGE,
+    })
+  }
+  try {
+    return { html: readFileSync(absolute, 'utf8'), path: absolute }
+  } catch (cause) {
+    throw new KsbError({
+      code: CODES.ARTIFACT_UNREADABLE,
+      message: `could not read artifact ${spec}: ${cause.message}`,
+      exitCode: EXIT.VALIDATION,
+    })
+  }
+}
+
+function sniffFormat(source, ext) {
+  if (ext === '.json') return 'json'
+  return source.trimStart().startsWith('{') ? 'json' : 'markdown'
+}

package/src/delivery/run.js

@@ -0,0 +1,95 @@
+import { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs'
+import { CODES, EXIT, KsbError } from '../core/errors.js'
+import { writeFileAtomic } from './atomic.js'
+import { runDir, servePidfile } from './home.js'
+
+/**
+ * The serve pidfile (CONTRACT E1 — `run/serve.pid` under the store root, whose
+ * one resolver is `./home.js`; the env-var name is spelled only there).
+ *
+ * G2's promoted trap is the reason this file exists at all: a dev server that
+ * outlives its session is invisible — it holds a port, keeps re-rendering, and
+ * nothing on screen says so. `close` can only be honest about "everything this
+ * SDK started is now stopped" if starting one *records* it.
+ *
+ * The file holds a JSON **array** of records, not a bare pid, for two reasons:
+ * `close` must be able to stop every server this SDK started rather than only
+ * the most recent one (the orphan case is precisely the one that hides), and a
+ * recycled pid must be distinguishable from the process we meant — the record
+ * carries the port and start time so a stale entry can be recognised instead of
+ * blindly signalled.
+ *
+ * `run/` is ephemeral state, never a record: unlike `artifacts/`, deleting it
+ * loses nothing but the ability to stop a process that is already gone.
+ */
+
+const runFailed = (path, cause) =>
+  new KsbError({
+    code: CODES.WRITE_FAILED,
+    message: `could not update the serve pidfile at ${path}: ${cause.message}`,
+    exitCode: EXIT.VALIDATION,
+  })
+
+/** Is this pid a live process? Signal 0 tests existence without delivering one. */
+export function isAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (cause) {
+    // EPERM means the process exists but belongs to someone else — still alive.
+    return cause?.code === 'EPERM'
+  }
+}
+
+const isRecord = (value) =>
+  value !== null && typeof value === 'object' && Number.isInteger(value.pid) && value.pid > 0
+
+/**
+ * Every recorded server, in start order. A corrupt pidfile yields an empty list
+ * rather than throwing: `close` must stay usable exactly when state is broken.
+ *
+ * @returns {Array<{pid: number, port: number, url: string, input: string, startedAt: string}>}
+ */
+export function readServeRecords(env = process.env) {
+  const path = servePidfile(env)
+  if (!existsSync(path)) return []
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'))
+    return Array.isArray(parsed) ? parsed.filter(isRecord) : []
+  } catch {
+    return []
+  }
+}
+
+const writeRecords = (records, env) => {
+  const path = servePidfile(env)
+  try {
+    if (records.length === 0) {
+      rmSync(path, { force: true })
+      return records
+    }
+    mkdirSync(runDir(env), { recursive: true })
+    writeFileAtomic(path, `${JSON.stringify(records, null, 2)}\n`)
+  } catch (cause) {
+    throw runFailed(path, cause)
+  }
+  return records
+}
+
+/**
+ * Record a newly started server, dropping entries whose process is gone.
+ *
+ * Pruning on write rather than on read is deliberate: the pidfile is the thing
+ * `close` reads, and a file that accumulates dead pids would make `close`
+ * report work it did not do.
+ */
+export function registerServe(record, env = process.env) {
+  const live = readServeRecords(env).filter((entry) => isAlive(entry.pid))
+  return writeRecords([...live, record], env)
+}
+
+/** Forget every record (used after `close` has signalled them). */
+export function clearServeRecords(env = process.env) {
+  return writeRecords([], env)
+}