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

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# Installed by `dsh plugin add dsh-artcraft-plugin-vectorcraft`.
+# One row: the plugin package that provides the VectorCraft tools.
+- insert:
+    - id: artcraft-vectorcraft
+      name: "dsh-artcraft-plugin-vectorcraft"

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "dsh-artcraft-plugin-vectorcraft",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "DSH plugin: drive VectorCraft (vector art) headlessly through its own CLI and MCP server.",
+  "license": "MIT OR Apache-2.0",
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "*",
+    "@deepseek-ai/dsh-tools": "*"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    }
+  },
+  "files": [
+    "src",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "keywords": [
+    "dsh-plugin",
+    "dsh",
+    "deepseek-harness",
+    "cordis",
+    "artcraft",
+    "vectorcraft",
+    "ai-agent",
+    "mcp"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,38 @@
+/**
+ * VectorCraft as a DSH plugin.
+ *
+ * Registers model-callable tools that drive the `vectorcraft-cli` binary this machine
+ * already has — both its generic `--cmd` surface and its own MCP server. The
+ * VectorCraft 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-vectorcraft
+ */
+
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { Context } from '@deepseek-ai/cordis'
+import { applyCraftPlugin, profileOf } from './kit/index.js'
+import type { CraftPluginConfig } from './kit/index.js'
+import { PLUGIN_ROOT } from './root.ts'
+
+export const name = 'dsh-artcraft-vectorcraft'
+export const inject = ['tools', 'systemPrompt']
+
+/** The craft this plugin exposes. */
+export const craft = profileOf('vectorcraft')
+
+/** Configuration is the shared craft config. */
+export type Config = CraftPluginConfig
+
+export function apply(ctx: Context, config: Config = {}): void {
+  if (craft === undefined) throw new Error('dsh-artcraft-vectorcraft: profile "vectorcraft" 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 as never,
+  }))
+}

package/src/kit/catalog.js

@@ -0,0 +1,230 @@
+/**
+ * Load and normalize a craft's command catalog.
+ *
+ * Every craft ships `commands`; some print JSON, some a fixed-width table.
+ * Plugins use the catalog to tell the model which verbs exist, and the
+ * snapshot files generated by `scripts/gen-catalogs.mjs` let a plugin answer
+ * from disk when the binary is not installed yet.
+ * @module @dsh-artcraft/craft-kit/catalog
+ */
+
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { CATALOG_CAPTURE_BYTES, runCraft } from './exec.js'
+                                                                         
+
+/** Directory holding this module's compiled/`src` file. */
+const here = dirname(fileURLToPath(import.meta.url))
+
+/** Where `scripts/gen-catalogs.mjs` writes snapshots, relative to a plugin package. */
+export const CATALOG_DIR = 'catalog'
+
+/** Infer the command family from its dotted id: `insert.chart` → `insert`. */
+export function groupOf(id        )         {
+  const dot = id.indexOf('.')
+  return dot === -1 ? '(root)' : id.slice(0, dot)
+}
+
+/**
+ * Normalize one raw catalog entry from any craft's JSON.
+ *
+ * Most crafts use `{ id, label, params, menu, shortcut }`; PdfCraft's `tools`
+ * output instead uses `{ command, description, input_schema }`, so both shapes
+ * are folded into the same record.
+ */
+function normalize(raw                         )                           {
+  // `name` wins over `command`: PdfCraft's tool list carries the runnable tool
+  // name in `name` and a UI-level command id in `command`, and only `name` works
+  // with `pdfcraft-cli run`.
+  const id = typeof raw.id === 'string' && raw.id.length > 0
+    ? raw.id
+    : typeof raw.name === 'string' && raw.name.length > 0
+      ? raw.name
+      : typeof raw.command === 'string' && raw.command.length > 0 ? raw.command : undefined
+  if (id === undefined) return undefined
+  const menu = Array.isArray(raw.menu) ? raw.menu.filter((m)              => typeof m === 'string') : undefined
+  // PdfCraft describes parameters as a JSON Schema; render it back to a grammar
+  // string so every craft's catalog reads the same way in the tool output.
+  const schema = typeof raw.input_schema === 'object' && raw.input_schema !== null
+    ? raw.input_schema                                                                                                 
+    : undefined
+  const params = typeof raw.params === 'string'
+    ? raw.params
+    : schema?.properties !== undefined
+      ? Object.entries(schema.properties)
+        .map(([key, node]) => `${key}${schema.required?.includes(key) === true ? '' : '?'}: ${node.type ?? 'value'}${node.description !== undefined ? ` (${node.description})` : ''}`)
+        .join(', ')
+      : undefined
+  return {
+    id,
+    ...typeof raw.label === 'string' ? { label: raw.label } : {},
+    ...params !== undefined && params.length > 0 ? { params } : {},
+    ...menu !== undefined ? { menu } : {},
+    ...typeof raw.shortcut === 'string' || raw.shortcut === null ? { shortcut: raw.shortcut                  } : {},
+    ...Array.isArray(raw.aliases) ? { aliases: raw.aliases.filter((a)              => typeof a === 'string') } : {},
+    ...typeof raw.interactive === 'boolean' ? { interactive: raw.interactive } : {},
+    ...typeof raw.enabled === 'boolean' ? { enabled: raw.enabled } : {},
+    ...typeof raw.description === 'string' ? { description: raw.description } : {},
+    group: groupOf(id),
+  }
+}
+
+/**
+ * Parse a craft's `commands` output.
+ * @param stdout - raw stdout of the `commands` subcommand.
+ * @param json - whether the CLI was asked for JSON.
+ * @returns every command the output described.
+ */
+export function parseCatalog(stdout        , json         )                 {
+  const text = stdout.trim()
+  if (text.length === 0) return []
+  if (json || text.startsWith('[')) {
+    try {
+      const parsed          = JSON.parse(text)
+      if (Array.isArray(parsed)) {
+        return parsed
+          .filter((entry)                                   => typeof entry === 'object' && entry !== null)
+          .map(normalize)
+          .filter((entry)                        => entry !== undefined)
+      }
+    } catch {
+      // Fall through to the table parser: a CLI may ignore an unknown --json.
+    }
+  }
+  return parseTable(text)
+}
+
+/**
+ * Parse a craft's fixed-column `commands` table.
+ *
+ * Every table puts the id in the first column and keeps later columns
+ * aligned, so a split on 2+ spaces is reliable; parameter grammars and long
+ * labels wrap onto continuation lines that stay indented, and those are folded
+ * back into the entry they belong to.
+ * @param text - raw table output.
+ * @returns every command the table described.
+ */
+export function parseTable(text        )                 {
+  const out                 = []
+  let current                                               
+  const flush = ()       => {
+    if (current === undefined) return
+    const { id, columns } = current
+    const rest = columns.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.
+    const shortcutMatch = /\[([^\]]+)\]\s*$/.exec(labelPart)
+    const label = (shortcutMatch === null ? labelPart : labelPart.slice(0, shortcutMatch.index)).trim()
+    out.push({
+      id,
+      ...label.length > 0 ? { label } : {},
+      ...paramsMatch !== null ? { params: paramsMatch[1].replace(/\s+/g, ' ').trim() } : {},
+      ...shortcutMatch !== null ? { shortcut: shortcutMatch[1] } : {},
+      group: groupOf(id),
+    })
+    current = undefined
+  }
+  for (const raw of text.split('\n')) {
+    if (raw.trim().length === 0) continue
+    if (/^\s/.test(raw)) {
+      // Continuation: a wrapped label/params line belongs to the open entry,
+      // unless it begins a fresh block (params: on its own column).
+      if (current !== undefined) current.columns.push(raw.trim())
+      continue
+    }
+    flush()
+    const columns = raw.trimEnd().split(/\s{2,}/).map(part => part.trim()).filter(part => part.length > 0)
+    const id = columns[0] ?? ''
+    if (id.length === 0 || /\s/.test(id) || !/^[\w.-]+$/.test(id)) continue
+    current = { id, columns: columns.slice(1) }
+  }
+  flush()
+  return out
+}
+
+/** Read a bundled catalog snapshot shipped beside a plugin package. */
+export function readSnapshot(packageRoot        , craftId        )                             {
+  try {
+    const raw = readFileSync(join(packageRoot, CATALOG_DIR, `${craftId}.json`), 'utf8')
+    const parsed          = JSON.parse(raw)
+    if (!Array.isArray(parsed)) return undefined
+    return parsed
+      .filter((entry)                                   => typeof entry === 'object' && entry !== null)
+      .map(normalize)
+      .filter((entry)                        => entry !== undefined)
+  } catch {
+    return undefined
+  }
+}
+
+/** Catalog source and its commands. */
+                                
+                                            
+                                                                                                       
+                                                
+                                              
+                        
+ 
+
+/**
+ * Load a craft's catalog, preferring the installed binary.
+ * @param profile - the craft profile.
+ * @param binary - resolved binary, or `undefined` to use the snapshot.
+ * @param packageRoot - plugin package root holding `catalog/`.
+ * @param timeoutMs - budget for the live read.
+ * @returns catalog commands plus where they came from.
+ */
+export async function loadCatalog(
+  profile              ,
+  binary                         ,
+  packageRoot        ,
+  timeoutMs = 30_000,
+)                         {
+  if (binary !== undefined) {
+    const argv = [...profile.catalogArgs ?? ['commands', ...profile.catalogJson ? ['--json'] : []]]
+    const result = await runCraft({
+      profile, binary, argv, cwd: process.cwd(), timeoutMs, maxCaptureBytes: CATALOG_CAPTURE_BYTES,
+    })
+    const parsed = parseCatalog(result.stdout, profile.catalogJson)
+    if (parsed.length > 0) return { commands: parsed, origin: 'live' }
+    const detail = (result.stderr || result.stdout).trim().slice(0, 300)
+    const snapshot = readSnapshot(packageRoot, profile.id)
+    return snapshot !== undefined
+      ? { commands: snapshot, origin: 'snapshot', note: `live catalog read failed: ${detail}` }
+      : { commands: [], origin: 'empty', note: `live catalog read returned no commands: ${detail}` }
+  }
+  const snapshot = readSnapshot(packageRoot, profile.id)
+  return snapshot !== undefined
+    ? { commands: snapshot, origin: 'snapshot' }
+    : { commands: [], origin: 'empty', note: `${profile.bin} is not installed and no catalog snapshot was bundled` }
+}
+
+/** All distinct command families in a catalog, in first-seen order. */
+export function groupsOf(commands                         )           {
+  const seen           = []
+  for (const command of commands) {
+    const group = command.group ?? groupOf(command.id)
+    if (!seen.includes(group)) seen.push(group)
+  }
+  return seen
+}
+
+/**
+ * Score a command against a free-text query, for search and ranking.
+ * @param command - catalog entry.
+ * @param needle - lowercased query.
+ * @returns 0 when unrelated, higher when more relevant.
+ */
+export function score(command              , needle        )         {
+  const id = command.id.toLowerCase()
+  const label = (command.label ?? '').toLowerCase()
+  const params = (command.params ?? '').toLowerCase()
+  if (id === needle) return 100
+  if (id.startsWith(needle)) return 60
+  if (id.includes(needle)) return 40
+  if (label.includes(needle)) return 25
+  if (params.includes(needle)) return 5
+  return 0
+}

package/src/kit/discover.js

@@ -0,0 +1,194 @@
+/**
+ * Locate a craft CLI on this machine.
+ *
+ * Search order is explicit and reported, because "the tool exists but the
+ * binary was not found" is the single most likely failure a user hits:
+ *   1. an explicit path written into `catalog/binaries.json` at install time,
+ *   2. an explicit path in the plugin config,
+ *   3. the craft's own environment variable (`GRIDCRAFT_CLI`, …),
+ *   4. the documented search directories, resolved against the plugin package,
+ *      the session cwd and this kernel (so the workspace `crafts-bin/` is found
+ *      from wherever the plugin is loaded),
+ *   5. `PATH`.
+ * @module @dsh-artcraft/craft-kit/discover
+ */
+
+import { accessSync, constants, readFileSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { delimiter, dirname, isAbsolute, join, resolve } from 'node:path'
+import { execFileSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+                                                           
+
+/** True when `path` is an executable regular file (or a symlink to one). */
+export function isExecutable(path        )          {
+  try {
+    if (!statSync(path).isFile()) return false
+    accessSync(path, constants.X_OK)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** Every directory on `PATH`, in order. */
+function pathDirs()           {
+  return (process.env.PATH ?? '').split(delimiter).filter(entry => entry.length > 0)
+}
+
+/** Directory holding this kernel (`<workspace>/dsh-plugins/craft-kit/src`). */
+const kernelDir = dirname(fileURLToPath(import.meta.url))
+
+/**
+ * Where `scripts/install-craft.mjs` puts downloaded CLIs.
+ *
+ * This is the location that works for an installed plugin: the package may sit
+ * in a profile's `node_modules` with no workspace around it, so the binary is
+ * cached under the harness home instead. `DSH_ARTCRAFT_BIN_DIR` overrides it.
+ */
+function cacheDirs()           {
+  const explicit = process.env.DSH_ARTCRAFT_BIN_DIR
+  if (explicit !== undefined && explicit.length > 0) return [explicit]
+  const roots = [process.env.DSH_HOME, join(homedir(), '.dsh'), join(homedir(), '.dsh-artcraft')]
+    .filter((root)                 => typeof root === 'string' && root.length > 0)
+  return [...new Set(roots.map(root => join(root, 'crafts', 'bin')))]
+}
+
+/**
+ * Bases a relative search directory is resolved against.
+ *
+ * The plugin package root comes first: `<workspace>/dsh-plugins/plugin-x` and
+ * `<workspace>/crafts-bin` are siblings, so `../crafts-bin` finds the
+ * workspace's installed binaries no matter which directory the agent runs in.
+ * @param packageRoot - the calling plugin's package root, when it has one.
+ * @returns absolute bases, most specific first.
+ */
+function searchBases(packageRoot         )           {
+  const bases = [
+    ...packageRoot !== undefined ? [packageRoot, dirname(packageRoot)] : [],
+    process.cwd(),
+    // `<workspace>/dsh-plugins/craft-kit/src` → up three levels is the workspace.
+    resolve(kernelDir, '..', '..', '..'),
+    dirname(kernelDir),
+  ]
+  return [...new Set(bases)]
+}
+
+/** Absolute path recorded by `scripts/link-into-profile.mjs`, when present. */
+function recordedBinary(profile              )                                               {
+  for (const base of searchBases()) {
+    const file = join(base, 'craft-kit', 'catalog', 'binaries.json')
+    try {
+      const parsed          = JSON.parse(readFileSync(file, 'utf8'))
+      if (typeof parsed !== 'object' || parsed === null) continue
+      const entry = (parsed                           )[profile.id]
+      if (typeof entry === 'string' && entry.length > 0) return { path: entry, source: 'craft-kit/catalog/binaries.json' }
+    } catch {
+      // No record at this base; keep looking.
+    }
+  }
+  return undefined
+}
+
+/**
+ * Candidate absolute paths for one craft binary, in priority order, with provenance.
+ * @param profile - the craft to locate.
+ * @param configured - explicit path from plugin configuration, if any.
+ * @param packageRoot - the calling plugin's package root, when it has one.
+ * @returns candidates in the order they will be tested.
+ */
+export function candidates(profile              , configured         , packageRoot         )                                     {
+  const out                                     = []
+  if (configured !== undefined && configured.length > 0) out.push({ path: configured, source: 'config.path' })
+  const fromEnv = process.env[profile.envVar]
+  if (fromEnv !== undefined && fromEnv.length > 0) out.push({ path: fromEnv, source: `env:${profile.envVar}` })
+  for (const dir of cacheDirs()) out.push({ path: join(dir, platformBinaryName(profile)), source: `cache:${dir}` })
+  const recorded = recordedBinary(profile)
+  if (recorded !== undefined) out.push(recorded)
+  const seen = new Set        ()
+  for (const base of searchBases(packageRoot)) {
+    for (const dir of profile.searchDirs) {
+      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}` })
+    }
+  }
+  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' })
+  }
+  return out
+}
+
+/** 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
+}
+
+/**
+ * Resolve the craft CLI for `profile`.
+ * @param profile - the craft to locate.
+ * @param configured - explicit path from plugin configuration, if any.
+ * @param packageRoot - the calling plugin's package root, when it has one.
+ * @returns the first executable candidate and its provenance, or `undefined`.
+ */
+export function discoverCraft(profile              , configured         , packageRoot         )                          {
+  for (const candidate of candidates(profile, configured, packageRoot)) {
+    if (isExecutable(candidate.path)) return { path: candidate.path, source: candidate.source }
+  }
+  return undefined
+}
+
+/** Cached `--version` output per resolved path; only successes are stored. */
+const versionCache = new Map                ()
+
+/**
+ * Read a craft binary's version, tolerating CLIs that spell the flag
+ * differently (`--version` and `version` are both in use).
+ * @param path - absolute path to the CLI.
+ * @param timeoutMs - hard cap on the probe; a slow binary yields `undefined`.
+ * @returns the first non-empty line of version output, or `undefined`.
+ */
+export function craftVersion(path        , timeoutMs = 5000)                     {
+  if (versionCache.has(path)) return versionCache.get(path)
+  let version                    
+  for (const flag of ['--version', 'version']) {
+    try {
+      const out = execFileSync(path, [flag], { encoding: 'utf8', timeout: timeoutMs, stdio: ['ignore', 'pipe', 'pipe'] })
+      const line = out.split('\n').map(part => part.trim()).find(part => part.length > 0)
+      if (line !== undefined) { version = line; break }
+    } catch {
+      // Try the next spelling; a missing flag is expected on some crafts.
+    }
+  }
+  // Only a successful probe is cached. A binary that is mid-install, or that
+  // had not been written when the previous call ran, must be retried rather
+  // than remembered as version-less for the rest of the session.
+  if (version !== undefined) versionCache.set(path, version)
+  return version
+}
+
+/**
+ * A ready-to-print diagnostic for a craft binary that could not be found.
+ * @param profile - the craft that was searched for.
+ * @param configured - explicit path from plugin configuration, if any.
+ * @param packageRoot - the calling plugin's package root, when it has one.
+ * @returns multi-line guidance naming every searched location.
+ */
+export function missingBinaryMessage(profile              , configured         , packageRoot         )         {
+  const tried = candidates(profile, configured, packageRoot)
+  const lines = [
+    `${profile.product}: '${profile.bin}' was not found, so the ${profile.id} tools cannot run.`,
+    `Searched, in order:`,
+    ...tried.slice(0, 10).map(entry => `  - ${entry.path}  (${entry.source})`),
+  ]
+  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}`,
+    `  - 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`,
+  )
+  return lines.join('\n')
+}