@punal_manalan/blender-project-harness 0.0.0-stage → 1.0.2

package/.kilo/blender-project-harness/tools/harness/blender.mjs

@@ -0,0 +1,301 @@
+import fs from 'node:fs';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { setTimeout as delay } from 'node:timers/promises';
+
+const BOOTSTRAP = `import bpy
+import os
+import socket
+import traceback
+from bpy.app.handlers import persistent
+
+MAX_START_ATTEMPTS = 5
+RETRY_INTERVAL = 0.5
+_start_attempts = 0
+
+
+def requested_port():
+    value = os.environ.get("BLENDER_PORT", "").strip()
+    if not value.isdigit() or not 1024 <= int(value) <= 65535:
+        raise RuntimeError(
+            "BLENDER_PORT is missing or invalid; launch Blender through the harness so the port matches .kilo/kilo.jsonc"
+        )
+    return int(value)
+
+
+def apply_port(*_args):
+    global _start_attempts
+    _start_attempts += 1
+    try:
+        scene = bpy.context.scene
+        if scene is None:
+            raise RuntimeError("No active scene available for MCP startup")
+        port = requested_port()
+
+        server = getattr(bpy.types, "blendermcp_server", None)
+        if server is not None or getattr(scene, "blendermcp_server_running", False):
+            try:
+                if "FINISHED" not in bpy.ops.blendermcp.stop_server():
+                    raise RuntimeError("MCP stop operator did not finish")
+            except Exception:
+                if server is None:
+                    raise
+                server.stop()
+            remaining = getattr(bpy.types, "blendermcp_server", None)
+            if remaining is not None:
+                if getattr(remaining, "running", False):
+                    remaining.stop()
+                if getattr(remaining, "running", False):
+                    raise RuntimeError("Existing MCP server did not stop")
+                del bpy.types.blendermcp_server
+            scene.blendermcp_server_running = False
+
+        scene.blendermcp_port = port
+        result = bpy.ops.blendermcp.start_server()
+        server = getattr(bpy.types, "blendermcp_server", None)
+        listener = getattr(server, "socket", None)
+        if ("FINISHED" not in result or not getattr(server, "running", False)
+                or not getattr(scene, "blendermcp_server_running", False)
+                or getattr(server, "port", None) != port or listener is None
+                or listener.getsockname()[1] != port
+                or not listener.getsockopt(socket.SOL_SOCKET, socket.SO_ACCEPTCONN)):
+            raise RuntimeError(f"MCP server is not listening on requested port {port}")
+        print(f"BlenderMCP: listening on port {port}", flush=True)
+    except Exception:
+        traceback.print_exc()
+        if _start_attempts < MAX_START_ATTEMPTS:
+            return RETRY_INTERVAL
+        print(f"BlenderMCP: startup stopped after {MAX_START_ATTEMPTS} attempts", flush=True)
+    return None
+
+
+def schedule_apply_port(*_args):
+    global _start_attempts
+    _start_attempts = 0
+    if not bpy.app.timers.is_registered(apply_port):
+        bpy.app.timers.register(apply_port, first_interval=0.4, persistent=True)
+
+
+@persistent
+def restart_after_load(*_args):
+    schedule_apply_port()
+
+
+restart_after_load._kilo_blender_mcp_apply_port = apply_port
+for handler in list(bpy.app.handlers.load_post):
+    previous_timer = getattr(handler, "_kilo_blender_mcp_apply_port", None)
+    if previous_timer is not None:
+        if bpy.app.timers.is_registered(previous_timer):
+            bpy.app.timers.unregister(previous_timer)
+        bpy.app.handlers.load_post.remove(handler)
+bpy.app.handlers.load_post.append(restart_after_load)
+schedule_apply_port()
+`;
+
+export const fail = (message) => { throw new Error(`Blender harness: ${message}`); };
+
+export const instanceFile = (home) => path.join(home, 'blender-instance.json');
+const launchLockFile = (home) => path.join(home, 'blender-launch.lock');
+
+export function readWorkspacePort(root) {
+  const file = path.join(root, '.kilo', 'kilo.jsonc');
+  if (!fs.existsSync(file)) fail(`workspace MCP config not found: ${file}`);
+  const text = fs.readFileSync(file, 'utf8')
+    .replace(/"(?:\\.|[^"\\])*"|\/\/[^\r\n]*|\/\*[\s\S]*?\*\//g, (token) => (token.startsWith('"') ? token : ' '));
+  const match = /"BLENDER_PORT"\s*:\s*"(\d+)"/.exec(text);
+  if (!match) fail('.kilo/kilo.jsonc lacks BLENDER_PORT');
+  const port = Number(match[1]);
+  if (!Number.isInteger(port) || port < 1024 || port > 65535) fail(`invalid BLENDER_PORT in .kilo/kilo.jsonc: ${match[1]}`);
+  return port;
+}
+
+function exeFile(candidate) {
+  try {
+    const full = path.resolve(candidate);
+    return fs.statSync(full).isFile() && path.extname(full).toLowerCase() === '.exe' ? full : null;
+  } catch { return null; }
+}
+
+function walkExecutables(directory, depth = 0) {
+  if (depth > 3) return [];
+  let entries;
+  try { entries = fs.readdirSync(directory, { withFileTypes: true }); } catch { return []; }
+  const found = [];
+  for (const entry of entries) {
+    const full = path.join(directory, entry.name);
+    if (entry.isFile() && entry.name.toLowerCase() === 'blender.exe') found.push(full);
+    else if (entry.isDirectory() && !entry.isSymbolicLink()) found.push(...walkExecutables(full, depth + 1));
+  }
+  return found;
+}
+
+export function findBlender(env = process.env) {
+  const candidates = [];
+  if (env.BLENDER_EXE) candidates.push(env.BLENDER_EXE);
+  const where = spawnSync('where.exe', ['blender.exe'], { encoding: 'utf8', windowsHide: true, timeout: 15000 });
+  if (where.status === 0) candidates.push(...where.stdout.split(/\r?\n/).filter(Boolean));
+  const roots = [
+    env.ProgramFiles && path.join(env.ProgramFiles, 'Blender Foundation'),
+    env['ProgramFiles(x86)'] && path.join(env['ProgramFiles(x86)'], 'Blender Foundation'),
+    env.LOCALAPPDATA && path.join(env.LOCALAPPDATA, 'Programs', 'Blender Foundation'),
+    env.ProgramFiles && path.join(env.ProgramFiles, 'Steam', 'steamapps', 'common', 'Blender'),
+    env.USERPROFILE && path.join(env.USERPROFILE, 'scoop', 'apps', 'blender', 'current'),
+  ].filter(Boolean);
+  for (const directory of roots) {
+    if (fs.existsSync(directory)) candidates.push(...walkExecutables(directory));
+  }
+  const unique = [...new Set(candidates.map((candidate) => exeFile(candidate)).filter(Boolean))];
+  if (!unique.length) fail('Blender not found. Set BLENDER_EXE to the full blender.exe path or add Blender to PATH.');
+  return unique
+    .map((file) => ({ file, version: spawnSync('powershell.exe', ['-NoLogo', '-NoProfile', '-Command',
+      `(Get-Item -LiteralPath '${file.replaceAll("'", "''")}').VersionInfo.ProductVersion`], { encoding: 'utf8', windowsHide: true, timeout: 15000 }).stdout?.trim() ?? '' }))
+    .sort((a, b) => b.version.localeCompare(a.version, undefined, { numeric: true }))[0].file;
+}
+
+export function isAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return error.code === 'EPERM'; }
+}
+
+export function readInstance(home) {
+  try { return JSON.parse(fs.readFileSync(instanceFile(home), 'utf8')); }
+  catch { return null; }
+}
+
+export function instanceStatus(home) {
+  const instance = readInstance(home);
+  if (!instance) return { running: false };
+  if (!isAlive(instance.pid)) {
+    try { fs.rmSync(instanceFile(home), { force: true }); } catch { /* recovery */ }
+    return { running: false, stalePid: instance.pid };
+  }
+  return { running: true, ...instance };
+}
+
+function writeInstance(home, instance) {
+  const file = instanceFile(home);
+  const temporary = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(temporary, `${JSON.stringify(instance, null, 2)}\n`);
+  fs.renameSync(temporary, file);
+}
+
+export function acquireLaunchLock(home) {
+  fs.mkdirSync(home, { recursive: true });
+  const file = launchLockFile(home);
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      const fd = fs.openSync(file, 'wx');
+      fs.writeSync(fd, JSON.stringify({ pid: process.pid, at: Date.now() }));
+      fs.closeSync(fd);
+      return () => { try { fs.rmSync(file, { force: true }); } catch { /* lock already gone */ } };
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      let stale = false;
+      try { stale = Date.now() - fs.statSync(file).mtimeMs > 60000; } catch { stale = true; }
+      if (stale) { fs.rmSync(file, { force: true }); continue; }
+      fail('another launch is in progress; wait for it to finish');
+    }
+  }
+  fail('launch lock could not be acquired');
+}
+
+export function portListening(port, timeout = 500) {
+  return new Promise((resolve) => {
+    const socket = net.connect({ host: '127.0.0.1', port });
+    const done = (value) => { socket.destroy(); resolve(value); };
+    socket.setTimeout(timeout);
+    socket.once('connect', () => done(true));
+    socket.once('timeout', () => done(false));
+    socket.once('error', () => done(false));
+  });
+}
+
+export function logTail(file, lines = 12) {
+  try { return fs.readFileSync(file, 'utf8').trimEnd().split(/\r?\n/).slice(-lines).join('\n'); }
+  catch { return ''; }
+}
+
+function killProcess(pid) {
+  if (!isAlive(pid)) return;
+  if (process.platform === 'win32') spawnSync('taskkill.exe', ['/PID', String(pid), '/T', '/F'], { windowsHide: true, timeout: 15000 });
+  else { try { process.kill(-pid, 'SIGTERM'); } catch { try { process.kill(pid, 'SIGTERM'); } catch { /* already gone */ } } }
+}
+
+export async function launchProject({ root, home, project, scene, session, env = process.env }) {
+  const projectPath = path.resolve(root, project);
+  const projectsRoot = path.resolve(root, 'Blender');
+  if (path.dirname(projectPath) !== projectsRoot) fail(`project must live under ${projectsRoot}: ${project}`);
+  if (!fs.existsSync(projectPath) || !fs.statSync(projectPath).isDirectory()) fail(`project not found: ${project}`);
+
+  const port = readWorkspacePort(root);
+  const scenePath = path.resolve(root, scene);
+  if (!scenePath.startsWith(`${projectPath}${path.sep}`)) fail(`scene must stay inside ${project}`);
+  const existing = instanceStatus(home);
+  if (existing.running) {
+    if (existing.project === project && existing.scene === scene && existing.port === port) return { started: false, ...existing };
+    fail(`only one Blender instance may run from this workspace; PID ${existing.pid} is using ${existing.project}`);
+  }
+  if (await portListening(port)) fail(`port ${port} is already in use; another process may be holding the MCP socket`);
+  const blender = findBlender(env);
+
+  const logsRoot = path.join(projectPath, 'logs');
+  fs.mkdirSync(logsRoot, { recursive: true });
+  const logName = `blender-${new Date().toISOString().replace(/[-:]/g, '').replace(/\..*/, '')}-${process.pid}.log`;
+  const logPath = path.join(logsRoot, logName);
+  fs.mkdirSync(home, { recursive: true });
+  const bootstrapPath = path.join(home, 'blender-bootstrap.py');
+  fs.writeFileSync(bootstrapPath, BOOTSTRAP);
+
+  const release = acquireLaunchLock(home);
+  try {
+    if (instanceStatus(home).running) fail('another Blender instance started while launching; stop it first');
+    const args = [];
+    if (fs.existsSync(scenePath)) args.push(scenePath);
+    args.push('--log', '*', '--python', bootstrapPath);
+    const out = fs.openSync(logPath, 'a');
+    let child;
+    try {
+      child = spawn(blender, args, { cwd: projectPath, env: { ...env, BLENDER_PORT: String(port) }, detached: true, stdio: ['ignore', out, out], windowsHide: false });
+    } finally { fs.closeSync(out); }
+    child.unref();
+    if (!child.pid) fail(`Blender did not start; see ${logPath}`);
+
+    const instance = {
+      pid: child.pid,
+      project,
+      scene,
+      port,
+      blender,
+      log: path.relative(root, logPath).replaceAll('\\', '/'),
+      startedAt: new Date().toISOString(),
+      session,
+    };
+    writeInstance(home, instance);
+
+    const timeout = Number(env.HARNESS_LAUNCH_TIMEOUT_MS ?? 25000);
+    const deadline = Date.now() + timeout;
+    while (Date.now() < deadline) {
+      if (!isAlive(child.pid)) {
+        fs.rmSync(instanceFile(home), { force: true });
+        fail(`Blender exited during startup; see ${instance.log}\n${logTail(logPath)}`);
+      }
+      if (await portListening(port)) return { started: true, ...instance, addonListening: true };
+      await delay(400);
+    }
+    return { started: true, ...instance, addonListening: false, warning: `addon is not listening on port ${port}; check ${instance.log}` };
+  } finally {
+    release();
+  }
+}
+
+export function stopProject({ home, project }) {
+  const instance = readInstance(home);
+  if (!instance) return { running: false };
+  if (project && instance.project !== project) fail(`running instance belongs to ${instance.project}, not ${project}; only its registered session may stop it`);
+  if (isAlive(instance.pid)) killProcess(instance.pid);
+  fs.rmSync(instanceFile(home), { force: true });
+  return { running: false, stopped: instance };
+}

package/.kilo/blender-project-harness/tools/harness/blender.test.mjs

@@ -0,0 +1,87 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import { spawn } from 'node:child_process';
+import { findBlender, instanceFile, instanceStatus, isAlive, launchProject, readWorkspacePort, stopProject } from './blender.mjs';
+
+const tempBase = path.join(os.tmpdir(), 'kilo');
+fs.mkdirSync(tempBase, { recursive: true });
+
+function workspace(t) {
+  const root = fs.mkdtempSync(path.join(tempBase, 'blender-launch-'));
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+  fs.mkdirSync(path.join(root, 'Blender', 'Test Project'), { recursive: true });
+  fs.mkdirSync(path.join(root, '.kilo'), { recursive: true });
+  fs.writeFileSync(path.join(root, '.kilo', 'kilo.jsonc'), '{ "mcp": { "blender": { "environment": { "BLENDER_PORT": "19877" } } } }\n');
+  const home = path.join(root, 'state');
+  fs.mkdirSync(home, { recursive: true });
+  return { root, home, project: 'Blender/Test Project' };
+}
+
+function writeInstance(home, instance) {
+  fs.writeFileSync(instanceFile(home), JSON.stringify(instance, null, 2));
+}
+
+test('workspace port is read from jsonc and validated', (t) => {
+  const f = workspace(t);
+  assert.equal(readWorkspacePort(f.root), 19877);
+  fs.writeFileSync(path.join(f.root, '.kilo', 'kilo.jsonc'), '// "BLENDER_PORT": "1"\n{ "mcp": { "blender": { "environment": { "BLENDER_PORT": "2222" } } } }\n');
+  assert.equal(readWorkspacePort(f.root), 2222);
+  fs.writeFileSync(path.join(f.root, '.kilo', 'kilo.jsonc'), '{ "environment": { "BLENDER_PORT": "80" } }\n');
+  assert.throws(() => readWorkspacePort(f.root), /invalid BLENDER_PORT/);
+  fs.writeFileSync(path.join(f.root, '.kilo', 'kilo.jsonc'), '{}\n');
+  assert.throws(() => readWorkspacePort(f.root), /lacks BLENDER_PORT/);
+});
+
+test('BLENDER_EXE is honoured for discovery', (t) => {
+  const f = workspace(t);
+  const fake = path.join(f.root, 'fake-blender.exe');
+  fs.writeFileSync(fake, 'fixture');
+  const found = findBlender({ BLENDER_EXE: fake, PATH: '' });
+  assert.equal(found, path.resolve(fake));
+  assert.throws(() => findBlender({ PATH: '' }), /Blender not found/);
+});
+
+test('stale instance metadata is cleared', (t) => {
+  const f = workspace(t);
+  writeInstance(f.home, { pid: 2147483647, project: f.project, scene: `${f.project}/x.blend`, port: 19877 });
+  const status = instanceStatus(f.home);
+  assert.equal(status.running, false);
+  assert.equal(fs.existsSync(instanceFile(f.home)), false);
+});
+
+test('stop terminates the recorded process and clears metadata', async (t) => {
+  const f = workspace(t);
+  const child = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)'], { detached: true, stdio: 'ignore', windowsHide: true });
+  child.unref();
+  t.after(() => { try { process.kill(child.pid); } catch { /* already stopped */ } });
+  writeInstance(f.home, { pid: child.pid, project: f.project, scene: `${f.project}/x.blend`, port: 19877 });
+  const result = stopProject({ home: f.home, project: f.project });
+  assert.equal(result.running, false);
+  assert.equal(fs.existsSync(instanceFile(f.home)), false);
+  for (let attempt = 0; attempt < 20 && isAlive(child.pid); attempt += 1) await new Promise((resolve) => setTimeout(resolve, 100));
+  assert.equal(isAlive(child.pid), false);
+});
+
+test('launch rejects a live instance for another project', async (t) => {
+  const f = workspace(t);
+  writeInstance(f.home, { pid: process.pid, project: 'Blender/Other', scene: 'Blender/Other/x.blend', port: 19877 });
+  await assert.rejects(launchProject({ root: f.root, home: f.home, project: f.project, scene: `${f.project}/x.blend`, session: 'ses_test' }), /only one Blender instance/);
+});
+
+test('launch rejects when the MCP port is already in use', async (t) => {
+  const f = workspace(t);
+  const server = net.createServer();
+  await new Promise((resolve) => server.listen(19877, '127.0.0.1', resolve));
+  t.after(() => server.close());
+  await assert.rejects(launchProject({ root: f.root, home: f.home, project: f.project, scene: `${f.project}/x.blend`, session: 'ses_test' }), /already in use/);
+});
+
+test('launch rejects projects outside the collection and scenes outside the project', async (t) => {
+  const f = workspace(t);
+  await assert.rejects(launchProject({ root: f.root, home: f.home, project: 'Other/Project', scene: 'Other/Project/x.blend', session: 'ses_test' }), /project must live under/);
+  await assert.rejects(launchProject({ root: f.root, home: f.home, project: f.project, scene: 'Blender/Other/x.blend', session: 'ses_test' }), /scene must stay inside/);
+});

package/.kilo/blender-project-harness/tools/harness/cli.mjs

@@ -0,0 +1,127 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { findBlender, instanceStatus } from './blender.mjs';
+import { Harness } from './engine.mjs';
+import { scaffold } from './scaffold.mjs';
+import { configPath, workspaceRoot } from './workspace.mjs';
+
+const packageRoot = path.dirname(fileURLToPath(import.meta.url));
+const root = workspaceRoot(packageRoot);
+
+function fail(message) {
+  throw new Error(`Harness: ${message}`);
+}
+
+function commandAvailable(command, args = ['--version']) {
+  const result = spawnSync(command, args, { cwd: root, encoding: 'utf8', windowsHide: true, timeout: 30000 });
+  if (result.error || result.status !== 0) fail(`${command} unavailable: ${result.error?.message ?? result.stderr?.trim() ?? `exit ${result.status}`}`);
+  return (result.stdout ?? result.stderr ?? '').trim();
+}
+
+function readJson(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8').replace(/^\uFEFF/, '')); }
+  catch (error) { fail(`invalid JSON ${path.relative(root, file)}: ${error.message}`); }
+}
+
+function stateHome() {
+  const key = crypto.createHash('sha256').update(root.toLowerCase()).digest('hex');
+  return path.join(os.homedir(), '.local', 'state', 'blender-workflow-harness', key);
+}
+
+function checkPackage() {
+  const pkg = readJson(path.join(packageRoot, 'package.json'));
+  const packagePath = path.relative(root, packageRoot).replaceAll('\\', '/') || '.';
+  if (pkg.type !== 'module' || pkg.engines?.node !== '>=22') fail('package requires ESM and Node >=22');
+  for (const dependency of ['@modelcontextprotocol/sdk', 'zod']) {
+    if (!fs.existsSync(path.join(packageRoot, 'node_modules', dependency))) fail(`dependency missing: ${dependency}; run npm ci in ${packagePath}`);
+  }
+  if (!fs.existsSync(path.join(packageRoot, 'package-lock.json'))) fail(`package-lock.json missing; run npm install in ${packagePath}`);
+}
+
+function checkConfig() {
+  const kiloConfig = path.join(root, '.kilo', 'kilo.jsonc');
+  const text = fs.readFileSync(kiloConfig, 'utf8');
+  const command = /"command"\s*:\s*\[([^\]]*)\]/.exec(text);
+  const server = command ? /"([^"]*server\.mjs)"/.exec(command[1])?.[1] : null;
+  if (!server) fail('.kilo/kilo.jsonc does not route Blender MCP through a harness server');
+  if (!fs.existsSync(path.resolve(root, server))) fail(`.kilo/kilo.jsonc points at missing harness server: ${server}`);
+  if (!/"BLENDER_PORT"\s*:\s*"\d+"/.test(text)) fail('.kilo/kilo.jsonc lacks BLENDER_PORT');
+  if (!fs.existsSync(path.join(root, '.kilo', 'plugins', 'blender-workflow.js'))) fail('auto-loaded Blender workflow plugin missing');
+}
+
+function checkUpstream() {
+  const version = commandAvailable('uvx', ['--from', 'mcp-for-blender==2.2.6', 'mcp-for-blender', '--help']);
+  if (!version.includes('mcp-for-blender')) fail('pinned mcp-for-blender command did not return expected help');
+}
+
+function doctor({ project } = {}) {
+  const node = process.versions.node;
+  if (Number.parseInt(node, 10) < 22) fail(`Node ${node} is too old; Node 22 or newer required`);
+  checkPackage();
+  checkConfig();
+  commandAvailable('git');
+  commandAvailable('uvx');
+  checkUpstream();
+  const blender = findBlender();
+  const instance = instanceStatus(stateHome());
+  const projectState = project ? new Harness(root).projectDoctor(project) : null;
+  process.stdout.write(JSON.stringify({ ok: true, root, node, upstream: 'mcp-for-blender==2.2.6', blender, instance, project: projectState }, null, 2) + '\n');
+}
+
+function parseOptions(args) {
+  const options = {};
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index];
+    if (!token.startsWith('--')) fail(`unexpected argument: ${token}`);
+    const key = token.slice(2).replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+    if (key === 'dryRun') { options.dryRun = true; continue; }
+    const value = args[index + 1];
+    if (value === undefined || value.startsWith('--')) fail(`missing value for ${token}`);
+    options[key] = value;
+    index += 1;
+  }
+  return options;
+}
+
+async function main() {
+  const command = process.argv[2];
+  if (command === 'doctor') return doctor(parseOptions(process.argv.slice(3)));
+  if (command === 'scaffold') {
+    const options = parseOptions(process.argv.slice(3));
+    if (!options.name) fail('usage: node .kilo/blender-project-harness/tools/harness/cli.mjs scaffold --name "Project Name" [--description "..."] [--goal "..."] [--goal-title "..."] [--dry-run]');
+    const result = scaffold(root, {
+      name: options.name,
+      description: options.description,
+      goal: options.goal,
+      goalTitle: options.goalTitle,
+      dryRun: Boolean(options.dryRun),
+    });
+    if (result.dryRun) process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    else {
+      process.stdout.write(`Created Blender project: ${result.destination}\n\n`);
+      process.stdout.write('Next:\n');
+      process.stdout.write('1. Fill confirmed records through blender_workflow bootstrap-document; use capabilities.documentFormats.\n');
+      process.stdout.write('2. Commit the exact scaffold through blender_workflow bootstrap-commit; do not use manual project Git.\n');
+      process.stdout.write('3. Call blender_workflow prepare, answer its exact question, then start or resume the goal.\n');
+      process.stdout.write(`4. After registration and goal start, call blender_workflow {action:"status",payload:"{\\"project\\":\\"Blender/<Name>\\"}"} and follow nextStep.\n`);
+    }
+    return undefined;
+  }
+  if (command === 'development') {
+    const state = process.argv[3];
+    if (!['on', 'off'].includes(state)) fail('invalid command');
+    const file = configPath(root);
+    const config = readJson(file);
+    config.development_mode = state === 'on';
+    fs.writeFileSync(file, JSON.stringify(config, null, 2) + '\n');
+    return undefined;
+  }
+  fail('usage: node .kilo/blender-project-harness/tools/harness/cli.mjs doctor [--project "Blender/Name"] | scaffold --name "Project Name"');
+}
+
+try { await main(); }
+catch (error) { process.stderr.write(`${error.message}\n`); process.exitCode = 1; }