Liking cljdoc? Tell your friends :D

hive-artcraft

hive · artcraft: eight Crafting Apps under one verb, drawn live in VectorCraft through artcraft

One hive addon, hive.artcraft, with one verb, artcraft, for every ArtCraft "Crafting App" (PhotoCraft, VectorCraft, LightCraft, DesignCraft, FilmCraft, EffectCraft, PdfCraft, ArtCraft Studio, DeckCraft, GridCraft, AniCraft, CADCraft, FigCraft, WordCraft, SoundCraft, MaterialCraft, TextureCraft). Each app is a module: a piece of data in a registry list. The app argument is an enum built from the apps that mounted.

The image above is not a mock-up. It was drawn in a running VectorCraft, entirely through artcraft call (file.new, shape.polygon, text.create, paint.setFill), and exported with artcraft control app.export.

Showcase: driving a live app

Start the app with its control channel, hot-inject the addon, and drive it from any MCP client that is already connected:

vectorcraft --control 7990                       # a real GUI window
hot inject  path=<checkout>/hive-artcraft        # no hive-mcp restart

code command="artcraft call"    app=vectorcraft engine_command=file.new        params={"name":"artcraft-e2e","width":400,"height":300}
code command="artcraft call"    app=vectorcraft engine_command=shape.rectangle params={"x":40,"y":40,"width":180,"height":120,"radius":16}
code command="artcraft call"    app=vectorcraft engine_command=paint.setFill   params={"color":"#e8553e","ids":[2]}
code command="artcraft call"    app=vectorcraft engine_command=shape.ellipse   params={"x":200,"y":110,"width":150,"height":150}
code command="artcraft control" app=vectorcraft method=ui.screenshot
code command="artcraft control" app=vectorcraft method=app.export params={"path":"…/artcraft-e2e.png","format":"png"}
the window, driven over artcraftthe exported PNG
VectorCraft window with the shapes drawn through artcraftthe 400×300 export

How it plugs into hive

client to hive-mcp code tool to hive.artcraft to the three transport shapes

artcraft is not a top-level MCP tool. initialize! contributes it as a subdomain of the host code tool through hive-addon.registry.commands/contribute!, and shutdown! retracts it. hive-mcp re-reads that registry on every call, so a client that connected before the addon was injected can still call code command="artcraft <verb>". A new top-level tool would stay invisible to that client until it reconnected. The addon is meant to be hot-injected when a creative app is in use, not loaded at hive-mcp startup.

This release mounts photocraft and vectorcraft. It depends on the published io.github.hive-agi/hive-photocraft and io.github.hive-agi/hive-vectorcraft (0.1.4) and forwards calls to their own tool handlers. Their code is not copied.

lightcraft (port 7980, LIGHTCRAFT_CONTROL_PORT) and designcraft (port 7981, DESIGNCRAFT_CONTROL_PORT) are :native :port modules. hive-artcraft serves them from resources/hive_artcraft/catalogs/<app>.edn. dev/extract_<app>.clj derives each catalog from a reference clone: clojure -M:dev -m extract-lightcraft [root]. pdfcraft (:control-file, catalog from clojure -M:dev -m extract-pdfcraft [root]) and studio, ArtCraft itself (:none, catalog-only, from clojure -M:dev -m extract-studio [root]) are native too. It uses the shared parser in dev/artcraft_extract.clj, which is ported from hive-vectorcraft and also reads DesignCraft's noundo arm. :reference-revision is the clone's HEAD sha.

Nine more storytold apps are native modules too. Each has its own dev/extract_<app>.clj. Apps whose sources declare commands differently share a variant parser: dev/cad_fig_word_extract.clj (CommandSpec::new builders, spec!, heading-style method docs) and dev/sound_material_texture_extract.clj (CLI-served MCP tools, a char-literal-safe scanner). Commands a wrapper macro hides from static reading are counted under :unexpanded, not dropped.

apptransportport (env)engine / MCP / controlcontrol auth
deckcraft:port7983 (DECKCRAFT_CONTROL_PORT)329 / 25 / 26none
gridcraft:port7985 (GRIDCRAFT_CONTROL_PORT)386 / 22 / 34first-line auth handshake (not sent yet)
anicraft:nonenone360 / 5 / 0no external control surface; MCP via anicraft-cli mcp
cadcraft:port7982 (CADCRAFT_CONTROL_PORT)439 / 15 / 26 (+18 unexpanded)top-level "token", :token-ref env CADCRAFT_CONTROL_TOKEN
figcraft:port7984 (FIGCRAFT_CONTROL_PORT)649 / 19 / 18none
wordcraft:port7986 (WORDCRAFT_CONTROL_PORT)674 / 18 / 19per-window "key" (not sent yet)
soundcraft:port7987 (SOUNDCRAFT_CONTROL_PORT)388 / 17 / 17 (+95 unexpanded)none
materialcraft:port7988 (MATERIALCRAFT_CONTROL_PORT)121 / 20 / 12first-line auth handshake (not sent yet)
texturecraft:port7989 (TEXTURECRAFT_CONTROL_PORT)178 / 22 / 15first-line auth handshake (not sent yet)

Catalog, doctor and the refusal paths work for all of them today. Live calls to gridcraft, wordcraft, materialcraft and texturecraft are refused by the app until a handshake transport lands.

Using it

Every call goes through the host code tool:

{"command":"artcraft apps"}
{"command":"artcraft catalog","app":"vectorcraft"}
{"command":"artcraft catalog","app":"vectorcraft","query":"control"}
{"command":"artcraft doctor","app":"vectorcraft"}
{"command":"artcraft call","app":"vectorcraft","engine_command":"shape.rectangle","params":{"x":0,"y":0,"width":10,"height":10}}
{"command":"artcraft control","app":"photocraft","method":"ui.inspect"}
argmeaning
appmounted app id (command="artcraft apps" lists them)
commandartcraft apps | artcraft catalog | artcraft doctor | artcraft call | artcraft control
querycatalog section (engine, mcp, control) or one exact command id
engine_command, method, params, idpassed through to the app

params may also arrive as JSON text. A client that still holds the code schema from before artcraft was contributed sends it that way, and it is decoded when it parses to a JSON object.

artcraft catalog app=vectorcraft returns exactly what hive-vectorcraft's own vectorcraft tool returns (793 engine commands, 33 MCP tools, 28 control methods at revision 0f8040e). A test checks this.

Configuration

;; hive-mcp config.edn
:addons {"hive.artcraft" {:apps {"vectorcraft" {:control-port 7979}
                                 "photocraft"  {:control-port 7878
                                                :token-ref {:scheme :env :name "PHOTOCRAFT_CONTROL_TOKEN"}}}}}

Each app's control port is chosen in this order:

  1. :apps {"<app>" {:control-port N}}
  2. the <APP>_CONTROL_PORT environment variable
  3. the module's default

The default ports are 7878 (photocraft), 7979 (vectorcraft), 7980 (lightcraft), 7981 (designcraft), 7982 (cadcraft), 7983 (deckcraft), 7984 (figcraft), 7985 (gridcraft), 7986 (wordcraft), 7987 (soundcraft), 7988 (materialcraft), 7989 (texturecraft), 9876 (filmcraft) and 9877 (effectcraft). They never collide. FigCraft's and WordCraft's own docs use 7979 and 7981, which belong to VectorCraft and DesignCraft here.

PhotoCraft authenticates its control channel, so it only gets a port when a :token-ref is also configured. Without one, its calls refuse with the fix instead of failing on the socket. Keep every control port on loopback.

FilmCraft: control token

FilmCraft's --control port only listens when FILMCRAFT_CONTROL_TOKEN (64 hex characters) is set, and every request must carry that value as a top-level "token". Otherwise the app replies with an auth error and closes the connection. Launch it with a fresh token:

export FILMCRAFT_CONTROL_TOKEN="$(python3 -c 'import secrets;print(secrets.token_hex(32))')"
filmcraft --control 9876

The filmcraft module defaults to :token-ref {:scheme :env :name "FILMCRAFT_CONTROL_TOKEN"}, so a hive JVM started from a shell holding the same export needs no config. Otherwise, keep the token in a file only you can read (regular file, mode 600, not a symlink) and point hive at it:

:addons {"hive.artcraft" {:apps {"filmcraft" {:control-port 9876
                                              :token-ref {:scheme :file :path "/home/me/.private/filmcraft-control.token"}}}}}

The token is read on every request, so a token exported or rotated later is picked up without a restart. It is never logged, returned or put in an error, and any echo of it in a reply is replaced by <redacted>. artcraft doctor app=filmcraft reports :token {:status ...}; when no token resolves, it shows the fix. Apps without a :token-ref are sent the request exactly as before.

Adding a Crafting App

An app is one module map appended to resources/hive_artcraft/apps.edn. A :native app also needs one catalog resource. Neither the shared code nor the tool schema changes: the app enum, apps, doctor and the routing all come from the registry. Every classpath copy of hive_artcraft/apps.edn is concatenated, so another jar can contribute apps as well.

The contract (hive-artcraft.schema/AppModule, Malli-validated at load)

keyrequiredmeaning
:app/idyeslowercase id, the value of app ("lightcraft")
:app/label, :app/summaryyesshown by command=apps
:app/kindyes:mount (forward to an existing hive addon) or :native (served here)
:app/transportyestransport shape, see below
:app/default-portfor :portdefault control port
:app/port-envfor :portenv override, <APP>_CONTROL_PORT
:app/catalog-resourcefor :nativeclasspath EDN satisfying schema/Catalog
:app/mountfor :mount{:ctor ns/addon-ctor :addon-id "hive.x" :port-requires [:token-ref]}
:app/token-refno (:native :port only)default token reference {:scheme :env :name "<APP>_CONTROL_TOKEN"} or {:scheme :file :path ...} for a port that authenticates every request (filmcraft); :apps {"<app>" {:token-ref ...}} overrides it
:app/upstreamnoupstream repository URL

Per-app runtime config (schema/AppConfig, under :apps {"<id>" {...}}) accepts: :control-port, :control-host, :control-file, :token-ref and :transport. An injected ControlTransport always wins.

If a module is invalid or an id is duplicated, the addon refuses to initialize and names the module and the reason.

Transport shapes

shapeappsbehaviour
:portvectorcraft, lightcraft, designcraft, filmcraft, effectcraft (photocraft adds a token)live: <app> --control PORT, one JSON line {id, method:"engine.execute", params:{command, params}} per request, over loopback (hive-artcraft.transport.socket). An app with a :token-ref (filmcraft) also gets a top-level "token" on each line
:control-filepdfcraftlive once :apps {"pdfcraft" {:control-file "~/.pdfcraft-control.json"}} is set: pdfcraft --control <FILE> listens on a random loopback port and writes {port, token} to FILE. Each request re-reads the file (it must be a regular file you own, mode 600, not a symlink, under 64 KiB), sends JSON-RPC auth {token} first, then one ui.* request (hive-artcraft.transport.control-file). call maps engine_command to ui.command {id}, and control sends catalogued ui.* methods (ui.commands, ui.inspect, ui.state...). The token is never logged or returned: it prints as #<redacted>. Without :control-file, calls refuse with :artcraft/no-transport
:nonestudio (ArtCraft, Tauri IPC)catalog only (its #[tauri::command] fns); doctor reports :status :no-control-surface with a remedy; call/control refuse with :artcraft/unsupported-shape

doctor always reports the app's shape, its resolved port and its source (:config, :env or :default), whether a transport is ready, and the remedy.

Example: a native :port app

;; resources/hive_artcraft/apps.edn — append:
{:app/id "lightcraft"
 :app/label "LightCraft"
 :app/summary "Photo library and raw development."
 :app/kind :native
 :app/transport :port
 :app/default-port 7980
 :app/port-env "LIGHTCRAFT_CONTROL_PORT"
 :app/catalog-resource "hive_artcraft/catalogs/lightcraft.edn"
 :app/upstream "https://github.com/storytold/lightcraft"}

resources/hive_artcraft/catalogs/lightcraft.edn holds the extracted vocabulary:

{:reference-revision "fb7ac08"
 :engine [{:id "develop.exposure" :label "Exposure"} ...]
 :mcp [{:name "..."} ...]
 :control ["engine.execute" "engine.commands" "ui.render" ...]}

That's it. call checks engine_command against :engine, control checks method against :control, and both go out over the resolved port.

Example: mounting an existing hive addon

{:app/id "vectorcraft" :app/label "VectorCraft" :app/summary "..."
 :app/kind :mount :app/transport :port
 :app/default-port 7979 :app/port-env "VECTORCRAFT_CONTROL_PORT"
 :app/mount {:ctor hive-vectorcraft.addon/addon-ctor :addon-id "hive.vectorcraft"}}

The delegate's manifest ctor receives its :apps config with the resolved :control-port. It is initialized once, and every command (minus app) goes to its tool handler unchanged. Add the delegate's library to deps.edn.

Layout

nsrole
hive-artcraft.schemaAppModule, AppConfig, TransportShape, Catalog contracts
hive-artcraft.registryreads and validates the app data list, resolves per-app config and ports
hive-artcraft.mountconstructs a delegate addon and forwards to its tool
hive-artcraft.servicenative-app catalog/doctor/call/control for each shape
hive-artcraft.core (.cljc)portable request/frame/reply values
hive-artcraft.port, .transport.socketControlTransport port and loopback JSON-lines client
hive-artcraft.addonthe IAddon and the artcraft tool

Tests

clojure -M:test

The suite covers every public function with a golden, property and mutation trifecta (a gate test reads the universe from src/), every one has a Malli contract (also census-checked), and there are acceptance tests against the real photocraft and vectorcraft delegates.

MIT licensed.

Can you improve this documentation?Edit on GitHub

cljdoc builds & hosts documentation for Clojure/Script libraries

Keyboard shortcuts
Ctrl+kJump to recent docs
←Move to previous article
→Move to next article
Ctrl+/Jump to the search field
× close