rig-review 2.1.0 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -58,7 +58,7 @@ http://127.0.0.1:4318/?workspace=<incarnation>#cap=…
58
58
  | --- | --- | --- |
59
59
  | **Hand off and compare** | | |
60
60
  | <a id="one-command-owner-handoff"></a>Open an inspection workspace | `open` | [Owner handoff — WORKFLOWS](docs/WORKFLOWS.md#one-command-owner-handoff) |
61
- | <a id="existing-output-handoff"></a>Inspect an existing folder | `check`, `review` | [Existing output handoff — WORKFLOWS](docs/WORKFLOWS.md#existing-output-handoff) |
61
+ | <a id="existing-output-handoff"></a>Inspect existing folders | `check`, `review DIR...` | [Existing output handoff — WORKFLOWS](docs/WORKFLOWS.md#existing-output-handoff) |
62
62
  | <a id="compare-two-outputs"></a>Compare two builds against a video | `compare` | [Compare two outputs — WORKFLOWS](docs/WORKFLOWS.md#compare-two-outputs) |
63
63
  | <a id="feedback-ownership"></a>Retrieve submitted feedback | `feedback` | [Feedback ownership — WORKFLOWS](docs/WORKFLOWS.md#feedback-ownership) |
64
64
  | <a id="frame-strip-export"></a>Export feedback intervals as strips | `strip` | [Frame strip export — WORKFLOWS](docs/WORKFLOWS.md#frame-strip-export) |
@@ -483,8 +483,10 @@ A private bounded `/api/open-status` handshake requires its instance capability,
483
483
  returns matching identity, and verifies current input hashes. The state registry
484
484
  never makes a PID/port alone authoritative. Changed input, reference, mode,
485
485
  canonical input location or actual tool source/static fingerprint gets a distinct
486
- instance identity. Existing foreground servers do not gain an open registration
487
- or browser filesystem API.
486
+ instance identity. Existing single foreground servers retain their direct lifecycle.
487
+ Plain multi-target foreground review uses the shared owner workspace registration
488
+ and capabilities described in [WORKFLOWS](WORKFLOWS.md#subsequent-cli-and-semantic-paths).
489
+ Neither path supplies a browser filesystem API.
488
490
 
489
491
  Registry/request/log/claim files are private tool-state files; a per-binding claim
490
492
  serializes startup, stale records are not reused, and no unrelated process is
package/docs/WORKFLOWS.md CHANGED
@@ -252,9 +252,34 @@ and APIs and never construct internal Review state or human acts.
252
252
 
253
253
  ### Subsequent CLI and semantic paths
254
254
 
255
- Plain foreground multi-target invocation and its compatible workspace joining
256
- remain pending. The current delivery is the `open` CLI workspace. Core's
257
- `rigc review` passes arguments through unchanged; Review owns the CLI grammar.
255
+ Plain multi-target review starts a workspace in the foreground CLI process:
256
+
257
+ ```sh
258
+ rig-review dirA dirB --animation idle --animation-for 2 walk --view-only
259
+ ```
260
+
261
+ A new owner prints `Review ready: <owner URL>` and stays in that terminal. Its
262
+ SIGINT/SIGTERM handlers await shutdown of the one listener and its contexts.
263
+ The same aggregate last-window and unopened timers described above apply.
264
+ A compatible active workspace receives the batch instead; that launcher prints
265
+ only the identical owner URL and exits 0 without acquiring stop ownership.
266
+ `open` and foreground multi can join each other's owner. Registration retains
267
+ its atomic validation, source identities and bounded target list.
268
+
269
+ Multi uses managed port 4318, or `RIG_REVIEW_FRONT_PORT`, with explicit `--port`
270
+ precedence. Its port range is 1..65535; `--port 0` refuses with
271
+ `OPEN_OPTION_INVALID`. Existing single foreground remains on 4317 and accepts
272
+ `--port 0`; existing `compare` behavior is unchanged.
273
+
274
+ `--animation` is common to all operands and 1-based `--animation-for INDEX NAME`
275
+ overrides one operand. Each target uses its explicit selection, report animation,
276
+ or unique actual clip; ambiguity refuses by name. Static/source-only inspections
277
+ retain their existing support. Multi accepts common reference/handoff flags,
278
+ `--view-only` and `--control`. Its exact inputs work with the existing feedback
279
+ and control commands. Multi checkpoint, batch compare, direct and project/joined
280
+ options refuse with `OPEN_OPTION_INVALID`; existing single options retain their
281
+ behavior. Flags and their literal values are consumed before counting operands.
282
+ Core's `rigc review` continues forwarding to `open`; Review owns this grammar.
258
283
 
259
284
  The embedded semantic-job hub also remains pending. Its same-process host will
260
285
  own trusted `readPublished`, `partsEnumerator` and `installWriterBinding`
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "rig-review",
3
- "version": "2.1.0",
3
+ "version": "2.2.0",
4
4
  "type": "module",
5
5
  "description": "Local human rig inspection and structured feedback export",
6
6
  "license": "MIT",
@@ -38,6 +38,11 @@ Both launchers exit 0 with the same root owner URL and capability within one
38
38
  host incarnation, adding no listener or per-rig worker. A consumer opened N rigs
39
39
  with N sequential `open` calls. Prefer one batch when the targets are known.
40
40
  Give the person the private owner link and one what-to-look-at line.
41
+ For terminal-owned multi review, use `rig-review dirA dirB --animation idle
42
+ --animation-for 2 walk --view-only`. A new owner stays foreground on managed
43
+ port 4318; compatible reuse prints the same URL and exits 0. `--port` overrides
44
+ the port and accepts 1..65535. Single foreground keeps 4317 and port 0 support.
45
+ Multi checkpoint, compare, direct and project/joined flags refuse by name.
41
46
  View-only entries are labelled **Inspection only**, without semantic acts or
42
47
  pending approvals. Existing feedback semantics apply per target. Retain each
43
48
  target's original feedback lookup arguments, inspection state, source-bound
package/src/cli.ts CHANGED
@@ -25,7 +25,7 @@ import { readCompareSession } from './compare-session.ts';
25
25
  import { exportReviewStrip, exportCompareStrip, stripJson, writeStripOutput, validateStripOutput } from './strip-export.ts';
26
26
  import type { StripInterval, StripRequest } from './strip.ts';
27
27
  const handoffUsage='[--config <path> [--parts <dir>] [--source <png> --full <dir> [--head <dir>]] [--keypoints <file>]]';
28
- const usage='Usage: rig-review open <dir> [<dir> ...] [--animation-for <index> <name>] [--reference <video>] [--compare <dir>] [--animation <name>] [--control] [--direct] [--view-only] [--project <create-root> (--project-version <rig> [--post-version <post>] | --project-draft <id> [--parts-verdict-dir <dir>]) --picks-dir <dir>] '+handoffUsage+'\n --config declares the producer handoff (wins over the review.json "producer" block and discovery of config.json, rig/config.json, ../config.json beside an opened out/); feedback and control take the same flags; --view-only opens without a producer handoff.\n open is managed by default: one owner workspace at 127.0.0.1:4318 (RIG_REVIEW_FRONT_PORT overrides) hosts targets in one process; --animation applies to all targets, --animation-for overrides one 1-based target, and --direct keeps a separate single-target worker.\n rig-review control <dir> [--reference <video>] [--compare <dir>] [--animation <name>] '+handoffUsage+' [--project <create-root> --project-version <rig> --picks-dir <dir> [--post-version <post>]] [--page <id> --expected-revision <n> --command <JSON> --wait-ms <n>]\n rig-review feedback <dir> [--reference <video>] [--compare <dir>] [--animation <name>] '+handoffUsage+' [--project <create-root> --project-version <rig> --picks-dir <dir> [--post-version <post>]] [--format json|issue] [--correction <item id>]\n Usage: bun run review -- <review.json|output-directory> [--port 4317] [--checkpoint ID] [--view-only]\n bun run check -- <review.json|output-directory>\n bun run feedback -- <review.json|output-directory>\n bun run review -- compare <a> <b> --reference <video> --animation <name> [--port 4317]\n bun run check -- compare <a> <b> --reference <video> --animation <name>\n bun run feedback -- compare <a> <b> --reference <video> --animation <name>\n rig-review parts <build root | parts dir | review package> [--rig <file>] [--mesh-report <file>] [--check <file>] [--verdict <file>] [--painting <png>] [--format json|issue] [--correction <item id> --parts-file <inventory> [--part-note <part>]] [--port <n>]\n rig-review interview <create-root> --picks-dir <project-relative directory> [--port <n>]\n rig-review --version';
28
+ const usage='Usage: rig-review open <dir> [<dir> ...] [--animation-for <index> <name>] [--reference <video>] [--compare <dir>] [--animation <name>] [--control] [--direct] [--view-only] [--project <create-root> (--project-version <rig> [--post-version <post>] | --project-draft <id> [--parts-verdict-dir <dir>]) --picks-dir <dir>] '+handoffUsage+'\n --config declares the producer handoff (wins over the review.json "producer" block and discovery of config.json, rig/config.json, ../config.json beside an opened out/); feedback and control take the same flags; --view-only opens without a producer handoff.\n open is managed by default: one owner workspace at 127.0.0.1:4318 (RIG_REVIEW_FRONT_PORT overrides) hosts targets in one process; --animation applies to all targets, --animation-for overrides one 1-based target, and --direct keeps a separate single-target worker.\n rig-review control <dir> [--reference <video>] [--compare <dir>] [--animation <name>] '+handoffUsage+' [--project <create-root> --project-version <rig> --picks-dir <dir> [--post-version <post>]] [--page <id> --expected-revision <n> --command <JSON> --wait-ms <n>]\n rig-review feedback <dir> [--reference <video>] [--compare <dir>] [--animation <name>] '+handoffUsage+' [--project <create-root> --project-version <rig> --picks-dir <dir> [--post-version <post>]] [--format json|issue] [--correction <item id>]\n rig-review <dir> <dir> ... [--animation <name>] [--animation-for <index> <name>] [--port 4318] [--reference <video>] [--view-only] [--control] '+handoffUsage+'\n Foreground multi owns a new workspace in this CLI process; a compatible existing owner is joined and the launcher exits. Multi --port accepts 1..65535; single foreground keeps 4317 and --port 0.\n Usage: bun run review -- <review.json|output-directory> [--port 4317] [--checkpoint ID] [--view-only]\n bun run check -- <review.json|output-directory>\n bun run feedback -- <review.json|output-directory>\n bun run review -- compare <a> <b> --reference <video> --animation <name> [--port 4317]\n bun run check -- compare <a> <b> --reference <video> --animation <name>\n bun run feedback -- compare <a> <b> --reference <video> --animation <name>\n rig-review parts <build root | parts dir | review package> [--rig <file>] [--mesh-report <file>] [--check <file>] [--verdict <file>] [--painting <png>] [--format json|issue] [--correction <item id> --parts-file <inventory> [--part-note <part>]] [--port <n>]\n rig-review interview <create-root> --picks-dir <project-relative directory> [--port <n>]\n rig-review --version';
29
29
  async function stripCommand(args:string[],options:{stateDir?:string}){
30
30
  const compare=args[0]==='compare';if(compare)args.shift();const a=args.shift(),b=compare?args.shift():undefined;if(!a||compare&&!b)throw new Error('strip: expected package input(s)');
31
31
  let reference:string|undefined,referenceVideo:string|undefined,animation:string|undefined,basis:'a'|'b'|undefined,range:string|undefined,output:string|undefined,jsonOnly=false,all=false;
@@ -114,6 +114,40 @@ export function parseOpenTargets(args: readonly string[]): OpenInputs[] {
114
114
  for (const [index, animation] of animations) targets[index - 1]!.animation = animation;
115
115
  return targets;
116
116
  }
117
+ /** Multi detection consumes known option values before counting folder operands. */
118
+ export function parseForegroundTargets(args: readonly string[]): {targets: OpenInputs[]; port?: number; help: boolean} | null {
119
+ const values = ['--port', '--checkpoint', '--reference', '--compare', '--animation', ...projectFlags,
120
+ ...HANDOFF_FLAGS.map(flag => '--' + flag)];
121
+ const booleans = ['--view-only', '--control', '--direct'];
122
+ const operands: string[] = [], forwarded: string[] = [];
123
+ const unsupported = new Set(['--checkpoint', '--compare', '--direct', ...projectFlags]);
124
+ const refused: string[] = [];
125
+ let port: number | undefined, help = false, duplicatePort = false;
126
+ for (let index = 0; index < args.length; index++) {
127
+ const flag = args[index]!;
128
+ if (flag === '--help' || flag === '-h') {help = true; continue;}
129
+ if (unsupported.has(flag)) refused.push(flag);
130
+ if (flag === '--animation-for') {
131
+ forwarded.push(flag, ...args.slice(index + 1, index + 3)); index += 2;
132
+ } else if (flag === '--port') {
133
+ duplicatePort = port !== undefined;
134
+ port = Number(args[++index]);
135
+ } else if (values.includes(flag)) {
136
+ forwarded.push(flag); if (args[index + 1] !== undefined) forwarded.push(args[++index]!);
137
+ } else if (booleans.includes(flag)) forwarded.push(flag);
138
+ else if (!flag.startsWith('-')) {operands.push(flag); forwarded.push(flag);}
139
+ // Preserve the legacy validator's unknown-option and help precedence.
140
+ else return null;
141
+ }
142
+ if (operands.length < 2) return null;
143
+ if (help) return {targets: [], port, help};
144
+ if (refused.length) throw new Error('OPEN_OPTION_INVALID ' + refused[0] + ': unsupported for foreground multi-target review');
145
+ if (duplicatePort || port !== undefined && (!Number.isSafeInteger(port) || port < 1 || port > 65535)) {
146
+ throw new Error('OPEN_OPTION_INVALID --port: foreground multi-target review expects integer 1..65535');
147
+ }
148
+ return {targets: parseOpenTargets(forwarded), port, help};
149
+ }
150
+
117
151
  async function controlCommand(args:string[],stateDir?:string){
118
152
  const input=args.shift();if(!input||input==='--help'||input==='-h'){console.log(usage);return;}
119
153
  const inputs:OpenInputs={input},options:Parameters<typeof controlReview>[1]={stateDir},seen=new Set<string>(),projectOptions:string[]=[];
@@ -213,6 +247,22 @@ export async function main(args:string[],options:{stateDir?:string}={}){
213
247
  if(args[0]==='interview')return (await import('./interview-server.ts')).interviewCommand(args.slice(1));
214
248
  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';}
215
249
  if(args[0]==='--help'||args[0]==='-h'){console.log(usage);return;}
250
+ const foreground = command === 'review' && args[0] !== 'compare' ? parseForegroundTargets(args) : null;
251
+ if (foreground) {
252
+ if (foreground.help) {console.log(usage); return;}
253
+ const {openWorkspace} = await import('./open-workspace-launch.ts');
254
+ const result = await openWorkspace(foreground.targets, {...options, frontPort: foreground.port, foreground: true});
255
+ if (!result.interrupted) {
256
+ for (const target of result.prepared) {
257
+ if (target.build) console.error(buildOpenDiagnostic(target.build));
258
+ if (target.package.selection) console.error(animationDiagnostic(target.package.selection));
259
+ }
260
+ if (result.waitForExit) console.log(`Review ready: ${result.url}\nTargets: ${foreground.targets.length}\nPress Ctrl+C to stop.`);
261
+ else console.log(result.url);
262
+ }
263
+ await result.waitForExit?.();
264
+ return;
265
+ }
216
266
  let format:'json'|'issue'='json',correctionId:string|undefined;if(command==='feedback'){const parsed=feedbackFormat(args);args=parsed.args;format=parsed.format;correctionId=parsed.correctionId;}
217
267
  // Feedback formatting assigns --format/value ownership before the help pass.
218
268
  if(commandHelpRequested(args,command)){console.log(usage);return;}
@@ -23,7 +23,7 @@ async function register(record: WorkspaceRecord, targets: WorkspaceDesignation[]
23
23
  }
24
24
 
25
25
  /** Launchers exchange designated package data, never callbacks or human acts. */
26
- export async function openWorkspace(inputs: readonly OpenInputs[], options: OpenOptions = {}) {
26
+ export async function openWorkspace(inputs: readonly OpenInputs[], options: OpenOptions & {foreground?: boolean} = {}) {
27
27
  const fingerprint = await openFingerprint();
28
28
  const prepared = [];
29
29
  for (const input of inputs) prepared.push(await prepareOpenTarget(input, options, fingerprint));
@@ -40,11 +40,20 @@ export async function openWorkspace(inputs: readonly OpenInputs[], options: Open
40
40
  const acquired = ready ? {row: ready} : await acquireClaim(directory, 'host', nonce, reuse,
41
41
  performance.now() + 20_000, 'WORKSPACE_START_BUSY');
42
42
  let child: ReturnType<typeof spawn> | undefined, handedOff = false, request: string | undefined;
43
+ let owner: Awaited<ReturnType<typeof import('./open-workspace.ts').startOpenWorkspace>> | undefined;
44
+ let interrupted = false;
45
+ const stopOwner = () => {interrupted = true; void owner!.stop().catch(() => {});};
46
+ const detach = () => {process.removeListener('SIGINT', stopOwner); process.removeListener('SIGTERM', stopOwner);};
43
47
  try {
44
48
  let record: WorkspaceRecord;
45
49
  const reused = 'row' in acquired;
46
50
  if ('row' in acquired) record = acquired.row;
47
- else {
51
+ else if (options.foreground) {
52
+ const {startOpenWorkspace} = await import('./open-workspace.ts');
53
+ owner = await startOpenWorkspace({stateDir, fingerprint, port, idleMs: options.idleMs, graceMs: options.graceMs});
54
+ process.once('SIGINT', stopOwner); process.once('SIGTERM', stopOwner);
55
+ record = owner.record;
56
+ } else {
48
57
  request = join(directory, nonce + '.request.json');
49
58
  await writePrivate(request, {schema: WORKSPACE_SCHEMA, stateDir, fingerprint, port,
50
59
  ...(options.idleMs !== undefined ? {idleMs: options.idleMs} : {}),
@@ -73,9 +82,18 @@ export async function openWorkspace(inputs: readonly OpenInputs[], options: Open
73
82
  await Bun.sleep(30);
74
83
  }
75
84
  }
76
- await register(record, designations);
85
+ try {await register(record, designations);}
86
+ catch (error) {if (!interrupted) throw error;}
77
87
  handedOff = true;
78
- return {url: record.origin + '/?workspace=' + record.incarnation + '#cap=' + record.ownerCapability, reused, prepared};
88
+ const waitForExit = owner ? async () => {
89
+ try {await owner!.live.exited; await owner!.stop();}
90
+ finally {detach();}
91
+ } : undefined;
92
+ return {url: record.origin + '/?workspace=' + record.incarnation + '#cap=' + record.ownerCapability,
93
+ reused, prepared, interrupted, waitForExit};
94
+ } catch (error) {
95
+ if (owner) {detach(); await owner.stop().catch(() => {});}
96
+ throw error;
79
97
  } finally {
80
98
  if (child && !handedOff && child.exitCode === null && child.signalCode === null) child.kill('SIGTERM');
81
99
  if ('claim' in acquired) await releaseClaim(acquired.claim, nonce);