dsh-labscript 0.2.0 → 0.2.2

package/lib/index.js

@@ -1,138 +1,138 @@
-/**
- * dsh-labscript -- host half.
- *
- * Registers the labs_* tools, the runtime skill, and a small HTTP API used by
- * the browser configuration page. The browser half is optional: the tools work
- * without it, and the page only edits the four connection settings (backend,
- * python, runmanager host/port, protocolsDir).
- */
-import fs from 'node:fs'
-import { createRuntime, LabError } from './runtime.js'
-import { registerTools } from './tools.js'
-import { registerSkill } from './skill.js'
-import { writeUiConfig } from './store.mjs'
-
-export const name = 'dsh-labscript'
-export const inject = ['tools', 'skills']
-
-const PACKAGE = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
-const API_PREFIX = '/dsh-labscript/api'
-const MAX_BODY_BYTES = 64 * 1024
-
-function sendJson(response, status, body) {
-  response.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' })
-  response.end(JSON.stringify(body))
-}
-
-function readJsonBody(request) {
-  return new Promise((resolve, reject) => {
-    const chunks = []
-    let size = 0
-    request.on('data', (chunk) => {
-      size += chunk.length
-      if (size > MAX_BODY_BYTES) {
-        reject(new Error('request body too large'))
-        request.destroy()
-        return
-      }
-      chunks.push(chunk)
-    })
-    request.on('end', () => {
-      try {
-        resolve(chunks.length === 0 ? {} : JSON.parse(Buffer.concat(chunks).toString('utf8')))
-      } catch (error) {
-        reject(new Error('request body is not JSON'))
-      }
-    })
-    request.on('error', reject)
-  })
-}
-
-function isTrustedRequest(ctx, request) {
-  let connection
-  try {
-    connection = typeof ctx.get === 'function' ? ctx.get('connection') : undefined
-  } catch {
-    connection = undefined
-  }
-  if (connection === undefined) return false
-  try {
-    if (typeof connection.isTrusted === 'function' && connection.isTrusted(request) === true) return true
-    if (typeof connection.requestRejection === 'function') {
-      const code = connection.requestRejection(request)
-      return code === undefined || code === null || code === false
-    }
-  } catch {
-    /* fall through to reject */
-  }
-  return false
-}
-
-function registerRoutes(ctx, runtime) {
-  const webServer = typeof ctx.get === 'function' ? ctx.get('webServer') : ctx.webServer
-  if (!webServer || typeof webServer.register !== 'function') return
-  const handler = async (request, response) => {
-    const url = new URL(request.url || '/', 'http://127.0.0.1')
-    if (!url.pathname.startsWith(API_PREFIX)) {
-      sendJson(response, 404, { ok: false, error: 'not found' })
-      return
-    }
-    if (!isTrustedRequest(ctx, request)) {
-      sendJson(response, 403, { ok: false, error: 'untrusted request origin' })
-      return
-    }
-    const route = url.pathname.slice(API_PREFIX.length).replace(/\/+$/, '') || '/'
-    try {
-      if (route === '/config' && request.method === 'GET') {
-        const config = runtime.config
-        const doctorInfo = { configFile: runtime.uiConfigPath(), stateFile: runtime.statePath(), python: config.python }
-        sendJson(response, 200, {
-          ok: true,
-          version: runtime.version,
-          packageName: PACKAGE.name,
-          ...doctorInfo,
-          config: {
-            backend: config.backend,
-            python: config.python,
-            runmanager: config.runmanager,
-            protocolsDir: config.protocolsDir,
-          },
-        })
-        return
-      }
-      if (route === '/config' && request.method === 'POST') {
-        const body = await readJsonBody(request)
-        const stored = writeUiConfig(body, runtime.uiHome)
-        sendJson(response, 200, { ok: true, config: stored })
-        return
-      }
-      if (route === '/doctor' && request.method === 'POST') {
-        const result = await runtime.doctor()
-        sendJson(response, 200, { ok: true, ...result })
-        return
-      }
-      sendJson(response, 404, { ok: false, error: 'not found' })
-    } catch (error) {
-      sendJson(response, 400, { ok: false, error: error && error.message ? error.message : String(error) })
-    }
-  }
-  ctx.effect(() => webServer.register({ kind: 'prefix', path: API_PREFIX, handler }))
-}
-
-export function apply(ctx, config) {
-  const runtime = createRuntime(ctx, config)
-  registerTools(ctx, runtime)
-  registerSkill(ctx)
-  registerRoutes(ctx, runtime)
-  const logger = ctx.logger
-  if (logger && typeof logger.info === 'function') {
-    const current = runtime.config
-    logger.info('[dsh-labscript] v' + runtime.version + ' backend=' + current.backend + ' python=' + (current.python || '<unset>'))
-    if (current.backend === 'labscript' && !current.python) {
-      logger.warn('[dsh-labscript] backend is labscript but config.python is empty; every hardware tool will fail')
-    }
-  }
-  return runtime
-}
-
-export { LabError }
+/**
+ * dsh-labscript -- host half.
+ *
+ * Registers the labs_* tools, the runtime skill, and a small HTTP API used by
+ * the browser configuration page. The browser half is optional: the tools work
+ * without it, and the page only edits the four connection settings (backend,
+ * python, runmanager host/port, protocolsDir).
+ */
+import fs from 'node:fs'
+import { createRuntime, LabError } from './runtime.js'
+import { registerTools } from './tools.js'
+import { registerSkill } from './skill.js'
+import { writeUiConfig } from './store.mjs'
+
+export const name = 'dsh-labscript'
+export const inject = ['tools', 'skills']
+
+const PACKAGE = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+const API_PREFIX = '/dsh-labscript/api'
+const MAX_BODY_BYTES = 64 * 1024
+
+function sendJson(response, status, body) {
+  response.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' })
+  response.end(JSON.stringify(body))
+}
+
+function readJsonBody(request) {
+  return new Promise((resolve, reject) => {
+    const chunks = []
+    let size = 0
+    request.on('data', (chunk) => {
+      size += chunk.length
+      if (size > MAX_BODY_BYTES) {
+        reject(new Error('request body too large'))
+        request.destroy()
+        return
+      }
+      chunks.push(chunk)
+    })
+    request.on('end', () => {
+      try {
+        resolve(chunks.length === 0 ? {} : JSON.parse(Buffer.concat(chunks).toString('utf8')))
+      } catch (error) {
+        reject(new Error('request body is not JSON'))
+      }
+    })
+    request.on('error', reject)
+  })
+}
+
+function isTrustedRequest(ctx, request) {
+  let connection
+  try {
+    connection = typeof ctx.get === 'function' ? ctx.get('connection') : undefined
+  } catch {
+    connection = undefined
+  }
+  if (connection === undefined) return false
+  try {
+    if (typeof connection.isTrusted === 'function' && connection.isTrusted(request) === true) return true
+    if (typeof connection.requestRejection === 'function') {
+      const code = connection.requestRejection(request)
+      return code === undefined || code === null || code === false
+    }
+  } catch {
+    /* fall through to reject */
+  }
+  return false
+}
+
+function registerRoutes(ctx, runtime) {
+  const webServer = typeof ctx.get === 'function' ? ctx.get('webServer') : ctx.webServer
+  if (!webServer || typeof webServer.register !== 'function') return
+  const handler = async (request, response) => {
+    const url = new URL(request.url || '/', 'http://127.0.0.1')
+    if (!url.pathname.startsWith(API_PREFIX)) {
+      sendJson(response, 404, { ok: false, error: 'not found' })
+      return
+    }
+    if (!isTrustedRequest(ctx, request)) {
+      sendJson(response, 403, { ok: false, error: 'untrusted request origin' })
+      return
+    }
+    const route = url.pathname.slice(API_PREFIX.length).replace(/\/+$/, '') || '/'
+    try {
+      if (route === '/config' && request.method === 'GET') {
+        const config = runtime.config
+        const doctorInfo = { configFile: runtime.uiConfigPath(), stateFile: runtime.statePath(), python: config.python }
+        sendJson(response, 200, {
+          ok: true,
+          version: runtime.version,
+          packageName: PACKAGE.name,
+          ...doctorInfo,
+          config: {
+            backend: config.backend,
+            python: config.python,
+            runmanager: config.runmanager,
+            protocolsDir: config.protocolsDir,
+          },
+        })
+        return
+      }
+      if (route === '/config' && request.method === 'POST') {
+        const body = await readJsonBody(request)
+        const stored = writeUiConfig(body, runtime.uiHome)
+        sendJson(response, 200, { ok: true, config: stored })
+        return
+      }
+      if (route === '/doctor' && request.method === 'POST') {
+        const result = await runtime.doctor()
+        sendJson(response, 200, { ok: true, ...result })
+        return
+      }
+      sendJson(response, 404, { ok: false, error: 'not found' })
+    } catch (error) {
+      sendJson(response, 400, { ok: false, error: error && error.message ? error.message : String(error) })
+    }
+  }
+  ctx.effect(() => webServer.register({ kind: 'prefix', path: API_PREFIX, handler }))
+}
+
+export function apply(ctx, config) {
+  const runtime = createRuntime(ctx, config)
+  registerTools(ctx, runtime)
+  registerSkill(ctx)
+  registerRoutes(ctx, runtime)
+  const logger = ctx.logger
+  if (logger && typeof logger.info === 'function') {
+    const current = runtime.config
+    logger.info('[dsh-labscript] v' + runtime.version + ' backend=' + current.backend + ' python=' + (current.python || '<unset>'))
+    if (current.backend === 'labscript' && !current.python) {
+      logger.warn('[dsh-labscript] backend is labscript but config.python is empty; every hardware tool will fail')
+    }
+  }
+  return runtime
+}
+
+export { LabError }

package/lib/protocols.js

@@ -1,112 +1,112 @@
-/**
- * Protocol files: discovery, YAML parsing, name resolution.
- *
- * A protocol is a YAML mapping. The schema is deliberately small: name,
- * labscript (or joint_script), set, scan, reps, engage, postprocess,
- * finish.restore/panel/history. Unknown keys are reported as warnings; the
- * legacy key "analysis" is accepted as an alias for "postprocess".
- */
-import fs from 'node:fs'
-import path from 'node:path'
-import YAML from 'yaml'
-
-const KNOWN_KEYS = new Set(['name', 'labscript', 'joint_script', 'set', 'scan', 'reps', 'engage', 'postprocess', 'finish', 'analysis'])
-const MAX_PROTOCOL_BYTES = 256 * 1024
-
-function protocolFiles(dir) {
-  if (!dir) return []
-  let entries = []
-  try {
-    entries = fs.readdirSync(dir)
-  } catch (error) {
-    return []
-  }
-  return entries
-    .filter((name) => name.endsWith('.yaml') || name.endsWith('.yml'))
-    .sort()
-    .map((name) => path.join(dir, name))
-}
-
-export function listProtocols(dir) {
-  return protocolFiles(dir).map((file) => {
-    try {
-      const loaded = loadProtocolFile(file)
-      return { name: loaded.name, file: path.basename(file), warnings: loaded.warnings }
-    } catch (error) {
-      return { name: path.basename(file), file: path.basename(file), error: error.message }
-    }
-  })
-}
-
-export function resolveProtocolPath(dir, ref) {
-  const value = String(ref || '').trim()
-  if (!value) throw new Error('protocol name is required')
-  if (path.isAbsolute(value)) {
-    if (fs.existsSync(value)) return value
-    throw new Error('protocol file not found: ' + value)
-  }
-  const candidates = [path.join(dir || '', value)]
-  if (!value.endsWith('.yaml') && !value.endsWith('.yml')) {
-    candidates.push(path.join(dir || '', value + '.yaml'))
-    candidates.push(path.join(dir || '', value + '.yml'))
-  }
-  for (const candidate of candidates) {
-    if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) return candidate
-  }
-  throw new Error('protocol not found in protocolsDir: ' + value)
-}
-
-export function loadProtocol(dir, ref) {
-  return loadProtocolFile(resolveProtocolPath(dir, ref))
-}
-
-export function loadProtocolFile(file) {
-  const stat = fs.statSync(file)
-  if (stat.size > MAX_PROTOCOL_BYTES) throw new Error('protocol file is too large: ' + file)
-  const text = fs.readFileSync(file, 'utf8')
-  let data
-  try {
-    data = YAML.parse(text)
-  } catch (error) {
-    throw new Error('cannot parse protocol YAML ' + path.basename(file) + ': ' + error.message)
-  }
-  return normalizeProtocol(data, file)
-}
-
-export function normalizeProtocol(data, file) {
-  if (!data || typeof data !== 'object' || Array.isArray(data)) {
-    throw new Error('protocol must be a YAML mapping: ' + (file || 'inline'))
-  }
-  const warnings = []
-  for (const key of Object.keys(data)) {
-    if (!KNOWN_KEYS.has(key)) warnings.push('unknown protocol key ignored: ' + key)
-  }
-  const plan = {
-    name: data.name ? String(data.name) : path.basename(file || 'protocol').replace(/\.ya?ml$/, ''),
-    labscript: data.labscript ? String(data.labscript) : undefined,
-    joint_script: data.joint_script ? String(data.joint_script) : undefined,
-    set: data.set && typeof data.set === 'object' ? Object.assign({}, data.set) : {},
-    scan: data.scan && typeof data.scan === 'object' ? Object.assign({}, data.scan) : {},
-    reps: data.reps === undefined ? 1 : data.reps,
-    engage: data.engage === undefined ? true : Boolean(data.engage),
-    postprocess: null,
-    finish: { restore: true, panel: {}, history: {} },
-  }
-  if (data.analysis !== undefined && data.postprocess === undefined) {
-    plan.postprocess = data.analysis ? String(data.analysis) : null
-    warnings.push('legacy key "analysis" used as "postprocess"')
-  } else if (data.postprocess !== undefined) {
-    plan.postprocess = data.postprocess ? String(data.postprocess) : null
-  }
-  if (data.finish && typeof data.finish === 'object') {
-    plan.finish.restore = data.finish.restore === undefined ? true : Boolean(data.finish.restore)
-    if (data.finish.panel && typeof data.finish.panel === 'object') plan.finish.panel = Object.assign({}, data.finish.panel)
-    if (data.finish.history && typeof data.finish.history === 'object') plan.finish.history = Object.assign({}, data.finish.history)
-    for (const key of Object.keys(data.finish)) {
-      if (!['restore', 'panel', 'history'].includes(key)) warnings.push('unknown finish key ignored: ' + key)
-    }
-  }
-  if (!plan.labscript && !plan.joint_script) throw new Error('protocol needs "labscript" or "joint_script": ' + (file || 'inline'))
-  if (!Number.isInteger(plan.reps) || plan.reps < 1) throw new Error('protocol reps must be a positive integer: ' + (file || 'inline'))
-  return { name: plan.name, file: file || null, plan, warnings }
-}
+/**
+ * Protocol files: discovery, YAML parsing, name resolution.
+ *
+ * A protocol is a YAML mapping. The schema is deliberately small: name,
+ * labscript (or joint_script), set, scan, reps, engage, postprocess,
+ * finish.restore/panel/history. Unknown keys are reported as warnings; the
+ * legacy key "analysis" is accepted as an alias for "postprocess".
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import YAML from 'yaml'
+
+const KNOWN_KEYS = new Set(['name', 'labscript', 'joint_script', 'set', 'scan', 'reps', 'engage', 'postprocess', 'finish', 'analysis'])
+const MAX_PROTOCOL_BYTES = 256 * 1024
+
+function protocolFiles(dir) {
+  if (!dir) return []
+  let entries = []
+  try {
+    entries = fs.readdirSync(dir)
+  } catch (error) {
+    return []
+  }
+  return entries
+    .filter((name) => name.endsWith('.yaml') || name.endsWith('.yml'))
+    .sort()
+    .map((name) => path.join(dir, name))
+}
+
+export function listProtocols(dir) {
+  return protocolFiles(dir).map((file) => {
+    try {
+      const loaded = loadProtocolFile(file)
+      return { name: loaded.name, file: path.basename(file), warnings: loaded.warnings }
+    } catch (error) {
+      return { name: path.basename(file), file: path.basename(file), error: error.message }
+    }
+  })
+}
+
+export function resolveProtocolPath(dir, ref) {
+  const value = String(ref || '').trim()
+  if (!value) throw new Error('protocol name is required')
+  if (path.isAbsolute(value)) {
+    if (fs.existsSync(value)) return value
+    throw new Error('protocol file not found: ' + value)
+  }
+  const candidates = [path.join(dir || '', value)]
+  if (!value.endsWith('.yaml') && !value.endsWith('.yml')) {
+    candidates.push(path.join(dir || '', value + '.yaml'))
+    candidates.push(path.join(dir || '', value + '.yml'))
+  }
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) return candidate
+  }
+  throw new Error('protocol not found in protocolsDir: ' + value)
+}
+
+export function loadProtocol(dir, ref) {
+  return loadProtocolFile(resolveProtocolPath(dir, ref))
+}
+
+export function loadProtocolFile(file) {
+  const stat = fs.statSync(file)
+  if (stat.size > MAX_PROTOCOL_BYTES) throw new Error('protocol file is too large: ' + file)
+  const text = fs.readFileSync(file, 'utf8')
+  let data
+  try {
+    data = YAML.parse(text)
+  } catch (error) {
+    throw new Error('cannot parse protocol YAML ' + path.basename(file) + ': ' + error.message)
+  }
+  return normalizeProtocol(data, file)
+}
+
+export function normalizeProtocol(data, file) {
+  if (!data || typeof data !== 'object' || Array.isArray(data)) {
+    throw new Error('protocol must be a YAML mapping: ' + (file || 'inline'))
+  }
+  const warnings = []
+  for (const key of Object.keys(data)) {
+    if (!KNOWN_KEYS.has(key)) warnings.push('unknown protocol key ignored: ' + key)
+  }
+  const plan = {
+    name: data.name ? String(data.name) : path.basename(file || 'protocol').replace(/\.ya?ml$/, ''),
+    labscript: data.labscript ? String(data.labscript) : undefined,
+    joint_script: data.joint_script ? String(data.joint_script) : undefined,
+    set: data.set && typeof data.set === 'object' ? Object.assign({}, data.set) : {},
+    scan: data.scan && typeof data.scan === 'object' ? Object.assign({}, data.scan) : {},
+    reps: data.reps === undefined ? 1 : data.reps,
+    engage: data.engage === undefined ? true : Boolean(data.engage),
+    postprocess: null,
+    finish: { restore: true, panel: {}, history: {} },
+  }
+  if (data.analysis !== undefined && data.postprocess === undefined) {
+    plan.postprocess = data.analysis ? String(data.analysis) : null
+    warnings.push('legacy key "analysis" used as "postprocess"')
+  } else if (data.postprocess !== undefined) {
+    plan.postprocess = data.postprocess ? String(data.postprocess) : null
+  }
+  if (data.finish && typeof data.finish === 'object') {
+    plan.finish.restore = data.finish.restore === undefined ? true : Boolean(data.finish.restore)
+    if (data.finish.panel && typeof data.finish.panel === 'object') plan.finish.panel = Object.assign({}, data.finish.panel)
+    if (data.finish.history && typeof data.finish.history === 'object') plan.finish.history = Object.assign({}, data.finish.history)
+    for (const key of Object.keys(data.finish)) {
+      if (!['restore', 'panel', 'history'].includes(key)) warnings.push('unknown finish key ignored: ' + key)
+    }
+  }
+  if (!plan.labscript && !plan.joint_script) throw new Error('protocol needs "labscript" or "joint_script": ' + (file || 'inline'))
+  if (!Number.isInteger(plan.reps) || plan.reps < 1) throw new Error('protocol reps must be a positive integer: ' + (file || 'inline'))
+  return { name: plan.name, file: file || null, plan, warnings }
+}