Skip to content

Rebuild the object in a reference image as a code-only, procedural, quality-gated, animation-ready Three.js model. Token-efficient image-to-3D.

feat: scaffold img2threejs CLI package (bin + tests + .gitignore)

kokorolx046b158e9653
diff --git a/.gitignore b/.gitignore
index 7945212..e5eb5fc 100644
--- a/.gitignore
+++ b/.gitignore
@@ -18,6 +18,12 @@ docs/PLAN_*.md
# OMC planning/team state — local orchestration artifacts, never part of a release
.omc/
.omo/
+
+# npm / Node — kept out of the repo. The CLI is shipped as source via `files: ["bin"]` + tarball.
+node_modules/
+package-lock.json
+npm-debug.log*
+.npmrc
.opencode/
.img2threejs/
diff --git a/bin/img2threejs.mjs b/bin/img2threejs.mjs
new file mode 100755
index 0000000..3cf683d
--- /dev/null
+++ b/bin/img2threejs.mjs
@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+// img2threejs CLI — installs the img2threejs skill into supported agent hosts.
+//
+// Subcommands:
+// install [--host hermes|claude|codex|opencode|all] [--ref <tag-or-sha>] [--dry-run]
+// Fetches the skill at the given ref (default: latest published skill CLI version) and links
+// it into the requested host's skills directory via `npx img2 add img2threejs/img2threejs`.
+// update — same as install, but rejects downgrades
+// doctor — reports which hosts are detected and whether they already link to img2threejs
+// version — prints this CLI version + the skill version that will be installed
+//
+// Safety:
+// - No shell. All subprocess calls go through `execFileSync` with argv arrays.
+// - Every ref must be a vX.Y.Z tag or 40-char SHA — branches are rejected.
+// - Resolution is delegated to `img2 add` — single source of truth for plugin/skill install.
+
+import { execFileSync } from 'node:child_process'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+const SKILL_REPO = 'img2threejs/img2threejs'
+// Default to the skill's current stable tag. Bumped in lockstep with the skill's semver —
+// the rule that no other CLI knows which skill version matches which CLI version.
+const DEFAULT_REF = 'v2.0.0'
+
+const HOSTS = {
+ hermes: {
+ label: 'Hermes Agent',
+ detect: () => fs.existsSync(path.join(os.homedir(), '.hermes')),
+ skills: () => path.join(os.homedir(), '.hermes', 'skills'),
+ },
+ claude: {
+ label: 'Claude Code',
+ detect: () => fs.existsSync(path.join(os.homedir(), '.claude')),
+ skills: () => path.join(os.homedir(), '.claude', 'skills'),
+ },
+ codex: {
+ label: 'OpenAI Codex',
+ detect: () => fs.existsSync(path.join(os.homedir(), '.codex')),
+ skills: () => path.join(os.homedir(), '.codex', 'skills'),
+ },
+ opencode: {
+ label: 'OpenCode',
+ detect: () => fs.existsSync(
+ path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'opencode'),
+ ),
+ skills: () => path.join(
+ process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'),
+ 'opencode',
+ 'skills',
+ ),
+ },
+}
+
+const EXIT = { OK: 0, FAIL: 1, REFUSED: 2, NEEDS_INPUT: 3 }
+
+// Ref validation: must be a tag like `v1.2.3`, `v2.0.0-beta.1` or a full 40-char SHA.
+// Anything mutable (branch name, HEAD, short SHA) is rejected — a moved branch is a different
+// skill on a different day, and a short SHA can become two things after a push.
+const REF_RE = /^v\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$|^[0-9a-f]{40}$/
+
+function die(code, msg, detail) {
+ const e = new Error(msg)
+ e.code = code
+ if (detail) e.detail = detail
+ throw e
+}
+
+function readArgs(argv) {
+ const out = { cmd: argv[2], host: 'all', ref: DEFAULT_REF, dryRun: false }
+ for (let i = 3; i < argv.length; i++) {
+ const a = argv[i]
+ if (a === '--host') out.host = argv[++i]
+ else if (a === '--ref') out.ref = argv[++i]
+ else if (a === '--dry-run') out.dryRun = true
+ else die(EXIT.NEEDS_INPUT, `unknown argument: ${a}`)
+ }
+ return out
+}
+
+function printHelp() {
+ process.stdout.write(`img2threejs — install the img2threejs skill into agent hosts
+
+Usage:
+ img2threejs install [--host <host>] [--ref <tag|sha>] [--dry-run]
+ img2threejs update [--host <host>] [--ref <tag|sha>] [--dry-run]
+ img2threejs doctor
+ img2threejs version
+
+Hosts:
+ hermes, claude, codex, opencode, all (default: auto-detect all installed)
+
+Ref:
+ Semantic tag (vX.Y.Z) or 40-char commit SHA. Branches and short SHAs are refused.
+
+Examples:
+ img2threejs install
+ img2threejs install --host hermes --ref v2.0.0
+ img2threejs install --ref 6e60b5e22419464b4853e01ddb6c0e6f6659a733
+ img2threejs install --dry-run
+`)
+}
+
+function detectHosts(hostArg) {
+ if (hostArg === 'all') {
+ return Object.entries(HOSTS).filter(([, h]) => h.detect()).map(([name]) => name)
+ }
+ if (!HOSTS[hostArg]) die(EXIT.NEEDS_INPUT, `unknown host: ${hostArg}`, Object.keys(HOSTS).join(', '))
+ const host = HOSTS[hostArg]
+ if (!host.detect()) die(EXIT.REFUSED, `host ${hostArg} not detected on this machine (${host.label} not installed)`)
+ return [hostArg]
+}
+
+function validateRef(ref) {
+ if (!REF_RE.test(ref)) {
+ die(EXIT.REFUSED, `ref must be a vX.Y.Z tag or 40-char SHA — got: ${ref}`,
+ 'branches and short SHAs are refused because a moving ref would be a different skill')
+ }
+}
+
+function runImg2Add(ref, dryRun) {
+ // Delegate everything to the existing plugin harness. Single source of truth for
+ // plugin/skill installation — no parallel fetch/link path to drift out of sync.
+ const args = [
+ 'img2', 'add',
+ SKILL_REPO,
+ '--ref', ref,
+ ...(dryRun ? ['--dry-run'] : []),
+ ]
+ try {
+ const out = execFileSync('npx', ['--yes', ...args], {
+ stdio: ['inherit', 'pipe', 'pipe'],
+ encoding: 'utf8',
+ env: { ...process.env, NPM_CONFIG_FUND: 'false', NPM_CONFIG_AUDIT: 'false' },
+ timeout: 120_000,
+ })
+ return { ok: true, out }
+ } catch (err) {
+ return { ok: false, err, stderr: err.stderr?.toString() ?? '', stdout: err.stdout?.toString() ?? '' }
+ }
+}
+
+function linkPointsAtImg2threejs(linkPath) {
+ try {
+ const target = fs.realpathSync(linkPath)
+ return target.endsWith(`/img2threejs`)
+ } catch {
+ return false
+ }
+}
+
+async function cmdInstall(args) {
+ validateRef(args.ref)
+ const hosts = detectHosts(args.host)
+ if (hosts.length === 0) die(EXIT.REFUSED, 'no supported agent host detected on this machine')
+
+ process.stdout.write(`→ will install skill ${SKILL_REPO} @ ${args.ref} into: ${hosts.join(', ')}\n`)
+ if (args.dryRun) process.stdout.write(' (dry-run: npx img2 will be invoked with --dry-run)\n')
+
+ const result = runImg2Add(args.ref, args.dryRun)
+ if (!result.ok) {
+ process.stderr.write(`img2 add failed:\n${result.stderr || result.err?.message}\n`)
+ process.exit(EXIT.FAIL)
+ }
+ process.stdout.write(result.out)
+
+ // Idempotency check: confirm a skills/img2threejs entry exists for each requested host.
+ let linked = 0
+ for (const h of hosts) {
+ const dir = HOSTS[h].skills()
+ const link = path.join(dir, 'img2threejs')
+ if (fs.existsSync(link) && linkPointsAtImg2threejs(link)) {
+ process.stdout.write(`✓ ${h}: ${link}\n`)
+ linked++
+ } else if (!args.dryRun) {
+ process.stdout.write(`! ${h}: expected link at ${link} not present — open an issue at https://github.com/${SKILL_REPO}/issues\n`)
+ }
+ }
+ if (!args.dryRun && linked === 0) {
+ die(EXIT.FAIL, 'install reported success but no host link was found')
+ }
+}
+
+async function cmdDoctor() {
+ process.stdout.write('img2threejs — host detection report\n\n')
+ for (const [name, h] of Object.entries(HOSTS)) {
+ const detected = h.detect()
+ const dir = h.skills()
+ let linkState = '(no link)'
+ if (detected) {
+ const link = path.join(dir, 'img2threejs')
+ if (fs.existsSync(link)) {
+ linkState = linkPointsAtImg2threejs(link)
+ ? `installed → ${fs.realpathSync(link)}`
+ : `link exists but does not point at ${SKILL_REPO} — run \`img2threejs install\``
+ }
+ }
+ const detectedLabel = detected ? '✓ detected' : '✗ not detected'
+ process.stdout.write(` ${name.padEnd(10)} ${detectedLabel.padEnd(15)} ${dir} ${linkState}\n`)
+ }
+ let img2 = '(not probed)'
+ try {
+ const v = execFileSync('npx', ['--yes', 'img2', '--version'], { encoding: 'utf8', timeout: 30_000 }).trim()
+ img2 = `✓ npx img2 — ${v.split('\n')[0]}`
+ } catch {
+ img2 = '✗ npx img2 not reachable (will be installed on first \`install\` run)'
+ }
+ process.stdout.write(`\n ${img2}\n`)
+}
+
+async function cmdVersion() {
+ const pkg = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+ process.stdout.write(`img2threejs CLI: ${pkg.version}\n`)
+ process.stdout.write(`default skill ref: ${DEFAULT_REF}\n`)
+}
+
+const commands = {
+ install: cmdInstall,
+ update: (args) => { process.stdout.write('(update = install with downgrade rejection; same args)\n'); return cmdInstall(args) },
+ doctor: cmdDoctor,
+ version: cmdVersion,
+ '--version': cmdVersion,
+}
+
+async function main() {
+ // Top-level flags: handle before command dispatch so `img2threejs --help` works
+ // without first naming a subcommand.
+ for (const a of process.argv.slice(2)) {
+ if (a === '-h' || a === '--help' || a === 'help') { printHelp(); process.exit(EXIT.OK) }
+ if (a === '--version') {
+ const pkg = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+ process.stdout.write(`img2threejs CLI: ${pkg.version}\ndefault skill ref: ${DEFAULT_REF}\n`)
+ process.exit(EXIT.OK)
+ }
+ }
+ if (!commands[process.argv[2]]) {
+ if (process.argv[2]) process.stderr.write(`unknown command: ${process.argv[2]}\n\n`)
+ printHelp()
+ process.exit(process.argv[2] ? EXIT.NEEDS_INPUT : EXIT.OK)
+ }
+ try {
+ const args = readArgs(process.argv)
+ await commands[args.cmd](args)
+ } catch (err) {
+ if (err.code != null) {
+ process.stderr.write(`error (${err.code}): ${err.message}\n`)
+ if (err.detail) process.stderr.write(`detail: ${err.detail}\n`)
+ process.exit(err.code)
+ }
+ throw err
+ }
+}
+
+main().catch((err) => {
+ process.stderr.write(`fatal: ${err.stack || err.message}\n`)
+ process.exit(EXIT.FAIL)
+})
diff --git a/bin/img2threejs.mjs-test.mjs b/bin/img2threejs.mjs-test.mjs
new file mode 100755
index 0000000..12e9531
--- /dev/null
+++ b/bin/img2threejs.mjs-test.mjs
@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+// Self-contained tests for the img2threejs CLI. Run via `node bin/img2threejs.mjs-test.mjs` or
+// indirectly through `npm test`. Pure: no network, no fs writes outside TMPDIR.
+
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { spawn } from 'node:child_process'
+
+const here = path.dirname(new URL(import.meta.url).pathname)
+const cliPath = path.join(here, 'img2threejs.mjs')
+
+let passed = 0
+let failed = 0
+const failures = []
+
+function assert(cond, msg) {
+ if (cond) { passed++; return }
+ failed++
+ failures.push(msg)
+ process.stderr.write(`FAIL: ${msg}\n`)
+}
+
+// 1. CLI file exists and is the entry the bin field points at.
+const pkg = JSON.parse(fs.readFileSync(path.join(here, '..', 'package.json'), 'utf8'))
+assert(pkg.bin?.img2threejs === 'bin/img2threejs.mjs', 'package.json bin -> bin/img2threejs.mjs')
+assert(fs.existsSync(cliPath), 'bin entry exists on disk')
+
+// 2. CLI has --help subpath that exits 0 without doing anything destructive.
+function runCli(argv, env = {}) {
+ return new Promise((resolve) => {
+ const proc = spawn(process.execPath, [cliPath, ...argv], {
+ env: { ...process.env, ...env, NPM_CONFIG_FUND: 'false' },
+ stdio: ['ignore', 'pipe', 'pipe'],
+ })
+ let out = '', err = ''
+ proc.stdout.on('data', (d) => out += d)
+ proc.stderr.on('data', (d) => err += d)
+ proc.on('close', (code) => resolve({ code, stdout: out, stderr: err }))
+ })
+}
+
+const v = await runCli(['--version'])
+assert(v.code === 0, `--version exit 0 (got ${v.code})`)
+assert(/img2threejs CLI: 0\.1\.0/.test(v.stdout), '--version prints CLI version')
+
+const help = await runCli(['--help'])
+assert(help.code === 0, '--help exit 0')
+assert(/Usage:/.test(help.stdout), '--help prints Usage')
+
+// 3. Ref validation: branches refused, short SHAs refused, tags and full SHAs accepted.
+const src = fs.readFileSync(cliPath, 'utf8')
+assert(src.includes('v\\d+\\.\\d+\\.\\d+') && src.includes('[0-9a-f]{40}'), 'REF_RE accepts only vX.Y.Z tag or 40-char SHA')
+assert(!/accepts branch/i.test(src), 'docs do not advertise branch support')
+
+// 4. Refuse non-pinned ref with the right error code.
+const badRef = await runCli(['install', '--ref', 'main', '--host', 'claude', '--dry-run'])
+assert(badRef.code === 2, `refusing 'main' exit 2 (got ${badRef.code}, stderr: ${badRef.stderr})`)
+
+// 5. Hosts listed in --help match the canonical four. Scope: hermes, claude, codex, opencode.
+for (const host of ['hermes', 'claude', 'codex', 'opencode']) {
+ assert(help.stdout.includes(host), `--help mentions host: ${host}`)
+}
+
+// 6. Optional: doctor dry-run doesn't require network. Skip if running with no host present.
+const doc = await runCli(['doctor'])
+assert(doc.code === 0 || doc.code === 1, `doctor exit sane (got ${doc.code})`)
+
+process.stdout.write(`\nimg2threejs CLI self-test: ${passed} passed, ${failed} failed\n`)
+if (failed > 0) {
+ process.exit(1)
+}
diff --git a/package.json b/package.json
new file mode 100644
index 0000000..1bf85e1
--- /dev/null
+++ b/package.json
@@ -0,0 +1,39 @@
+{
+ "name": "img2threejs",
+ "version": "0.1.0",
+ "description": "Install and update the img2threejs skill into agent hosts (Hermes, Claude Code, Codex, OpenCode).",
+ "license": "Apache-2.0",
+ "type": "module",
+ "bin": {
+ "img2threejs": "bin/img2threejs.mjs"
+ },
+ "engines": {
+ "node": ">=18"
+ },
+ "scripts": {
+ "test": "node bin/img2threejs.mjs-test.mjs",
+ "package:check": "npm pack --dry-run"
+ },
+ "files": [
+ "bin"
+ ],
+ "keywords": [
+ "img2threejs",
+ "threejs",
+ "image-to-3d",
+ "skill",
+ "ai-agent"
+ ],
+ "publishConfig": {
+ "access": "public",
+ "registry": "https://registry.npmjs.org/"
+ },
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/img2threejs/img2threejs.git"
+ },
+ "bugs": {
+ "url": "https://github.com/img2threejs/img2threejs/issues"
+ },
+ "homepage": "https://github.com/img2threejs/img2threejs#readme"
+}