motionloom 2.0.0 → 2.1.0

package/scripts/project_memory_loader.py

@@ -0,0 +1,31 @@
+"""Small import-safe bridge for the cross-platform analyzer."""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+
+
+def _module():
+    path = Path(__file__).with_name("project-memory.py")
+    spec = importlib.util.spec_from_file_location("motionloom_project_memory", path)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"Cannot load Project Memory module: {path}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def refresh_if_present(root: Path, context_path: Path, initialize: bool = False):
+    module = _module()
+    memory_path = (root / ".motionloom" / "project-memory.json").resolve()
+    if not memory_path.exists():
+        if not initialize:
+            return None
+        memory = module.base_memory(root, str(context_path))
+        module.write_atomic(memory_path, memory)
+        return {"status": "initialized", "memory_path": str(memory_path), "freshness": memory["freshness"]}
+    memory = module.load_or_fail(memory_path)
+    refreshed = module.refresh_memory(memory, root, str(context_path))
+    module.write_atomic(memory_path, refreshed)
+    return {"status": refreshed["freshness"]["status"], "memory_path": str(memory_path), "freshness": refreshed["freshness"]}

package/scripts/release-verify.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""Verify the immutable metadata chain before an npm/GitHub release."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Verify package version, changelog and release note alignment.")
+    parser.add_argument("--expected-version", default="")
+    parser.add_argument("--package", default=str(ROOT / "package.json"))
+    parser.add_argument("--changelog", default=str(ROOT / "CHANGELOG.md"))
+    parser.add_argument("--release-note", default="")
+    parser.add_argument("--tag", default="", help="Optional Git tag; accepts v<version> or <version>")
+    args = parser.parse_args()
+
+    errors: list[str] = []
+    package_path = Path(args.package).resolve()
+    package = json.loads(package_path.read_text(encoding="utf-8"))
+    actual = str(package.get("version", ""))
+    expected = str(args.expected_version or actual).removeprefix("v")
+    if actual != expected:
+        errors.append(f"package version {actual!r} does not match expected {expected!r}")
+
+    changelog = Path(args.changelog).resolve()
+    if not re.search(rf"^## \[{re.escape(expected)}\](?:\s|$)", changelog.read_text(encoding="utf-8"), re.MULTILINE):
+        errors.append(f"CHANGELOG.md has no heading for [{expected}]")
+
+    note = Path(args.release_note) if args.release_note else ROOT / "docs/releases" / f"{expected}.md"
+    if not note.is_absolute():
+        note = ROOT / note
+    if not note.is_file():
+        errors.append(f"release note is missing: {note.relative_to(ROOT) if note.is_relative_to(ROOT) else note}")
+
+    if args.tag and args.tag.removeprefix("v") != expected:
+        errors.append(f"tag {args.tag!r} does not match version {expected!r}")
+
+    report = {"status": "fail" if errors else "pass", "version": actual, "expected_version": expected, "errors": errors}
+    print(json.dumps(report, indent=2))
+    return 1 if errors else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/render.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+"""
+MotionLoom render entrypoint.
+
+Style contract: evidence-first, explicit runtime mode and no hidden approval
+side effects. This is the cross-platform equivalent of render.sh and delegates
+to the canonical Python snapshot renderer without requiring Bash.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import sys
+from pathlib import Path
+
+
+SCENE_RE = re.compile(r"^[A-Za-z0-9._-]+$")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Render MotionLoom runtime snapshots")
+    parser.add_argument("scene")
+    parser.add_argument("--repo", default=None, help="Repository root; defaults to the script parent")
+    parser.add_argument("--progress", default="0,50,100")
+    parser.add_argument("--allow-placeholder", action="store_true")
+    args = parser.parse_args()
+
+    if not SCENE_RE.fullmatch(args.scene):
+        parser.error("scene id contains unsafe path characters")
+
+    repo = Path(args.repo).expanduser().resolve() if args.repo else Path(__file__).resolve().parents[1]
+    scene_dir = repo / "src" / "output" / args.scene
+    if not scene_dir.is_dir():
+        print(f"error: scene directory not found: {scene_dir}", file=sys.stderr)
+        return 1
+
+    try:
+        progress = [int(value) for value in args.progress.split(",") if value.strip()]
+    except ValueError:
+        print("error: progress must be a comma-separated list of integers", file=sys.stderr)
+        return 1
+
+    if not progress or any(value < 0 or value > 100 for value in progress):
+        print("error: progress values must be between 0 and 100", file=sys.stderr)
+        return 1
+
+    # Import by path-independent package layout. The repository root is added
+    # only for this process; no cwd or shell-specific import assumptions.
+    sys.path.insert(0, str(repo))
+    from src.core.snapshot import render_snapshots  # pylint: disable=import-outside-toplevel
+
+    result = render_snapshots(
+        args.scene,
+        scene_dir,
+        progress,
+        allow_placeholder=args.allow_placeholder or os.environ.get("ALLOW_PLACEHOLDER") == "1",
+    )
+    print(__import__("json").dumps(result, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/report.py

@@ -6,6 +6,7 @@ from __future__ import annotations
 import argparse
 import hashlib
 import json
+import shutil
 import sys
 from datetime import datetime, timezone
 from pathlib import Path
@@ -49,6 +50,39 @@ def read_json(path: Path, default: dict | list | None = None):
     return json.loads(path.read_text(encoding="utf-8"))
 
 
+def project_memory_path() -> Path:
+    return ROOT / ".motionloom" / "project-memory.json"
+
+
+def memory_summary() -> dict | None:
+    path = project_memory_path()
+    if not path.is_file():
+        return None
+    try:
+        memory = read_json(path)
+        digest = hashlib.sha256(path.read_bytes()).hexdigest()
+    except (OSError, json.JSONDecodeError):
+        return {"path": ".motionloom/project-memory.json", "status": "invalid"}
+    freshness = memory.get("freshness") if isinstance(memory, dict) else {}
+    return {
+        "path": ".motionloom/project-memory.json",
+        "snapshot_path": "project-memory.json",
+        "memory_id": memory.get("memory_id"),
+        "status": freshness.get("status", "invalid"),
+        "sha256": digest,
+        "updated_at": memory.get("updated_at"),
+    }
+
+
+def sync_memory_snapshot(task_dir: Path) -> dict | None:
+    source = project_memory_path()
+    if not source.is_file():
+        return None
+    destination = task_dir / "project-memory.json"
+    shutil.copy2(source, destination)
+    return memory_summary()
+
+
 def has_symlink_component(path: Path) -> bool:
     current = path
     while True:
@@ -78,6 +112,7 @@ def candidate_is_current(candidate: dict) -> bool:
 def init_task(args: argparse.Namespace) -> int:
     task_dir = Path(args.output or ROOT / "artifacts" / args.task_id).resolve()
     timestamp = now()
+    memory = memory_summary()
     task = {
         "schema_version": "1.0",
         "task_id": args.task_id,
@@ -92,6 +127,8 @@ def init_task(args: argparse.Namespace) -> int:
         "created_at": timestamp,
         "updated_at": timestamp,
     }
+    if memory:
+        task["project_memory"] = memory
     report = {
         "report_version": "1.0",
         "task_id": args.task_id,
@@ -103,7 +140,7 @@ def init_task(args: argparse.Namespace) -> int:
         "problems": [],
         "structure_review": {"missing_files": [], "broken_references": [], "untracked_artifacts": []},
         "browser_review": [],
-        "next_agent": [{"agent": args.agent, "action": "Run project analysis and populate context before generation."}],
+        "next_agent": [{"agent": args.agent, "action": "Recover Project Memory and run project analysis before generation.", "evidence_needed": ["project-memory.json", "project-context.json"]}],
         "generated_at": timestamp,
     }
     handoff = {
@@ -114,7 +151,7 @@ def init_task(args: argparse.Namespace) -> int:
         "state": "created",
         "summary": "New animation task initialized.",
         "next_actions": [{"action": "Analyze host project context", "skill": "motionloom", "evidence_needed": ["project-context.json"]}],
-        "required_artifacts": ["task.json", "execution-report.json", *EVIDENCE_ARTIFACTS],
+        "required_artifacts": ["task.json", "execution-report.json", *EVIDENCE_ARTIFACTS, *( ["project-memory.json"] if memory else [] )],
         "blockers": [],
     }
     write_json(task_dir / "task.json", task)
@@ -122,6 +159,8 @@ def init_task(args: argparse.Namespace) -> int:
     write_json(task_dir / "issue-register.json", {"version": "1.0", "task_id": args.task_id, "issues": []})
     write_json(task_dir / "handoff.json", handoff)
     write_json(task_dir / "artifact-manifest.json", {"manifest_version": "1.0", "task_id": args.task_id, "generated_at": timestamp, "artifacts": []})
+    if memory:
+        sync_memory_snapshot(task_dir)
     (task_dir / "decision-log.jsonl").write_text("", encoding="utf-8")
     print(json.dumps({"status": "created", "task_id": args.task_id, "task_dir": str(task_dir)}, ensure_ascii=False))
     return 0
@@ -130,6 +169,7 @@ def init_task(args: argparse.Namespace) -> int:
 def collect(args: argparse.Namespace) -> int:
     task_dir = Path(args.task_dir).resolve()
     task = read_json(task_dir / "task.json")
+    sync_memory_snapshot(task_dir)
     excluded = {"artifact-manifest.json", "execution-report.json", "decision-log.jsonl"}
     artifacts = []
     for path in sorted(task_dir.rglob("*")):
@@ -146,6 +186,8 @@ def collect(args: argparse.Namespace) -> int:
         handoff = read_json(handoff_path)
         required = set(handoff.get("required_artifacts", []))
         required.update(name for name in EVIDENCE_ARTIFACTS if (task_dir / name).is_file())
+        if (task_dir / "project-memory.json").is_file():
+            required.add("project-memory.json")
         handoff["required_artifacts"] = sorted(required)
         write_json(handoff_path, handoff)
     print(json.dumps({"status": "collected", "task_id": manifest["task_id"], "artifact_count": len(artifacts)}, ensure_ascii=False))

package/scripts/review-hook.py

@@ -7,6 +7,7 @@ import argparse
 import hashlib
 import json
 import re
+import shutil
 import subprocess
 import sys
 from datetime import datetime, timedelta, timezone
@@ -68,6 +69,11 @@ def prepare(args: argparse.Namespace) -> int:
     if not scene:
         raise ValueError("task.json requires scene")
     scene_dir, source_path, render_meta, context_path = paths(task_dir, task)
+    memory_path = ROOT / ".motionloom" / "project-memory.json"
+    memory = read_json(memory_path, {}) if memory_path.is_file() else {}
+    memory_status = (memory.get("freshness") or {}).get("status")
+    if memory_path.is_file() and memory_status not in {"fresh", None}:
+        raise ValueError(f"project memory is {memory_status}; run motionloom memory refresh/analyze before browser review")
     spec = read_json(scene_dir / "motion-spec.json")
     context_hash = (spec.get("context_binding") or {}).get("context_sha256") or sha256(context_path)
     source_hash = sha256(source_path)
@@ -92,6 +98,9 @@ def prepare(args: argparse.Namespace) -> int:
         "prepared_at": now(),
         "expires_at": (datetime.now(timezone.utc) + CANDIDATE_TTL).replace(microsecond=0).isoformat().replace("+00:00", "Z"),
     }
+    if memory_path.is_file():
+        candidate["project_memory_sha256"] = sha256(memory_path)
+        candidate["project_memory_id"] = memory.get("memory_id")
     (scene_dir / "browser-review.json").write_text(json.dumps(candidate, indent=2) + "\n", encoding="utf-8")
     task["state"] = "review_required"
     task["updated_at"] = now()
@@ -109,9 +118,11 @@ def prepare(args: argparse.Namespace) -> int:
     report_path.write_text(json.dumps(report, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
     handoff_path = task_dir / "handoff.json"
     handoff = read_json(handoff_path)
-    handoff.update({"state": "review_required", "to_agent": "browser-review-agent", "summary": "Open the exact rendered candidate in the internal Dev Lab and obtain user approval before PR.", "next_actions": [{"action": "Open internal Dev Lab candidate", "kind": "browser_review", "agent": "browser-review-agent", "skill": "browser-review", "url": url, "candidate_id": cid, "requires_user_approval": True, "evidence_needed": ["review.json"], "output_artifacts": ["review.json"]}], "required_artifacts": sorted(set(handoff.get("required_artifacts", []) + ["browser-review.json", "review.json", "semantic-lint-benchmark.json", "evidence-verifier-report.json", "runtime-adapters/runtime-evidence.json"]))})
+    if memory_path.is_file():
+        shutil.copy2(memory_path, task_dir / "project-memory.json")
+    handoff.update({"state": "review_required", "to_agent": "browser-review-agent", "summary": "Open the exact rendered candidate in the internal Dev Lab and obtain user approval before PR.", "next_actions": [{"action": "Open internal Dev Lab candidate", "kind": "browser_review", "agent": "browser-review-agent", "skill": "browser-review", "url": url, "candidate_id": cid, "requires_user_approval": True, "evidence_needed": ["review.json"], "output_artifacts": ["review.json"]}], "required_artifacts": sorted(set(handoff.get("required_artifacts", []) + ["browser-review.json", "review.json", "semantic-lint-benchmark.json", "evidence-verifier-report.json", "runtime-adapters/runtime-evidence.json"] + (["project-memory.json"] if memory_path.is_file() else [])))})
     handoff_path.write_text(json.dumps(handoff, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
-    subprocess.run(["bash", str(ROOT / "scripts/devlab.sh"), scene, "--prepare-only", str(task_dir)], check=True, capture_output=True, text=True)
+    subprocess.run([sys.executable, str(ROOT / "scripts/devlab.py"), scene, "--prepare-only", "--task-dir", str(task_dir)], check=True, capture_output=True, text=True)
     subprocess.run([sys.executable, str(ROOT / "scripts/report.py"), "collect", "--task-dir", str(task_dir)], check=True, capture_output=True, text=True)
     print(json.dumps({"status": "review_required", "task_id": task["task_id"], "candidate_id": cid, "url": url, "agent": "browser-review-agent", "action": "Open this exact URL in the internal browser; ask the user to inspect frames 0/50/100 and approve or request changes.", "requires_user_approval": True, "output_artifacts": ["review.json"]}, ensure_ascii=False))
     return 0

package/scripts/skill-doctor.py

@@ -13,7 +13,16 @@ from pathlib import Path
 ROOT = Path(__file__).resolve().parents[1]
 REQUIRED_FILES = ["SKILL.md", "agent-card.json", "package.json"]
 REQUIRED_DIRS = ["scripts", "templates", "references", "schemas"]
-REQUIRED_SCRIPT_FILES = ["scripts/report-contract.py", "scripts/review-hook.py", "scripts/quality-gate.py", "scripts/runtime-adapters.mjs"]
+REQUIRED_SCRIPT_FILES = [
+    "scripts/report-contract.py",
+    "scripts/review-hook.py",
+    "scripts/quality-gate.py",
+    "scripts/runtime-adapters.mjs",
+    "scripts/project-memory.py",
+    "scripts/project_memory_loader.py",
+    "scripts/analyze.py",
+    "scripts/devlab.py",
+]
 REQUIRED_SCHEMAS = [
     "task.schema.json",
     "execution-report.schema.json",
@@ -26,6 +35,7 @@ REQUIRED_SCHEMAS = [
     "provenance.schema.json",
     "capability-registry.schema.json",
     "motion-ir.schema.json",
+    "project-memory.schema.json",
 ]
 
 
@@ -121,7 +131,7 @@ def run() -> int:
     package_path = ROOT / "package.json"
     try:
         package = json.loads(package_path.read_text(encoding="utf-8"))
-        for script in ("test", "validate", "doctor", "report", "report:check", "review"):
+        for script in ("test", "validate", "doctor", "report", "report:check", "review", "memory:bootstrap", "memory:recover", "memory:validate", "devlab", "pack:dotlottie"):
             if script not in package.get("scripts", {}):
                 warnings.append({"code": "missing_package_script", "message": f"package.json has no {script} script."})
     except (FileNotFoundError, json.JSONDecodeError) as exc:

package/scripts/to-dotlottie.mjs

@@ -6,9 +6,8 @@
  */
 import crypto from "node:crypto";
 import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
-import { execFileSync } from "node:child_process";
+import { strFromU8, zipSync, unzipSync } from "fflate";
 
 function arg(name, fallback = undefined) {
   const index = process.argv.indexOf(name);
@@ -43,17 +42,14 @@ if (!/^[a-zA-Z0-9._ -]+$/.test(animationId)) {
 }
 readJson(sourcePath);
 
-const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "animation-skill-dotlottie-"));
-const archiveRoot = path.join(tmp, "archive");
-fs.mkdirSync(path.join(archiveRoot, "a"), { recursive: true });
-fs.copyFileSync(sourcePath, path.join(archiveRoot, "a", `${animationId}.json`));
+const archive = {
+  [`a/${animationId}.json`]: fs.readFileSync(sourcePath),
+};
 
 const optionalDirectories = ["i", "t", "s", "f"];
 for (const directory of optionalDirectories) {
   const candidate = path.join(sceneDir, "dotlottie", directory);
-  if (fs.existsSync(candidate)) {
-    fs.cpSync(candidate, path.join(archiveRoot, directory), { recursive: true });
-  }
+  if (fs.existsSync(candidate)) addTree(candidate, directory);
 }
 
 const dotManifest = {
@@ -62,20 +58,13 @@ const dotManifest = {
   initial: { animation: animationId },
   animations: [{ id: animationId }],
 };
-fs.writeFileSync(
-  path.join(archiveRoot, "manifest.json"),
-  `${JSON.stringify(dotManifest, null, 2)}\n`,
-  "utf8",
-);
+archive["manifest.json"] = Buffer.from(`${JSON.stringify(dotManifest, null, 2)}\n`, "utf8");
 
 fs.mkdirSync(path.dirname(output), { recursive: true });
 if (fs.existsSync(output)) fs.rmSync(output, { force: true });
-execFileSync("zip", ["-X", "-q", "-r", output, "."], { cwd: archiveRoot });
+fs.writeFileSync(output, zipSync(archive, { level: 6 }));
 
-const entries = execFileSync("unzip", ["-Z1", output], { encoding: "utf8" })
-  .trim()
-  .split(/\r?\n/)
-  .filter(Boolean);
+const entries = Object.keys(unzipSync(fs.readFileSync(output))).sort();
 if (!entries.includes("manifest.json")) throw new Error("archive missing manifest.json");
 if (!entries.includes(`a/${animationId}.json`)) {
   throw new Error("archive missing initial animation payload");
@@ -95,5 +84,22 @@ console.log(JSON.stringify({
 }, null, 2));
 
 function readJsonFromZip(file, entry) {
-  return JSON.parse(execFileSync("unzip", ["-p", file, entry], { encoding: "utf8" }));
+  const payload = unzipSync(fs.readFileSync(file))[entry];
+  if (!payload) throw new Error(`archive entry is missing: ${entry}`);
+  return JSON.parse(strFromU8(payload));
+}
+
+function addTree(directory, archivePrefix) {
+  const entries = fs.readdirSync(directory, { withFileTypes: true });
+  for (const entry of entries) {
+    const sourceEntry = path.join(directory, entry.name);
+    const archiveEntry = `${archivePrefix}/${entry.name.replaceAll("\\", "/")}`;
+    const stat = fs.lstatSync(sourceEntry);
+    if (stat.isSymbolicLink()) continue;
+    if (stat.isDirectory()) {
+      addTree(sourceEntry, archiveEntry);
+    } else if (stat.isFile()) {
+      archive[archiveEntry] = fs.readFileSync(sourceEntry);
+    }
+  }
 }