@rig-c/review 0.2.1 → 0.3.0

package/README.md

@@ -205,6 +205,31 @@ printed: every current instance binds only `127.0.0.1`.
 The printed feedback retrieval command uses POSIX shell quoting for literal path
 arguments. It is not a PowerShell or cmd.exe command string.
 
+### Launcher contract
+
+A launcher may start `rig-review open` as a child process and rely on its stdout,
+stderr and exit code alone:
+
+1. On success stdout is exactly one line, the URL. `open` never writes anything
+   else to stdout.
+2. On success stderr carries the human lines in this fixed order: the animation
+   diagnostic (when a clip is selected), the control notice (with `--control`),
+   then the copyable retrieval line `Review started|reused; feedback: rig-review feedback …`.
+3. A refusal exits with code 1, writes nothing to stdout, and its first stderr line
+   starts with a name, followed by a colon and the explanation:
+   - `OPEN_INPUT_MISSING <path>`: the input or `--compare` path does not exist, or is neither a directory nor a regular file.
+   - `OPEN_INPUT_UNRECOGNIZED <path>`: the folder holds no recognized model, skeleton, motion, report, reference or pose sequence, or the file is not a JSON manifest.
+   - `OPEN_REFERENCE_REQUIRED`: `--compare` was given without an explicit `--reference`.
+   - `OPEN_ANIMATION_UNKNOWN <name>`: the explicit or report-named clip (JSON-quoted) is not in the compiled model.
+   - `OPEN_ANIMATION_AMBIGUOUS`: no flag or report selects one clip, or the A/B reports conflict.
+   - `OPEN_ANIMATION_UNVALIDATABLE`: a clip was requested but no compiled model can validate it.
+   - `OPEN_OPTION_INVALID <flag>`: an unknown, duplicate, empty or value-less option.
+4. Exit codes: 0 applied, 1 refused. (`control` keeps its own exit 2 for an
+   unapplied command.)
+
+Package validation and worker startup refusals keep their existing messages; the
+named refusals above are decided before any state is written.
+
 ### Managed front and write capability
 
 `open` is **managed by default**. It ensures one detached loopback front at
@@ -230,7 +255,10 @@ One origin cannot isolate scripts that run on it, so writes are bound to a
 per-instance capability rather than to the page's origin or the key in its path.
 Each worker mints a 256-bit capability kept only in its private 0600 open record.
 `open` (managed or direct) and the foreground `review`/`review compare` commands
-print it in the `#cap=` fragment, which browsers never send to a server. The page
+print it in the `#cap=` fragment, which browsers never send to a server. That
+printed link goes only to the terminal of the command that started the instance.
+Output meant for a log does not carry it: the install smoke (`bun run smoke`, whose output CI publishes) prints the same
+URL as `#cap=<redacted>` and fails if any capability value reaches its stdout. The page
 moves it into memory and that tab's `sessionStorage`, then removes the fragment
 from the address bar. Every mutation sends it as `X-Review-Capability`; the front
 checks it before forwarding and the worker compares it again in constant time

package/docs/REVIEW_PACKAGE.md

@@ -239,9 +239,8 @@ A strip plan with one clock basis reports `plan.basis:"single"|"a"|"b"`. A compa
 
 `rig-review open <input> [--reference <local-video>] [--compare <input>]
 [--animation <name>]` hashes and validates the input, starts/reuses a fixed-binding
-background instance and prints a URL alone on stdout. Its matching read-only
-`feedback <input> --reference <same-video> [--compare <input> --animation <name>]`
-command is printed on stderr. Existing `feedback compare ...` remains supported.
+background instance and follows the [launcher contract](../README.md#launcher-contract)
+for stdout, stderr and exit codes. Existing `feedback compare ...` remains supported.
 Open animation selection uses `--animation` first, a normalized report `animation`
 second, and a unique actual model clip (or common A/B clip) last. Report metadata
 comes from the exact already-hashed recognized report bytes, never a separately

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/review",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "type": "module",
   "description": "Local human rig inspection and structured feedback export",
   "license": "MIT",

package/src/animation-selection.ts

@@ -2,21 +2,25 @@
 import type {FeedbackCatalog} from './feedback-validation.ts';
 import type {ReportSeeds} from './report.ts';
 export interface AnimationSelection {name:string;source:'cli'|'report'|'unique';reportPaths?:string[]}
+/** The message stays the shared check/feedback text; `kind` lets the open launcher name the refusal. */
+export class AnimationSelectionError extends Error {
+ constructor(message:string,readonly kind:'empty'|'unknown'|'ambiguous'|'unvalidatable',readonly label:string|null=null,readonly animation?:string){super(message);}
+}
 interface Source {label:string;catalog:Pick<FeedbackCatalog,'animations'>;report:Pick<ReportSeeds,'animation'|'path'>|null}
 export function selectAnimation(sources:Source[],explicit?:string,allowStatic=false):AnimationSelection|null {
  if(!sources.length||sources.length>2)throw new Error('open.animation: expected one or two actual catalogs');
- if(explicit!==undefined&&(!explicit.trim()))throw new Error('open.animation: expected nonempty animation name');
- const requireName=(name:string)=>{for(const source of sources){if(source.catalog.animations===null)throw new Error(`open.${source.label}.animation: validation unavailable without compiled model`);if(!source.catalog.animations.some(clip=>clip.name===name))throw new Error(`open.${source.label}.animation: model has no animation ${JSON.stringify(name)}`);}};
+ if(explicit!==undefined&&(!explicit.trim()))throw new AnimationSelectionError('open.animation: expected nonempty animation name','empty');
+ const requireName=(name:string)=>{for(const source of sources){if(source.catalog.animations===null)throw new AnimationSelectionError(`open.${source.label}.animation: validation unavailable without compiled model`,'unvalidatable',source.label);if(!source.catalog.animations.some(clip=>clip.name===name))throw new AnimationSelectionError(`open.${source.label}.animation: model has no animation ${JSON.stringify(name)}`,'unknown',source.label,name);}};
  if(explicit!==undefined){requireName(explicit);return {name:explicit,source:'cli'};}
  if(allowStatic&&sources.length===1&&sources[0]!.catalog.animations===null)return null;
  const reports=sources.filter(source=>source.report?.animation!==undefined);
  const names=[...new Set(reports.map(source=>source.report!.animation!))];
- if(names.length>1)throw new Error(`open.animation: conflicting report animations: ${reports.map(source=>`${source.label}=${JSON.stringify(source.report!.animation)}`).join(', ')}; select --animation explicitly`);
+ if(names.length>1)throw new AnimationSelectionError(`open.animation: conflicting report animations: ${reports.map(source=>`${source.label}=${JSON.stringify(source.report!.animation)}`).join(', ')}; select --animation explicitly`,'ambiguous');
  if(names.length===1){requireName(names[0]!);return {name:names[0]!,source:'report',reportPaths:[...new Set(reports.map(source=>source.report!.path))]};}
- if(sources.some(source=>source.catalog.animations===null))throw new Error('open.animation: validation unavailable without compiled models');
+ if(sources.some(source=>source.catalog.animations===null))throw new AnimationSelectionError('open.animation: validation unavailable without compiled models','unvalidatable');
  const common=sources[0]!.catalog.animations!.filter(clip=>sources.every(source=>source.catalog.animations!.some(other=>other.name===clip.name))).map(clip=>clip.name);
  if(allowStatic&&sources.length===1&&sources[0]!.catalog.animations!.length===0)return null;
- if(common.length!==1)throw new Error(`open.animation: expected --animation; ${sources.length>1?'common animations':'model animations'}: ${common.join(', ')||'(none)'}`);
+ if(common.length!==1)throw new AnimationSelectionError(`open.animation: expected --animation; ${sources.length>1?'common animations':'model animations'}: ${common.join(', ')||'(none)'}`,'ambiguous');
  return {name:common[0]!,source:'unique'};
 }
 export function animationDiagnostic(selection:AnimationSelection):string {

package/src/cli.ts

@@ -35,7 +35,7 @@ async function stripCommand(args:string[],options:{stateDir?:string}){
 }
 export function parseOpenInputs(args:string[]):OpenInputs {
  const input=args.shift();if(!input||input.startsWith('--'))throw new Error(usage);const result:OpenInputs={input},seen=new Set<string>();
- while(args.length){const flag=args.shift()!;if(seen.has(flag))throw new Error(`Duplicate open option ${flag}`);seen.add(flag);if(flag==='--control'){result.control=true;continue;}if(flag==='--direct'){result.direct=true;continue;}const value=args.shift();if(value===undefined||value==='')throw new Error(`Missing value for ${flag}`);if(flag==='--reference')result.reference=value;else if(flag==='--compare')result.compare=value;else if(flag==='--animation')result.animation=value;else throw new Error(`Unknown open option ${flag}`);}return result;
+ while(args.length){const flag=args.shift()!;if(seen.has(flag))throw new Error(`OPEN_OPTION_INVALID ${flag}: Duplicate open option ${flag}`);seen.add(flag);if(flag==='--control'){result.control=true;continue;}if(flag==='--direct'){result.direct=true;continue;}const value=args.shift();if(value===undefined||value==='')throw new Error(`OPEN_OPTION_INVALID ${flag}: Missing value for ${flag}`);if(flag==='--reference')result.reference=value;else if(flag==='--compare')result.compare=value;else if(flag==='--animation')result.animation=value;else throw new Error(`OPEN_OPTION_INVALID ${flag}: Unknown open option ${flag}`);}return result;
 }
 async function controlCommand(args:string[],stateDir?:string){
  const input=args.shift();if(!input||input==='--help'||input==='-h'){console.log(usage);return;}
@@ -83,7 +83,8 @@ function commandHelpRequested(args:readonly string[],command:'open'|'review'|'ch
 export async function main(args:string[],options:{stateDir?:string}={}){
   options={stateDir:options.stateDir??defaultStateDir()};if(args[0]==='--')args.shift();
   if(args[0]==='control')return controlCommand(args.slice(1),options.stateDir);
-  if(args[0]==='open'){const openArgs=args.slice(1);if(commandHelpRequested(openArgs,'open')){console.log(usage);return;}const inputs=parseOpenInputs(openArgs);const result=await openReview(inputs,options);console.log(result.url);if(inputs.control)console.error('Inspection control enabled; query the current connected page with rig-review control and the same inputs.');if(result.selection)console.error(animationDiagnostic(result.selection));console.error(`Review ${result.reused?'reused':'started'}; feedback: rig-review feedback ${[result.inputs.input,...(result.inputs.compare?['--compare',result.inputs.compare]:[]),...(result.inputs.reference?['--reference',result.inputs.reference]:[]),...(result.inputs.animation?['--animation',result.inputs.animation]:[])].map(shellWord).join(' ')}`);return;}
+  if(args[0]==='open'){const openArgs=args.slice(1);if(commandHelpRequested(openArgs,'open')){console.log(usage);return;}const inputs=parseOpenInputs(openArgs);const result=await openReview(inputs,options);// Launcher contract (README): stdout is the URL line alone; stderr is diagnostic, control notice, retrieval, in that order.
+    console.log(result.url);if(result.selection)console.error(animationDiagnostic(result.selection));if(inputs.control)console.error('Inspection control enabled; query the current connected page with rig-review control and the same inputs.');console.error(`Review ${result.reused?'reused':'started'}; feedback: rig-review feedback ${[result.inputs.input,...(result.inputs.compare?['--compare',result.inputs.compare]:[]),...(result.inputs.reference?['--reference',result.inputs.reference]:[]),...(result.inputs.animation?['--animation',result.inputs.animation]:[])].map(shellWord).join(' ')}`);return;}
   if(args[0]==='strip'){args.shift();if(args.includes('--help')){console.log(usage+'\nStrip: strip <package> --reference <declared-video-id> --animation <name> (--frames FIRST:LAST | --all-feedback) [--json] [--out path]\n       strip compare <a> <b> --reference <video> --animation <name> --basis a|b (--frames FIRST:LAST | --all-feedback) [--json] [--out path]');return;}return stripCommand(args,options);}let command:'review'|'check'|'feedback'='review';if(args[0]==='check'||args[0]==='feedback'){command=args.shift() as 'check'|'feedback';}
   if(args[0]==='--help'||args[0]==='-h'){console.log(usage);return;}
   let format:'json'|'issue'='json';if(command==='feedback'){const parsed=feedbackFormat(args);args=parsed.args;format=parsed.format;}

package/src/manifest.ts

@@ -103,6 +103,10 @@ export async function loadReview(input: string): Promise<ReviewPackage> {
   return {root,manifestPath,manifest,sourceHash:hash.digest('hex'),reviewedSource,files,report,feedbackCatalog};
 }
 
+/** Same text for every command; `root` lets the open launcher name the refused input. */
+export class UnrecognizedOutputError extends Error {
+  constructor(readonly root:string){super('Output folder: no recognized skeleton.*, build/skeleton.model.json, motion.json, report.json, source video, pose sequence or contact strip');}
+}
 /** An adapter over an existing output directory; never writes a manifest there. */
 async function folderManifest(root:string):Promise<ReviewManifest>{
   const entries=(await readdir(root,{withFileTypes:true})).filter(v=>v.isFile()||v.isSymbolicLink()).map(v=>v.name).sort();
@@ -121,7 +125,7 @@ async function folderManifest(root:string):Promise<ReviewManifest>{
   }
   const name=basename(root);const packageId=name.replace(/[^a-zA-Z0-9._-]+/g,'-').replace(/^[^a-zA-Z0-9]+/,'').slice(0,128)||'output-bundle';
   const authoring=entries.filter(n=>n==='motion.json'||n==='report.json'||(/^skeleton\./i.test(n)&&n!=='skeleton.model.json')).map(path=>({label:path+' · read only',path}));
-  if(!references.length&&!authoring.length&&!model)throw new Error('Output folder: no recognized skeleton.*, build/skeleton.model.json, motion.json, report.json, source video, pose sequence or contact strip');
+  if(!references.length&&!authoring.length&&!model)throw new UnrecognizedOutputError(root);
   return parseManifest({schema:'rig-review/1',id:packageId,title:name,revision:'folder-adapter/1',model,motion:has('motion.json')?'motion.json':undefined,references,authoring,checkpoints:references.map(r=>({id:r.id,title:'Inspect '+r.label,reference:r.id,workspace:'motion'}))});
 }
 

package/src/open.ts

@@ -3,16 +3,16 @@ import {parseControlCommand,type ControlCommand,type ControlReceipt} from './con
 import {createHash,randomBytes,randomUUID} from 'node:crypto';
 import {spawn} from 'node:child_process';
 import {homedir} from 'node:os';
-import {mkdir,readFile,readdir,writeFile,rename,unlink,rm,rmdir,realpath,lstat,open as openFile} from 'node:fs/promises';
+import {mkdir,readFile,readdir,writeFile,rename,unlink,rm,rmdir,realpath,lstat,stat,open as openFile} from 'node:fs/promises';
 import {constants} from 'node:fs';
 import {basename,dirname,join,relative,resolve,isAbsolute} from 'node:path';
 import {fileURLToPath} from 'node:url';
 import {loadReferencedReview,selectedReference,assertReviewUnchanged} from './reference.ts';
-import {loadReview,type ReviewPackage} from './manifest.ts';
+import {loadReview,UnrecognizedOutputError,type ReviewPackage} from './manifest.ts';
 import {loadCompare,assertCompareUnchanged,type ComparePackage} from './compare.ts';
 import {startServer} from './server.ts';
 import {startCompareServer} from './compare-server.ts';
-import {selectAnimation,type AnimationSelection} from './animation-selection.ts';
+import {selectAnimation,AnimationSelectionError,type AnimationSelection} from './animation-selection.ts';
 import {capabilityHeader,capabilityPattern,type OpenIdentity} from './open-protocol.ts';
 import {ensureFront,frontPort} from './front.ts';
 import {playPackagePath} from './versions.ts';
@@ -74,11 +74,28 @@ export async function acquireClaim<T>(control:string,name:string,nonce:string,re
  catch(error){if((error as NodeJS.ErrnoException).code!=='ENOENT')throw error;}if(performance.now()>deadline)throw new Error(busy);await sleep(30);}}}
  catch(error){await rm(candidate,{recursive:true,force:true});throw error;}
 }
+/** Launcher contract (README "Launcher contract"): an `open` refusal's first line starts with a stable OPEN_* name.
+ * The shared loaders keep their check/feedback text; only this path renames them. */
+async function assertOpenInput(path:string):Promise<void>{
+ let info;try{info=await stat(path);}catch(e){if(['ENOENT','ENOTDIR','ELOOP','ENAMETOOLONG'].includes((e as NodeJS.ErrnoException).code??''))throw new Error(`OPEN_INPUT_MISSING ${path}: no such path; expected an existing output directory or review.json`);throw e;}
+ if(!info.isDirectory()&&!info.isFile())throw new Error(`OPEN_INPUT_MISSING ${path}: found a non-regular file; expected an output directory or a review.json manifest`);
+ if(info.isFile()){try{JSON.parse(await readFile(path,'utf8'));}catch(e){throw new Error(`OPEN_INPUT_UNRECOGNIZED ${path}: not a JSON manifest; expected an output directory or a review.json manifest`,{cause:e});}}
+}
+async function openRefusal(error:unknown,inputs:OpenInputs):Promise<unknown>{
+ if(error instanceof UnrecognizedOutputError){const first=await realpath(resolve(inputs.input)).catch(()=>null),path=inputs.compare!==undefined&&error.root!==first?inputs.compare:inputs.input;return new Error(`OPEN_INPUT_UNRECOGNIZED ${path}: ${error.message}`,{cause:error});}
+ if(!(error instanceof AnimationSelectionError))return error;
+ const detail=(error.label==='a'||error.label==='b'?`side ${error.label}: `:'')+error.message.replace(/^open\.(?:[a-z]+\.)?animation: /,'');
+ const name=error.kind==='empty'?'OPEN_OPTION_INVALID --animation':error.kind==='unknown'?`OPEN_ANIMATION_UNKNOWN ${JSON.stringify(error.animation)}`:error.kind==='ambiguous'?'OPEN_ANIMATION_AMBIGUOUS':'OPEN_ANIMATION_UNVALIDATABLE';
+ return new Error(`${name}: ${detail}`,{cause:error});
+}
 /** Managed is the default: the printed URL goes through the one loopback front (127.0.0.1:4318, or
  * RIG_REVIEW_FRONT_PORT) so browser storage keeps one origin across reopens. `direct` keeps the worker's own port. */
 export async function openReview(inputs:OpenInputs,options:{stateDir?:string;idleMs?:number;direct?:boolean;frontPort?:number;frontIdleMs?:number}={}):Promise<{url:string;reused:boolean;nonce:string;inputs:OpenInputs;selection:AnimationSelection|null;direct:boolean}>{
  const direct=options.direct??inputs.direct??false,port=direct?0:frontPort(options.frontPort);
- const p=await loadOpenPackage(inputs),fingerprint=await openFingerprint(),key=openKey(p,fingerprint);
+ for(const path of [inputs.input,...(inputs.compare!==undefined?[inputs.compare]:[])])await assertOpenInput(path);
+ if(inputs.compare!==undefined&&!inputs.reference)throw new Error('OPEN_REFERENCE_REQUIRED: compare: explicit --reference required');
+ let p:OpenPackage;try{p=await loadOpenPackage(inputs);}catch(error){throw await openRefusal(error,inputs);}
+ const fingerprint=await openFingerprint(),key=openKey(p,fingerprint);
  const stateDir=await canonicalDestination(resolve(options.stateDir??defaultStateDir())),roots=p.mode==='single'?[p.p.root]:[p.p.a.root,p.p.b.root];
  for(const root of roots){const rel=relative(root,stateDir);if(!rel||rel!=='..'&&!rel.startsWith('..'+(process.platform==='win32'?'\\':'/'))&&!isAbsolute(rel))throw new Error('open.state: must be outside input packages');}
  const control=join(stateDir,'open');await mkdir(control,{recursive:true,mode:0o700});const canonicalControl=await realpath(control);if((await lstat(control)).isSymbolicLink())throw new Error('open.state: control directory cannot be a symlink');