dsh-artcraft-plugin-vectorcraft 0.0.0-stage → 0.1.0

package/src/kit/exec.js

@@ -0,0 +1,242 @@
+/**
+ * Run a craft CLI headlessly and collect a bounded, structured result.
+ *
+ * The craft processes are ordinary external programs: this module deliberately
+ * uses `node:child_process` rather than a harness capability seam so the same
+ * code works from a Cordis plugin, the MCP bridge, the CLI and the tests.
+ * @module @dsh-artcraft/craft-kit/exec
+ */
+
+import { spawn } from 'node:child_process'
+import { appendFileSync } from 'node:fs'
+                                                                           
+
+/** Default cap on captured stdout+stderr, so a runaway export cannot flood the model. */
+export const MAX_CAPTURE_BYTES = 256 * 1024
+
+/** Cap used for catalog reads, whose JSON is legitimately large (VectorCraft is ~350 KB). */
+export const CATALOG_CAPTURE_BYTES = 16 * 1024 * 1024
+
+/** Default wall-clock budget for one headless craft run. */
+export const DEFAULT_TIMEOUT_MS = 120_000
+
+/** Arguments accepted by {@link runCraft}. */
+                                  
+                                
+                              
+                                  
+                      
+                             
+                               
+                                                              
+                                   
+ 
+
+/**
+ * Spawn a craft CLI, capture both streams, and settle on exit.
+ *
+ * Never rejects for a non-zero exit: the craft's own error text is the useful
+ * result, so it is returned as `ok: false` with the raw output attached.
+ * Rejects only when the process could not be spawned at all.
+ * @param options - profile, resolved binary, argv, cwd, and limits.
+ * @returns the structured run result.
+ */
+export async function runCraft(options                 )                          {
+  const { profile, binary, argv, cwd } = options
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  const started = Date.now()
+  const full = [...(profile.baseArgs ?? []), ...argv]
+  const cap = options.maxCaptureBytes ?? MAX_CAPTURE_BYTES
+  // DSH_ARTCRAFT_TRACE=<file> records every exact invocation, which is how a
+  // craft whose CLI is picky about argument shape gets debugged without
+  // guessing at what the plugin sent.
+  if (process.env.DSH_ARTCRAFT_TRACE !== undefined) {
+    try {
+      appendFileSync(process.env.DSH_ARTCRAFT_TRACE, `${binary.path} ${full.map(a => JSON.stringify(a)).join(' ')}\n`)
+    } catch {
+      // Tracing must never break a run.
+    }
+  }
+
+  return await new Promise                ((resolve, reject) => {
+    const child = spawn(binary.path, full, {
+      cwd,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: { ...process.env, NO_COLOR: '1', TERM: 'dumb' },
+    })
+
+    const stdout           = []
+    const stderr           = []
+    let captured = 0
+    let truncated = false
+
+    const collect = (sink          ) => (chunk        ) => {
+      if (captured >= cap) { truncated = true; return }
+      const room = cap - captured
+      if (chunk.length > room) {
+        sink.push(chunk.subarray(0, room))
+        captured = cap
+        truncated = true
+      } else {
+        sink.push(chunk)
+        captured += chunk.length
+      }
+    }
+
+    child.stdout.on('data', collect(stdout))
+    child.stderr.on('data', collect(stderr))
+
+    let timedOut = false
+    const timer = setTimeout(() => {
+      timedOut = true
+      child.kill('SIGKILL')
+    }, timeoutMs)
+
+    const onAbort = ()       => { child.kill('SIGKILL') }
+    options.signal?.addEventListener('abort', onAbort, { once: true })
+
+    const cleanup = ()       => {
+      clearTimeout(timer)
+      options.signal?.removeEventListener('abort', onAbort)
+    }
+
+    child.on('error', (error) => {
+      cleanup()
+      reject(new Error(`${profile.product}: failed to start ${binary.path}: ${error.message}`))
+    })
+
+    child.on('close', (code, signal) => {
+      cleanup()
+      const out = Buffer.concat(stdout).toString('utf8')
+      const err = Buffer.concat(stderr).toString('utf8')
+      const tail = timedOut ? `\n[timed out after ${timeoutMs}ms]` : ''
+      resolve({
+        ok: code === 0 && !timedOut,
+        bin: binary.path,
+        argv: full,
+        cwd,
+        exitCode: code,
+        signal,
+        stdout: out,
+        stderr: err + tail,
+        truncated,
+        durationMs: Date.now() - started,
+        artifacts: [],
+      })
+    })
+  })
+}
+
+/**
+ * Compose the argv for one headless `run` invocation.
+ *
+ * Each craft spells "run these commands" differently — repeated `--cmd id=json`
+ * (CADCraft, GridCraft), `--cmd id --params json` (PhotoCraft, VectorCraft),
+ * positional `id key=value` (LightCraft, EffectCraft), or a JSON-lines script
+ * file (FilmCraft). Profile fields select the spelling; this function owns the
+ * assembly so every plugin behaves identically.
+ * @param profile - the craft profile supplying flag spellings.
+ * @param options - document source, commands, outputs and extras.
+ * @returns the argv after the executable.
+ */
+export function buildRunArgv(
+  profile              ,
+  options   
+                           
+                                      
+                                                    
+                          
+                            
+                                    
+                            
+                                      
+                                                  
+                                            
+   ,
+)           {
+  const spec = profile.run
+  const inputMode = spec.inputMode ?? (spec.inFlag.length > 0 ? 'flag' : 'none')
+  // Some crafts take project-level flags before the subcommand, not after.
+  const argv           = [...options.globalFlags ?? [], spec.verb]
+  // CADCraft takes the drawing as a positional argument to `run` itself.
+  if (options.input !== undefined && inputMode === 'positional') argv.push(options.input)
+  else if (options.input !== undefined && inputMode === 'flag' && spec.inFlag.length > 0) {
+    argv.push(spec.inFlag, options.input)
+  } else if (options.input === undefined && options.sample !== undefined && options.sample !== false) {
+    if (spec.sampleFlag.length > 0) {
+      argv.push(spec.sampleFlag)
+      if (typeof options.sample === 'string') argv.push(options.sample)
+      else if (spec.newSampleValue !== undefined) argv.push(spec.newSampleValue)
+    }
+  }
+  for (const command of options.commands ?? []) {
+    const style = spec.cmdStyle ?? 'flag'
+    const json = command.json === undefined || command.json === null || command.json === '' ? undefined : command.json
+    const jsonText = json === undefined ? undefined : typeof json === 'string' ? json : JSON.stringify(json)
+    switch (style) {
+      case 'flag':
+        argv.push(spec.cmdFlag, formatCommand(command.id, json, spec.cmdSeparator))
+        break
+      case 'flag-params':
+        argv.push(spec.cmdFlag, command.id)
+        if (spec.cmdParamsFlag !== undefined && jsonText !== undefined) argv.push(spec.cmdParamsFlag, jsonText)
+        break
+      case 'positional-pair':
+        argv.push(command.id)
+        if (jsonText !== undefined) argv.push(jsonText)
+        break
+      case 'positional-kv':
+        argv.push(command.id)
+        for (const [key, value] of Object.entries(asRecord(json))) {
+          argv.push(`${key}=${typeof value === 'string' ? value : JSON.stringify(value)}`)
+        }
+        break
+    }
+  }
+  if (options.save !== undefined && (spec.saveMode ?? 'flag') === 'flag') argv.push(spec.saveFlag, options.save)
+  if (options.export !== undefined && spec.exportFlag !== undefined) argv.push(spec.exportFlag, options.export)
+  if (options.exportAllPages !== undefined && spec.exportAllPagesFlag !== undefined) {
+    argv.push(spec.exportAllPagesFlag, options.exportAllPages)
+  }
+  if (options.print === true && spec.printFlag !== undefined) argv.push(spec.printFlag)
+  argv.push(...options.extra ?? [])
+  return argv
+}
+
+/** One command to apply, before it is spelled for a particular CLI. */
+                                    
+                     
+                         
+ 
+
+/** Coerce a model-supplied JSON argument into a flat parameter map. */
+function asRecord(value         )                          {
+  if (typeof value === 'string' && value.trim().length > 0) {
+    try {
+      const parsed          = JSON.parse(value)
+      if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) return parsed                           
+    } catch {
+      return {}
+    }
+  }
+  if (typeof value === 'object' && value !== null && !Array.isArray(value)) return value                           
+  return {}
+}
+
+/**
+ * Normalize one model-supplied command into the CLI's `--cmd` value.
+ *
+ * The model writes `{ "id": "cell.set", "json": "{\"cell\":\"A1\"}" }` or a
+ * bare id; the craft CLI wants `id={...}` on GridCraft and `id {...}` on
+ * SoundCraft, so the separator comes from the profile.
+ * @param id - command id.
+ * @param json - optional JSON argument object.
+ * @param separator - the craft's separator between id and JSON.
+ * @returns the single argv value for `--cmd`.
+ */
+export function formatCommand(id        , json         , separator        )         {
+  if (json === undefined || json === null || json === '') return id
+  const text = typeof json === 'string' ? json : JSON.stringify(json)
+  if (text.length === 0) return id
+  return `${id}${separator}${text}`
+}

package/src/kit/index.js

@@ -0,0 +1,16 @@
+/**
+ * The ArtCraft DSH plugin kernel.
+ *
+ * Import this from a plugin package that does the actual
+ * `ctx.tools.register(defineTool(...))` calls; everything here is plain Node
+ * so it can also run from the MCP bridge, the CLI verifier and unit tests.
+ * @module @dsh-artcraft/craft-kit
+ */
+
+export * from './types.js'
+export * from './discover.js'
+export * from './exec.js'
+export * from './catalog.js'
+export * from './tools.js'
+export * from './mcp.js'
+export { CRAFT_PROFILES, CRAFTS_BIN_DIR, PROFILES_BY_ID, REPOS_DIR, profileOf } from './profiles.mjs'

package/src/kit/mcp.js

@@ -0,0 +1,231 @@
+/**
+ * An MCP (Model Context Protocol) client for a craft's own stdio server.
+ *
+ * Every craft ships `*-cli mcp`, a JSON-RPC 2.0 server with a modelled tool set
+ * (GridCraft 21 tools, SoundCraft more) alongside the generic command strings
+ * the CLI takes. Bridging to it gives the model tools with real JSON Schemas
+ * instead of one `--cmd` string, which is why the plugins expose both.
+ *
+ * The server is spawned once per runtime and kept warm: starting GridCraft's
+ * engine costs ~600 ms, which is too much to pay on every call. It is killed
+ * after `idleMs` without a request, and again when the plugin unloads.
+ * @module @dsh-artcraft/craft-kit/mcp
+ */
+
+import { spawn } from 'node:child_process'
+                                                                        
+                                                           
+
+/** One tool as the MCP server declares it. */
+                          
+                       
+                               
+                                                
+ 
+
+/** A settled JSON-RPC response. */
+                   
+                                   
+                                
+                       
+ 
+
+/** Default MCP protocol revision; servers negotiate down if they need to. */
+const PROTOCOL_VERSION = '2024-11-05'
+
+/**
+ * One live MCP connection to a craft.
+ *
+ * Kept deliberately small: one process, one pending-request table, and a
+ * close path that always kills the child, because a craft's engine holds
+ * memory and a leaked server would outlive the session that started it.
+ */
+export class CraftMcpClient {
+           #profile              
+           #binary             
+           #args                   
+  #child                                            
+  #buffer = ''
+  #nextId = 1
+           #pending = new Map                 ()
+  #idleTimer                            
+  #handshake                                                          
+  #tools                       
+  #closed = false
+
+  constructor(profile              , binary             , args                    = []) {
+    this.#profile = profile
+    this.#binary = binary
+    this.#args = args
+  }
+
+  /** Whether a live server process is currently attached. */
+  get running()          {
+    return this.#child !== undefined && this.#child.exitCode === null && !this.#closed
+  }
+
+  /** Tools the server declared, from the cached `tools/list` result. */
+  get cachedTools()                                 {
+    return this.#tools
+  }
+
+  /** One-line description of how this client was started, for diagnostics. */
+  describe()         {
+    return `${this.#binary.path} ${[...this.#args].join(' ')}`.trim()
+  }
+
+  /** Start the server if needed and complete the MCP handshake. */
+  async start(idleMs        )                {
+    if (this.#closed) throw new Error(`${this.#profile.product}: MCP client is closed`)
+    if (this.running) return
+    const child = spawn(this.#binary.path, [...(this.#profile.mcpArgs ?? ['mcp']), ...this.#args], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: { ...process.env, NO_COLOR: '1', TERM: 'dumb' },
+    })
+    this.#child = child
+    this.#buffer = ''
+    child.stdout.setEncoding('utf8')
+    child.stdout.on('data', (chunk        ) => { this.#onData(chunk) })
+    child.stderr.setEncoding('utf8')
+    // Craft servers announce themselves on stderr; it is not an error stream.
+    child.stderr.on('data', (chunk        ) => {
+      const text = chunk.trim()
+      if (text.length > 0 && process.env.DSH_ARTCRAFT_TRACE !== undefined) {
+        process.stderr.write(`[${this.#profile.id} mcp] ${text}\n`)
+      }
+    })
+    child.on('exit', () => {
+      this.#child = undefined
+      for (const [, pending] of this.#pending) {
+        clearTimeout(pending.timer)
+        pending.reject(new Error(`${this.#profile.product}: MCP server exited`))
+      }
+      this.#pending.clear()
+    })
+    child.on('error', (error) => {
+      this.#child = undefined
+      for (const [, pending] of this.#pending) {
+        clearTimeout(pending.timer)
+        pending.reject(new Error(`${this.#profile.product}: MCP server failed to start: ${error.message}`))
+      }
+      this.#pending.clear()
+    })
+    this.#idleMs = idleMs
+    await this.#request('initialize', {
+      protocolVersion: PROTOCOL_VERSION,
+      capabilities: {},
+      clientInfo: { name: 'dsh-artcraft', version: '0.1.0' },
+    })
+    this.#notify('notifications/initialized', {})
+  }
+
+  #idleMs = 300_000
+
+  /** Walk the server's tool list, caching it for later calls. */
+  async listTools()                     {
+    if (this.#tools !== undefined) return [...this.#tools]
+    const result = await this.#request('tools/list', {})                         
+    this.#tools = Array.isArray(result.tools) ? result.tools : []
+    return [...this.#tools]
+  }
+
+  /**
+   * Call one tool.
+   * @param name - tool name as declared by the server.
+   * @param args - the tool's JSON arguments.
+   * @returns the concatenated text content of the result.
+   */
+  async callTool(name        , args                         )                  {
+    const result = await this.#request('tools/call', { name, arguments: args })     
+                                                  
+                       
+     
+    const text = (result.content ?? [])
+      .map(block => (block.type === 'text' ? block.text ?? '' : `[${block.type ?? 'unknown'} content]`))
+      .join('\n')
+      .trim()
+    return `${text.length > 0 ? text : '(no content)'}${result.isError === true ? '\n[mcp: tool reported an error]' : ''}`
+  }
+
+  /** Terminate the server process now. */
+  close()       {
+    this.#closed = true
+    if (this.#idleTimer !== undefined) clearTimeout(this.#idleTimer)
+    const child = this.#child
+    this.#child = undefined
+    if (child !== undefined && child.exitCode === null) child.kill('SIGKILL')
+  }
+
+  /** Buffer stdout and resolve one response per complete line. */
+  #onData(chunk        )       {
+    this.#buffer += chunk
+    let index        
+    while ((index = this.#buffer.indexOf('\n')) !== -1) {
+      const line = this.#buffer.slice(0, index).trim()
+      this.#buffer = this.#buffer.slice(index + 1)
+      if (line.length === 0) continue
+      let message                                                                 
+      try {
+        message = JSON.parse(line)                  
+      } catch {
+        continue // A craft may log to stdout; only JSON-RPC lines matter.
+      }
+      if (typeof message.id !== 'number') continue
+      const pending = this.#pending.get(message.id)
+      if (pending === undefined) continue
+      this.#pending.delete(message.id)
+      clearTimeout(pending.timer)
+      if (message.error !== undefined) pending.reject(new Error(message.error.message ?? 'MCP error'))
+      else pending.resolve(message.result)
+    }
+  }
+
+  /** Send one request and await its response, arming the idle timer. */
+  #request(method        , params         , timeoutMs = 60_000)                   {
+    const child = this.#child
+    if (child === undefined || child.exitCode !== null) {
+      return Promise.reject(new Error(`${this.#profile.product}: MCP server is not running`))
+    }
+    const id = this.#nextId++
+    return new Promise         ((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.#pending.delete(id)
+        reject(new Error(`${this.#profile.product}: MCP ${method} timed out after ${timeoutMs}ms`))
+      }, timeoutMs)
+      this.#pending.set(id, { resolve, reject, timer })
+      child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id, method, params })}\n`)
+      this.#armIdle()
+    })
+  }
+
+  /** Send a notification, which has no response. */
+  #notify(method        , params         )       {
+    this.#child?.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', method, params })}\n`)
+    this.#armIdle()
+  }
+
+  /** (Re)start the countdown that shuts an unused server down. */
+  #armIdle()       {
+    if (this.#idleTimer !== undefined) clearTimeout(this.#idleTimer)
+    this.#idleTimer = setTimeout(() => { this.close() }, this.#idleMs)
+    this.#idleTimer.unref?.()
+  }
+}
+
+/**
+ * Render an MCP tool's JSON Schema as a compact parameter grammar for the model.
+ * @param schema - the tool's `inputSchema`.
+ * @returns one line per property, or `(no parameters)`.
+ */
+export function renderSchema(schema                                     )         {
+  const properties = schema?.properties
+  if (typeof properties !== 'object' || properties === null) return '(no parameters)'
+  const required = new Set(Array.isArray(schema?.required) ? schema.required.filter((r)              => typeof r === 'string') : [])
+  return Object.entries(properties                                                                             )
+    .map(([name, node]) => {
+      const type = node.type ?? (Array.isArray(node.enum) ? 'enum' : 'value')
+      const enumText = Array.isArray(node.enum) ? ` (${node.enum.map(e => JSON.stringify(e)).join(' | ')})` : ''
+      return `  ${name}${required.has(name) ? '' : '?'}: ${type}${enumText}${node.description !== undefined ? ` — ${node.description}` : ''}`
+    })
+    .join('\n')
+}

package/src/kit/platform.js

@@ -0,0 +1,82 @@
+/**
+ * Which release asset to install on this machine, and where the CLI sits inside it.
+ *
+ * Each craft publishes its CLI in a different wrapper per platform — a dedicated
+ * `-cli-` zip on macOS, but the full application archive on Windows and Linux.
+ * Everything below was measured against the real release assets:
+ *
+ *   macOS   <craft>-cli-<v>-macos-universal.zip        → <craft>-cli
+ *   Windows <craft>-<v>-windows-x64-portable.zip       → <craft>-cli.exe
+ *   Linux   <craft>-<v>-linux-x86_64.tar.gz            → bin/<craft>-cli
+ *
+ * The tables are data, not logic, so adding a craft or a platform is a one-line
+ * change and `scripts/install-craft.mjs --list` can print what would be fetched.
+ * @module @dsh-artcraft/craft-kit/platform
+ */
+
+import { arch as nodeArch, platform as nodePlatform } from 'node:process'
+
+/** A supported operating system, as Node names it. */
+                                                           
+
+/** CPU families the crafts publish builds for. */
+                                          
+
+/** One downloadable archive plus how to get the CLI out of it. */
+                                
+                                               
+                        
+                                                                                             
+                                                                        
+                                                             
+                                                          
+                                                        
+                                      
+ 
+
+/** Written version marker beside each installed binary. */
+export const VERSION_MARKER = '.version.json'
+
+/** Target for a craft `id` (product) on `platform`/`arch`, or `undefined` when unsupported. */
+export function releaseTarget(
+  id        ,
+  platform                   = nodePlatform                    ,
+  arch               = nodeArch                ,
+)                            {
+  if (platform === 'darwin') {
+    // One universal build covers Intel and Apple silicon.
+    return {
+      label: 'macOS (universal)',
+      asset: (craft, version) => `${craft}-cli-${version}-macos-universal.zip`,
+      // Release archives wrap everything in a versioned directory, so match on
+      // the final segment rather than the whole path.
+      match: (craft, path) => path === `${craft}-cli` || path.endsWith(`/${craft}-cli`),
+      container: 'zip',
+    }
+  }
+  if (platform === 'win32') {
+    if (arch !== 'x64' && arch !== 'arm64') return undefined
+    return {
+      label: `Windows ${arch} (portable)`,
+      asset: (craft, version) => `${craft}-${version}-windows-${arch}-portable.zip`,
+      match: (craft, path) => path.endsWith(`${craft}-cli.exe`),
+      container: 'zip',
+    }
+  }
+  if (platform === 'linux') {
+    if (arch !== 'x64' && arch !== 'arm64') return undefined
+    return {
+      label: `Linux ${arch} (tarball)`,
+      // riscv64 builds exist for some crafts but are not a Node platform here.
+      asset: (craft, version) => `${craft}-${version}-linux-${arch === 'x64' ? 'x86_64' : 'aarch64'}.tar.gz`,
+      match: (craft, path) => path === `bin/${craft}-cli` || path.endsWith(`/${craft}-cli`),
+      container: 'tar.gz',
+    }
+  }
+  return undefined
+}
+
+/** The executable name a craft's CLI has on this platform. */
+export function binaryName(craft        , platform                   = nodePlatform                    )         {
+  return platform === 'win32' ? `${craft}-cli.exe` : `${craft}-cli`
+}