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

package/README.md

@@ -1,3 +1,369 @@
-# Temporary Holding Version
+<h1 align="center">Blender Project Harness</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <strong>A guarded, evidence-driven Blender production workflow for Kilo.</strong><br>
+  Requirements, bounded scene changes, worker tickets, sealed evidence, independent graders, and clean project history.
+</p>
+
+<p align="center">
+  <a href="https://github.com/punal100/blender-project-harness/releases"><img alt="GitHub release" src="https://img.shields.io/github/v/release/punal100/blender-project-harness?display_name=tag&sort=semver"></a>
+  <a href="https://www.npmjs.com/package/@punal_manalan/blender-project-harness"><img alt="npm" src="https://img.shields.io/badge/npm-1.0.2-CB3837?logo=npm&logoColor=white"></a>
+  <a href="https://github.com/punal100/blender-project-harness/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/github/license/punal100/blender-project-harness"></a>
+  <img alt="Node" src="https://img.shields.io/badge/node-%3E%3D22-brightgreen">
+  <img alt="Blender" src="https://img.shields.io/badge/Blender-5.2-orange">
+  <img alt="MCP for Blender" src="https://img.shields.io/badge/MCP%20for%20Blender-2.2.6-blueviolet">
+  <a href="https://github.com/punal100/blender-project-harness/issues"><img alt="Issues" src="https://img.shields.io/github/issues/punal100/blender-project-harness"></a>
+  <a href="https://github.com/punal100/blender-project-harness/pulls"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen"></a>
+</p>
+
+<p align="center">
+  <a href="#why">Why</a> |
+  <a href="#features">Features</a> |
+  <a href="#install">Install</a> |
+  <a href="#quick-start">Quick start</a> |
+  <a href="#how-it-works">How it works</a> |
+  <a href="#safety-model">Safety</a> |
+  <a href="#tests">Tests</a> |
+  <a href="#star-history">Star history</a>
+</p>
+
+---
+
+## Why
+
+Blender projects are easy to start and hard to keep honest. A scene can look right in the viewport while the geometry, topology, assets, exports, and project history are wrong. A long agent session can also lose track of what changed, what was reviewed, and what is safe to commit.
+
+Blender Project Harness makes the workflow explicit:
+
+- requirements are confirmed before work starts;
+- scene edits are bounded by object names, paths, and declared scenes;
+- a worker executes one ticketed apply batch at a time;
+- visual evidence is inspected, not assumed;
+- the final scene, renders, facts, manifest, and evidence key are sealed;
+- independent graders review frozen evidence;
+- project commits and checkpoints are harness-owned;
+- assets, licences, and exports are verified before completion.
+
+The user stays in plain language. The harness handles the production contract.
+
+---
+
+## Features
+
+| Area | What you get |
+|---|---|
+| Guarded lifecycle | Registration, goals, bounded changes, tickets, WIP renders, seals, reviews, and checkpoints |
+| Single writer | One Blender instance and one apply writer at a time; parallel read-only inspection is allowed |
+| Exact scope | Object names, project-relative paths, declared scenes, requirements, and milestones |
+| Evidence contract | Saved scene hash, per-scene renders, camera evidence, scene facts, manifest, and evidence key |
+| Geometry checks | Dimensions, transforms, materials, topology, non-manifold edges, boundary edges, and loose vertices |
+| Independent grading | Visual, technical, and spec graders with primary and backup models |
+| Review modes | Off, Single, and All |
+| Autonomy modes | Fully Autonomous and Partially Autonomous |
+| Asset governance | Intake, hashes, MIME, dimensions, source, licence, sidecars, and strict asset checks |
+| Multi-scene support | Declared scenes, duplicate/link semantics, per-scene evidence, and a master Video Sequencer scene |
+| Export receipts | Format, path, bytes, SHA-256, source scene, and signature verification |
+| Kilo integration | MCP routing, plugin permissions, goal state, skills, and subagent delegation |
+| Installer | Versioned install, config preservation, dependency install, and automatic backups |
+| Documentation | Setup guide, expected-flow reference, project templates, and contract tests |
+
+---
+
+## Architecture
+
+```mermaid
+flowchart LR
+  U[User] --> K[Kilo]
+  K --> H[Blender Project Harness]
+  H --> T[Apply ticket]
+  T --> W[Worker]
+  W --> B[Blender]
+  B --> S[Saved scene]
+  S --> E[Sealed evidence]
+  E --> G[Visual, technical, spec graders]
+  G --> R[Review verdict]
+  R --> C[Commit and checkpoint]
+  C --> D[Completion]
+```
+
+The harness is the only writer of workflow state. Workers execute assigned tickets. Graders read sealed evidence and write only their own reports.
+
+---
+
+## Install
+
+### Requirements
+
+| Requirement | Version / notes |
+|---|---|
+| Blender | 5.2 is the current tested baseline; the MCP addon requires 3.0+ |
+| MCP for Blender | Pinned `mcp-for-blender==2.2.6` |
+| Node.js | 22 or newer |
+| npm | Bundled with Node.js |
+| uv / uvx | Required for the Blender MCP addon |
+| Kilo | VS Code extension or CLI |
+
+Install the Blender addon:
+
+```powershell
+uvx --from mcp-for-blender==2.2.6 mcp-for-blender install-addon
+```
+
+Enable **Interface: MCP for Blender** under **Edit > Preferences > Add-ons**, then restart Blender.
+
+### From npm
+
+```powershell
+npx @punal_manalan/blender-project-harness@latest install
+```
+
+The 1.0.2 package is the current release. If the registry does not have it yet, use the release
+tarball or a source checkout below.
+
+### From the release tarball
+
+```powershell
+npm install --save-dev https://github.com/punal100/blender-project-harness/releases/download/v1.0.2/punal_manalan-blender-project-harness-1.0.2.tgz
+npx blender-project-harness install
+```
+
+### From source
+
+```powershell
+git clone https://github.com/punal100/blender-project-harness.git
+Set-Location blender-project-harness
+npm ci --prefix .kilo/blender-project-harness/tools/harness
+npm run doctor --prefix .kilo/blender-project-harness/tools/harness
+```
+
+### What the installer does
+
+- Copies the harness into `.kilo/blender-project-harness/tools/`.
+- Writes `VERSION`, `install.json`, `config.json`, and a copy of the package `AGENTS.md`.
+- Runs `npm ci` for the installed harness.
+- Updates `.kilo/kilo.jsonc` and `.kilo/plugins/blender-workflow.js`.
+- Adds missing `AGENTS.md`, `.kilo/skills/`, `.kilo/agent/`, and `Blender/README.md`.
+- Adds the local config and backups to `.gitignore`.
+
+Run the same command to update. The previous installation is moved to:
+
+```text
+.temp/blender-project-harness-backups/<version>-<timestamp>/
+```
+
+The old copy is preserved, not deleted. The new version keeps `config.json` unless you pass
+`--reset-config`. The package `AGENTS.md` is always available at
+`.kilo/blender-project-harness/AGENTS.md`; the root `AGENTS.md` is only installed when missing and is
+never overwritten.
+
+---
+
+## Quick start
+
+Open the workspace in Kilo and describe the project. Include the subject, style, key objects, camera
+and lighting preferences, dimensions, deliverables, and whether external files or paid media
+generation are allowed.
+
+```text
+Create a small cozy retro computer room. Use warm lamp light, a cool window accent, a desk with a
+CRT monitor, keyboard, mug, chair, rug, and wall decor. Make one hero camera view and save the scene
+inside a new Blender project.
+```
+
+The agent then:
+
+1. Confirms requirements and asks for the workflow mode: **Fully Autonomous** or **Partially
+   Autonomous**.
+2. Asks for the review mode: **Off**, **Single**, or **All**.
+3. Scaffolds the project, fills its records, registers it, and starts the goal.
+4. Launches Blender through the harness and saves the bootstrap scene.
+5. Builds the project in bounded changes using worker apply tickets.
+6. Renders and inspects WIP evidence, then seals a review round.
+7. Dispatches the configured graders and aggregates their reports.
+8. Commits the scoped change, checkpoints the project, and reports the result.
+
+---
+
+## How it works
+
+```text
+status and capabilities
+  -> requirements confirmation
+  -> workflow and review mode selection
+  -> scaffold, documents, registration, and goal
+  -> bounded scene change
+  -> apply ticket and worker execution
+  -> save and WIP render
+  -> finalize and seal
+  -> independent graders
+  -> review verdict
+  -> scoped commit and checkpoint
+  -> completion
+```
+
+### Bounded changes
+
+- One observable outcome per change.
+- Exact object names and project-relative paths.
+- Declared scenes for multi-scene work.
+- Requirement and milestone scoping.
+- One open change per project.
+- Apply batches up to ten operations.
+- Ticket expiry and change-window recovery.
+- Worker-only apply execution.
+
+### Sealed evidence
+
+A sealed round captures:
+
+- the saved `.blend` hash;
+- per-scene renders;
+- camera evidence;
+- scene facts including dimensions and topology;
+- a manifest with every evidence hash;
+- a reproducible evidence key;
+- a review round folder;
+- the strict asset-check receipt when assets were used.
+
+Graders must cite the same scene hash and evidence key. Missing evidence or tooling problems produce
+`BLOCKED`, not a pass.
+
+### Review modes
+
+| Mode | Behavior |
+|---|---|
+| Off | Self-review only |
+| Single | One configured grader |
+| All | Every configured grader, up to `max_parallel` |
+
+Every worker and grader has a primary and backup provider/model/reasoning variant. A missing or
+disabled grader is a tooling failure, not a silent pass.
+
+### Assets and exports
+
+- User-supplied files enter through guarded `intake`.
+- Downloads stage public HTTPS assets only; they do not import or register automatically.
+- Generated media is agent-owned and requires permission before credits are spent.
+- External assets require `SOURCE.md` and `LICENSE.txt`.
+- Non-redistributable binaries stay out of Git.
+- Strict `check_assets` must pass on the final unchanged scene.
+- Exports receive a verified receipt with format, path, bytes, SHA-256, source scene, and signature.
+
+---
+
+## Safety model
+
+| Guarantee | Behavior |
+|---|---|
+| One Blender instance | The workspace runs one guarded instance at a time |
+| One writer | Apply operations execute through one worker at a time |
+| Bounded edits | Every scene change has exact names, paths, and declared scenes |
+| No raw Python | Arbitrary Blender Python and project Python execution are blocked |
+| No manual project Git | Project commits go through the harness |
+| No silent pass | Missing evidence and grader failures produce `BLOCKED` |
+| No fake assets | Generated or downloaded files must be inspected, registered, and licensed |
+| No hidden exports | Every export needs a verified receipt |
+| No frozen-record edits | Registration changes require explicit re-registration |
+
+---
+
+## Configuration
+
+Worker and grader configuration lives at:
+
+```text
+.kilo/blender-project-harness/config.json
+```
+
+The tracked template is:
+
+```text
+.kilo/blender-project-harness/config.example.json
+```
+
+Review and autonomy modes are frozen at registration. Changing them requires explicit
+re-registration, not an in-place edit.
+
+---
+
+## Tests
+
+```powershell
+npm run test:installer
+npm test --prefix .kilo/blender-project-harness/tools/harness
+python -B -m unittest discover -s .kilo/blender-project-harness/tools -p "test_*.py" -v
+```
+
+The Node suite is comprehensive and can take several minutes on Windows. Use `npm run pack:check` to
+inspect the npm package contents without publishing.
+
+Current release checks:
+
+- Installer tests: `6/6` passing.
+- Python harness contract tests: `21` passing with `112` subtests.
+- Targeted engine, plugin, shell-policy, and workspace tests: passing.
+- Doctor: passing.
+- npm package: `91` files, no `node_modules`, no local `config.json`.
+
+---
+
+## What's in the repo
+
+```text
+AGENTS.md                 Internal agent contract and workflow rules
+README.md                 This human setup and usage guide
+package.json              npm package metadata and installer entry point
+bin/                      npm installer executable
+installer/                Versioned installer, update, and backup logic
+.kilo/                    Workspace Kilo config, skills, agents, and plugin
+.kilo/blender-project-harness/
+                          Harness, config, and version records
+.kilo/blender-project-harness/config.example.json
+                          Default worker and grader configuration
+.kilo/blender-project-harness/config.json
+                          Local worker and grader configuration (ignored)
+.kilo/blender-project-harness/tools/harness/
+                          Guarded Node.js workflow, MCP bridge, and harness tests
+.kilo/blender-project-harness/tools/harness/EXPECTED_FLOW.md
+                          Developer reference for the expected lifecycle and evidence
+Blender/                  Blender project collection
+Commands/                 Approved non-project shell-command records
+```
+
+[`Blender/README.md`](Blender/README.md) covers the project-collection conventions. The generic
+harness lifecycle and evidence contract are documented in
+[`.kilo/blender-project-harness/tools/harness/EXPECTED_FLOW.md`](.kilo/blender-project-harness/tools/harness/EXPECTED_FLOW.md).
+Licensing lives in [`LICENSE`](LICENSE) and [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).
+
+---
+
+## Star history
+
+<a href="https://www.star-history.com/#punal100/blender-project-harness&Date">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=punal100/blender-project-harness&type=Date&theme=dark">
+    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=punal100/blender-project-harness&type=Date">
+    <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=punal100/blender-project-harness&type=Date">
+  </picture>
+</a>
+
+Star history is provided by [star-history.com](https://www.star-history.com/).
+
+---
+
+## Known limits
+
+- No arbitrary Blender Python execution.
+- No browser or authentication bypass.
+- No automatic licence acceptance.
+- Media generation is agent-owned; the harness intakes and records the result.
+- Multi-scene, media-generation, and export paths are implemented, but the current live acceptance
+  run is a single scene. Verify those paths in the project where they are used.
+- One live Blender instance and one writer at a time; parallel read-only inspection is allowed.
+- Windows is the primary documented setup environment.
+
+---
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,51 @@
+# Third-party notices
+
+## MCP for Blender workflow guides
+
+The files in `.kilo/skills/blender-mcp/references/` are adapted from the workflow
+guides shipped with [ahujasid/mcp-for-blender](https://github.com/ahujasid/mcp-for-blender)
+(`src/blender_mcp/guides/`) and are used under the MIT License.
+
+Adapted files:
+
+- `animation.md`
+- `bpy.md`
+- `level-design.md`
+- `materials.md`
+- `retopology.md`
+- `rigging.md`
+- `scene.md`
+
+Local changes: version-specific API corrections, safety and approval wording,
+neutral examples (reference values are not project requirements), source links,
+and workspace-specific guidance. Git history records each change.
+
+### Upstream license
+
+MIT License
+
+Copyright (c) 2025 Siddharth Ahuja
+
+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.
+
+## Blender
+
+Blender is a trademark of the Blender Foundation. This project is an unaided
+workspace and tooling template; it is not affiliated with or endorsed by the
+Blender Foundation or the mcp-for-blender project.

package/bin/blender-project-harness.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from '../installer/cli.mjs';
+
+await main(process.argv.slice(2));

package/installer/cli.mjs

@@ -0,0 +1,116 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { install, status, INSTALL_RELATIVE, PACKAGE_NAME } from './install.mjs';
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const packageJson = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+
+function usage() {
+  return [
+    `${PACKAGE_NAME} ${packageJson.version}`,
+    '',
+    'Usage:',
+    '  npx @punal_manalan/blender-project-harness [install] [options]',
+    '  npx @punal_manalan/blender-project-harness status [--root <path>] [--json]',
+    '  npx @punal_manalan/blender-project-harness doctor [--root <path>]',
+    '',
+    'Options:',
+    '  --root <path>       Workspace root (default: current directory)',
+    '  --force             Reinstall the current version',
+    '  --dry-run           Show what would change without writing',
+    '  --skip-deps         Do not run npm ci in the installed harness',
+    '  --reset-config      Replace the installed config with the package example',
+    '  --json              Print machine-readable output',
+    '  --version           Print the package version',
+    '  --help              Show this help',
+    '',
+    'The harness is installed under .kilo/blender-project-harness.',
+    'An existing installation is moved to .temp/blender-project-harness-backups.',
+  ].join('\n');
+}
+
+function parse(argv) {
+  const known = new Set(['install', 'status', 'doctor', 'help']);
+  const command = known.has(argv[0]) ? argv.shift() : 'install';
+  const options = { root: process.cwd(), force: false, dryRun: false, skipDeps: false, resetConfig: false, json: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === '--root') {
+      const value = argv[index + 1];
+      if (!value || value.startsWith('--')) throw new Error('missing value for --root');
+      options.root = path.resolve(value);
+      index += 1;
+    } else if (token === '--force') options.force = true;
+    else if (token === '--dry-run') options.dryRun = true;
+    else if (token === '--skip-deps' || token === '--no-deps') options.skipDeps = true;
+    else if (token === '--reset-config') options.resetConfig = true;
+    else if (token === '--json') options.json = true;
+    else if (token === '--help' || token === '-h') options.help = true;
+    else if (token === '--version' || token === '-v') options.version = true;
+    else throw new Error(`unknown option: ${token}`);
+  }
+  return { command, options };
+}
+
+function humanInstall(result) {
+  if (result.status === 'current') {
+    return `${PACKAGE_NAME} ${result.version} is already installed at ${INSTALL_RELATIVE}. Use --force to reinstall.`;
+  }
+  const lines = [
+    `${result.status === 'updated' ? 'Updated' : 'Installed'} ${PACKAGE_NAME} ${result.version}`,
+    `Location: ${path.relative(result.root, result.installDir).replaceAll('\\', '/')}`,
+    `Dependencies: ${result.dependencies}`,
+  ];
+  if (result.backup) lines.push(`Backup: ${result.backup}`);
+  if (result.written?.length) lines.push(`Updated: ${result.written.join(', ')}`);
+  if (result.actions?.length) lines.push(`Created: ${result.actions.join(', ')}`);
+  if (result.warnings?.length) lines.push(...result.warnings.map((warning) => `Warning: ${warning}`));
+  return lines.join('\n');
+}
+
+async function main(argv) {
+  try {
+    const { command, options } = parse([...argv]);
+    if (options.help || command === 'help') {
+      process.stdout.write(`${usage()}\n`);
+      return;
+    }
+    if (options.version) {
+      process.stdout.write(`${packageJson.version}\n`);
+      return;
+    }
+    if (command === 'status') {
+      const result = status({ root: options.root });
+      process.stdout.write(options.json ? `${JSON.stringify(result, null, 2)}\n`
+        : result.installed
+          ? `${PACKAGE_NAME} ${result.version} installed at ${path.relative(result.root, result.installDir).replaceAll('\\', '/')}\n`
+          : `${PACKAGE_NAME} is not installed under ${INSTALL_RELATIVE}\n`);
+      return;
+    }
+    if (command === 'doctor') {
+      const cli = path.join(options.root, INSTALL_RELATIVE, 'tools', 'harness', 'cli.mjs');
+      if (!fs.existsSync(cli)) throw new Error(`harness is not installed at ${INSTALL_RELATIVE}; run install first`);
+      const result = spawnSync(process.execPath, [cli, 'doctor'], { cwd: options.root, stdio: 'inherit', windowsHide: false });
+      if (result.error) throw result.error;
+      process.exitCode = result.status ?? 1;
+      return;
+    }
+    const result = install({
+      root: options.root,
+      packageRoot,
+      version: packageJson.version,
+      force: options.force,
+      dryRun: options.dryRun,
+      skipDeps: options.skipDeps,
+      resetConfig: options.resetConfig,
+    });
+    process.stdout.write(options.json || options.dryRun ? `${JSON.stringify(result, null, 2)}\n` : `${humanInstall(result)}\n`);
+  } catch (error) {
+    process.stderr.write(`${PACKAGE_NAME}: ${error.message}\n`);
+    process.exitCode = 1;
+  }
+}
+
+export { main };