mirror of
https://github.com/storytold/AniCraft.git
synced 2026-11-19 09:01:29 +01:00
Merge outside PR #216: feat(control): live control port and MCP bridge (ADR 0104) (M8)
# Conflicts: # CHANGELOG.md # docs/roadmap.md # src/main.rs
This commit is contained in:
commit
6f1adc4ea2
17 files changed
+1303
-20
No files matched your search
@@ -481,6 +481,21 @@
|
||||
click, Shift-click, Ctrl-click or a box. **Properties › Bone** counts the bone's points and
|
||||
has **Rebind All**.
|
||||
* Headless: `bone.add_in_shape`, `bone.bind`, and `bone.info` with `points`.
|
||||
* **Remote control: assistants edit the open window live** (ADR 0104).
|
||||
* `anicraft --control 9878` opens AniCraft as usual and lets an assistant edit the document you
|
||||
have open, through a port on this computer only. Its edits appear at once and undo with
|
||||
Ctrl+Z, like yours; the status bar says "Remote control on (port 9878)" while it is open. Also
|
||||
`ANICRAFT_CONTROL_PORT`.
|
||||
* `anicraft-cli mcp --bridge 9878`: the MCP server's five tools, acting on that window. It starts
|
||||
before AniCraft is open, connects on the first call, says how to start AniCraft when it isn't
|
||||
running, and reconnects after AniCraft is reopened.
|
||||
* No setup: each run makes a fresh token and writes it to `control.json` in AniCraft's settings
|
||||
folder (only you can read it), where the bridge finds it. `ANICRAFT_CONTROL_TOKEN` overrides it.
|
||||
* While you drag, the assistant's edits wait until you let go, so the two never share an undo step.
|
||||
* The protocol (`docs/control-protocol.md`): JSON lines on `127.0.0.1`; `hello`, `tools.list`,
|
||||
`tools.call`; anything that isn't a JSON request (such as a web page's request to localhost) is
|
||||
refused.
|
||||
|
||||
* **CI on macOS and Windows** (ADR 0067, M8). Every pull request that changes code now builds,
|
||||
tests and lints the workspace on macOS (arm64) and Windows (x64) runners as well as Linux, so
|
||||
macOS-only and Windows-only code is checked before it merges. Documentation-only changes skip
|
||||
|
||||
Generated
+2
@@ -234,6 +234,7 @@ name = "anicraft"
|
||||
version = "0.3.0"
|
||||
dependencies = [
|
||||
"anicraft-audio",
|
||||
"anicraft-cli",
|
||||
"anicraft-doc",
|
||||
"anicraft-engine",
|
||||
"anicraft-geom",
|
||||
@@ -284,6 +285,7 @@ dependencies = [
|
||||
"anicraft-geom",
|
||||
"anicraft-guide",
|
||||
"anicraft-render",
|
||||
"getrandom 0.3.4",
|
||||
"serde_json",
|
||||
"wat",
|
||||
]
|
||||
|
||||
@@ -120,6 +120,9 @@ sys-locale = "0.3"
|
||||
[target.'cfg(not(target_arch = "wasm32"))'.dependencies]
|
||||
# The user guide, bundled for Help › User Guide (ADR 0069). The web build serves it as pages instead.
|
||||
anicraft-guide.workspace = true
|
||||
# The live control port and the tools it serves (ADR 0104): the same dispatcher as the
|
||||
# headless MCP server, so live and headless never drift.
|
||||
anicraft-cli = { path = "crates/cli" }
|
||||
craft-update = { git = "https://github.com/storytold/craft-libs", rev = "6ac2a6a34ae83fc0f0bfb25a569ba6388b72266a" }
|
||||
|
||||
eframe = { workspace = true, features = ["links"] }
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "anicraft-cli"
|
||||
description = "AniCraft L4: headless CLI and JSON-lines control channel for agents and pipelines"
|
||||
description = "AniCraft L4: headless CLI, MCP server and the desktop app's live control channel"
|
||||
version.workspace = true
|
||||
edition.workspace = true
|
||||
license.workspace = true
|
||||
@@ -21,6 +21,9 @@ anicraft-render.workspace = true
|
||||
anicraft-geom.workspace = true
|
||||
anicraft-guide.workspace = true
|
||||
serde_json.workspace = true
|
||||
# The live control port's per-run token (ADR 0104): the operating system's random numbers.
|
||||
# MIT OR Apache-2.0, already in the tree.
|
||||
getrandom = "0.3"
|
||||
|
||||
[dev-dependencies]
|
||||
# Exporter plug-in fixtures written in WebAssembly text (Apache-2.0 WITH LLVM-exception).
|
||||
|
||||
@@ -0,0 +1,493 @@
|
||||
//! The live control channel (ADR 0104, `docs/control-protocol.md`): the desktop app's control
|
||||
//! port, and the client `anicraft-cli mcp --bridge <port>` uses to reach it.
|
||||
//!
|
||||
//! The app listens on `127.0.0.1` only. Each connection carries one JSON object per line each
|
||||
//! way, answered in order. Every request carries the run's token, which the app writes to
|
||||
//! `control.json` in the AniCraft settings folder, so a client running as the same user finds it
|
||||
//! with no setup. The tools are the MCP server's ([`crate::mcp::tools`], [`crate::mcp::call_tool`]),
|
||||
//! so live and headless never drift.
|
||||
//!
|
||||
//! Nothing here touches the window: [`listen`] hands each tool call to whoever drains
|
||||
//! [`Server::try_recv`] (the app's frame loop), with a channel for the answer.
|
||||
|
||||
use crate::mcp;
|
||||
use serde_json::{Value, json};
|
||||
use std::io::{BufRead, BufReader, Read, Write};
|
||||
use std::net::{Ipv4Addr, SocketAddr, SocketAddrV4, TcpListener, TcpStream};
|
||||
use std::path::{Path, PathBuf};
|
||||
use std::sync::Arc;
|
||||
use std::sync::atomic::{AtomicUsize, Ordering};
|
||||
use std::sync::mpsc::{Receiver, RecvTimeoutError, Sender, channel};
|
||||
use std::time::{Duration, Instant};
|
||||
|
||||
/// The wire protocol's version, reported by `hello`.
|
||||
pub const PROTOCOL: u32 = 1;
|
||||
/// The port AniCraft's documentation and shortcuts use (VectorCraft 7979, CadCraft 7980,
|
||||
/// FilmCraft 9876, EffectCraft 9877).
|
||||
pub const DEFAULT_PORT: u16 = 9878;
|
||||
/// Longest request or reply line, in bytes.
|
||||
pub const MAX_LINE: usize = 4 * 1024 * 1024;
|
||||
/// Most connections open at once.
|
||||
pub const MAX_CONNECTIONS: usize = 16;
|
||||
/// How long a tool call may wait for the app (a frame, or the end of the person's drag).
|
||||
pub const REQUEST_TIMEOUT: Duration = Duration::from_secs(60);
|
||||
/// Extra time the connection waits past the deadline: a call that started just before it
|
||||
/// still gets its real answer.
|
||||
const GRACE: Duration = Duration::from_secs(10);
|
||||
/// Overrides the generated token on both sides (CI, power users).
|
||||
pub const TOKEN_ENV: &str = "ANICRAFT_CONTROL_TOKEN";
|
||||
/// The port when `--control` isn't given.
|
||||
pub const PORT_ENV: &str = "ANICRAFT_CONTROL_PORT";
|
||||
/// The file the app writes in the settings folder while its control port is open.
|
||||
pub const CONTROL_FILE: &str = "control.json";
|
||||
|
||||
/// AniCraft's settings folder: %APPDATA%\AniCraft, ~/Library/Application Support/AniCraft, or
|
||||
/// $XDG_CONFIG_HOME/anicraft (default ~/.config/anicraft). The shell's `platform::config_dir`
|
||||
/// owns this rule; a shell test keeps the two the same (this crate can't use the shell).
|
||||
pub fn settings_dir() -> Option<PathBuf> {
|
||||
let env = |k: &str| std::env::var_os(k).filter(|v| !v.is_empty()).map(PathBuf::from);
|
||||
if cfg!(windows) {
|
||||
env("APPDATA").map(|p| p.join("AniCraft"))
|
||||
} else if cfg!(target_os = "macos") {
|
||||
env("HOME").map(|p| p.join("Library").join("Application Support").join("AniCraft"))
|
||||
} else {
|
||||
env("XDG_CONFIG_HOME").or_else(|| env("HOME").map(|h| h.join(".config"))).map(|p| p.join("anicraft"))
|
||||
}
|
||||
}
|
||||
|
||||
/// Where `control.json` lives.
|
||||
pub fn control_file() -> Option<PathBuf> {
|
||||
settings_dir().map(|d| d.join(CONTROL_FILE))
|
||||
}
|
||||
|
||||
/// `ANICRAFT_CONTROL_TOKEN`, when set and not blank.
|
||||
pub fn token_from_env() -> Option<String> {
|
||||
std::env::var(TOKEN_ENV).ok().map(|t| t.trim().to_string()).filter(|t| !t.is_empty())
|
||||
}
|
||||
|
||||
/// A fresh token: 32 random bytes from the operating system, as 64 hex digits.
|
||||
pub fn new_token() -> Result<String, String> {
|
||||
let mut bytes = [0u8; 32];
|
||||
getrandom::fill(&mut bytes).map_err(|e| format!("no random numbers from the system: {e}"))?;
|
||||
Ok(bytes.iter().map(|b| format!("{b:02x}")).collect())
|
||||
}
|
||||
|
||||
/// Reads a port: a number from 1 to 65535.
|
||||
pub fn parse_port(s: &str) -> Result<u16, String> {
|
||||
match s.trim().parse::<u16>() {
|
||||
Ok(p) if p > 0 => Ok(p),
|
||||
_ => Err(format!("'{s}' is not a port: use a number from 1 to 65535, such as {DEFAULT_PORT}")),
|
||||
}
|
||||
}
|
||||
|
||||
/// What `control.json` holds.
|
||||
#[derive(Clone, Debug, PartialEq)]
|
||||
pub struct ControlFile {
|
||||
pub port: u16,
|
||||
pub token: String,
|
||||
pub pid: u32,
|
||||
pub version: String,
|
||||
}
|
||||
|
||||
impl ControlFile {
|
||||
pub fn to_json(&self) -> Value {
|
||||
json!({"port": self.port, "token": self.token, "pid": self.pid, "version": self.version})
|
||||
}
|
||||
pub fn parse(text: &str) -> Result<ControlFile, String> {
|
||||
let v: Value = serde_json::from_str(text.trim_start_matches('\u{feff}')).map_err(|e| format!("{CONTROL_FILE} is not JSON: {e}"))?;
|
||||
let token = v.get("token").and_then(Value::as_str).filter(|t| !t.is_empty()).ok_or_else(|| format!("{CONTROL_FILE} has no token"))?;
|
||||
let port = v.get("port").and_then(Value::as_u64).and_then(|p| u16::try_from(p).ok()).ok_or_else(|| format!("{CONTROL_FILE} has no port"))?;
|
||||
let pid = v.get("pid").and_then(Value::as_u64).and_then(|p| u32::try_from(p).ok()).unwrap_or(0);
|
||||
let version = v.get("version").and_then(Value::as_str).unwrap_or("").to_string();
|
||||
Ok(ControlFile { port, token: token.to_string(), pid, version })
|
||||
}
|
||||
}
|
||||
|
||||
/// Why a line could not be read.
|
||||
#[derive(Debug)]
|
||||
pub enum LineError {
|
||||
TooLong,
|
||||
NotText,
|
||||
Io(std::io::Error),
|
||||
}
|
||||
|
||||
/// Reads one line (without its line break), at most `limit` bytes; `Ok(None)` at the end.
|
||||
pub fn read_line<R: BufRead>(r: &mut R, limit: usize) -> Result<Option<String>, LineError> {
|
||||
let mut buf = Vec::new();
|
||||
let cap = u64::try_from(limit).unwrap_or(u64::MAX).saturating_add(1);
|
||||
let n = r.by_ref().take(cap).read_until(b'\n', &mut buf).map_err(LineError::Io)?;
|
||||
if n == 0 {
|
||||
return Ok(None);
|
||||
}
|
||||
if buf.last() == Some(&b'\n') {
|
||||
buf.pop();
|
||||
} else if buf.len() > limit {
|
||||
return Err(LineError::TooLong);
|
||||
}
|
||||
if buf.len() > limit {
|
||||
return Err(LineError::TooLong);
|
||||
}
|
||||
if buf.last() == Some(&b'\r') {
|
||||
buf.pop();
|
||||
}
|
||||
String::from_utf8(buf).map(Some).map_err(|_| LineError::NotText)
|
||||
}
|
||||
|
||||
/// One request off the wire.
|
||||
#[derive(Debug, PartialEq)]
|
||||
pub struct Incoming {
|
||||
pub id: Value,
|
||||
pub token: Option<String>,
|
||||
pub method: String,
|
||||
pub params: Value,
|
||||
}
|
||||
|
||||
/// Reads a request line: a JSON object with a string `method`. Anything else (an HTTP request
|
||||
/// line, which is how a web page's `fetch` to localhost begins, included) is refused.
|
||||
pub fn parse_request(line: &str) -> Result<Incoming, String> {
|
||||
let v: Value = serde_json::from_str(line.trim_start_matches('\u{feff}')).map_err(|_| "expected one JSON object per line, such as {\"id\":1,\"token\":\"…\",\"method\":\"hello\"}".to_string())?;
|
||||
let Value::Object(mut o) = v else { return Err("expected a JSON object".into()) };
|
||||
let method = match o.remove("method") {
|
||||
Some(Value::String(m)) => m,
|
||||
_ => return Err("the request needs a string \"method\"".into()),
|
||||
};
|
||||
let token = match o.remove("token") {
|
||||
Some(Value::String(t)) => Some(t),
|
||||
_ => None,
|
||||
};
|
||||
Ok(Incoming { id: o.remove("id").unwrap_or(Value::Null), token, method, params: o.remove("params").unwrap_or_else(|| json!({})) })
|
||||
}
|
||||
|
||||
/// Compares tokens in time that doesn't depend on where they differ.
|
||||
pub fn token_matches(given: Option<&str>, expected: &str) -> bool {
|
||||
let Some(given) = given else { return false };
|
||||
let (a, b) = (given.as_bytes(), expected.as_bytes());
|
||||
a.len() == b.len() && !b.is_empty() && a.iter().zip(b).fold(0u8, |acc, (x, y)| acc | (x ^ y)) == 0
|
||||
}
|
||||
|
||||
fn ok(id: &Value, result: Value) -> Value {
|
||||
json!({"id": id, "ok": true, "result": result})
|
||||
}
|
||||
|
||||
fn fail(id: &Value, error: impl Into<String>) -> Value {
|
||||
json!({"id": id, "ok": false, "error": error.into()})
|
||||
}
|
||||
|
||||
/// The message when a tool call never got its turn.
|
||||
pub const BUSY: &str = "AniCraft was busy for 60 s (an edit in progress in the window, such as a drag, typing or a plug-in dialog), so this call was not run. Try again.";
|
||||
|
||||
/// A tool call waiting for the app's frame loop.
|
||||
pub struct Request {
|
||||
pub name: String,
|
||||
pub arguments: Value,
|
||||
deadline: Instant,
|
||||
reply: Sender<Result<Value, String>>,
|
||||
}
|
||||
|
||||
impl Request {
|
||||
/// Whether it can change the document (and so waits for the person's own gesture to end).
|
||||
pub fn changes_document(&self) -> bool {
|
||||
mcp::tool_changes_document(&self.name)
|
||||
}
|
||||
/// Past its deadline: it must not run any more (the client was told it didn't).
|
||||
pub fn expired(&self) -> bool {
|
||||
Instant::now() >= self.deadline
|
||||
}
|
||||
/// Runs it on `host` and sends the answer; an expired request is refused instead.
|
||||
pub fn run<H: mcp::Host + ?Sized>(self, host: &mut H) {
|
||||
let result = if self.expired() { Err(BUSY.to_string()) } else { mcp::call_tool(host, &self.name, &self.arguments) };
|
||||
let _ = self.reply.send(result);
|
||||
}
|
||||
/// Answers without running (the app is closing).
|
||||
pub fn refuse(self, why: &str) {
|
||||
let _ = self.reply.send(Err(why.to_string()));
|
||||
}
|
||||
}
|
||||
|
||||
/// Wakes the app's frame loop (`egui::Context::request_repaint`), from any thread.
|
||||
pub type Wake = Arc<dyn Fn() + Send + Sync>;
|
||||
|
||||
/// An open control port.
|
||||
pub struct Server {
|
||||
pub port: u16,
|
||||
rx: Receiver<Request>,
|
||||
}
|
||||
|
||||
impl Server {
|
||||
/// The next waiting tool call, if any.
|
||||
pub fn try_recv(&self) -> Option<Request> {
|
||||
self.rx.try_recv().ok()
|
||||
}
|
||||
}
|
||||
|
||||
/// Opens the control port on `127.0.0.1:port`. Tool calls arrive through [`Server::try_recv`];
|
||||
/// `wake` is called whenever one is waiting.
|
||||
pub fn listen(port: u16, token: String, wake: Wake) -> std::io::Result<Server> {
|
||||
let listener = TcpListener::bind(SocketAddrV4::new(Ipv4Addr::LOCALHOST, port))?;
|
||||
let port = listener.local_addr()?.port();
|
||||
let (tx, rx) = channel();
|
||||
let token: Arc<str> = token.into();
|
||||
std::thread::Builder::new().name("anicraft-control".into()).spawn(move || accept_loop(&listener, &token, &tx, &wake))?;
|
||||
Ok(Server { port, rx })
|
||||
}
|
||||
|
||||
fn accept_loop(listener: &TcpListener, token: &Arc<str>, tx: &Sender<Request>, wake: &Wake) {
|
||||
let active = Arc::new(AtomicUsize::new(0));
|
||||
for stream in listener.incoming() {
|
||||
let Ok(mut stream) = stream else { continue };
|
||||
let _ = stream.set_write_timeout(Some(Duration::from_secs(10)));
|
||||
if active.fetch_add(1, Ordering::SeqCst) >= MAX_CONNECTIONS {
|
||||
active.fetch_sub(1, Ordering::SeqCst);
|
||||
let _ = writeln!(stream, "{}", fail(&Value::Null, format!("too many connections (at most {MAX_CONNECTIONS})")));
|
||||
continue;
|
||||
}
|
||||
let (token, tx, wake, active2) = (token.clone(), tx.clone(), wake.clone(), active.clone());
|
||||
let spawned = std::thread::Builder::new().name("anicraft-control-conn".into()).spawn(move || {
|
||||
serve_connection(stream, &token, &tx, &wake);
|
||||
active2.fetch_sub(1, Ordering::SeqCst);
|
||||
});
|
||||
if spawned.is_err() {
|
||||
active.fetch_sub(1, Ordering::SeqCst);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// One connection: requests in order, until the client leaves or sends something it shouldn't.
|
||||
fn serve_connection(stream: TcpStream, token: &str, tx: &Sender<Request>, wake: &Wake) {
|
||||
let Ok(read_half) = stream.try_clone() else { return };
|
||||
let mut reader = BufReader::new(read_half);
|
||||
let mut out = stream;
|
||||
loop {
|
||||
let line = match read_line(&mut reader, MAX_LINE) {
|
||||
Ok(Some(l)) => l,
|
||||
Ok(None) | Err(LineError::Io(_)) => return,
|
||||
Err(LineError::TooLong) => {
|
||||
let _ = writeln!(out, "{}", fail(&Value::Null, format!("request longer than {} MiB", MAX_LINE / (1024 * 1024))));
|
||||
return;
|
||||
}
|
||||
Err(LineError::NotText) => {
|
||||
let _ = writeln!(out, "{}", fail(&Value::Null, "the request is not UTF-8 text"));
|
||||
return;
|
||||
}
|
||||
};
|
||||
if line.trim().is_empty() {
|
||||
continue;
|
||||
}
|
||||
let (reply, keep_open) = answer(&line, token, tx, wake);
|
||||
if writeln!(out, "{reply}").and_then(|()| out.flush()).is_err() || !keep_open {
|
||||
return;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// The reply to one request line, and whether the connection stays open.
|
||||
fn answer(line: &str, token: &str, tx: &Sender<Request>, wake: &Wake) -> (Value, bool) {
|
||||
let req = match parse_request(line) {
|
||||
Ok(r) => r,
|
||||
Err(e) => return (fail(&Value::Null, e), false),
|
||||
};
|
||||
if !token_matches(req.token.as_deref(), token) {
|
||||
let why = if req.token.is_none() { "missing token" } else { "wrong token" };
|
||||
return (fail(&req.id, format!("{why}: send the \"token\" from {CONTROL_FILE} in AniCraft's settings folder (or {TOKEN_ENV})")), false);
|
||||
}
|
||||
let id = &req.id;
|
||||
match req.method.as_str() {
|
||||
"hello" => (ok(id, json!({"app": "AniCraft", "version": env!("CARGO_PKG_VERSION"), "protocol": PROTOCOL})), true),
|
||||
"tools.list" => (ok(id, mcp::tools()), true),
|
||||
"tools.call" => {
|
||||
let Some(name) = req.params.get("name").and_then(Value::as_str) else { return (fail(id, "tools.call needs a tool \"name\" in params"), true) };
|
||||
let arguments = req.params.get("arguments").cloned().unwrap_or_else(|| json!({}));
|
||||
let (reply, rx) = channel();
|
||||
let request = Request { name: name.to_string(), arguments, deadline: Instant::now() + REQUEST_TIMEOUT, reply };
|
||||
if tx.send(request).is_err() {
|
||||
return (fail(id, "AniCraft is closing"), false);
|
||||
}
|
||||
wake();
|
||||
match rx.recv_timeout(REQUEST_TIMEOUT + GRACE) {
|
||||
Ok(Ok(result)) => (ok(id, result), true),
|
||||
Ok(Err(e)) => (fail(id, e), true),
|
||||
Err(RecvTimeoutError::Timeout) => (fail(id, "AniCraft didn't answer in time; the call may still have run. Check with anicraft_document before trying again."), true),
|
||||
Err(RecvTimeoutError::Disconnected) => (fail(id, "AniCraft closed before answering"), false),
|
||||
}
|
||||
}
|
||||
other => (fail(id, format!("unknown method '{other}' (hello, tools.list, tools.call)")), true),
|
||||
}
|
||||
}
|
||||
|
||||
// ----- the client: `anicraft-cli mcp --bridge` -------------------------------------------------
|
||||
|
||||
/// Reads `--bridge`'s value: a port, or `127.0.0.1:port` / `localhost:port`. Other hosts are
|
||||
/// refused: the control port is for this computer only.
|
||||
pub fn parse_bridge_target(s: &str) -> Result<SocketAddr, String> {
|
||||
let s = s.trim();
|
||||
let (host, port) = match s.rsplit_once(':') {
|
||||
Some((h, p)) => (h, p),
|
||||
None => ("127.0.0.1", s),
|
||||
};
|
||||
if !matches!(host, "127.0.0.1" | "localhost") {
|
||||
return Err(format!("--bridge connects to this computer only: give a port, or 127.0.0.1:<port> (not {host})"));
|
||||
}
|
||||
Ok(SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::LOCALHOST, parse_port(port)?)))
|
||||
}
|
||||
|
||||
/// The token to send: `ANICRAFT_CONTROL_TOKEN` when set, else the one in `control.json`.
|
||||
pub fn find_token(env: Option<String>, file: Option<&Path>) -> Result<String, String> {
|
||||
if let Some(t) = env {
|
||||
return Ok(t);
|
||||
}
|
||||
let Some(file) = file else { return Err(not_running(None)) };
|
||||
match std::fs::read_to_string(file) {
|
||||
Ok(text) => ControlFile::parse(&text).map(|c| c.token),
|
||||
Err(_) => Err(not_running(None)),
|
||||
}
|
||||
}
|
||||
|
||||
/// What to tell the person when the app isn't there.
|
||||
fn not_running(port: Option<u16>) -> String {
|
||||
let port = port.unwrap_or(DEFAULT_PORT);
|
||||
format!(
|
||||
"AniCraft isn't open with remote control on. Start it with `anicraft --control {port}` (the \"AniCraft (Claude)\" shortcut), then try again; there is no need to restart the assistant."
|
||||
)
|
||||
}
|
||||
|
||||
/// Why a bridged call failed.
|
||||
#[derive(Debug, PartialEq)]
|
||||
pub enum BridgeError {
|
||||
/// Couldn't reach the app (not running, no token): nothing ran.
|
||||
NotRunning(String),
|
||||
/// The connection broke after the request went out: it may have run.
|
||||
Lost(String),
|
||||
/// The app refused the call (the headless server's protocol error).
|
||||
Refused(String),
|
||||
}
|
||||
|
||||
struct Conn {
|
||||
reader: BufReader<TcpStream>,
|
||||
writer: TcpStream,
|
||||
}
|
||||
|
||||
impl Conn {
|
||||
/// Whether the app is still at the other end (an app that quit leaves the socket closed).
|
||||
fn alive(&self) -> bool {
|
||||
if self.writer.set_nonblocking(true).is_err() {
|
||||
return false;
|
||||
}
|
||||
let r = self.writer.peek(&mut [0u8; 1]);
|
||||
let back = self.writer.set_nonblocking(false).is_ok();
|
||||
back && matches!(r, Err(ref e) if e.kind() == std::io::ErrorKind::WouldBlock)
|
||||
}
|
||||
}
|
||||
|
||||
/// The bridge's link to the app: connected on the first call, again after a break.
|
||||
pub struct Bridge {
|
||||
addr: SocketAddr,
|
||||
conn: Option<Conn>,
|
||||
next_id: u64,
|
||||
/// Where the token comes from (tests point it elsewhere).
|
||||
token_file: Option<PathBuf>,
|
||||
}
|
||||
|
||||
impl Bridge {
|
||||
/// Doesn't connect: the assistant starts its servers when it starts, often before AniCraft.
|
||||
pub fn new(addr: SocketAddr) -> Bridge {
|
||||
Bridge { addr, conn: None, next_id: 1, token_file: control_file() }
|
||||
}
|
||||
|
||||
pub fn with_token_file(addr: SocketAddr, file: Option<PathBuf>) -> Bridge {
|
||||
Bridge { addr, conn: None, next_id: 1, token_file: file }
|
||||
}
|
||||
|
||||
fn connect(&mut self) -> Result<String, BridgeError> {
|
||||
let token = find_token(token_from_env(), self.token_file.as_deref()).map_err(BridgeError::NotRunning)?;
|
||||
if self.conn.as_ref().is_some_and(Conn::alive) {
|
||||
return Ok(token);
|
||||
}
|
||||
self.conn = None;
|
||||
let stream = TcpStream::connect_timeout(&self.addr, Duration::from_secs(3)).map_err(|_| BridgeError::NotRunning(not_running(Some(self.addr.port()))))?;
|
||||
let _ = stream.set_nodelay(true);
|
||||
let _ = stream.set_read_timeout(Some(REQUEST_TIMEOUT + GRACE + Duration::from_secs(5)));
|
||||
let reader = BufReader::new(stream.try_clone().map_err(|e| BridgeError::NotRunning(e.to_string()))?);
|
||||
self.conn = Some(Conn { reader, writer: stream });
|
||||
Ok(token)
|
||||
}
|
||||
|
||||
/// One round trip; any transport failure drops the connection.
|
||||
fn round_trip(&mut self, token: &str, method: &str, params: Value) -> Result<Value, BridgeError> {
|
||||
let id = self.next_id;
|
||||
self.next_id += 1;
|
||||
let line = json!({"id": id, "token": token, "method": method, "params": params}).to_string();
|
||||
let Some(conn) = self.conn.as_mut() else { return Err(BridgeError::NotRunning(not_running(Some(self.addr.port())))) };
|
||||
let sent = writeln!(conn.writer, "{line}").and_then(|()| conn.writer.flush());
|
||||
let reply = sent.map_err(|e| e.to_string()).and_then(|()| match read_line(&mut conn.reader, MAX_LINE) {
|
||||
Ok(Some(l)) => Ok(l),
|
||||
Ok(None) => Err("AniCraft closed the connection".to_string()),
|
||||
Err(LineError::Io(e)) => Err(e.to_string()),
|
||||
Err(_) => Err("unreadable reply".to_string()),
|
||||
});
|
||||
let reply = match reply {
|
||||
Ok(l) => l,
|
||||
Err(e) => {
|
||||
self.conn = None;
|
||||
return Err(BridgeError::Lost(e));
|
||||
}
|
||||
};
|
||||
let v: Value = serde_json::from_str(&reply).map_err(|e| {
|
||||
self.conn = None;
|
||||
BridgeError::Lost(format!("unreadable reply: {e}"))
|
||||
})?;
|
||||
if v.get("ok").and_then(Value::as_bool) == Some(true) {
|
||||
return Ok(v.get("result").cloned().unwrap_or(Value::Null));
|
||||
}
|
||||
let error = v.get("error").and_then(Value::as_str).unwrap_or("AniCraft refused the request").to_string();
|
||||
if v.get("id").is_some_and(Value::is_null) || error.starts_with("missing token") || error.starts_with("wrong token") {
|
||||
// The app closes the connection after these (an old token: AniCraft was restarted
|
||||
// and control.json has the new one by the next call).
|
||||
self.conn = None;
|
||||
}
|
||||
Err(BridgeError::Refused(error))
|
||||
}
|
||||
|
||||
/// Runs a tool in the app. An edit whose answer was lost is never sent again (the app may
|
||||
/// have made it); a call that only reads is tried once more on a new connection.
|
||||
pub fn call_tool(&mut self, name: &str, args: &Value) -> Result<Value, BridgeError> {
|
||||
let retries = if mcp::tool_changes_document(name) { 0 } else { 1 };
|
||||
let mut attempt = 0;
|
||||
loop {
|
||||
let token = self.connect()?;
|
||||
match self.round_trip(&token, "tools.call", json!({"name": name, "arguments": args})) {
|
||||
Err(BridgeError::Lost(_)) if attempt < retries => attempt += 1,
|
||||
Err(BridgeError::Refused(e)) if e.starts_with("wrong token") && attempt < 1 => attempt += 1,
|
||||
other => return other,
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// The bridge's instructions: the same tools, acting on the person's open window.
|
||||
pub const BRIDGE_INSTRUCTIONS: &str = "AniCraft is a 2D animation studio, and these tools act on the AniCraft window the person \
|
||||
has open: every edit appears there immediately and can be undone with Ctrl+Z (or edit.undo). Every edit is a command: call \
|
||||
anicraft_commands to find one (filter by words such as 'tween' or 'export'), then anicraft_run with its id and params, or \
|
||||
anicraft_run_script for several in order. Frames in params are 0-based. Commands act on the current scene, layer, frame and \
|
||||
selection, which anicraft_document reports (the person may change them between your calls). Use anicraft_render to see a \
|
||||
frame. Commands that would lose work or replace a file refuse until params include \"confirm\": true; ask the person before \
|
||||
confirming. If AniCraft isn't open with remote control on, the tools say how to start it.";
|
||||
|
||||
impl mcp::Backend for Bridge {
|
||||
fn instructions(&self) -> &'static str {
|
||||
BRIDGE_INSTRUCTIONS
|
||||
}
|
||||
fn call(&mut self, name: &str, args: &Value) -> Result<Value, String> {
|
||||
match self.call_tool(name, args) {
|
||||
Ok(v) => Ok(v),
|
||||
Err(BridgeError::Refused(e)) => Err(e),
|
||||
Err(BridgeError::NotRunning(e)) => Ok(mcp::text_result(&Value::String(e), true)),
|
||||
Err(BridgeError::Lost(e)) => {
|
||||
let what = if mcp::tool_changes_document(name) { " It may have been made: check with anicraft_document before trying again." } else { "" };
|
||||
Ok(mcp::text_result(&Value::String(format!("The connection to AniCraft broke ({e}).{what}")), true))
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests;
|
||||
@@ -0,0 +1,253 @@
|
||||
use super::*;
|
||||
use crate::mcp::Backend;
|
||||
use anicraft_engine::Session;
|
||||
use std::sync::atomic::AtomicBool;
|
||||
|
||||
const TOKEN: &str = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
|
||||
|
||||
/// A control port on a free port, with a stand-in for the app's frame loop running each call on
|
||||
/// its own session (as `App::poll_remote` does). Stops when dropped.
|
||||
struct App {
|
||||
port: u16,
|
||||
stop: Arc<AtomicBool>,
|
||||
loop_thread: Option<std::thread::JoinHandle<Session>>,
|
||||
}
|
||||
|
||||
impl App {
|
||||
fn start(session: Session) -> App {
|
||||
let server = listen(0, TOKEN.into(), Arc::new(|| {})).unwrap();
|
||||
let port = server.port;
|
||||
let stop = Arc::new(AtomicBool::new(false));
|
||||
let stop2 = stop.clone();
|
||||
let loop_thread = std::thread::spawn(move || {
|
||||
let mut s = session;
|
||||
while !stop2.load(Ordering::SeqCst) {
|
||||
while let Some(r) = server.try_recv() {
|
||||
r.run(&mut s);
|
||||
}
|
||||
std::thread::sleep(Duration::from_millis(2));
|
||||
}
|
||||
s
|
||||
});
|
||||
App { port, stop, loop_thread: Some(loop_thread) }
|
||||
}
|
||||
|
||||
fn session(mut self) -> Session {
|
||||
self.stop.store(true, Ordering::SeqCst);
|
||||
self.loop_thread.take().unwrap().join().unwrap()
|
||||
}
|
||||
|
||||
fn connect(&self) -> (BufReader<TcpStream>, TcpStream) {
|
||||
let s = TcpStream::connect(("127.0.0.1", self.port)).unwrap();
|
||||
s.set_read_timeout(Some(Duration::from_secs(20))).unwrap();
|
||||
(BufReader::new(s.try_clone().unwrap()), s)
|
||||
}
|
||||
}
|
||||
|
||||
impl Drop for App {
|
||||
fn drop(&mut self) {
|
||||
self.stop.store(true, Ordering::SeqCst);
|
||||
}
|
||||
}
|
||||
|
||||
fn send(conn: &mut (BufReader<TcpStream>, TcpStream), line: &str) -> Value {
|
||||
writeln!(conn.1, "{line}").unwrap();
|
||||
serde_json::from_str(&read_line(&mut conn.0, MAX_LINE).unwrap().unwrap()).unwrap()
|
||||
}
|
||||
|
||||
/// The app closed the connection: nothing more to read.
|
||||
fn closed(conn: &mut (BufReader<TcpStream>, TcpStream)) -> bool {
|
||||
matches!(read_line(&mut conn.0, MAX_LINE), Ok(None) | Err(LineError::Io(_)))
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn requests_are_json_objects_with_a_string_method() {
|
||||
let r = parse_request(r#"{"id":3,"token":"t","method":"hello"}"#).unwrap();
|
||||
assert_eq!((r.id, r.token.as_deref(), r.method.as_str(), r.params), (json!(3), Some("t"), "hello", json!({})));
|
||||
// A web page's fetch to localhost starts with an HTTP request line: refused.
|
||||
assert!(parse_request("GET / HTTP/1.1").is_err());
|
||||
assert!(parse_request("POST /tools HTTP/1.1").is_err());
|
||||
assert!(parse_request("[1,2]").is_err());
|
||||
assert!(parse_request(r#"{"id":1}"#).is_err(), "no method");
|
||||
assert!(parse_request(r#"{"id":1,"method":7}"#).is_err(), "method must be a string");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn tokens_must_match_exactly() {
|
||||
assert!(token_matches(Some(TOKEN), TOKEN));
|
||||
assert!(!token_matches(None, TOKEN));
|
||||
assert!(!token_matches(Some(""), ""), "an empty token never opens the port");
|
||||
assert!(!token_matches(Some(&TOKEN[..63]), TOKEN));
|
||||
assert!(!token_matches(Some(&TOKEN.replace('f', "e")), TOKEN));
|
||||
let t = new_token().unwrap();
|
||||
assert_eq!(t.len(), 64);
|
||||
assert!(t.bytes().all(|b| b.is_ascii_hexdigit()));
|
||||
assert_ne!(t, new_token().unwrap(), "fresh each time");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn lines_are_capped() {
|
||||
let mut r = &b"one\r\ntwo\nthree"[..];
|
||||
assert_eq!(read_line(&mut r, 10).unwrap().as_deref(), Some("one"));
|
||||
assert_eq!(read_line(&mut r, 10).unwrap().as_deref(), Some("two"));
|
||||
assert_eq!(read_line(&mut r, 10).unwrap().as_deref(), Some("three"));
|
||||
assert!(read_line(&mut r, 10).unwrap().is_none());
|
||||
let mut exact = &b"0123456789\n"[..];
|
||||
assert_eq!(read_line(&mut exact, 10).unwrap().as_deref(), Some("0123456789"));
|
||||
let mut long = &b"0123456789A\n"[..];
|
||||
assert!(matches!(read_line(&mut long, 10), Err(LineError::TooLong)));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn ports_and_bridge_targets() {
|
||||
assert_eq!(parse_port("9878"), Ok(9878));
|
||||
assert!(parse_port("0").is_err());
|
||||
assert!(parse_port("70000").is_err());
|
||||
assert!(parse_port("port").is_err());
|
||||
let local = SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::LOCALHOST, 9878));
|
||||
assert_eq!(parse_bridge_target("9878"), Ok(local));
|
||||
assert_eq!(parse_bridge_target("127.0.0.1:9878"), Ok(local));
|
||||
assert_eq!(parse_bridge_target("localhost:9878"), Ok(local));
|
||||
assert!(parse_bridge_target("192.168.1.5:9878").is_err(), "this computer only");
|
||||
assert!(parse_bridge_target("example.com:9878").is_err());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn the_control_file_round_trips() {
|
||||
let c = ControlFile { port: 9878, token: TOKEN.into(), pid: 42, version: "0.2.1".into() };
|
||||
assert_eq!(ControlFile::parse(&c.to_json().to_string()), Ok(c));
|
||||
assert!(ControlFile::parse("{}").is_err());
|
||||
assert!(ControlFile::parse("nonsense").is_err());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn the_token_comes_from_the_environment_then_the_control_file() {
|
||||
let dir = std::env::temp_dir().join(format!("anicraft-control-token-{}", std::process::id()));
|
||||
std::fs::create_dir_all(&dir).unwrap();
|
||||
let file = dir.join(CONTROL_FILE);
|
||||
std::fs::write(&file, ControlFile { port: 9878, token: "from-file".into(), pid: 1, version: String::new() }.to_json().to_string()).unwrap();
|
||||
assert_eq!(find_token(Some("from-env".into()), Some(&file)), Ok("from-env".into()), "the environment wins");
|
||||
assert_eq!(find_token(None, Some(&file)), Ok("from-file".into()));
|
||||
let missing = find_token(None, Some(&dir.join("gone.json"))).unwrap_err();
|
||||
assert!(missing.contains("anicraft --control"), "{missing}");
|
||||
assert!(find_token(None, None).is_err());
|
||||
let _ = std::fs::remove_dir_all(&dir);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_missing_or_wrong_token_is_refused_and_the_connection_closed() {
|
||||
let app = App::start(Session::default());
|
||||
let mut c = app.connect();
|
||||
let r = send(&mut c, r#"{"id":1,"method":"tools.call","params":{"name":"anicraft_run","arguments":{"command":"draw.rect","params":{"x":0,"y":0,"w":5,"h":5}}}}"#);
|
||||
assert_eq!(r["ok"], false);
|
||||
assert!(r["error"].as_str().unwrap().starts_with("missing token"), "{r}");
|
||||
assert!(closed(&mut c));
|
||||
let mut c = app.connect();
|
||||
let r = send(&mut c, &json!({"id": 2, "token": "nope", "method": "tools.call", "params": {"name": "anicraft_run", "arguments": {"command": "draw.rect", "params": {"x": 0, "y": 0, "w": 5, "h": 5}}}}).to_string());
|
||||
assert!(r["error"].as_str().unwrap().starts_with("wrong token"), "{r}");
|
||||
assert!(closed(&mut c));
|
||||
assert!(app.session().visible_elements().is_empty(), "nothing ran");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn http_and_oversized_lines_are_refused_and_the_connection_closed() {
|
||||
let app = App::start(Session::default());
|
||||
let mut c = app.connect();
|
||||
let r = send(&mut c, "GET / HTTP/1.1\r\nHost: 127.0.0.1\r\n");
|
||||
assert_eq!((r["ok"].clone(), r["id"].clone()), (json!(false), Value::Null));
|
||||
assert!(closed(&mut c));
|
||||
let mut c = app.connect();
|
||||
let big = format!(r#"{{"id":1,"token":"{TOKEN}","method":"hello","pad":"{}"}}"#, "x".repeat(MAX_LINE));
|
||||
// The app stops reading at the limit and answers; the rest of the write may fail.
|
||||
let _ = c.1.write_all(big.as_bytes());
|
||||
let _ = c.1.write_all(b"\n");
|
||||
let reply: Value = serde_json::from_str(&read_line(&mut c.0, MAX_LINE).unwrap().unwrap()).unwrap();
|
||||
assert!(reply["error"].as_str().unwrap().contains("longer than 4 MiB"), "{reply}");
|
||||
assert!(closed(&mut c));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_call_through_the_port_matches_the_headless_server() {
|
||||
let app = App::start(Session::default());
|
||||
let mut c = app.connect();
|
||||
let hello = send(&mut c, &json!({"id": 1, "token": TOKEN, "method": "hello"}).to_string());
|
||||
assert_eq!(hello, json!({"id": 1, "ok": true, "result": {"app": "AniCraft", "version": env!("CARGO_PKG_VERSION"), "protocol": PROTOCOL}}));
|
||||
let list = send(&mut c, &json!({"id": 2, "token": TOKEN, "method": "tools.list"}).to_string());
|
||||
assert_eq!(list["result"], mcp::tools());
|
||||
let args = json!({"command": "draw.rect", "params": {"x": 10, "y": 10, "w": 50, "h": 40, "fill": "#ff0000"}});
|
||||
let live = send(&mut c, &json!({"id": 3, "token": TOKEN, "method": "tools.call", "params": {"name": "anicraft_run", "arguments": args}}).to_string());
|
||||
assert_eq!(live["ok"], true, "{live}");
|
||||
let mut headless = Session::default();
|
||||
assert_eq!(live["result"], mcp::call_tool(&mut headless, "anicraft_run", &args).unwrap(), "the same dispatcher, the same answer");
|
||||
// A protocol error in headless mode is an error reply here; the connection stays usable.
|
||||
let bad = send(&mut c, &json!({"id": 4, "token": TOKEN, "method": "tools.call", "params": {"name": "nope"}}).to_string());
|
||||
assert_eq!((bad["ok"].clone(), bad["error"].clone()), (json!(false), json!("unknown tool 'nope'")));
|
||||
let unknown = send(&mut c, &json!({"id": 5, "token": TOKEN, "method": "frobnicate"}).to_string());
|
||||
assert_eq!(unknown["ok"], false);
|
||||
let doc = send(&mut c, &json!({"id": 6, "token": TOKEN, "method": "tools.call", "params": {"name": "anicraft_document"}}).to_string());
|
||||
// `state` numbers saved states across every session in the process, so it differs.
|
||||
let described = |r: &Value| {
|
||||
let mut v: Value = serde_json::from_str(r["content"][0]["text"].as_str().unwrap()).unwrap();
|
||||
v.as_object_mut().unwrap().remove("state");
|
||||
v
|
||||
};
|
||||
assert_eq!(described(&doc["result"]), described(&mcp::call_tool(&mut headless, "anicraft_document", &json!({})).unwrap()));
|
||||
let s = app.session();
|
||||
assert_eq!(s.visible_elements().len(), 1);
|
||||
assert!(s.doc == headless.doc);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_call_that_waited_past_its_deadline_does_not_run() {
|
||||
let (reply, answer) = channel();
|
||||
let r = Request { name: "anicraft_run".into(), arguments: json!({"command": "draw.rect", "params": {"x": 0, "y": 0, "w": 5, "h": 5}}), deadline: Instant::now(), reply };
|
||||
assert!(r.expired() && r.changes_document());
|
||||
let mut s = Session::default();
|
||||
r.run(&mut s);
|
||||
assert_eq!(answer.recv().unwrap(), Err(BUSY.to_string()));
|
||||
assert!(s.visible_elements().is_empty());
|
||||
}
|
||||
|
||||
fn free_port() -> u16 {
|
||||
TcpListener::bind("127.0.0.1:0").unwrap().local_addr().unwrap().port()
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn the_bridge_starts_without_the_app_and_says_how_to_start_it() {
|
||||
let addr = SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::LOCALHOST, free_port()));
|
||||
let dir = std::env::temp_dir().join(format!("anicraft-bridge-none-{}", std::process::id()));
|
||||
let mut b = Bridge::with_token_file(addr, Some(dir.join(CONTROL_FILE)));
|
||||
// The handshake and the tool list need no app.
|
||||
let init = mcp::handle(&mut b, r#"{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}"#).unwrap();
|
||||
assert!(init["result"]["instructions"].as_str().unwrap().contains("open"));
|
||||
let list = mcp::handle(&mut b, r#"{"jsonrpc":"2.0","id":2,"method":"tools/list"}"#).unwrap();
|
||||
assert_eq!(list["result"]["tools"], mcp::tools());
|
||||
let r = mcp::handle(&mut b, r#"{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"anicraft_document"}}"#).unwrap();
|
||||
assert_eq!(r["result"]["isError"], true);
|
||||
assert!(r["result"]["content"][0]["text"].as_str().unwrap().contains("anicraft --control"), "{r}");
|
||||
// A token file but no app listening: the same advice.
|
||||
std::fs::create_dir_all(&dir).unwrap();
|
||||
std::fs::write(dir.join(CONTROL_FILE), ControlFile { port: addr.port(), token: TOKEN.into(), pid: 1, version: String::new() }.to_json().to_string()).unwrap();
|
||||
assert!(matches!(b.call_tool("anicraft_document", &json!({})), Err(BridgeError::NotRunning(_))));
|
||||
let _ = std::fs::remove_dir_all(&dir);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn the_bridge_drives_the_app_and_says_when_it_has_gone() {
|
||||
let dir = std::env::temp_dir().join(format!("anicraft-bridge-live-{}", std::process::id()));
|
||||
std::fs::create_dir_all(&dir).unwrap();
|
||||
let file = dir.join(CONTROL_FILE);
|
||||
let app = App::start(Session::default());
|
||||
std::fs::write(&file, ControlFile { port: app.port, token: TOKEN.into(), pid: 1, version: String::new() }.to_json().to_string()).unwrap();
|
||||
let addr = SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::LOCALHOST, app.port));
|
||||
let mut b = Bridge::with_token_file(addr, Some(file.clone()));
|
||||
let r = b.call("anicraft_run", &json!({"command": "draw.rect", "params": {"x": 0, "y": 0, "w": 9, "h": 9}})).unwrap();
|
||||
assert_eq!(r["isError"], false, "{r}");
|
||||
assert_eq!(b.call("anicraft_document", &json!({})).unwrap()["isError"], false);
|
||||
assert_eq!(app.session().visible_elements().len(), 1, "the edit landed in the app's session");
|
||||
// The app's frame loop is gone: the call fails (as an error the assistant reads), never
|
||||
// silently.
|
||||
let r = b.call("anicraft_run", &json!({"command": "draw.rect", "params": {"x": 0, "y": 0, "w": 9, "h": 9}}));
|
||||
assert!(r.as_ref().map_or(true, |v| v["isError"] == true), "{r:?}");
|
||||
let _ = std::fs::remove_dir_all(&dir);
|
||||
}
|
||||
@@ -2,6 +2,7 @@
|
||||
//! server (`mcp`). Every operation goes through the engine's command registry.
|
||||
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
|
||||
|
||||
pub mod control;
|
||||
pub mod mcp;
|
||||
|
||||
use anicraft_engine::{Session, commands, format};
|
||||
@@ -45,6 +46,9 @@ USAGE:
|
||||
{\"id\":1,\"cmd\":\"draw.rect\",\"params\":{\"x\":10,\"y\":10,\"w\":50,\"h\":50}}
|
||||
anicraft-cli mcp [file|--sample] Model Context Protocol server on stdin/stdout,
|
||||
for AI assistants (see docs/mcp.md)
|
||||
anicraft-cli mcp --bridge <port> the same tools, acting live on the AniCraft window
|
||||
started with `anicraft --control <port>`
|
||||
(docs/control-protocol.md)
|
||||
anicraft-cli --version
|
||||
|
||||
--plugins <folder> loads the WebAssembly plug-ins in a folder first (also the
|
||||
@@ -292,6 +296,16 @@ pub fn run(argv: &[String]) -> Result<String, String> {
|
||||
Ok(String::new())
|
||||
}
|
||||
"mcp" => {
|
||||
if let Some(target) = a.flag("bridge") {
|
||||
if src.is_some() || a.flag("plugins").is_some() {
|
||||
return Err("mcp --bridge acts on the open AniCraft window: it takes no file or --plugins".into());
|
||||
}
|
||||
let mut b = control::Bridge::new(control::parse_bridge_target(target)?);
|
||||
let stdin = std::io::stdin();
|
||||
let mut stdout = std::io::stdout();
|
||||
mcp::serve(&mut b, stdin.lock(), &mut stdout).map_err(|e| e.to_string())?;
|
||||
return Ok(String::new());
|
||||
}
|
||||
let mut s = session(&a, src)?;
|
||||
let stdin = std::io::stdin();
|
||||
let mut stdout = std::io::stdout();
|
||||
|
||||
+68
-14
@@ -6,6 +6,10 @@
|
||||
//! frame as a picture. Everything still goes through `Session::execute`, so undo, validation
|
||||
//! and the confirmation tiers (ADR 0004: `"confirm": true` before irreversible loss) apply to
|
||||
//! an assistant exactly as to the app.
|
||||
//!
|
||||
//! The same tools drive the desktop app live (ADR 0104): the app runs [`call_tool`] on its own
|
||||
//! session for requests from its control port, and `anicraft-cli mcp --bridge <port>` is this
|
||||
//! server with a [`Backend`] that forwards each tool call there (`crate::control`).
|
||||
|
||||
use anicraft_engine::{Session, commands};
|
||||
use serde_json::{Value, json};
|
||||
@@ -20,7 +24,8 @@ const MAX_PICTURE_EDGE: f32 = 2048.0;
|
||||
/// Most steps in one `anicraft_run_script` call.
|
||||
const MAX_STEPS: usize = 10_000;
|
||||
|
||||
const INSTRUCTIONS: &str = "AniCraft is a 2D animation studio. Every edit is a command: call \
|
||||
/// The headless server's instructions (an in-process document no one sees).
|
||||
pub const INSTRUCTIONS: &str = "AniCraft is a 2D animation studio. Every edit is a command: call \
|
||||
anicraft_commands to find one (filter by words such as 'tween' or 'export'), then anicraft_run \
|
||||
with its id and params, or anicraft_run_script for several in order. Frames in params are \
|
||||
0-based. Commands act on the current scene, layer, frame and selection, which anicraft_document \
|
||||
@@ -28,7 +33,8 @@ reports. Use anicraft_render to see a frame. Edits can be undone with edit.undo.
|
||||
would lose work or replace a file refuse until params include \"confirm\": true; ask the person \
|
||||
before confirming.";
|
||||
|
||||
fn tools() -> Value {
|
||||
/// The tools, as `tools/list` returns them. The desktop app's control port lists the same.
|
||||
pub fn tools() -> Value {
|
||||
json!([
|
||||
{
|
||||
"name": "anicraft_commands",
|
||||
@@ -95,21 +101,46 @@ fn error(id: Value, code: i64, message: impl Into<String>) -> Value {
|
||||
json!({"jsonrpc": "2.0", "id": id, "error": {"code": code, "message": message.into()}})
|
||||
}
|
||||
|
||||
fn text_result(v: &Value, is_error: bool) -> Value {
|
||||
/// A tool result holding `v` as text (pretty JSON unless it is a string).
|
||||
pub fn text_result(v: &Value, is_error: bool) -> Value {
|
||||
let text = if let Value::String(s) = v { s.clone() } else { serde_json::to_string_pretty(v).unwrap_or_default() };
|
||||
json!({"content": [{"type": "text", "text": text}], "isError": is_error})
|
||||
}
|
||||
|
||||
/// Where tools run: a session, and how a command runs on it. The headless server uses the
|
||||
/// [`Session`] itself; the desktop app runs commands through its own follow-up (the status
|
||||
/// line, the view a new document resets), as for the person's own edits.
|
||||
pub trait Host {
|
||||
fn session(&self) -> &Session;
|
||||
/// Runs one command; the error is the engine's message.
|
||||
fn execute(&mut self, id: &str, params: &Value) -> Result<Value, String>;
|
||||
}
|
||||
|
||||
impl Host for Session {
|
||||
fn session(&self) -> &Session {
|
||||
self
|
||||
}
|
||||
fn execute(&mut self, id: &str, params: &Value) -> Result<Value, String> {
|
||||
Session::execute(self, id, params).map_err(|e| e.to_string())
|
||||
}
|
||||
}
|
||||
|
||||
/// Whether a tool can change the document (the app holds these back while the person is in
|
||||
/// the middle of a drag or typing, so the two edits never share an undo step).
|
||||
pub fn tool_changes_document(name: &str) -> bool {
|
||||
!matches!(name, "anicraft_commands" | "anicraft_document" | "anicraft_render")
|
||||
}
|
||||
|
||||
/// Runs one tool. Tool failures are results with `isError` (so the assistant can read and
|
||||
/// correct them); only malformed calls are protocol errors.
|
||||
fn call_tool(s: &mut Session, name: &str, args: &Value) -> Result<Value, String> {
|
||||
let run = |s: &mut Session, step: &Value| -> Result<Value, String> {
|
||||
pub fn call_tool<H: Host + ?Sized>(h: &mut H, name: &str, args: &Value) -> Result<Value, String> {
|
||||
let run = |h: &mut H, step: &Value| -> Result<Value, String> {
|
||||
let id = step.get("command").and_then(Value::as_str).ok_or("missing \"command\"")?;
|
||||
let params = step.get("params").cloned().unwrap_or_else(|| json!({}));
|
||||
if !params.is_object() {
|
||||
return Err(format!("{id}: \"params\" must be an object"));
|
||||
}
|
||||
s.execute(id, ¶ms).map_err(|e| format!("{id}: {e}"))
|
||||
h.execute(id, ¶ms).map_err(|e| format!("{id}: {e}"))
|
||||
};
|
||||
Ok(match name {
|
||||
"anicraft_commands" => {
|
||||
@@ -125,8 +156,11 @@ fn call_tool(s: &mut Session, name: &str, args: &Value) -> Result<Value, String>
|
||||
.collect();
|
||||
text_result(&Value::Array(list), false)
|
||||
}
|
||||
"anicraft_run" => match run(s, args) {
|
||||
Ok(v) => text_result(&json!({"result": v, "revision": s.revision, "frame": s.frame, "scene": s.scene}), false),
|
||||
"anicraft_run" => match run(h, args) {
|
||||
Ok(v) => {
|
||||
let s = h.session();
|
||||
text_result(&json!({"result": v, "revision": s.revision, "frame": s.frame, "scene": s.scene}), false)
|
||||
}
|
||||
Err(e) => text_result(&Value::String(e), true),
|
||||
},
|
||||
"anicraft_run_script" => {
|
||||
@@ -136,15 +170,17 @@ fn call_tool(s: &mut Session, name: &str, args: &Value) -> Result<Value, String>
|
||||
}
|
||||
let mut results = Vec::with_capacity(steps.len());
|
||||
for (i, step) in steps.iter().enumerate() {
|
||||
match run(s, step) {
|
||||
match run(h, step) {
|
||||
Ok(v) => results.push(v),
|
||||
Err(e) => return Ok(text_result(&json!({"failed_step": i + 1, "error": e, "done": results}), true)),
|
||||
}
|
||||
}
|
||||
let s = h.session();
|
||||
text_result(&json!({"results": results, "revision": s.revision, "frame": s.frame}), false)
|
||||
}
|
||||
"anicraft_document" => text_result(&s.info(), false),
|
||||
"anicraft_document" => text_result(&h.session().info(), false),
|
||||
"anicraft_render" => {
|
||||
let s = h.session();
|
||||
let frame = match args.get("frame") {
|
||||
None | Some(Value::Null) => s.frame,
|
||||
Some(v) => v.as_u64().and_then(|f| u32::try_from(f).ok()).ok_or("\"frame\" must be a whole number from 0")?,
|
||||
@@ -173,8 +209,26 @@ fn call_tool(s: &mut Session, name: &str, args: &Value) -> Result<Value, String>
|
||||
})
|
||||
}
|
||||
|
||||
/// What answers `tools/call`: the in-process session (headless), or the desktop app through
|
||||
/// its control port (`--bridge`, `crate::control::Bridge`).
|
||||
pub trait Backend {
|
||||
/// The `instructions` the server gives the assistant at `initialize`.
|
||||
fn instructions(&self) -> &'static str;
|
||||
/// A `tools/call` result, or the message of a protocol error (a malformed call).
|
||||
fn call(&mut self, name: &str, args: &Value) -> Result<Value, String>;
|
||||
}
|
||||
|
||||
impl Backend for Session {
|
||||
fn instructions(&self) -> &'static str {
|
||||
INSTRUCTIONS
|
||||
}
|
||||
fn call(&mut self, name: &str, args: &Value) -> Result<Value, String> {
|
||||
call_tool(self, name, args)
|
||||
}
|
||||
}
|
||||
|
||||
/// Answers one JSON-RPC message; `None` for notifications (and responses), which get no reply.
|
||||
pub fn handle(s: &mut Session, line: &str) -> Option<Value> {
|
||||
pub fn handle<B: Backend + ?Sized>(s: &mut B, line: &str) -> Option<Value> {
|
||||
let msg: Value = match serde_json::from_str(line.trim_start_matches('\u{feff}')) {
|
||||
Ok(v) => v,
|
||||
Err(e) => return Some(error(Value::Null, -32700, format!("parse error: {e}"))),
|
||||
@@ -198,7 +252,7 @@ pub fn handle(s: &mut Session, line: &str) -> Option<Value> {
|
||||
"protocolVersion": version,
|
||||
"capabilities": {"tools": {"listChanged": false}},
|
||||
"serverInfo": {"name": "anicraft", "title": "AniCraft", "version": env!("CARGO_PKG_VERSION")},
|
||||
"instructions": INSTRUCTIONS
|
||||
"instructions": s.instructions()
|
||||
})
|
||||
}
|
||||
"ping" => json!({}),
|
||||
@@ -206,7 +260,7 @@ pub fn handle(s: &mut Session, line: &str) -> Option<Value> {
|
||||
"tools/call" => {
|
||||
let Some(name) = params.get("name").and_then(Value::as_str) else { return Some(error(id, -32602, "tools/call needs a tool \"name\"")) };
|
||||
let args = params.get("arguments").cloned().unwrap_or_else(|| json!({}));
|
||||
match call_tool(s, name, &args) {
|
||||
match s.call(name, &args) {
|
||||
Ok(v) => v,
|
||||
Err(e) => return Some(error(id, -32602, e)),
|
||||
}
|
||||
@@ -218,7 +272,7 @@ pub fn handle(s: &mut Session, line: &str) -> Option<Value> {
|
||||
|
||||
/// The stdio loop: one message per line in, one reply per line out, until stdin closes.
|
||||
/// Nothing but protocol messages is written to `out` (logs would corrupt the stream).
|
||||
pub fn serve<R: BufRead, W: Write>(s: &mut Session, input: R, out: &mut W) -> std::io::Result<()> {
|
||||
pub fn serve<B: Backend + ?Sized, R: BufRead, W: Write>(s: &mut B, input: R, out: &mut W) -> std::io::Result<()> {
|
||||
for line in input.lines() {
|
||||
let line = line?;
|
||||
if line.trim().is_empty() {
|
||||
|
||||
@@ -0,0 +1,99 @@
|
||||
# ADR 0104: A live control port, so assistants edit the open window
|
||||
|
||||
* Status: accepted (2026-11-12)
|
||||
* Relates to: ADR 0004 (destructive actions), ADR 0005 (typography), ADR 0006 (platforms),
|
||||
ADR 0040 (interface languages), `docs/mcp.md`, `docs/control-protocol.md`
|
||||
|
||||
## Context
|
||||
|
||||
`anicraft-cli mcp` gives AI assistants the engine's commands as five MCP tools, but it edits a
|
||||
document inside its own process, with no window. To see the result the person saves, then opens
|
||||
the file in the app. Every edit is invisible until then, and the assistant and the person can
|
||||
never work on the same document at once.
|
||||
|
||||
The sister apps (VectorCraft, CadCraft, FilmCraft, EffectCraft) already let an assistant drive the
|
||||
open window through a TCP port on `127.0.0.1`, with a line-per-message JSON protocol and an MCP
|
||||
"bridge" that forwards to it. AniCraft should behave the same way.
|
||||
|
||||
One lesson from FilmCraft: its token was an environment variable, which a desktop shortcut's
|
||||
process received and an MCP server started by the assistant's desktop app did not. Authentication
|
||||
must not depend on an environment variable reaching two unrelated processes.
|
||||
|
||||
## Decision
|
||||
|
||||
1. **`anicraft --control <port>`** (also `ANICRAFT_CONTROL_PORT`; the flag wins) opens a control
|
||||
port on `127.0.0.1` only. 9878 is the convention (after EffectCraft's 9877). A bad port is an
|
||||
error before any window opens. If the port can't be opened (in use), the window opens anyway
|
||||
and the status bar says why.
|
||||
2. **The protocol is small** (`docs/control-protocol.md`): one JSON object per line each way,
|
||||
persistent connections, answered in order. Methods: `hello`, `tools.list`, `tools.call`.
|
||||
Replies are `{"id", "ok": true, "result"}` or `{"id", "ok": false, "error"}`.
|
||||
3. **One dispatcher for live and headless.** The app depends on the `anicraft-cli` library and
|
||||
runs its `mcp::call_tool` and `mcp::tools` on the window's session. `call_tool` is generic over
|
||||
a small `Host` trait (the session, and how a command runs), so the app runs commands through
|
||||
its own follow-up (`App::announce`: the status line, the view a new document resets, Open
|
||||
Recent), as for the person's own edits.
|
||||
|
||||
*Considered:* a new crate for the dispatcher, used by both. It would have to be L4 (it needs
|
||||
the engine and the renderer), and the CLI (L4) may not depend on a crate in its own layer, so
|
||||
the CLI would have to move up beside the shell. The shell (L5) depending on the CLI library
|
||||
(L4) fits the layering as it is, adds no crate, and the CLI library has no dependency the shell
|
||||
doesn't already have (except `getrandom`, below). The CLI's library already was the MCP server;
|
||||
it now also holds the control port's protocol, its listener threads and the bridge client
|
||||
(`crates/cli/src/control.rs`), none of which touches the UI toolkit, so they are tested there.
|
||||
4. **Threads, and the frame.** One listener thread and one thread per connection (at most 16). A
|
||||
tool call goes to the UI thread through a channel with a reply sender; the connection thread
|
||||
wakes the window (`request_repaint`). The frame loop runs waiting calls at the start of the
|
||||
frame, before anything draws, so their edits show in the same frame (AGENTS.md "edits are
|
||||
live"). The window never takes focus. An edit made behind the start screen (ADR 0059)
|
||||
closes it, so the person sees the document change.
|
||||
5. **The person's own gestures.** An edit from a tool must not join the person's undo step. While
|
||||
the person is dragging (pointer held, a stage drag, or a plug-in dialog previewing), calls that
|
||||
can change the document wait (calls that only read don't). A call that waited 60 s is refused
|
||||
without running, and the client is told so. An open gesture that is only typing (a property
|
||||
field still focused) is committed first, as its own undo step, as clicking elsewhere would do;
|
||||
waiting for that could block an assistant indefinitely.
|
||||
|
||||
*Considered:* committing the gesture mid-drag. The rest of the drag would then record one undo
|
||||
step per frame, so we wait instead.
|
||||
6. **Authentication: a token file, no setup.** Each run with `--control` makes a fresh 32-byte
|
||||
token from the operating system's random numbers (`getrandom`, MIT OR Apache-2.0, already in
|
||||
the tree) and writes `control.json` (`port`, `token`, `pid`, `version`) to the AniCraft settings
|
||||
folder, owner-only on macOS and Linux (`%APPDATA%` is already private on Windows). It is
|
||||
replaced at start and removed on exit if it still holds this run's token. Every request carries
|
||||
the token; a missing or wrong token is refused and the connection closed before anything runs.
|
||||
`ANICRAFT_CONTROL_TOKEN`, when set, is the token on both sides (CI, power users).
|
||||
|
||||
The CLI can't use the shell's `platform::config_dir`, so it has its own copy of the folder rule
|
||||
(`control::settings_dir`) and a shell test keeps the two equal.
|
||||
|
||||
*Considered:* no authentication (VectorCraft, CadCraft, EffectCraft). Any local process, and a
|
||||
web page able to reach localhost, could then edit and save files as the person. *Considered:*
|
||||
an environment-variable token only (FilmCraft): see Context.
|
||||
7. **Hardening, as in the sister apps.** Every line must be a JSON object with a string `method`;
|
||||
anything else gets one error line and the connection closes. That also refuses a web page's
|
||||
`fetch` to localhost, which starts with an HTTP request line. Lines are capped at 4 MiB. Writes
|
||||
time out after 10 s so a client that stops reading can't hold a thread.
|
||||
8. **Safety rules unchanged.** Calls run through `Session::execute`, so `"confirm": true` (ADR 0004)
|
||||
is needed exactly as headless, unsaved-work guards and crash recovery see the edits as the
|
||||
person's, and every edit undoes with Ctrl+Z.
|
||||
9. **`anicraft-cli mcp --bridge <port | 127.0.0.1:port>`** is the MCP server with a backend that
|
||||
forwards `tools/call` to the app; `initialize` and `tools/list` are answered locally (the same
|
||||
tool list), so the server starts and lists its tools before AniCraft is open. It connects on
|
||||
the first call and returns an error that says how to start the app when it can't. It reconnects
|
||||
after a break (an app that quit is noticed before the next request is sent). An edit whose reply
|
||||
was lost is never sent again (the app may have made it); a call that only reads is tried once
|
||||
more. Hosts other than this computer are refused.
|
||||
10. **Visible.** While the port is open the status bar says "Remote control on (port N)" (through
|
||||
`tr!` and `theme::Type`), with a tooltip saying what that means.
|
||||
|
||||
## Consequences
|
||||
|
||||
* The shell now builds the CLI library (small; nothing new for the web build, which leaves the
|
||||
control port out).
|
||||
* The tool behaviour can't drift between live and headless: one function serves both, and a test
|
||||
checks that a call through the port answers as `call_tool` does.
|
||||
* Remote edits arrive at most once per frame batch; a long `anicraft_run_script` blocks the window
|
||||
while it runs, as a long menu command would.
|
||||
* Not yet: a screenshot tool that returns the window itself (the app already captures itself for
|
||||
`--screenshot`).
|
||||
@@ -0,0 +1,103 @@
|
||||
# The live control port
|
||||
|
||||
`anicraft --control <port>` opens the AniCraft window as usual and also listens on a port on this
|
||||
computer, so an assistant (or a script) can edit the open document while you watch. Every edit
|
||||
appears in the window at once and undoes with Ctrl+Z, like your own. The status bar says
|
||||
"Remote control on (port N)" while it is open. ADR 0104 records the design.
|
||||
|
||||
Most people never speak this protocol themselves: AI assistants reach it through
|
||||
`anicraft-cli mcp --bridge <port>` (see `docs/mcp.md`).
|
||||
|
||||
```sh
|
||||
anicraft --control 9878 # 9878 by convention
|
||||
ANICRAFT_CONTROL_PORT=9878 anicraft # the same; --control wins over the variable
|
||||
```
|
||||
|
||||
## Transport
|
||||
|
||||
* TCP on `127.0.0.1` only.
|
||||
* One JSON object per line (UTF-8, `\n`; a `\r` before it is ignored), each way.
|
||||
* Connections stay open; requests on one connection are answered in order.
|
||||
|
||||
## Authentication
|
||||
|
||||
Each run makes a fresh token: 64 hex digits from the operating system's random numbers. The app
|
||||
writes it to `control.json` in AniCraft's settings folder:
|
||||
|
||||
| System | File |
|
||||
|---|---|
|
||||
| Windows | `%APPDATA%\AniCraft\control.json` |
|
||||
| macOS | `~/Library/Application Support/AniCraft/control.json` |
|
||||
| Linux | `$XDG_CONFIG_HOME/anicraft/control.json` (default `~/.config/anicraft/`) |
|
||||
|
||||
```json
|
||||
{"port": 9878, "token": "3f1c…", "pid": 12345, "version": "0.2.1"}
|
||||
```
|
||||
|
||||
On macOS and Linux the file is readable only by you; on Windows the settings folder already is.
|
||||
It is replaced when AniCraft starts with `--control` and removed when it closes. A program running
|
||||
as you finds the token there, with nothing to copy into its settings.
|
||||
|
||||
If `ANICRAFT_CONTROL_TOKEN` is set, it is the token instead (set it for both the app and the
|
||||
client: CI, power users).
|
||||
|
||||
Every request carries `"token"`. A missing or wrong token gets an error and the connection
|
||||
closes before anything runs.
|
||||
|
||||
## Requests and replies
|
||||
|
||||
```json
|
||||
{"id": 1, "token": "…", "method": "hello"}
|
||||
{"id": 1, "ok": true, "result": {"app": "AniCraft", "version": "0.2.1", "protocol": 1}}
|
||||
```
|
||||
|
||||
`id` is any JSON value and comes back as it was. A reply is `{"id", "ok": true, "result"}` or
|
||||
`{"id", "ok": false, "error": "message"}`.
|
||||
|
||||
| Method | Params | Result |
|
||||
|---|---|---|
|
||||
| `hello` | | `{app, version, protocol}` |
|
||||
| `tools.list` | | the tools, exactly as MCP `tools/list` lists them (`docs/mcp.md`) |
|
||||
| `tools.call` | `{name, arguments}` | exactly what MCP `tools/call` returns: `{content: […], isError}` |
|
||||
|
||||
`tools.call` runs the same code as the headless MCP server. A tool that fails (a command's error)
|
||||
is a result with `"isError": true`; a malformed call (an unknown tool, a missing `name`) is an
|
||||
`"ok": false` reply.
|
||||
|
||||
```json
|
||||
{"id": 2, "token": "…", "method": "tools.call", "params": {"name": "anicraft_run", "arguments": {"command": "draw.rect", "params": {"x": 10, "y": 10, "w": 50, "h": 50}}}}
|
||||
{"id": 2, "ok": true, "result": {"content": [{"type": "text", "text": "{\"frame\": 0, \"result\": {…}, \"revision\": 3, \"scene\": 0}"}], "isError": false}}
|
||||
```
|
||||
|
||||
## When calls run
|
||||
|
||||
The window runs calls at the start of a frame, so an edit shows in that frame. It never takes
|
||||
keyboard focus and doesn't need to be the front window. An edit made while the start screen is showing closes it, so you see
|
||||
the document it changed.
|
||||
|
||||
While you are dragging (or a plug-in dialog is previewing), calls that could change the document
|
||||
wait until you let go, so your drag and the assistant's edit stay separate undo steps. Calls that
|
||||
only read run at once. If you were typing in a field, your change is kept as its own undo step
|
||||
first. A call that waited 60 seconds is not run, and its reply says so.
|
||||
|
||||
Commands that would lose work or replace a file still need `"confirm": true` (ADR 0004).
|
||||
|
||||
## Limits
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Line length | 4 MiB; a longer line gets an error and the connection closes |
|
||||
| Connections | 16 at once; another gets an error line and is closed |
|
||||
| Waiting | 60 s per call |
|
||||
| First line | must be a JSON object with a string `"method"`, or the connection closes (this also refuses a web page's request to localhost) |
|
||||
|
||||
## Trying it by hand
|
||||
|
||||
With AniCraft open with `--control 9878`, in PowerShell:
|
||||
|
||||
```powershell
|
||||
$t = (Get-Content "$env:APPDATA\AniCraft\control.json" | ConvertFrom-Json).token
|
||||
$c = New-Object Net.Sockets.TcpClient 127.0.0.1, 9878
|
||||
$w = New-Object IO.StreamWriter $c.GetStream(); $r = New-Object IO.StreamReader $c.GetStream()
|
||||
$w.WriteLine("{""id"":1,""token"":""$t"",""method"":""hello""}"); $w.Flush(); $r.ReadLine()
|
||||
```
|
||||
+30
@@ -8,8 +8,22 @@ look at frames and export through the same commands the app uses.
|
||||
anicraft-cli mcp # a new, empty document
|
||||
anicraft-cli mcp scene.anicraft # open a document
|
||||
anicraft-cli mcp --sample # the sample animation
|
||||
anicraft-cli mcp --bridge 9878 # the AniCraft window you have open (below)
|
||||
```
|
||||
|
||||
## Headless or live
|
||||
|
||||
Without `--bridge` the server edits a document of its own, with no window: good for pipelines and
|
||||
batch work. Save it (`file.save`) to keep the result.
|
||||
|
||||
With `--bridge <port>` the same tools act on the AniCraft window you have open, started with
|
||||
`anicraft --control <port>`: every edit appears there at once, and Ctrl+Z undoes it
|
||||
(`docs/control-protocol.md`, ADR 0104). The server starts even when AniCraft isn't open (an
|
||||
assistant starts its servers when it starts) and connects on the first tool call; until AniCraft is
|
||||
open with remote control, the tools answer with how to start it. Close and reopen AniCraft whenever
|
||||
you like: the next call reconnects, with no need to restart the assistant. It finds the run's token
|
||||
in `control.json` in AniCraft's settings folder, so there is nothing to copy.
|
||||
|
||||
The server talks MCP's stdio transport: JSON-RPC 2.0, one message per line on stdin and stdout.
|
||||
It speaks protocol revisions 2025-06-18, 2025-03-26 and 2024-11-05.
|
||||
|
||||
@@ -28,6 +42,19 @@ Most clients take a server entry like this one (use the full path to `anicraft-c
|
||||
}
|
||||
```
|
||||
|
||||
For live editing, start AniCraft with `--control 9878` (a desktop shortcut is handy) and use:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"anicraft": {
|
||||
"command": "C:\\path\\to\\anicraft-cli.exe",
|
||||
"args": ["mcp", "--bridge", "9878"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Tools
|
||||
|
||||
| Tool | What it does |
|
||||
@@ -59,3 +86,6 @@ unlike `anicraft_run_script` a failing step leaves the document as it was. `macr
|
||||
save, import, export), as with the CLI. Only connect clients you trust with those files.
|
||||
* A failing command comes back as a tool result marked as an error, so the assistant can read
|
||||
the message and try again; it never stops the server.
|
||||
* Live (`--bridge`): an edit whose answer was lost (AniCraft closed mid-call) is never sent again,
|
||||
since it may have been made; the assistant is told to check with `anicraft_document`. While you
|
||||
are dragging, the assistant's edits wait until you let go, so the two stay separate undo steps.
|
||||
+1
-1
@@ -18,7 +18,7 @@ This integration depends on craft-libs #1962 and still requires hosted parity va
|
||||
| Drawing | Selection (click, shift-add, marquee, drag-move, arrow nudge; **across layers**, ADR 0044: a selection holds artwork on several visible, unlocked layers, the timeline marks them, Properties shows mixed values), **Free Transform (Q)**: scale from corner/edge handles (Shift proportional, Alt from centre), rotate outside corners (Shift snaps 15°), move; one undo step per drag. Rectangle (corner radius), oval, PolyStar, line (45° snap), hand, zoom. **Pen (P)**: click for corners, drag for smooth handles (Alt breaks them), close on the first point, Enter/Esc/last-point click finishes, Backspace takes back a point; one undo step per path. **Pencil (Shift+Y)**: Smooth (Schneider curve fitting with corner detection), Straighten and Ink modes, smoothing relative to the screen. **Subselection (A)**: anchors and handles on selected shapes, drag points/handles (anchors bring their handles; one undo step per drag), point marquee, double-click an edge to add a point, Delete removes points, right-click Make Smooth/Corner; closed shapes' start point and closing edge edit like any other. **Cut/Copy/Paste in Center/Paste in Place** (the clipboard carries symbols across documents). **Rotate 90° CW/CCW, Flip H/V. Align** left/centre/right/top/middle/bottom (Ctrl+Alt+1…6; a single element aligns to the stage) and distribute. Convert to symbol / break apart; arrange; duplicate. Headless: `draw.path`, `draw.freehand`, `path.move_points/add_point/delete_points/convert_point`. **Paint Bucket (K)**: click a fill to recolour it, or inside an outline (one shape or several) to fill the enclosed area; gap size None/Small/Medium/Large closes openings; the fill is traced and curve-fitted into a new shape placed under its lines; open areas say so instead of flooding. **Ink Bottle (S)**: gives the clicked shape the current stroke. Headless: `paint.bucket`, `paint.ink`. Tool options show first in Properties while a drawing tool is active. **Text (T)** (ADR 0012): click to type on the stage, click or double-click text to edit it; font (installed families, plus the embedded Inter), size, colour, under or over the artwork, snap accuracy up to Always); Snap to Pixels; one snap engine for every drawing tool, the Selection tool's moves and Free Transform's handles (point › guide › line › grid › pixel, guides and grid per axis); stage only, never exported, on the CPU and GPU stage. Headless: `view.rulers`, `view.grid_show/grid_snap/grid_set`, `view.guides_show/guides_lock/guides_snap/guides_set`, `view.guide_add/guide_move/guide_delete/guides_clear`, `view.snap_pixels`, `view.aids`, `moving` on `draw.snap`. *Not yet:* units other than px, a movable ruler origin, a symbol's own guides, guides and grid from Animate files, Snap Align and Edit Snapping, snapping while rotating. bold, italic, alignment, letter/line spacing, wrap width; the last style is kept for new text; laid out by `anicraft-text` (`fontdb` discovery, `harfrust` shaping, `skrifa` outlines) and stored as outlines with the source, so rendering never needs the font; Break Apart makes a shape. **Variable-width strokes** (ADR 0018): a stroke's width varies along it through width points (position by arc length, a width on each side as a factor of the stroke width, smooth monotone interpolation); built-in profiles (Uniform, Taper both ends, Taper start, Taper end, Bulge, Pinch) in Properties › Width with a picture of each, and in the drawing tools' options for new strokes; the **Width tool (U)**: hover a stroke to see its width points, drag a handle to widen or narrow (Alt: one side), drag the dot to slide a point, drag anywhere on the stroke to add one, Delete removes; one undo step per drag; rendered by the oracle as trapezoids with outer round joins and cross-section caps, written by SVG and Lottie export as the same filled outlines; shape tweens blend profiles; `.anicraft` keeps them (older files open as uniform). Headless: `stroke.set_profile`, `stroke.set_width_point`, `stroke.delete_width_point`, `stroke.width_at`, `profile` on `element.set_stroke`, the drawing commands and `paint.ink`. Not yet: width data from or to Animate files, saved custom profiles, pressure. **Stroke styles** (ADR 0046): Properties › Style (Solid, Dashed with dash and gap, Dotted with spacing), Cap (None, Round, Square), Join (Miter, Round, Bevel) and Miter limit, also in the drawing tools' options for new strokes; drawn exactly by the oracle (butt and square caps, miters bevelled past the limit, dashes by arc length restarting per subpath, round dots, dashes keeping a width profile's widths; sub-pixel patterns solid and faded) and so by the GPU stage; the Ink Bottle carries the style and the Eyedropper picks it; merge drawing keeps it on cut pieces; shape tweens blend miter limits and dash lengths; SVG, HTML canvas and Lottie export write it. Headless: `stroke.set_style`, and `cap`, `join`, `miter`, `style`, `dash`, `dash_offset`, `dot_spacing` on `element.set_stroke`, the drawing Line truncated
|
||||
| Plug-ins | **WebAssembly plug-ins** (ADR 0017, `docs/plugins.md`): sandboxed modules run by `wasmi` with no imports but the AniCraft ABI (`anicraft.call`/`anicraft.response`: JSON requests that run registry commands, read a compact document view or the active layer's elements, and log); fuel (10⁹ instructions), memory (256 MiB), wall-clock (5 s), request, size and log limits, a fresh instance per run; file, plug-in, undo and clipboard commands refused. `plugin.install/list/run/remove/reload`; a run is atomic and one undo step named after the plug-in. App: **Commands** menu (Plug-ins, Install, Manage, Reload), palette entries, a dialog generated from the manifest's parameters with a live preview; plug-ins load from `<settings>/plugins` or `ANICRAFT_PLUGINS`; CLI `--plugins`. Samples in Rust (Star Field, Jitter Selection, guest SDK) in `examples/plugins`. Frame scripts: see Interactivity. **Exporter and ease plug-ins** (ADR 0088): `kind: "exporter"` declares a format (name, extension, options) and gets evaluated frames (`movie`, `frame`: the flattened display list, never the document), returning the file's bytes from `ac_export` (64 MiB cap, 5·10¹⁰ instructions, 10 min); File › Export lists it with an Export window (options, frames, file, progress bar and Cancel on a worker thread); `file.export_plugin`, `file.export_formats`, `anicraft-cli export --format <id>` and `formats`. `kind: "ease"` declares named eases, `ac_ease(i, t)` sampled into 257 values at load (NaN, unbounded or end-missing eases refused); `Easing::Sampled` keeps the table in the document, so it plays the same without the plug-in; the ease menus list them under Plug-in eases; `{plugin, ease}` easing params. Samples: Plain Text Frames and Stepped Eases, built and run in CI. Not yet: plug-in formats in Publish, bitmaps' pixels and sounds for exporters, ease plug-ins with parameters, background runs of command plug-ins, a binary document view. |
|
||||
| Interactivity | **Frame actions, frame scripts and Test Movie, first slice** (ADR 0024): a typed timeline action IR (`anicraft-actions`: stop, play, go to a frame or label in a scene, next/previous frame and scene, trace, set x/y/alpha/visible/rotation/scale, instance-name target paths) on keyframes and on button and movie clip instances (click, press, release, over, out); a pure, deterministic, budgeted player in `anicraft-doc` (`step(doc, &state, &events)`; movie clip playheads, button Up/Over/Down states with Hit-frame hit tests, script-set properties) drawn by `evaluate_player`, while `evaluate` and exports stay script-free. **Actions panel** (F9: structured lists, targets/labels/scenes picked from the document; movie clip timelines too), instance name and events in Properties, an "a" on keyframes with actions. **Frame scripts** on the plug-in host (`kind: "frame-script"`, entry points, `player`/`action` ops, 20 M instructions per frame shared, no document access). **Test Movie** (Control › Test Movie, Ctrl+Enter): the player at the document frame rate in its own window with the pointer, restart/pause/step and an Output panel. **A window of its own on the desktop** (ADR 0062): sized to the stage at 100 % (smaller to fit the screen), titled with the document, back where it was last (not on Wayland, where the desktop places windows), with the keyboard when it opens; Esc or Ctrl+W (⌘W) closes it, Ctrl+Enter restarts it in place, and the editor's Ctrl/Alt shortcuts work from it; floating inside the editor in the web build, where the system can't open windows (it says so), or by choice in Preferences › Test Movie. Not yet: full screen, zoom in the movie window, remembering its size. Headless: `actions.set/clear/list`, `instance.set_name`, `control.test_movie` (timed pointer events, returns output and state). **HTML canvas export** (ADR 0028, `file.export_html`, File › Export › Export HTML Canvas…): one self-contained page (data, player and drawing code inline; images and sounds embedded) that plays in any browser with canvas 2D; every used timeline baked frame by frame (tweens of every kind exact, identical paths, paints and frames stored once), movie clips, buttons with Hit areas and every action run by `player.js`, a port of the Rust player checked against it step by step in Boa (state, output and display list); masks and fading/blending groups on offscreen layers; **filters and Subtract/Invert in the page** (ADR 0072: `filters.js`, a port of the renderer's filters run over the group's pixels on a layer that reaches past the canvas by the filters' reach, Subtract and Invert composited per pixel, results kept while the group is unchanged; equal to the oracle's pixels within 9.3e-4 in Boa; 3.4 ms a frame for the demo's filters at 1080p while they change); Web Audio for Event/Start/Stop/Stream sounds; bitmap tints, 9-slice scaling and plug-in frame scripts reported. Not yet: 9-slice in the page, keeping a moving filtered group's pixels, filters off the main thread. **Kept frame scripts** (ADR 0013 tier 1): scripts written in another language (an Animate document's ActionScript) kept verbatim on keyframes with their language, symbol linkage classes and the document class; the Actions panel's **Script** view (monospace editor with line numbers, language, live and undoable), the same "a" marker, Class rows in Properties; `script.set/clear/list/set_class`; **ActionScript timeline subset runs** (ADR 0013 tier 2): a hand-written, bounded lexer and parser (`anicraft_actions::as3`) lower stop/play/go to/next and previous frame and scene on instance-name paths, mouse listeners (click, down, up, roll over and out; named or inline functions, `currentTarget`), `trace` and property settings to the action IR, compiled once per script; anything else is reported with line and column and the script doesn't run (never half-run), `navigateToURL` and the like are ignored and noted; the player keeps listeners per instance, Test Movie's Output says which scripts run and which don't and why, the Script view lists problems in place, the XFL report and `script.list/check` say what runs, and the HTML page runs the same steps (`player.js` checked against the Rust player). **ActionScript small logic** (ADR 0052): scripts compile to a small typed script IR evaluated by the player with fuel (100,000 per script or listener call, 1,000,000 per step; an endless loop or a run-time error stops its script with an Output line and the movie plays on): typed variables (Number, int, uint, Boolean, String, untyped) kept per timeline instance across its frame scripts, expressions as ECMA-262 has them, `if`/`else`, `for`/`while`/`do`, functions with parameters, results and recursion, called from any frame of the same timeline (a timeline-level link step; names that aren't there keep the script from running, said in place), property reads of instances and timelines (`x`, `y`, `alpha`, `visible`, `rotation`, `scaleX/Y`, `currentFrame`, `tLine truncated
|
||||
| Headless | CLI: info, render, render-seq, **gif**, **apng**, **webp**, commands, exec, run, serve (JSON-lines). **MCP server** (`anicraft-cli mcp`, `docs/mcp.md`): stdio JSON-RPC, protocol 2025-06-18 (and 2025-03-26, 2024-11-05); five tools over the command registry (list, run, run a script, describe the document, render a frame as a PNG picture); confirmation tiers and undo apply as in the app. |
|
||||
| Headless | CLI: info, render, render-seq, **gif**, **apng**, **webp**, commands, exec, run, serve (JSON-lines). **MCP server** (`anicraft-cli mcp`, `docs/mcp.md`): stdio JSON-RPC, protocol 2025-06-18 (and 2025-03-26, 2024-11-05); five tools over the command registry (list, run, run a script, describe the document, render a frame as a PNG picture); confirmation tiers and undo apply as in the app. **Live control** (ADR 0104, `docs/control-protocol.md`): `anicraft --control <port>` and `anicraft-cli mcp --bridge <port>` run the same tools on the open window, on this computer only, with a per-run token in `control.json`. |
|
||||
| Sound | **Audio layers, first slice** (ADR 0020): WAV (own reader), Ogg Vorbis (`lewton`) and MP3 (`nanomp3`) import, bounded and crash-proof; sounds live in the library, stored in `.anicraft` as imported, decoded once in the background. A sound belongs to a keyframe as in Animate (Properties › Sound: name, Sync Event/Start/Stop/Stream, Repeat ×N or Loop); Import to Stage puts one on a new layer spanning its length, Import to Library only adds it, the Library previews, places and deletes sounds. The timeline draws each sound's waveform over its span. Stage playback plays the mix through `cpal` (default feature `sound-output`) and the playhead follows the audio clock; stream sounds resync after a jump and scrubbing plays one-frame snippets. Mixing is pure and sample-exact (`doc::sound::voices` + `audio::mix`, Catmull-Rom resampling between rates). Headless: `sound.place/set/remove/rename/delete`, `file.import_to_library`, **`file.export_audio`** (WAV, 16/24-bit or float, any rate), and Export Video carries the soundtrack (Opus in WebM, AAC in MP4, by the user's ffmpeg). **Second slice** (ADR 0039): each frame sound has an **Effect** (None, Left channel, Right channel, Fade left to right, Fade right to left, Fade in, Fade out, shaped over the time it is heard, or **Custom**: up to 16 volume points per channel in the **Edit Envelope** window, drawn on each channel's waveform; the timeline's waveform follows the envelope). Layers holding sounds get a **Volume** and **Mute** (Properties, and a speaker toggle in the timeline); volumes multiply down through symbols and muted layers are silent in playback and every export. **Sounds inside symbols** play: a graphic's on its own frames mapped to the parent's time (loop mode and first frame apply; streams join mid-way and follow the parent playhead), a movie clip's on a loop from when the instance appeared; in the interactive player and **Test Movie** (which now has sound, the picture keeping time with it) movie clips start theirs as their own timelines reach them. The HTML page carries envelopes, volumes and graphic sounds. Headless: `sound.set {effect, envelope}`, `layer.set_volume`, `layer.toggle_mute`. **Sounds on button frames** (ADR 0057) play in Test Movie and the HTML page as the pointer changes the button's state (Over, Down, and Up and Hit on leaving and release, as the SWF format keeps them; never in the soundtrack); `control.test_movie` lists the sounds it starts. **XFL** brings sounds whose file is in the package (WAV, Ogg, MP3) with the sounds on frames that use them, buttons' included. **Output polish** (ADR 0095): the playhead follows the sound *heard* (the device's latency taken off, frames dropped rather than drifting; under a frame off over an hour in tests), event sounds play to their end across a loop and after the last frame (Enter stops all), a **monitor volume and mute** in the timeline header (Control › Mute Sounds; the listener's, in preferences, never in exports), **Control › Audio Scrubbing** (a slice of at least 1/20 s), a lost or missing device never crashes (silent playback, one notice, a log line, reopened on the next play; a new default device is followed), and the **web build plays sound through Web Audio**. The device sits behind an `Output` trait, so the clock and mixing paths are tested with a fake one. Not yet: sounds kept only in Animate's own data format (undocumented; reported), sound effects and in/out points from XFL, sound panning beyond the envelope, audio in Lottie, stream sounds that follow go-tos in the HTML page, lossless compression of stored WAVs, choosing an output device other than the system's default, `stopAllSounds` as a timeline action. |
|
||||
| Files | `.anicraft` JSON load/save (v3, with scenes; v1 and v2 files open as one scene), PNG frame and sequence export, **animated GIF export** (parallel render and quantize, exact frame timing, looping), **animated PNG and animated WebP export** (WebP container writing delegates to shared `craft-webp`; APNG framing remains app-local; ADR 0063: full colour and real alpha, transparent or on the stage colour; every frame exactly the renderer's; repeated frames merged into longer delays; later frames only the rectangle that changed (APNG blends opaque changes over, WebP replaces); APNG delays exact fractions of the frame rate, WebP milliseconds that never drift; loop forever, once or N times; File › Export, Publish Settings, the web build's downloads, `anicraft-cli apng`/`webp`; not yet: lossy WebP (no permissive pure-Rust VP8 encoder exists), dispose-to-background frames, palette or RGB APNG for smaller files), **SVG frame export** (from the same evaluated frame as the renderer: stage-space paths, renderer-matched stroke widths, caps, joins and dashes, gradients under `gradientTransform`, colour effects baked in, masks as nested `clipPath`s). **Opens Animate documents** (`.fla`, `.xfl`, XFL folders; ADR 0009; `.fla` archives in every common zip layout, ZIP64 included, and hostile ones refused with a readable error, ADR 0054): stage, first scene, layers, keyframes, labels, classic tweens with ease, shapes (solid/linear/radial fills, strokes), groups, primitives, symbol instances (matrix, alpha, tint, loop, blend mode, all seven filters), library symbols, **shape tweens**, **layer folders** and **mask layers** (masks inside folders too); imported files are untitled so Save never overwrites them; what isn't supported yet is reported after opening. One damaged bitmap, sound or library symbol is left out and reported rather than refusing the whole file (#226), and a document without a stage colour gets Animate's default white (#163). Every scene comes across. **Bitmaps**: library items whose image is in the package as PNG or JPEG (the original in `LIBRARY/`, else the `bin/` data file when it is PNG or JPEG), instances, and bitmap fills with their matrix (twips scale removed; repeating unless clipped); Animate's own bitmap encodings are not public and are reported, not decoded. **Text** (ADR 0014): static, dynamic and input text fields become text blocks laid out by `anicraft-text`, with face (by PostScript name, family, or the family the name suggests; `_sans`/`_serif`/`_typewriter`), size, colour, bold/italic, alignment, letter and line spacing, margins, matrix, fixed width (wraps) or auto-size, and several lines; runs in different styles become one block per run of same-style lines, stacked as in Animate; a line mixing styles takes its main style and is counted; missing families fall back and are named in the report; dynamic/input fields come across as static text (reported). **Shape hints** on shape tweens (a tolerant self-authored `shapeHints` reader, ADR 0023). Colour effects in every style (Brightness, Tint, Advanced, Alpha; ADR 0056), movie clip and button instance names, one-segment custom eases (as cubic Béziers); a symbol without `symbolType` is a movie clip; frame comments aren't labels. Stroke caps, joins and miter limit, dashed and dotted strokes (ADR 0046; ragged, stipple and hatched are drawn solid and reported). Reported rather than silently changed: gradient strokes, repeating/reflecting, focal-point, elliptical and linear-RGB gradients, reverse loop modes, extra tween spins. A self-authored corpus with golden renders covers all of it (ADR 0035). Shared `craft-xfl` readers now parse filters, shape hints, tween easing, and frame-sound envelopes; AniCraft retains document-model mapping and validation. The XFL schema audit remains in progress, including per-character styles and motion-tween records; **frame scripts are kept** verbatim (scenes and every symbol, with the language from the publish settings), with symbol linkage classes and the document class, and the report lists them as kept, not run (ADR 0013 tier 1; scripts on instances and linkage on bitmaps and sounds are reported); **Import to Stage (Ctrl+R) for SVG drawings**: editable shapes on a new layer at the playhead, with groups, use and symbols, transforms, viewBox, styles, opacity and gradients; **clip paths and opaque masks** (ADR 0021) become mask layers in a folder named after the file (clips that cut nothing dropped, clips inside clips intersected exactly when all but one are convex polygons, curves kept), and **text** becomes text blocks, one per text chunk (position, anchor, font family list, size, weight, style, letter spacing, fill), with missing fonts named; stroke caps, joins, miter limits and dashes come across (ADR 0046); soft masks, per-character positions and text on a path are reported, as is anything else unsupported. **Sprite sheet export**: movie frames on one PNG grid (parallel render, columns/padding/scale, tranLine truncated
|
||||
| Library | **Library management, first slice** (ADR 0050): nested **folders** (New Folder, rename, drag items and folders in and out, Move to; deleting a folder that holds items asks), **inline rename** (F2 or double-click the name; names unique per folder, case aside), **Duplicate Symbol** (fresh ids, same folder, “Ball copy”), **Swap Symbol** in Properties (keeps transform, colour effect, filters, looping and name), a **use count** column, **Select Unused Items** and **Delete Unused Items** (unused = not reachable from any scene; linkage classes count as used; asks first), deleting used items asks and removes their instances, fills and keyframe sounds, **sort** by name, type, use count or date added, **search** (opens the folders that lead to a match), multiple selection, a **preview** (a symbol's first frame from the oracle, a bitmap as smoothed or not, a sound's waveform with play) and **item properties** (symbol type and linkage class, bitmap **Allow Smoothing**, which the oracle, the GPU stage, SVG and HTML honour). Folders are a side table in the document (older files open flat); XFL import keeps folders and Allow Smoothing. Headless: `library.items/new_folder/rename/move/duplicate/delete/unused/delete_unused/set_smoothing`, `element.swap_symbol`. **Second slice** (ADR 0053): **drag items onto the stage** (symbols and bitmaps land at the pointer on the active layer at the playhead, sounds go onto its keyframe; several at once; one undo step; inside a symbol open for editing too), **Place on Stage** (button, right-click, or Enter) at the centre of the view, **Swap Bitmap** in Properties (a placed bitmap keeps its corner and takes the new size; a bitmap fill keeps its shape), a **Convert to Symbol** dialog with name, type and **folder** that offers the last folder and type again, and **"mixed" on every Properties row** for several elements (Scale, Rotation, Alpha, Symbol, Type, Filters, Blending, Looping, First frame, Fill, Bitmap, Stroke, Width, Style; each row compares only the elements it edits; editing a mixed row sets all, and Type sets every selected instance's symbol). Headless: `library.place {items, x, y}` (and `sound`), `element.swap_bitmap`, `kind` and `folder` on `modify.convert_to_symbol`. **9-slice scaling** (ADR 0055): Enable guides for 9-slice scaling on a symbol (Library or Properties). Scaled instances keep their corners, stretch their edges one way and the centre both ways, and strokes keep their width. Rotation and skew apply after; nested symbols, text and bitmaps scale normally. Guides are dragged as dashed lines while editing the symbol in place, or typed in Properties. The CPU, GPU, SVG and Lottie output all show it, and XFL `scaleGrid*` attributes are imported; guides switched off are kept and come back when switched on (ADR 0057). Not yet: 9-slice in HTML canvas export (scaled as a whole and reported), guides in Library previews, snapping guides. Not yet: shared libraries and importing items from another document, linkage on bitmaps and sounds, bitmap compression, dropping files from the desktop, a picture of the item while dragging, Swap Bitmap on a Library item (every use), mixed text style rows, a Colour Effect row with tint. |
|
||||
|
||||
+10
@@ -340,6 +340,9 @@ impl PolyStarOptions {
|
||||
pub struct App {
|
||||
#[cfg(not(target_arch = "wasm32"))]
|
||||
pub(crate) updates: crate::updates::Updates,
|
||||
/// The live control port, with `--control` (ADR 0104).
|
||||
#[cfg(not(target_arch = "wasm32"))]
|
||||
pub(crate) remote: Option<crate::remote::Remote>,
|
||||
pub s: Session,
|
||||
pub tool: Tool,
|
||||
pub view: StageView,
|
||||
@@ -669,6 +672,8 @@ impl App {
|
||||
let mut app = App {
|
||||
#[cfg(not(target_arch = "wasm32"))]
|
||||
updates: Default::default(),
|
||||
#[cfg(not(target_arch = "wasm32"))]
|
||||
remote: None,
|
||||
s: session,
|
||||
tool: Tool::Select,
|
||||
view: StageView { zoom: 1.0, pan: egui::Vec2::ZERO, fit: true, fitted: None, clip_to_stage: false },
|
||||
@@ -3769,6 +3774,8 @@ impl eframe::App for App {
|
||||
self.recovery.finish(&self.s, clean);
|
||||
#[cfg(not(target_arch = "wasm32"))]
|
||||
self.updates.finish();
|
||||
#[cfg(not(target_arch = "wasm32"))]
|
||||
crate::remote::finish(self);
|
||||
}
|
||||
|
||||
fn ui(&mut self, ui: &mut egui::Ui, _frame: &mut eframe::Frame) {
|
||||
@@ -3790,6 +3797,9 @@ impl App {
|
||||
}
|
||||
}
|
||||
self.handle_screenshot(&ctx);
|
||||
// An assistant's edits (ADR 0104), before anything draws: they show in this frame.
|
||||
#[cfg(not(target_arch = "wasm32"))]
|
||||
crate::remote::poll(self, &ctx);
|
||||
self.poll_font_scan(&ctx);
|
||||
self.follow_system_look(&ctx);
|
||||
if let Some(p) = platform::picked_file() {
|
||||
|
||||
+33
-4
@@ -152,7 +152,7 @@ struct Look {
|
||||
}
|
||||
|
||||
#[cfg(not(target_arch = "wasm32"))]
|
||||
fn run(attempt: startup::Attempt, file: Option<&Path>, shot: Option<PathBuf>, open: Option<String>, look: Look) -> eframe::Result {
|
||||
fn run(attempt: startup::Attempt, file: Option<&Path>, shot: Option<PathBuf>, open: Option<String>, look: Look, control: Option<u16>) -> eframe::Result {
|
||||
let options = attempt.options(eframe::NativeOptions {
|
||||
viewport: platform::viewport(egui::ViewportBuilder::default().with_title("AniCraft").with_inner_size([1600.0, 940.0]).with_min_inner_size([960.0, 600.0])),
|
||||
..Default::default()
|
||||
@@ -184,6 +184,10 @@ fn run(attempt: startup::Attempt, file: Option<&Path>, shot: Option<PathBuf>, op
|
||||
start::open(&mut a);
|
||||
}
|
||||
a.preview_look(&cc.egui_ctx, look.theme, look.scale);
|
||||
// `--control`: an assistant can edit this window live (ADR 0104).
|
||||
if let Some(port) = control {
|
||||
remote::start(&mut a, &cc.egui_ctx, port);
|
||||
}
|
||||
a.open_panel(open.as_deref());
|
||||
match report {
|
||||
// An imported document says what came across, as opening it from the menu does.
|
||||
@@ -214,6 +218,8 @@ struct Args {
|
||||
open: Option<String>,
|
||||
renderer: Option<String>,
|
||||
look: Look,
|
||||
/// `--control <port>`: the live control port (ADR 0104).
|
||||
control: Option<u16>,
|
||||
/// `--version` / `--help`: print and leave.
|
||||
print: Option<Print>,
|
||||
}
|
||||
@@ -234,6 +240,8 @@ fn parse_args(args: impl IntoIterator<Item = String>) -> Result<Args, String> {
|
||||
match a.as_str() {
|
||||
"--screenshot" => out.shot = Some(PathBuf::from(args.next().ok_or("--screenshot needs a file name")?)), // i18n-exempt: a console message
|
||||
"--open" => out.open = args.next(),
|
||||
// i18n-exempt: a console message
|
||||
"--control" => out.control = Some(anicraft_cli::control::parse_port(&args.next().unwrap_or_default()).map_err(|e| format!("--control: {e}"))?),
|
||||
"--renderer" => out.renderer = args.next(),
|
||||
"--shot-width" => match args.next().and_then(|s| s.parse::<u32>().ok()) {
|
||||
Some(w) if (64..=8192).contains(&w) => out.look.shot_width = Some(w),
|
||||
@@ -270,7 +278,7 @@ fn parse_args(args: impl IntoIterator<Item = String>) -> Result<Args, String> {
|
||||
/// `--help` (the console's text, in English).
|
||||
#[cfg(not(target_arch = "wasm32"))]
|
||||
// i18n-exempt: the --help console text
|
||||
const HELP: &str = "anicraft [file.anicraft|file.fla|file.xfl] [--version] [--screenshot out.png [--shot-width <px>]] [--renderer gl|wgpu|vulkan|dx12|metal] [--theme graphite|high-contrast] [--scale <percent>] [--lang <code>|auto|pseudo] [--open palette|shortcuts|helpbone|lastscene|start|drop|droplibrary|select|selectzoom|about|files|confirm|transform|points|merge|rawparts|rawedit|rawsub|rawpoints|rawsnap|rulers|editguides|editgrid|symboledit|groups|combine|nineslice|nineslicedit|brush|brushing|polystar|paintinside|drawingedit|shapeenvelope|brushlibrary|brushcurve|paintbrush|eraser|erasing|erasemerge|tiltbrush|eyedropper|pen|frames|span|bucket|tlzoom|tlwide|motion|motionspan|motionpath|motionpoints|motionedit|motionpins|motionpinsspan|hints|hintsend|camera|cameraview|bones|springbones|shapebones|shapeweights|layerdepth|layerdepthview|filters|strokes|prefs|licenses|zoom|recovery|plugins|actions|script|scriptproblems|testmovie|testmovieinside|testscript|textfields|testtext|softmask|pathtext|button|testhits|exporthtml|publish|publishreport|publishanim|sound|envelope|ease|easepreset|plugineases|pluginexport|pluginexportwindow|library|librarymenu|libraryfolders|colour|layerprops|frameview|layercolour|timelinepolish|dock|dockicons|floattabs|docknarrow|workspaces|animator|designer|gradient|gradientbucket|swatches|swatchpanel]\n\
|
||||
const HELP: &str = "anicraft [file.anicraft|file.fla|file.xfl] [--version] [--screenshot out.png [--shot-width <px>]] [--renderer gl|wgpu|vulkan|dx12|metal] [--theme graphite|high-contrast] [--scale <percent>] [--lang <code>|auto|pseudo] [--control <port>] [--open palette|shortcuts|helpbone|lastscene|start|drop|droplibrary|select|selectzoom|about|files|confirm|transform|points|merge|rawparts|rawedit|rawsub|rawpoints|rawsnap|rulers|editguides|editgrid|symboledit|groups|combine|nineslice|nineslicedit|brush|brushing|polystar|paintinside|drawingedit|shapeenvelope|brushlibrary|brushcurve|paintbrush|eraser|erasing|erasemerge|tiltbrush|eyedropper|pen|frames|span|bucket|tlzoom|tlwide|motion|motionspan|motionpath|motionpoints|motionedit|motionpins|motionpinsspan|hints|hintsend|camera|cameraview|bones|springbones|shapebones|shapeweights|layerdepth|layerdepthview|filters|strokes|prefs|licenses|zoom|recovery|plugins|actions|script|scriptproblems|testmovie|testmovieinside|testscript|textfields|testtext|softmask|pathtext|button|testhits|exporthtml|publish|publishreport|publishanim|sound|envelope|ease|easepreset|plugineases|pluginexport|pluginexportwindow|library|librarymenu|libraryfolders|colour|layerprops|frameview|layercolour|timelinepolish|dock|dockicons|floattabs|docknarrow|workspaces|animator|designer|gradient|gradientbucket|swatches|swatchpanel]\n\
|
||||
--renderer the window's graphics (also ANICRAFT_RENDERER); default automatic, falling back to OpenGL\n\
|
||||
--open shows a panel at start (handy with --screenshot for visual checks)\n\
|
||||
--shot-width scales the screenshot down to this width (the user guide's pictures)\n\
|
||||
@@ -278,6 +286,8 @@ const HELP: &str = "anicraft [file.anicraft|file.fla|file.xfl] [--version] [--sc
|
||||
--theme the interface palette for this run (not saved)\n\
|
||||
--scale the interface scale for this run, 75 to 200 (not saved)\n\
|
||||
--lang the interface language for this run (not saved); pseudo tests the layout\n\
|
||||
--control lets an assistant edit this window live through a port on this computer\n\
|
||||
(also ANICRAFT_CONTROL_PORT; 9878 by convention; see docs/control-protocol.md)\n\
|
||||
Headless use: anicraft-cli --help";
|
||||
|
||||
#[cfg(not(target_arch = "wasm32"))]
|
||||
@@ -307,7 +317,21 @@ fn main() -> eframe::Result {
|
||||
}
|
||||
None => {}
|
||||
}
|
||||
let Args { shot, file, open, renderer, look, .. } = args;
|
||||
let Args { shot, file, open, renderer, look, control, .. } = args;
|
||||
// ANICRAFT_CONTROL_PORT when there is no --control; a bad port stops here, before a window.
|
||||
let control = match control {
|
||||
Some(p) => Some(p),
|
||||
None => match std::env::var(anicraft_cli::control::PORT_ENV).ok().filter(|v| !v.trim().is_empty()) {
|
||||
Some(v) => match anicraft_cli::control::parse_port(&v) {
|
||||
Ok(p) => Some(p),
|
||||
Err(e) => {
|
||||
eprintln!("{}: {e}", anicraft_cli::control::PORT_ENV);
|
||||
std::process::exit(2);
|
||||
}
|
||||
},
|
||||
None => None,
|
||||
},
|
||||
};
|
||||
// macOS hands documents over as Apple Events, the one that launched the app included: listen
|
||||
// from before the event loop starts until it ends (ADR 0062).
|
||||
let _documents = platform::listen_for_documents();
|
||||
@@ -326,7 +350,7 @@ fn main() -> eframe::Result {
|
||||
let attempts = startup::plan(platform::forced_backend(renderer.as_deref()), prefs::Prefs::load().window_backend, &platform::window_attempts(platform::OS), &last);
|
||||
for (n, attempt) in attempts.iter().enumerate() {
|
||||
startup::trying(attempt, n + 1, attempts.len());
|
||||
let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| run(*attempt, file.as_deref(), shot.clone(), open.clone(), look.clone())));
|
||||
let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| run(*attempt, file.as_deref(), shot.clone(), open.clone(), look.clone(), control)));
|
||||
why = match result {
|
||||
Ok(Ok(())) => {
|
||||
// The window's graphics device was lost mid-session (ADR 0092): it closed
|
||||
@@ -393,6 +417,11 @@ mod args_tests {
|
||||
assert_eq!(parse(&["--screenshot", "a.png", "--shot-width", "1200"]).look.shot_width, Some(1200));
|
||||
assert!(parse_args(["--shot-width".to_string(), "9".to_string()]).is_err());
|
||||
assert_eq!(parse(&["--version"]).print, Some(Print::Version));
|
||||
// `--control <port>` (ADR 0104): a port from 1 to 65535, or an error before any window.
|
||||
assert_eq!(parse(&["--control", "9878"]).control, Some(9878));
|
||||
for bad in [&["--control"][..], &["--control", "0"], &["--control", "99999"], &["--control", "port"]] {
|
||||
assert!(parse_args(bad.iter().map(|a| a.to_string())).is_err(), "{bad:?}");
|
||||
}
|
||||
// And the file opens: the session starts with it, not the sample.
|
||||
let dir = std::env::temp_dir().join(format!("anicraft-shell-args-{}", std::process::id()));
|
||||
std::fs::create_dir_all(&dir).unwrap();
|
||||
|
||||
@@ -363,6 +363,13 @@ pub fn status_bar(app: &mut App, ui: &mut egui::Ui) {
|
||||
let small = |t: String| text(Type::Data, t).color(T.text_faint);
|
||||
ui.label(small(tr!("undo {steps} · {size} MB", steps = app.s.history().undo_len(), size = format!("{:.1}", app.s.history().bytes() as f32 / (1024.0 * 1024.0)))));
|
||||
ui.add_space(12.0);
|
||||
// An assistant can edit this window (ADR 0104): always in view while that is so.
|
||||
#[cfg(not(target_arch = "wasm32"))]
|
||||
if let Some(port) = crate::remote::port(app) {
|
||||
ui.label(text(Type::Label, tr!("Remote control on (port {port})", port = port)).color(T.text_faint))
|
||||
.on_hover_text(tr!("An assistant can edit this document through a control port on this computer. Its edits appear here at once and undo like your own. Started with --control; close AniCraft to turn it off."));
|
||||
ui.add_space(12.0);
|
||||
}
|
||||
if let Some(a) = crate::autosave::status(app, now) {
|
||||
ui.label(small(a)).on_hover_text(tr!("A recovery copy of your unsaved work. If AniCraft closes unexpectedly, the next start offers it back."));
|
||||
ui.add_space(12.0);
|
||||
|
||||
@@ -412,6 +412,31 @@ pub fn recovery_dir() -> Option<PathBuf> {
|
||||
}
|
||||
}
|
||||
|
||||
/// Writes a file only this user may read (the control port's token, ADR 0104), making its folder
|
||||
/// first. On Windows the settings folder (%APPDATA%) is already private to the user; elsewhere
|
||||
/// the file is made owner-only (0600).
|
||||
#[cfg(not(target_arch = "wasm32"))]
|
||||
pub fn write_private_file(path: &std::path::Path, contents: &[u8]) -> std::io::Result<()> {
|
||||
use std::io::Write;
|
||||
if let Some(dir) = path.parent() {
|
||||
std::fs::create_dir_all(dir)?;
|
||||
}
|
||||
let mut options = std::fs::OpenOptions::new();
|
||||
options.write(true).create(true).truncate(true);
|
||||
#[cfg(unix)]
|
||||
{
|
||||
use std::os::unix::fs::{OpenOptionsExt, PermissionsExt};
|
||||
options.mode(0o600);
|
||||
// An older file keeps its mode when opened: tighten it first.
|
||||
if path.exists() {
|
||||
std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o600))?;
|
||||
}
|
||||
}
|
||||
let mut f = options.open(path)?;
|
||||
f.write_all(contents)?;
|
||||
f.sync_all()
|
||||
}
|
||||
|
||||
/// Whether the recovery folder was chosen explicitly (screenshot runs only touch it then).
|
||||
pub fn recovery_dir_overridden() -> bool {
|
||||
std::env::var_os("ANICRAFT_RECOVERY_DIR").is_some_and(|v| !v.is_empty())
|
||||
|
||||
+143
@@ -0,0 +1,143 @@
|
||||
//! Remote control (ADR 0104, `docs/control-protocol.md`): `anicraft --control <port>` opens a
|
||||
//! control port on this computer, and an assistant (through `anicraft-cli mcp --bridge`) edits
|
||||
//! the open document live. The port, its threads and the tools are `anicraft_cli::control`'s;
|
||||
//! this module runs each call on the window's session at the start of a frame, writes the
|
||||
//! run's token to `control.json` in the settings folder, and removes it on exit.
|
||||
//!
|
||||
//! A call that edits waits while the person is dragging (or a plug-in dialog has its preview
|
||||
//! open), so the two never share an undo step. Typing in a field doesn't hold it back: the
|
||||
//! person's typed change is committed as its own step first, as clicking elsewhere would.
|
||||
|
||||
use crate::app::{App, Drag};
|
||||
use crate::platform;
|
||||
use anicraft_cli::{control, mcp};
|
||||
use anicraft_engine::Session;
|
||||
use serde_json::Value;
|
||||
use std::collections::VecDeque;
|
||||
use std::path::PathBuf;
|
||||
use std::sync::Arc;
|
||||
|
||||
/// An open control port.
|
||||
pub struct Remote {
|
||||
server: control::Server,
|
||||
/// Calls in arrival order; the first one that edits holds the rest back during a drag.
|
||||
waiting: VecDeque<control::Request>,
|
||||
token: String,
|
||||
/// `control.json`, when it could be written.
|
||||
file: Option<PathBuf>,
|
||||
}
|
||||
|
||||
/// Opens the control port; failures go to the status bar (the window still opens).
|
||||
pub fn start(app: &mut App, ctx: &egui::Context, port: u16) {
|
||||
let token = match control::token_from_env().map_or_else(control::new_token, Ok) {
|
||||
Ok(t) => t,
|
||||
Err(e) => {
|
||||
app.status_err(tr!("Remote control is off: {reason}", reason = e));
|
||||
return;
|
||||
}
|
||||
};
|
||||
let wake_ctx = ctx.clone();
|
||||
let server = match control::listen(port, token.clone(), Arc::new(move || wake_ctx.request_repaint())) {
|
||||
Ok(s) => s,
|
||||
Err(e) => {
|
||||
app.status_err(tr!("Remote control is off: port {port} is in use or not allowed ({reason}). Is another AniCraft already open with remote control?", port = port, reason = e));
|
||||
return;
|
||||
}
|
||||
};
|
||||
let file = control::control_file();
|
||||
let written = file.as_ref().map(|path| {
|
||||
let contents = control::ControlFile { port: server.port, token: token.clone(), pid: std::process::id(), version: env!("CARGO_PKG_VERSION").to_string() };
|
||||
platform::write_private_file(path, contents.to_json().to_string().as_bytes())
|
||||
});
|
||||
if let Some(Err(e)) = &written {
|
||||
// The port works with ANICRAFT_CONTROL_TOKEN; without the file a bridge can't find it.
|
||||
app.status_err(tr!("Remote control is on, but its token could not be saved ({reason}); set ANICRAFT_CONTROL_TOKEN for the assistant.", reason = e));
|
||||
}
|
||||
let file = if matches!(written, Some(Ok(()))) { file } else { None };
|
||||
app.remote = Some(Remote { server, waiting: VecDeque::new(), token, file });
|
||||
}
|
||||
|
||||
/// The port, while remote control is on (the status bar shows it).
|
||||
pub fn port(app: &App) -> Option<u16> {
|
||||
app.remote.as_ref().map(|r| r.server.port)
|
||||
}
|
||||
|
||||
/// Whether the person is in the middle of an edit a remote one must not join.
|
||||
fn person_is_dragging(app: &App, ctx: &egui::Context) -> bool {
|
||||
app.drag != Drag::None || app.plugin_dialog.is_some() || (app.s.in_gesture() && ctx.egui_is_using_pointer())
|
||||
}
|
||||
|
||||
/// Runs the waiting calls: at the start of a frame, so their edits draw in this one.
|
||||
pub fn poll(app: &mut App, ctx: &egui::Context) {
|
||||
let Some(r) = app.remote.as_mut() else { return };
|
||||
while let Some(req) = r.server.try_recv() {
|
||||
r.waiting.push_back(req);
|
||||
}
|
||||
loop {
|
||||
let dragging = person_is_dragging(app, ctx);
|
||||
let Some(r) = app.remote.as_mut() else { return };
|
||||
let Some(next) = r.waiting.front() else { return };
|
||||
if next.changes_document() && dragging && !next.expired() {
|
||||
// Look again shortly: the drag ends without a remote wake-up.
|
||||
ctx.request_repaint_after(std::time::Duration::from_millis(50));
|
||||
return;
|
||||
}
|
||||
let Some(req) = r.waiting.pop_front() else { return };
|
||||
// (An expired call is refused without running: it leaves the person's gesture alone.)
|
||||
if req.changes_document() && !req.expired() && !dragging && app.s.in_gesture() {
|
||||
// A typed property change still open: it becomes its own undo step first.
|
||||
app.s.end_gesture();
|
||||
}
|
||||
req.run(&mut Live(app));
|
||||
}
|
||||
}
|
||||
|
||||
/// On exit: calls still waiting are told so, and `control.json` goes (if it is still ours).
|
||||
pub fn finish(app: &mut App) {
|
||||
let Some(mut r) = app.remote.take() else { return };
|
||||
for req in r.waiting.drain(..) {
|
||||
// i18n-exempt: the protocol's English, read by the assistant (as MCP)
|
||||
req.refuse("AniCraft is closing");
|
||||
}
|
||||
if let Some(path) = &r.file {
|
||||
let ours = std::fs::read_to_string(path).ok().and_then(|t| control::ControlFile::parse(&t).ok()).is_some_and(|c| c.token == r.token);
|
||||
if ours {
|
||||
let _ = std::fs::remove_file(path);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// The window as the tools' host: commands run with the follow-up the person's own get (the
|
||||
/// status line, the view a new document resets, Open Recent).
|
||||
struct Live<'a>(&'a mut App);
|
||||
|
||||
impl mcp::Host for Live<'_> {
|
||||
fn session(&self) -> &Session {
|
||||
&self.0.s
|
||||
}
|
||||
fn execute(&mut self, id: &str, params: &Value) -> Result<Value, String> {
|
||||
let selected = self.0.s.selection.len();
|
||||
let revision = self.0.s.revision;
|
||||
let v = self.0.s.execute(id, params).map_err(|e| e.to_string())?;
|
||||
// An edit to the document behind the start screen: show the document, so the person
|
||||
// sees it land (ADR 0059's start screen otherwise covers the workspace).
|
||||
if self.0.s.revision != revision {
|
||||
self.0.start = None;
|
||||
}
|
||||
self.0.announce(id, &v, selected);
|
||||
Ok(v)
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use crate::platform;
|
||||
|
||||
/// The CLI finds `control.json` with its own copy of the settings-folder rule (it can't use
|
||||
/// the shell); they must agree, or the bridge looks in the wrong place.
|
||||
#[test]
|
||||
fn the_bridge_looks_for_the_token_in_the_settings_folder() {
|
||||
assert_eq!(anicraft_cli::control::settings_dir(), platform::config_dir());
|
||||
assert_eq!(anicraft_cli::control::control_file(), platform::config_dir().map(|d| d.join("control.json")));
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user