dsh-artcraft-plugin-soundcraft 0.1.2 → 0.2.0

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "dsh-artcraft-plugin-soundcraft",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "private": false,
   "type": "module",
   "description": "DSH plugin: drive SoundCraft (audio production) headlessly through its own CLI and MCP server.",
   "license": "MIT OR Apache-2.0",
   "exports": {
-    ".": "./src/index.ts",
+    ".": "./src/index.js",
     "./package.json": "./package.json"
   },
   "peerDependencies": {
@@ -23,8 +23,7 @@
   },
   "files": [
     "src",
-    "cordis.patch.yml",
-    "README.md"
+    "cordis.patch.yml"
   ],
   "dsh": {
     "bundle": {

package/src/index.js

@@ -0,0 +1,38 @@
+/**
+ * SoundCraft as a DSH plugin.
+ *
+ * Registers model-callable tools that drive the `soundcraft-cli` binary this machine
+ * already has — both its generic `--cmd` surface and its own MCP server. The
+ * SoundCraft source tree is never touched: the CLI is an external process, located
+ * at call time so installing it mid-session works.
+ *
+ * The kernel under `./kit/` is generated from `dsh-plugins/craft-kit/src` by
+ * `scripts/build-kit.mjs` and inlined so this package installs standalone.
+ * @module dsh-artcraft-plugin-soundcraft
+ */
+
+import { defineTool } from '@deepseek-ai/dsh-tools'
+                                                  
+import { applyCraftPlugin, profileOf } from './kit/index.js'
+                                                       
+import { PLUGIN_ROOT } from './root.js'
+
+export const name = 'dsh-artcraft-soundcraft'
+export const inject = ['tools', 'systemPrompt']
+
+/** The craft this plugin exposes. */
+export const craft = profileOf('soundcraft')
+
+/** Configuration is the shared craft config. */
+                                      
+
+export function apply(ctx         , config         = {})       {
+  if (craft === undefined) throw new Error('dsh-artcraft-soundcraft: profile "soundcraft" is missing from the inlined kernel')
+  // `ctx.effect` ties the registration and the MCP server to this plugin's fiber.
+  ctx.effect(() => applyCraftPlugin(ctx, {
+    profile: craft,
+    packageRoot: PLUGIN_ROOT,
+    config,
+    defineTool: defineTool         ,
+  }))
+}

package/src/kit/catalog.js

@@ -92,9 +92,44 @@ export function parseCatalog(stdout        , json         )                 {
       // Fall through to the table parser: a CLI may ignore an unknown --json.
     }
   }
+  const emDash = parseEmDash(text)
+  if (emDash.length > 0) return emDash
   return parseTable(text)
 }
 
+/**
+ * Parse an `id — Label: {params}` catalogue (DeckCraft 0.14+).
+ *
+ * One command per line, single-spaced, with an em dash between the id and its
+ * label. `: {…}` introduces the parameter grammar and ` → …` describes what the
+ * command answers, which is not part of the grammar.
+ * @param text - raw `commands` output.
+ * @returns every command whose line has the `id — label` shape.
+ */
+export function parseEmDash(text        )                 {
+  const out                 = []
+  for (const raw of text.split('\n')) {
+    const line = raw.trimEnd()
+    if (line.length === 0 || line.startsWith('#')) continue
+    const match = /^([\w.-]+)\s+—\s+(.*)$/.exec(line)
+    if (match === null) continue
+    const id = match[1]
+    const rest = match[2]
+    const returnIndex = rest.indexOf(' → ')
+    const beforeReturn = returnIndex === -1 ? rest : rest.slice(0, returnIndex)
+    const brace = beforeReturn.indexOf(': {')
+    const label = brace === -1 ? beforeReturn.trim() : beforeReturn.slice(0, brace).trim()
+    const params = brace === -1 ? undefined : beforeReturn.slice(brace + 2).trim()
+    out.push({
+      id,
+      ...label.length > 0 ? { label } : {},
+      ...params !== undefined && params.length > 0 ? { params } : {},
+      group: groupOf(id),
+    })
+  }
+  return out
+}
+
 /**
  * Parse a craft's fixed-column `commands` table.
  *
@@ -111,7 +146,14 @@ export function parseTable(text        )                 {
   const flush = ()       => {
     if (current === undefined) return
     const { id, columns } = current
-    const rest = columns.join(' ').trim()
+    let rest = columns.join(' ').trim()
+    // Some tables end with the grammar as its own column (`{name?, color?}`),
+    // with no `params:` label; take the last column when it is only an object.
+    let columnParams
+    if (columns.length > 1 && /^\{.*\}$/.test(columns[columns.length - 1].trim())) {
+      columnParams = columns[columns.length - 1].trim()
+      rest = columns.slice(0, -1).join(' ').trim()
+    }
     const paramsMatch = /\bparams:\s*(\{.*)$/.exec(rest)
     const labelPart = paramsMatch === null ? rest : rest.slice(0, paramsMatch.index).trim()
     // Trailing `label  [Shortcut]` and an interleaved menu column.
@@ -120,7 +162,9 @@ export function parseTable(text        )                 {
     out.push({
       id,
       ...label.length > 0 ? { label } : {},
-      ...paramsMatch !== null ? { params: paramsMatch[1].replace(/\s+/g, ' ').trim() } : {},
+      ...columnParams !== undefined
+        ? { params: columnParams.replace(/\s+/g, ' ') }
+        : paramsMatch !== null ? { params: paramsMatch[1].replace(/\s+/g, ' ').trim() } : {},
       ...shortcutMatch !== null ? { shortcut: shortcutMatch[1] } : {},
       group: groupOf(id),
     })
@@ -136,7 +180,8 @@ export function parseTable(text        )                 {
     }
     flush()
     const columns = raw.trimEnd().split(/\s{2,}/).map(part => part.trim()).filter(part => part.length > 0)
-    const id = columns[0] ?? ''
+    // Rust CLIs mark undoable commands with a trailing `*`; it is not the id.
+    const id = (columns[0] ?? '').replace(/\*$/, '')
     if (id.length === 0 || /\s/.test(id) || !/^[\w.-]+$/.test(id)) continue
     current = { id, columns: columns.slice(1) }
   }

package/src/kit/discover.js

@@ -20,20 +20,36 @@ import { execFileSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
                                                            
 
-/** True when `path` is an executable regular file (or a symlink to one). */
+/**
+ * True when `path` is an executable regular file (or a symlink to one).
+ *
+ * `X_OK` is a no-op on Windows — it succeeds for any file that exists — so on
+ * that platform the name is additionally required to carry an executable
+ * extension (`PATHEXT`), which stops a stray text file called
+ * `gridcraft-cli` from being adopted as the binary.
+ */
 export function isExecutable(path        )          {
   try {
     if (!statSync(path).isFile()) return false
     accessSync(path, constants.X_OK)
+    if (process.platform === 'win32') {
+      const extensions = (process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD')
+        .split(';').map(extension => extension.trim().toLowerCase()).filter(extension => extension.length > 0)
+      const lower = path.toLowerCase()
+      return extensions.some(extension => lower.endsWith(extension))
+    }
     return true
   } catch {
     return false
   }
 }
 
-/** Every directory on `PATH`, in order. */
+/** Every directory on `PATH`, in order, with quoting removed. */
 function pathDirs()           {
-  return (process.env.PATH ?? '').split(delimiter).filter(entry => entry.length > 0)
+  return (process.env.PATH ?? '')
+    .split(delimiter)
+    .map(entry => entry.trim().replace(/^"(.*)"$/, '$1'))
+    .filter(entry => entry.length > 0)
 }
 
 /** Directory holding this kernel (`<workspace>/dsh-plugins/craft-kit/src`). */
@@ -111,16 +127,39 @@ export function candidates(profile              , configured         , packageRo
       const resolved = isAbsolute(dir) ? dir : resolve(base, dir)
       if (seen.has(resolved)) continue
       seen.add(resolved)
-      out.push({ path: join(resolved, profile.bin), source: `search-dir:${resolved}` })
+      // Windows installs the CLI as `<craft>-cli.exe`, so the platform's own
+      // name has to be tried before the bare one; otherwise a workspace
+      // `crafts-bin/` copy is never found there.
+      for (const name of candidateNames(profile)) {
+        out.push({ path: join(resolved, name), source: `search-dir:${resolved}` })
+      }
     }
   }
   for (const dir of pathDirs()) {
-    out.push({ path: join(dir, profile.bin), source: 'PATH' })
-    if (process.platform === 'win32') out.push({ path: join(dir, `${profile.bin}.exe`), source: 'PATH' })
+    for (const name of candidateNames(profile)) {
+      out.push({ path: join(dir, name), source: 'PATH' })
+    }
   }
   return out
 }
 
+/**
+ * Names a craft CLI may have on this platform, most likely first.
+ *
+ * Windows installs `<craft>-cli.exe`, so the extension is what a `PATH` or
+ * `crafts-bin/` lookup has to try; `PATHEXT` is honoured rather than assumed
+ * because a machine may have narrowed it. The bare name comes last, and only on
+ * Windows, for a CLI a user renamed themselves.
+ * @param profile - the craft being located.
+ * @returns candidate file names, deduplicated.
+ */
+function candidateNames(profile              )           {
+  if (process.platform !== 'win32') return [profile.bin]
+  const extensions = (process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD')
+    .split(';').map(extension => extension.trim().toLowerCase()).filter(extension => extension.length > 0)
+  return [...new Set([platformBinaryName(profile), ...extensions.map(extension => `${profile.bin}${extension}`), profile.bin])]
+}
+
 /** The CLI's executable name on this platform (`-cli.exe` on Windows). */
 export function platformBinaryName(profile              )         {
   return process.platform === 'win32' ? `${profile.bin}.exe` : profile.bin
@@ -178,6 +217,13 @@ export function craftVersion(path        , timeoutMs = 5000)
  */
 export function missingBinaryMessage(profile              , configured         , packageRoot         )         {
   const tried = candidates(profile, configured, packageRoot)
+  const executable = `${profile.bin}${process.platform === 'win32' ? '.exe' : ''}`
+  const example = process.platform === 'win32'
+    ? `C:\\path\\to\\${executable}`
+    : `/absolute/path/to/${executable}`
+  const setEnv = process.platform === 'win32'
+    ? `$env:${profile.envVar}="${example}"   (PowerShell;  set ${profile.envVar}=${example} in cmd.exe)`
+    : `export ${profile.envVar}=${example}`
   const lines = [
     `${profile.product}: '${profile.bin}' was not found, so the ${profile.id} tools cannot run.`,
     `Searched, in order:`,
@@ -186,9 +232,12 @@ export function missingBinaryMessage(profile              , configured         ,
   lines.push(
     `Fix it by any of:`,
     `  - run \`node scripts/install-craft.mjs ${profile.id}\` (macOS, Windows and Linux)`,
-    `  - set ${profile.envVar}=/absolute/path/to/${profile.bin}`,
+    `  - set ${setEnv}`,
     `  - download the CLI from https://github.com/storytold/${profile.id}/releases/latest and put it on PATH`,
-    `  - pass { "path": "/absolute/path/to/${profile.bin}" } in this plugin's config`,
+    `  - pass { "path": "${example.replace(/\\/g, '\\\\')}" } in this plugin's config`,
   )
+  if (process.platform === 'win32') {
+    lines.push(`The Windows build is the portable archive's \`${executable}\`; no Rust toolchain is needed.`)
+  }
   return lines.join('\n')
 }

package/src/kit/exec.js

@@ -7,10 +7,36 @@
  * @module @dsh-artcraft/craft-kit/exec
  */
 
-import { spawn } from 'node:child_process'
+import { spawn, spawnSync } from 'node:child_process'
+                                                      
 import { appendFileSync } from 'node:fs'
                                                                            
 
+/**
+ * Terminate a craft process and anything it started.
+ *
+ * Windows has no process groups and no signals, so `child.kill` reaches only
+ * the direct child: a craft engine that spawned helpers would leave them
+ * running. `taskkill /T` walks the child tree instead. Both steps are
+ * best-effort, because by the time this runs the process may already be gone.
+ * @param child - the process to terminate.
+ */
+export function killTree(child              )       {
+  if (child.exitCode !== null || child.signalCode !== null) return
+  try {
+    child.kill('SIGKILL')
+  } catch {
+    // Already exited.
+  }
+  // Re-check before taskkill: a recycled pid would otherwise be killed.
+  if (process.platform !== 'win32' || child.pid === undefined || child.exitCode !== null) return
+  try {
+    spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' })
+  } catch {
+    // taskkill is absent on some minimal images; the direct kill still ran.
+  }
+}
+
 /** Default cap on captured stdout+stderr, so a runaway export cannot flood the model. */
 export const MAX_CAPTURE_BYTES = 256 * 1024
 
@@ -63,6 +89,8 @@ export async function runCraft(options                 )
       cwd,
       stdio: ['ignore', 'pipe', 'pipe'],
       env: { ...process.env, NO_COLOR: '1', TERM: 'dumb' },
+      // Without this Windows flashes a console window for every craft run.
+      windowsHide: true,
     })
 
     const stdout           = []
@@ -89,10 +117,10 @@ export async function runCraft(options                 )
     let timedOut = false
     const timer = setTimeout(() => {
       timedOut = true
-      child.kill('SIGKILL')
+      killTree(child)
     }, timeoutMs)
 
-    const onAbort = ()       => { child.kill('SIGKILL') }
+    const onAbort = ()       => { killTree(child) }
     options.signal?.addEventListener('abort', onAbort, { once: true })
 
     const cleanup = ()       => {

package/src/kit/mcp.js

@@ -14,6 +14,7 @@
 
 import { spawn } from 'node:child_process'
                                                                         
+import { killTree } from './exec.js'
                                                            
 
 /** One tool as the MCP server declares it. */
@@ -81,6 +82,8 @@ export class CraftMcpClient {
     const child = spawn(this.#binary.path, [...(this.#profile.mcpArgs ?? ['mcp']), ...this.#args], {
       stdio: ['pipe', 'pipe', 'pipe'],
       env: { ...process.env, NO_COLOR: '1', TERM: 'dumb' },
+      // Keeps the long-lived server from flashing a console window on Windows.
+      windowsHide: true,
     })
     this.#child = child
     this.#buffer = ''
@@ -153,7 +156,9 @@ export class CraftMcpClient {
     if (this.#idleTimer !== undefined) clearTimeout(this.#idleTimer)
     const child = this.#child
     this.#child = undefined
-    if (child !== undefined && child.exitCode === null) child.kill('SIGKILL')
+    // `killTree` rather than `child.kill`: on Windows the craft server's own
+    // helper processes are not in a process group and would otherwise survive.
+    if (child !== undefined && child.exitCode === null) killTree(child)
   }
 
   /** Buffer stdout and resolve one response per complete line. */

package/src/kit/profiles.mjs

@@ -359,6 +359,63 @@ export const CRAFT_PROFILES = [
     catalogArgs: ['commands'],
     mcpArgs: ['mcp'],
   },
+  {
+    id: 'figcraft',
+    product: 'FigCraft',
+    bin: 'figcraft-cli',
+    envVar: 'FIGCRAFT_CLI',
+    searchDirs: [CRAFTS_BIN_DIR],
+    extensions: ['.figcraft', '.penpot', '.fig', '.sketch', '.svg'],
+    blurb: 'Interface design and prototyping (Figma-style): frames, components, auto layout, variables, prototyping and code export.',
+    run: {
+      verb: 'run',
+      inputMode: 'flag',
+      inFlag: '--in',
+      sampleFlag: '',
+      cmdFlag: '',
+      cmdSeparator: ' ',
+      // `run script.json` takes a generated script, one step per command.
+      scriptFile: { encoding: 'json-array', commandKey: 'command', paramsKey: 'params', inputFlag: '--in', saveFlag: '--out' },
+      saveFlag: '--out',
+    },
+    reads: [
+      { name: 'inspect', verb: 'info', summary: 'Summarize a design file: pages, node counts, top-level frames, style and variable counts.' },
+      { name: 'convert', verb: 'convert', summary: 'Convert a design file between .figcraft, .json, .svg, .png, .pdf and more.' },
+    ],
+    catalogJson: true,
+    catalogArgs: ['commands', '--json'],
+    mcpArgs: ['mcp'],
+  },
+  {
+    id: 'texturecraft',
+    product: 'TextureCraft',
+    bin: 'texturecraft-cli',
+    envVar: 'TEXTURECRAFT_CLI',
+    searchDirs: [CRAFTS_BIN_DIR],
+    extensions: ['.tcraft'],
+    blurb: '3D texture painting: texture sets and layers over a mesh, baking, material channels and PBR export.',
+    run: {
+      verb: 'batch',
+      inputMode: 'flag',
+      inFlag: '',
+      sampleFlag: '',
+      cmdFlag: '',
+      cmdSeparator: ' ',
+      // `batch script.json` carries `{ open, steps, save }` in one file.
+      scriptFile: { encoding: 'json-array', commandKey: 'id', paramsKey: 'params', batch: { openKey: 'open', stepsKey: 'steps', saveKey: 'save' } },
+      saveMode: 'script',
+      saveFlag: '',
+      // A project is required before any command, so a bare run makes one.
+      sampleCreate: { verb: 'new', args: ['builtin:crate'], extension: '.tcraft' },
+    },
+    reads: [
+      { name: 'inspect', verb: 'info', summary: 'Summarize a texture project: texture sets, layers, triangles, materials and the UV report.' },
+      { name: 'convert', verb: 'export', summary: 'Export textures from a project: presets, formats, padding and size.' },
+    ],
+    catalogJson: false,
+    catalogArgs: ['commands'],
+    mcpArgs: ['mcp'],
+  },
 ]
 
 /** Profile lookup by craft id. */

package/src/kit/tools.js

@@ -39,6 +39,9 @@ function resolveSample(profile              , args                         )
   const requested = args.sample
   if (typeof requested === 'string' && requested.length > 0) return requested
   if (requested === true) {
+    // A craft that starts a new document by default, or creates one itself,
+    // has nothing to select; asking for the sample is a harmless no-op.
+    if (profile.run.sampleFlag.length === 0 && (profile.run.sampleCreate !== undefined || profile.run.scriptFile !== undefined)) return undefined
     if (profile.run.sampleFlag.length === 0) {
       throw new Error(
         `${profile.product} has no "new document" flag: pass \`input\` to open an existing document, `
@@ -361,7 +364,7 @@ export function createToolSet(runtime              )               {
         description: 'Ordered commands to apply. Each is { "id": "cell.set", "json": { "cell": "A1", "input": "x" } }. An entry may also be a raw CLI string.',
         items: { type: 'json' },
       },
-      ...(profile.run.saveMode ?? 'flag') === 'flag'
+      ...(profile.run.saveMode ?? 'flag') !== 'none'
         ? { save: { type: 'string', description: `Path to write the edited document to (${profile.extensions.join('/')}).` } }
         : {},
       // `export` is always advertised when the craft can render one. Where the
@@ -410,6 +413,48 @@ export function createToolSet(runtime              )               {
       // Crafts whose headless entry point only accepts a script file get one
       // written for this call; the file names the same commands the inline
       // style would have carried.
+      // Crafts whose headless verb takes a generated script file instead of
+      // inline command flags: FigCraft's `run script.json` and TextureCraft's
+      // `batch script.json`. The kernel writes it, so the model still supplies
+      // an ordered list and never has to know the file format.
+      if (profile.run.scriptFile !== undefined) {
+        const spec = profile.run.scriptFile
+        const savePath = typeof args.save === 'string' ? args.save : undefined
+        let effectiveInput = input
+        if (effectiveInput === undefined && profile.run.sampleCreate !== undefined) {
+          const created = join(craftWorkDir(profile), `sample-${Date.now()}${profile.run.sampleCreate.extension}`)
+          mkdirSync(dirname(created), { recursive: true })
+          const createdResult = await runCraft({
+            profile, binary,
+            argv: [profile.run.sampleCreate.verb, ...profile.run.sampleCreate.args, created],
+            cwd: process.cwd(), timeoutMs,
+          })
+          if (!createdResult.ok) return renderRun(createdResult, profile)
+          effectiveInput = created
+        }
+        const steps = commands.map(command => ({ [spec.commandKey]: command.id, [spec.paramsKey]: command.json ?? {} }))
+        const scriptPath = join(craftWorkDir(profile), `run-${Date.now()}.${spec.encoding === 'jsonl' ? 'jsonl' : 'json'}`)
+        mkdirSync(dirname(scriptPath), { recursive: true })
+        const argv = [profile.run.verb]
+        let body
+        if (spec.batch !== undefined) {
+          body = {
+            ...effectiveInput !== undefined ? { [spec.batch.openKey]: effectiveInput } : {},
+            [spec.batch.stepsKey]: steps,
+            ...savePath !== undefined ? { [spec.batch.saveKey]: savePath } : {},
+          }
+          argv.push(scriptPath)
+        } else {
+          body = spec.encoding === 'jsonl' ? steps.map(step => JSON.stringify(step)).join('\n') + '\n' : steps
+          argv.push(scriptPath)
+          if (effectiveInput !== undefined && spec.inputFlag !== undefined) argv.push(spec.inputFlag, effectiveInput)
+          if (savePath !== undefined && spec.saveFlag !== undefined) argv.push(spec.saveFlag, savePath)
+        }
+        writeFileSync(scriptPath, typeof body === 'string' ? body : JSON.stringify(body, null, 2) + '\n')
+        const extra = Array.isArray(args.extraArgs) ? args.extraArgs.filter((a)              => typeof a === 'string') : []
+        const scriptResult = await runCraft({ profile, binary, argv: [...argv, ...extra], cwd: process.cwd(), timeoutMs })
+        return renderRun(scriptResult, profile)
+      }
       if (profile.run.scriptFlag !== undefined) {
         const scriptPath = join(craftWorkDir(profile), `steps-${Date.now()}.json`)
         mkdirSync(dirname(scriptPath), { recursive: true })

package/src/kit/types.js

@@ -69,7 +69,7 @@
                                                                                  
                                                                            
      
-                                     
+                                                
                                                    
                            
                                                                       

package/src/root.js

@@ -0,0 +1,13 @@
+/**
+ * Resolve this plugin package's root directory at runtime.
+ *
+ * Kept in its own module so every craft plugin can share the same two lines
+ * while the kernel stays free of `import.meta` path arithmetic.
+ * @module @dsh-artcraft/plugin-soundcraft/root
+ */
+
+import { dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** Absolute path of this plugin package (`<root>/src/root.ts` → `<root>`). */
+export const PLUGIN_ROOT = dirname(dirname(fileURLToPath(import.meta.url)))