@shaztech/video-pipeline 1.0.1

package/src/executor/nodeHandlers/video-cutter.js

@@ -0,0 +1,145 @@
+/*
+ * Copyright 2026 Shazron Abdullah
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import os from 'os'
+import path from 'path'
+import { mkdirSync, rmSync, readdirSync, copyFileSync } from 'fs'
+import { glob } from 'glob'
+import { run } from '../runner.js'
+
+function expandPath(p) {
+  return p.startsWith('~/') ? path.join(os.homedir(), p.slice(2)) : p
+}
+
+/**
+ * Builds argv and executes video-cutter for a node.
+ * After execution, globs the output directory for segment files
+ * and stores them in context[nodeId].outputs (sorted).
+ *
+ * Input files come from (in priority order):
+ *   1. Connected input-file / input-folder nodes (opts.inputFiles)
+ *   2. config.input (legacy / backward-compat)
+ *
+ * When multiple input files are supplied each is cut into its own
+ * sub-directory of the output dir; all resulting segments are pooled
+ * into context[nodeId].outputs.
+ *
+ * @param {object} node - the spec node
+ * @param {Map} context - runtime context keyed by nodeId
+ * @param {string} _tempRoot - base temp directory (unused)
+ * @param {object} opts - { dryRun, overwrite, outputFolderPaths, inputFiles }
+ */
+export async function handleVideoCutter(node, context, _tempRoot, opts = {}) {
+  const { config } = node
+
+  // Resolve input file(s)
+  const inputFiles = opts.inputFiles?.length > 0
+    ? opts.inputFiles.map(expandPath).filter(Boolean)
+    : config.input ? [expandPath(config.input)] : []
+
+  if (inputFiles.length === 0) {
+    if (opts.dryRun) {
+      // dry-run with no input: emit a placeholder so downstream nodes can print
+      const outputDir = path.join(os.tmpdir(), 'video-pipeline', node.id)
+      const segCount = config.segments ?? 1
+      const dummyOutputs = Array.from({ length: segCount }, (_, i) =>
+        path.join(outputDir, `segment_${String(i + 1).padStart(3, '0')}.mp4`)
+      )
+      context.set(node.id, { outputDir, outputs: dummyOutputs })
+      return
+    }
+    throw new Error(`Node "${node.id}" (video-cutter): no input file configured — connect an InputFile or InputFolder node`)
+  }
+
+  // Output folder paths from connected OutputFolder nodes
+  const outputFolderPaths = (opts.outputFolderPaths ?? []).map(expandPath).filter(Boolean)
+
+  const allSegments = []
+  const multiInput = inputFiles.length > 1
+
+  // Determine base output dir (same for all input files)
+  const baseOutputDir = outputFolderPaths.length > 0
+    ? outputFolderPaths[0]
+    : config.output
+    ? expandPath(config.output)
+    : path.join(path.dirname(inputFiles[0]), 'cutter-output')
+
+  for (const inputFile of inputFiles) {
+    // Each input file gets its own sub-directory when processing multiple files
+    const outputDir = multiInput
+      ? path.join(baseOutputDir, path.basename(inputFile, path.extname(inputFile)))
+      : baseOutputDir
+
+    if (!opts.dryRun) {
+      if (opts.overwrite) rmSync(outputDir, { recursive: true, force: true })
+      mkdirSync(outputDir, { recursive: true })
+    }
+
+    const argv = ['-i', inputFile, '-o', outputDir]
+
+    if (config.segments != null) {
+      argv.push('-n', String(config.segments))
+    } else if (config.duration != null) {
+      argv.push('-d', String(config.duration))
+    } else if (config.sceneDetect != null) {
+      argv.push('--scene-detect', config.sceneDetect === true ? '' : String(config.sceneDetect))
+    }
+
+    if (config.verify) argv.push('--verify')
+    if (config.reEncode) argv.push('--re-encode')
+
+    await run('video-cutter', argv.filter(Boolean), {
+      label: node.label ?? node.id,
+      dryRun: opts.dryRun,
+      input: 'y\n'
+    })
+
+    if (opts.dryRun) {
+      const segCount = config.segments ?? 1
+      for (let i = 0; i < segCount; i++) {
+        allSegments.push(path.join(outputDir, `segment_${String(i + 1).padStart(3, '0')}.mp4`))
+      }
+      continue
+    }
+
+    const files = (await glob('**/*.mp4', { cwd: outputDir, absolute: true })).sort()
+
+    if (files.length === 0) {
+      let contents = []
+      try { contents = readdirSync(outputDir) } catch {}
+      const detail = contents.length > 0
+        ? `Output directory contains: ${contents.join(', ')}`
+        : 'Output directory is empty'
+      throw new Error(
+        `Node "${node.id}" (video-cutter): produced no output segments\n  ${detail}\n  Input: ${inputFile}`
+      )
+    }
+
+    allSegments.push(...files)
+  }
+
+  // Copy all segments to any additional output-folder paths
+  const additionalDirs = outputFolderPaths.slice(1)
+  for (const dir of additionalDirs) {
+    console.log(`  Copying ${allSegments.length} segment(s) → ${dir}`)
+    mkdirSync(dir, { recursive: true })
+    for (const file of allSegments) {
+      copyFileSync(file, path.join(dir, path.basename(file)))
+    }
+  }
+
+  context.set(node.id, { outputDir: baseOutputDir, outputs: allSegments })
+}

package/src/executor/nodeHandlers/video-stitcher.js

@@ -0,0 +1,190 @@
+/*
+ * Copyright 2026 Shazron Abdullah
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import os from 'os'
+import path from 'path'
+import { mkdirSync, existsSync, copyFileSync } from 'fs'
+import { run } from '../runner.js'
+
+function expandPath(p) {
+  return p.startsWith('~/') ? path.join(os.homedir(), p.slice(2)) : p
+}
+
+/**
+ * Builds the list of per-run inputs from inputOrder + edge outputs.
+ * Returns an array of { inputs: string[], name: string } — one entry per output file.
+ *
+ * When an edge item expands to N files, N runs are produced (one per edge file),
+ * with fixed items applied to every run. The output filename equals the basename
+ * of the corresponding edge file.
+ */
+function buildRuns(config, incomingEdges, context, nodeId) {
+  // Collect edge outputs keyed by source nodeId
+  const edgeOutputs = new Map()
+  for (const edge of incomingEdges) {
+    const sourceCtx = context.get(edge.source)
+    if (!sourceCtx) {
+      throw new Error(
+        `Node "${nodeId}" (video-stitcher): upstream node "${edge.source}" has no outputs in context`
+      )
+    }
+    edgeOutputs.set(edge.source, sourceCtx.outputs ?? [])
+  }
+
+  if (Array.isArray(config.inputOrder) && config.inputOrder.length > 0) {
+    const edgeItems = config.inputOrder.filter((i) => i.type === 'edge')
+
+    if (edgeItems.length === 0) {
+      // No edge connections — single run with all fixed inputs
+      const inputs = config.inputOrder
+        .filter((i) => i.type === 'fixed' && i.value)
+        .map((i) => i.imageDuration != null ? `${i.value}:${i.imageDuration}` : i.value)
+      return [{ inputs, name: 'output.mp4' }]
+    }
+
+    // Number of runs = max file count across all edge items
+    let runCount = 1
+    for (const item of edgeItems) {
+      const files = edgeOutputs.get(item.nodeId) ?? []
+      if (files.length > runCount) runCount = files.length
+    }
+
+    const runs = []
+    const pivotFiles = edgeOutputs.get(edgeItems[0].nodeId) ?? []
+
+    // When an InputFolder feeds multiple files into the cutter, each file's segments
+    // land in a named subfolder (e.g. cutter-output/movie1/seg_01.mp4).
+    // Detect this by checking whether the pivot files span more than one parent dir.
+    const pivotParents = new Set(pivotFiles.map((f) => path.dirname(f)))
+    const multiSource = pivotParents.size > 1
+
+    for (let i = 0; i < runCount; i++) {
+      const inputs = []
+      for (const item of config.inputOrder) {
+        if (item.type === 'fixed') {
+          if (item.value) inputs.push(item.imageDuration != null ? `${item.value}:${item.imageDuration}` : item.value)
+        } else if (item.type === 'edge') {
+          const files = edgeOutputs.get(item.nodeId) ?? []
+          // Use file i; clamp to last available if this edge has fewer files
+          const file = files[Math.min(i, files.length - 1)]
+          if (file) inputs.push(file)
+        }
+      }
+      const pivotFile = pivotFiles[i]
+      // Mirror the source subfolder name in the output so files from different input
+      // sources don't collide (e.g. stitch-output/movie1/seg_01.mp4).
+      const name = pivotFile
+        ? multiSource
+          ? path.join(path.basename(path.dirname(pivotFile)), path.basename(pivotFile))
+          : path.basename(pivotFile)
+        : `output_${String(i + 1).padStart(3, '0')}.mp4`
+      runs.push({ inputs, name })
+    }
+    return runs
+  } else {
+    // Legacy: fixed inputs first, then all edge outputs — single run
+    const fixedInputs = Array.isArray(config.inputs) ? config.inputs.filter(Boolean) : []
+    const variableInputs = []
+    for (const edge of incomingEdges) {
+      const sourceCtx = context.get(edge.source)
+      if (!sourceCtx) {
+        throw new Error(
+          `Node "${nodeId}" (video-stitcher): upstream node "${edge.source}" has no outputs in context`
+        )
+      }
+      variableInputs.push(...(sourceCtx.outputs ?? []))
+    }
+    return [{ inputs: [...fixedInputs, ...variableInputs], name: 'output.mp4' }]
+  }
+}
+
+/**
+ * Builds argv and executes video-stitcher for a node.
+ * Produces one output file per edge segment (N inputs → N outputs),
+ * all written into the configured output folder.
+ *
+ * @param {object} node - the spec node
+ * @param {Map} context - runtime context keyed by nodeId
+ * @param {string} tempRoot - base temp directory for this run
+ * @param {object[]} incomingEdges - edges where edge.target === node.id
+ * @param {object} opts - { dryRun, overwrite }
+ */
+export async function handleVideoStitcher(node, context, tempRoot, incomingEdges, opts = {}) {
+  const { config } = node
+
+  // Determine output directory: connected output-folder node > config.output > temp
+  const outputFolderPaths = (opts.outputFolderPaths ?? []).map(expandPath).filter(Boolean)
+  const outputDir = outputFolderPaths.length > 0
+    ? outputFolderPaths[0]
+    : config.output
+    ? expandPath(config.output)
+    : path.join(tempRoot, node.id)
+
+  if (!opts.dryRun) mkdirSync(outputDir, { recursive: true })
+
+  const runs = buildRuns(config, incomingEdges, context, node.id)
+
+  const outputFiles = []
+
+  for (const { inputs, name } of runs) {
+    if (inputs.length < 2) {
+      throw new Error(
+        `Node "${node.id}" (video-stitcher): at least 2 inputs required for "${name}", got ${inputs.length}`
+      )
+    }
+
+    const outputFile = path.join(outputDir, name)
+
+    if (!opts.dryRun) mkdirSync(path.dirname(outputFile), { recursive: true })
+
+    if (!opts.dryRun && !opts.overwrite && existsSync(outputFile)) {
+      throw new Error(
+        `Output file already exists: ${outputFile}\nUse --overwrite to replace it.`
+      )
+    }
+
+    const argv = [...inputs, '-o', outputFile]
+
+    if (config.imageDuration != null && config.imageDuration !== 1) {
+      argv.push('-d', String(config.imageDuration))
+    }
+    if (config.bgAudio) {
+      argv.push('--bg-audio', config.bgAudio)
+    }
+    if (config.bgAudioVolume != null && config.bgAudioVolume !== 1.0) {
+      argv.push('--bg-audio-volume', String(config.bgAudioVolume))
+    }
+
+    await run('video-stitcher', argv, {
+      label: node.label ?? node.id,
+      dryRun: opts.dryRun
+    })
+
+    outputFiles.push(outputFile)
+  }
+
+  // Copy outputs to any additional output-folder paths
+  const additionalDirs = outputFolderPaths.slice(1)
+  for (const dir of additionalDirs) {
+    console.log(`  Copying ${outputFiles.length} output(s) → ${dir}`)
+    mkdirSync(dir, { recursive: true })
+    for (const file of outputFiles) {
+      copyFileSync(file, path.join(dir, path.basename(file)))
+    }
+  }
+
+  context.set(node.id, { outputDir, outputs: outputFiles })
+}

package/src/executor/runner.js

@@ -0,0 +1,75 @@
+/*
+ * Copyright 2026 Shazron Abdullah
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { execa } from 'execa'
+import { spawn } from 'child_process'
+import { fileURLToPath } from 'url'
+import path from 'path'
+import { existsSync, realpathSync } from 'fs'
+import chalk from 'chalk'
+
+/**
+ * Resolves a CLI binary from the workspace node_modules/.bin,
+ * falling back to global PATH.
+ */
+function resolveBin(name) {
+  // Walk up from this file to find node_modules/.bin
+  const here = fileURLToPath(import.meta.url)
+  let dir = path.dirname(here)
+  for (let i = 0; i < 8; i++) {
+    const candidate = path.join(dir, 'node_modules', '.bin', name)
+    if (existsSync(candidate)) {
+      try { return realpathSync(candidate) } catch { return candidate }
+    }
+    dir = path.dirname(dir)
+  }
+  // Fall back to name on PATH
+  return name
+}
+
+/**
+ * Runs a CLI tool with the given args, streaming output.
+ * @param {string} bin - binary name (e.g. 'video-cutter')
+ * @param {string[]} args - argv array
+ * @param {{ label?: string, dryRun?: boolean }} opts
+ */
+export async function run(bin, args, opts = {}) {
+  const resolved = resolveBin(bin)
+  const label = opts.label ?? bin
+
+  if (opts.dryRun) {
+    console.log(chalk.dim(`[dry-run] ${resolved} ${args.join(' ')}`))
+    return
+  }
+
+  console.log(chalk.cyan(`▶ ${label}`) + chalk.dim(` $ ${bin} ${args.join(' ')}`))
+
+  if (opts.input !== undefined) {
+    // Use native spawn so stdin can be piped while stdout/stderr use real inherited file descriptors
+    await new Promise((resolve, reject) => {
+      const proc = spawn(resolved, args, { stdio: ['pipe', 'inherit', 'inherit'] })
+      proc.stdin.write(opts.input)
+      proc.stdin.end()
+      proc.on('close', (code) => {
+        if (code === 0) resolve()
+        else reject(new Error(`${bin} exited with code ${code}`))
+      })
+      proc.on('error', reject)
+    })
+  } else {
+    await execa(resolved, args, { stdio: 'inherit' })
+  }
+}

package/src/executor/topoSort.js

@@ -0,0 +1,61 @@
+/*
+ * Copyright 2026 Shazron Abdullah
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Kahn's topological sort algorithm.
+ * Returns an array of levels, where each level is an array of node IDs
+ * that can be executed in parallel (all their dependencies are in prior levels).
+ * Throws if a cycle is detected.
+ */
+export function topoSort(nodes, edges) {
+  const nodeIds = new Set(nodes.map((n) => n.id))
+
+  // Build adjacency: source -> [targets]
+  const outEdges = new Map()
+  const inDegree = new Map()
+
+  for (const id of nodeIds) {
+    outEdges.set(id, [])
+    inDegree.set(id, 0)
+  }
+
+  for (const edge of edges) {
+    outEdges.get(edge.source)?.push(edge.target)
+    inDegree.set(edge.target, (inDegree.get(edge.target) ?? 0) + 1)
+  }
+
+  const levels = []
+  let remaining = new Set(nodeIds)
+
+  while (remaining.size > 0) {
+    const level = [...remaining].filter((id) => inDegree.get(id) === 0)
+
+    if (level.length === 0) {
+      throw new Error('Pipeline has a cycle — cannot execute')
+    }
+
+    levels.push(level)
+
+    for (const id of level) {
+      remaining.delete(id)
+      for (const target of outEdges.get(id) ?? []) {
+        inDegree.set(target, inDegree.get(target) - 1)
+      }
+    }
+  }
+
+  return levels
+}

package/src/server/index.js

@@ -0,0 +1,81 @@
+/*
+ * Copyright 2026 Shazron Abdullah
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import http from 'http'
+import net from 'net'
+import path from 'path'
+import { fileURLToPath } from 'url'
+import express from 'express'
+import { WebSocketServer } from 'ws'
+import { createRoutes } from './routes.js'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const EDITOR_DIST = path.resolve(__dirname, '../../dist/editor')
+
+/**
+ * Finds an available TCP port starting from `start`.
+ */
+function findFreePort(start = 3847) {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer()
+    server.listen(start, () => {
+      const { port } = server.address()
+      server.close(() => resolve(port))
+    })
+    server.on('error', () => findFreePort(start + 1).then(resolve).catch(reject))
+  })
+}
+
+/**
+ * Starts the editor Express + WebSocket server.
+ * @param {string} specPath - absolute path to the spec JSON file
+ * @param {{ port?: number }} opts
+ * @returns {Promise<{ url: string, server: http.Server, wss: WebSocketServer }>}
+ */
+export async function startEditorServer(specPath, opts = {}) {
+  const port = opts.port ?? (await findFreePort())
+
+  const app = express()
+  const httpServer = http.createServer(app)
+  const wss = new WebSocketServer({ server: httpServer })
+
+  function broadcast(data) {
+    const msg = JSON.stringify(data)
+    for (const client of wss.clients) {
+      if (client.readyState === 1 /* OPEN */) {
+        client.send(msg)
+      }
+    }
+  }
+
+  app.use(express.json({ limit: '10mb' }))
+  app.use(createRoutes(specPath, broadcast))
+  app.use(express.static(EDITOR_DIST))
+
+  // Fallback for SPA routing
+  app.get('/*path', (_req, res) => {
+    res.sendFile(path.join(EDITOR_DIST, 'index.html'))
+  })
+
+  wss.on('connection', (ws) => {
+    ws.send(JSON.stringify({ type: 'ready', specPath }))
+  })
+
+  await new Promise((resolve) => httpServer.listen(port, resolve))
+
+  const url = `http://localhost:${port}`
+  return { url, server: httpServer, wss }
+}

package/src/server/routes.js

@@ -0,0 +1,123 @@
+/*
+ * Copyright 2026 Shazron Abdullah
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { readFileSync, writeFileSync, renameSync } from 'fs'
+import { execFile } from 'child_process'
+import path from 'path'
+import { Router } from 'express'
+
+function nativeBrowse() {
+  return new Promise((resolve) => {
+    const { platform } = process
+    if (platform === 'darwin') {
+      execFile('osascript', ['-e', 'POSIX path of (choose file)'], (err, stdout) => {
+        resolve(err ? null : stdout.trim())
+      })
+    } else if (platform === 'linux') {
+      execFile('zenity', ['--file-selection'], (err, stdout) => {
+        if (!err) return resolve(stdout.trim())
+        execFile('kdialog', ['--getopenfilename', '.'], (err2, stdout2) => {
+          resolve(err2 ? null : stdout2.trim())
+        })
+      })
+    } else if (platform === 'win32') {
+      const ps = `Add-Type -AssemblyName System.Windows.Forms; $d = New-Object System.Windows.Forms.OpenFileDialog; if ($d.ShowDialog() -eq 'OK') { $d.FileName }`
+      execFile('powershell', ['-Command', ps], (err, stdout) => {
+        resolve(err ? null : stdout.trim())
+      })
+    } else {
+      resolve(null)
+    }
+  })
+}
+
+function nativeBrowseFolder() {
+  return new Promise((resolve) => {
+    const { platform } = process
+    if (platform === 'darwin') {
+      execFile('osascript', ['-e', 'POSIX path of (choose folder)'], (err, stdout) => {
+        resolve(err ? null : stdout.trim())
+      })
+    } else if (platform === 'linux') {
+      execFile('zenity', ['--file-selection', '--directory'], (err, stdout) => {
+        if (!err) return resolve(stdout.trim())
+        execFile('kdialog', ['--getexistingdirectory', '.'], (err2, stdout2) => {
+          resolve(err2 ? null : stdout2.trim())
+        })
+      })
+    } else if (platform === 'win32') {
+      const ps = `Add-Type -AssemblyName System.Windows.Forms; $d = New-Object System.Windows.Forms.FolderBrowserDialog; if ($d.ShowDialog() -eq 'OK') { $d.SelectedPath }`
+      execFile('powershell', ['-Command', ps], (err, stdout) => {
+        resolve(err ? null : stdout.trim())
+      })
+    } else {
+      resolve(null)
+    }
+  })
+}
+
+/**
+ * Creates Express router for the editor API.
+ * @param {string} specPath - absolute path to the spec JSON file
+ * @param {function} broadcast - WebSocket broadcast function
+ */
+export function createRoutes(specPath, broadcast) {
+  const router = Router()
+
+  // GET /api/spec — return current spec from disk
+  router.get('/api/spec', (_req, res) => {
+    try {
+      const content = readFileSync(specPath, 'utf8')
+      const spec = JSON.parse(content)
+      res.json(spec)
+    } catch (err) {
+      res.status(500).json({ error: err.message })
+    }
+  })
+
+  // GET /api/browse — open a native OS file picker, return full path
+  router.get('/api/browse', async (_req, res) => {
+    const filePath = await nativeBrowse()
+    res.json({ path: filePath })
+  })
+
+  // GET /api/browse-folder — open a native OS folder picker, return full path
+  router.get('/api/browse-folder', async (_req, res) => {
+    const folderPath = await nativeBrowseFolder()
+    res.json({ path: folderPath })
+  })
+
+  // POST /api/spec — atomically write spec to disk
+  router.post('/api/spec', (req, res) => {
+    try {
+      const spec = req.body
+      if (!spec || typeof spec !== 'object') {
+        return res.status(400).json({ error: 'Request body must be a JSON object' })
+      }
+
+      const tmp = `${specPath}.tmp`
+      writeFileSync(tmp, JSON.stringify(spec, null, 2) + '\n', 'utf8')
+      renameSync(tmp, specPath)
+
+      broadcast({ type: 'saved', timestamp: Date.now() })
+      res.json({ ok: true })
+    } catch (err) {
+      res.status(500).json({ error: err.message })
+    }
+  })
+
+  return router
+}