@mcptoolshop/armature-studio 0.0.0 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mcp-tool-shop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,5 +1,68 @@
-# @mcptoolshop/armature-studio
+# armature-studio
 
-Name placeholder — `0.0.0` publishes nothing usable. The real package ships from
-[mcp-tool-shop-org/armature](https://github.com/mcp-tool-shop-org/armature) by OIDC trusted
-publishing, and replaces this on its first release.
+**You block the shot. The model shoots it.**
+
+Node launcher for [`armature-studio`](https://pypi.org/project/armature-studio/) — GLB-authored
+previz, control sequences and gates for video-diffusion generation.
+
+A video model can produce motion, light and life that no renderer can. It cannot be told
+*who is on screen and where they are standing*. armature supplies exactly that: a canonical
+character mesh is staged and animated in headless Blender, and the render becomes a per-frame
+**control sequence** the video model must obey — so AI-generated video can carry one
+persistent main character whose position and pose are known every frame.
+
+**armature is image-to-video with a GLB instead of an image.**
+
+## Install
+
+```bash
+npm install -g @mcptoolshop/armature-studio
+```
+
+The toolkit itself is Python, so install that too:
+
+```bash
+pip install armature-studio
+```
+
+```bash
+armature check
+```
+
+## Why a launcher and not a port
+
+armature's measured pieces — the gates, the framing solves, the channel maths — are Python.
+Re-implementing any of them in Node would create a second copy of a threshold, which is how a
+threshold drifts. This package installs the `armature` command and forwards it, verbatim, to
+the Python that holds the truth.
+
+**It will not install Python for you and will not `pip install` anything behind your back.**
+When the toolkit is missing it says which of the two things is wrong — no interpreter, or an
+interpreter without the package — prints the one command that fixes it, and exits non-zero.
+
+Point it at a specific interpreter with `ARMATURE_PYTHON` if you keep several.
+
+## Commands
+
+```bash
+armature check      # import every module and report what resolved
+armature modules    # what each module is for  (--json for machine output)
+armature where      # where the docs and the Blender-side scripts live
+```
+
+## The rendering scripts are not here, deliberately
+
+`render_turnaround.py` and its siblings run inside **Blender's own interpreter**:
+
+```bash
+blender -b -P tools/render_turnaround.py -- --glb subject.glb --out renders --ortho
+```
+
+They live in the repository, where the invocation that works is the one written down.
+
+- **Docs and handbook:** https://mcp-tool-shop-org.github.io/armature/
+- **Repository and the full record:** https://github.com/mcp-tool-shop-org/armature
+
+## License
+
+MIT.

package/bin/armature.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+/**
+ * armature — the Node launcher for the `armature-studio` Python toolkit.
+ *
+ * WHY A LAUNCHER AND NOT A PORT. armature's measured pieces are Python: the gates, the
+ * framing solves, the channel maths. Re-implementing any of them in Node would create a
+ * second copy of a threshold, which is how a threshold drifts — the exact failure the
+ * repository's own record was written to prevent. So this package installs a command and
+ * forwards it, verbatim, to the Python that holds the truth.
+ *
+ * WHAT IT WILL NOT DO. It does not install Python, does not pip-install anything behind
+ * your back, and does not guess at a substitute when the toolkit is absent. A launcher
+ * that silently installed things would make `npx` a package manager pointed at your
+ * machine. When the toolkit is missing it says so, prints the one command that fixes it,
+ * and exits non-zero.
+ */
+import { spawn, spawnSync } from "node:child_process";
+import process from "node:process";
+
+const PYPI = "armature-studio";
+const DOCS = "https://mcp-tool-shop-org.github.io/armature/";
+
+/** Interpreter candidates, in the order worth trying on each platform. */
+function candidates() {
+  const fromEnv = process.env.ARMATURE_PYTHON;
+  const list = fromEnv ? [fromEnv] : [];
+  // `py -3` is the Windows launcher and resolves when `python3` is only the Store stub.
+  return process.platform === "win32"
+    ? [...list, "python", "py", "python3"]
+    : [...list, "python3", "python"];
+}
+
+/** Args that turn a bare candidate into a working interpreter invocation. */
+function argsFor(exe) {
+  return exe === "py" ? ["-3"] : [];
+}
+
+/**
+ * Find an interpreter that can actually import the toolkit.
+ *
+ * Deliberately two questions, not one: an interpreter that exists but lacks the package
+ * is a DIFFERENT problem from no interpreter at all, and telling them apart is the whole
+ * value of this check. Reporting "python not found" to someone who has three Pythons and
+ * no package would send them fixing the wrong thing.
+ */
+function locate() {
+  let sawInterpreter = false;
+  for (const exe of candidates()) {
+    const pre = argsFor(exe);
+    const probe = spawnSync(exe, [...pre, "-c", "import armature_core"], {
+      stdio: "ignore",
+      shell: false,
+    });
+    if (probe.error) continue; // this candidate is not on PATH at all
+    sawInterpreter = true;
+    if (probe.status === 0) return { exe, pre };
+  }
+  return { exe: null, pre: null, sawInterpreter };
+}
+
+function fail(found) {
+  const what = found.sawInterpreter
+    ? `Python is installed, but the ${PYPI} toolkit is not importable from it.`
+    : "No Python interpreter was found on PATH.";
+  process.stderr.write(
+    `armature: ${what}\n\n` +
+      `  This package is a launcher. The toolkit itself is Python:\n\n` +
+      `      pip install ${PYPI}\n\n` +
+      `  Point at a specific interpreter with ARMATURE_PYTHON if you use one.\n` +
+      `  Docs: ${DOCS}\n`
+  );
+  process.exit(127);
+}
+
+const argv = process.argv.slice(2);
+
+// A self-test that does not need Python present: it proves this file parses, resolves its
+// candidate list and reports honestly. `npm test` runs it in CI where Python may be absent.
+if (argv[0] === "--node-selftest") {
+  const list = candidates();
+  if (!Array.isArray(list) || list.length === 0) {
+    process.stderr.write("selftest: no interpreter candidates\n");
+    process.exit(1);
+  }
+  if (argsFor("py")[0] !== "-3") {
+    process.stderr.write("selftest: the Windows launcher lost its -3\n");
+    process.exit(1);
+  }
+  process.stdout.write(`armature launcher ok — candidates: ${list.join(", ")}\n`);
+  process.exit(0);
+}
+
+const found = locate();
+if (!found.exe) fail(found);
+
+// Forward everything verbatim and inherit the child's exit code, so a gate that raises in
+// Python still fails the shell that called this launcher.
+const child = spawn(found.exe, [...found.pre, "-m", "armature_core.cli", ...argv], {
+  stdio: "inherit",
+  shell: false,
+});
+child.on("exit", (code, signal) => process.exit(signal ? 1 : code ?? 0));
+child.on("error", () => fail(found));

package/package.json

@@ -1,19 +1,43 @@
 {
   "name": "@mcptoolshop/armature-studio",
-  "version": "0.0.0",
-  "description": "Name placeholder. The real package publishes from mcp-tool-shop-org/armature by OIDC trusted publishing.",
-  "license": "MIT",
-  "author": "mcp-tool-shop <64996768+mcp-tool-shop@users.noreply.github.com>",
+  "version": "0.2.1",
+  "description": "You block the shot; the model shoots it — GLB-authored previz, control sequences and gates for video-diffusion generation. Node launcher for the armature-studio Python toolkit.",
+  "keywords": [
+    "previz",
+    "blender",
+    "video-diffusion",
+    "controlnet",
+    "turnaround",
+    "glb",
+    "character",
+    "animation",
+    "comfyui",
+    "sprite"
+  ],
   "homepage": "https://mcp-tool-shop-org.github.io/armature/",
+  "bugs": "https://github.com/mcp-tool-shop-org/armature/issues",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/mcp-tool-shop-org/armature.git",
     "directory": "npm"
   },
+  "license": "MIT",
+  "author": "mcp-tool-shop <64996768+mcp-tool-shop@users.noreply.github.com>",
+  "type": "module",
+  "bin": {
+    "armature": "bin/armature.mjs"
+  },
   "files": [
-    "README.md"
+    "bin/"
   ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node bin/armature.mjs --node-selftest"
+  },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
   }
 }