@pixel-point/toolcraft 0.0.18 → 0.0.19

package/templates/starter/e2e/toolcraft-feature-verification-reporter.spec.ts

@@ -0,0 +1,149 @@
+import { expect, test } from "@playwright/test";
+import type { FullConfig, FullResult, Suite } from "@playwright/test/reporter";
+
+import ToolcraftFeatureVerificationReporter, {
+  parseToolcraftFeatureVerificationRequest,
+} from "./toolcraft-feature-verification-reporter";
+
+const selectedPlan = Object.freeze({
+  acceptanceIds: Object.freeze(["material.layer"]),
+  testNames: Object.freeze(["browser: material.layer"]),
+  version: 1 as const,
+});
+
+function createSuite(testNames: readonly string[]): Suite {
+  return {
+    allTests: () => testNames.map((title) => ({ title })),
+  } as unknown as Suite;
+}
+
+const config = {} as FullConfig;
+const result = { status: "passed" } as FullResult;
+
+test("feature reporter parses only the exact versioned request shapes", () => {
+  expect(
+    parseToolcraftFeatureVerificationRequest(
+      '{"acceptanceIds":["material.layer"],"mode":"ids","version":1}',
+    ),
+  ).toEqual({ acceptanceIds: ["material.layer"], mode: "ids", version: 1 });
+  expect(
+    parseToolcraftFeatureVerificationRequest('{"mode":"all","version":1}'),
+  ).toEqual({ mode: "all", version: 1 });
+
+  for (const value of [
+    undefined,
+    "not-json",
+    '{"mode":"all","version":2}',
+    '{"mode":"all","version":1,"acceptanceIds":[]}',
+    '{"acceptanceIds":[],"mode":"ids","version":1}',
+    '{"acceptanceIds":["material.layer","material.layer"],"mode":"ids","version":1}',
+    '{"acceptanceIds":[" material.layer"],"mode":"ids","version":1}',
+    '{"acceptanceIds":["material.layer"],"mode":"ids","version":1,"extra":true}',
+  ]) {
+    expect(() => parseToolcraftFeatureVerificationRequest(value)).toThrow();
+  }
+});
+
+test("feature reporter selects current app semantics and emits exactly one plan line", async () => {
+  const output: string[] = [];
+  const selectionInputs: unknown[] = [];
+  const reporter = new ToolcraftFeatureVerificationReporter({
+    createSelection: (input) => {
+      selectionInputs.push(input);
+      return selectedPlan;
+    },
+    requestSource:
+      '{"acceptanceIds":["material.layer"],"mode":"ids","version":1}',
+    writeError: (source) => {
+      throw new Error(`Unexpected reporter error: ${source}`);
+    },
+    writeOutput: (source) => output.push(source),
+  });
+
+  reporter.onBegin(config, createSuite(selectedPlan.testNames));
+  await expect(reporter.onEnd(result)).resolves.toBeUndefined();
+  expect(selectionInputs).toHaveLength(1);
+  expect(selectionInputs[0]).toMatchObject({
+    acceptanceIds: ["material.layer"],
+    all: false,
+  });
+  expect(output).toEqual([`${JSON.stringify(selectedPlan)}\n`]);
+});
+
+test("feature reporter maps all mode without internal acceptance ids", async () => {
+  const inputs: unknown[] = [];
+  const reporter = new ToolcraftFeatureVerificationReporter({
+    createSelection: (input) => {
+      inputs.push(input);
+      return selectedPlan;
+    },
+    requestSource: '{"mode":"all","version":1}',
+    writeError: () => {},
+    writeOutput: () => {},
+  });
+
+  reporter.onBegin(config, createSuite(selectedPlan.testNames));
+  await expect(reporter.onEnd(result)).resolves.toBeUndefined();
+  expect(inputs[0]).toMatchObject({ all: true });
+  expect(inputs[0]).not.toHaveProperty("acceptanceIds");
+});
+
+test("feature reporter fails closed for absent and ambiguous selected tests", async () => {
+  for (const titles of [[], [...selectedPlan.testNames, ...selectedPlan.testNames]]) {
+    const errors: string[] = [];
+    const output: string[] = [];
+    const reporter = new ToolcraftFeatureVerificationReporter({
+      createSelection: () => selectedPlan,
+      requestSource: '{"mode":"all","version":1}',
+      writeError: (source) => errors.push(source),
+      writeOutput: (source) => output.push(source),
+    });
+
+    reporter.onBegin(config, createSuite(titles));
+    await expect(reporter.onEnd(result)).resolves.toEqual({ status: "failed" });
+    expect(output).toEqual([]);
+    expect(errors.join("\n")).toMatch(/exactly once/iu);
+  }
+});
+
+test("feature reporter suppresses output after malformed input or preparation failure", async () => {
+  for (const fixture of [
+    {
+      createSelection: () => selectedPlan,
+      requestSource: "not-json",
+      suite: createSuite(selectedPlan.testNames),
+    },
+    {
+      createSelection: () => {
+        throw new Error("unknown acceptance id");
+      },
+      requestSource: '{"mode":"all","version":1}',
+      suite: createSuite(selectedPlan.testNames),
+    },
+  ]) {
+    const errors: string[] = [];
+    const output: string[] = [];
+    const reporter = new ToolcraftFeatureVerificationReporter({
+      ...fixture,
+      writeError: (source) => errors.push(source),
+      writeOutput: (source) => output.push(source),
+    });
+
+    reporter.onBegin(config, fixture.suite);
+    await expect(reporter.onEnd(result)).resolves.toEqual({ status: "failed" });
+    expect(output).toEqual([]);
+    expect(errors).toHaveLength(1);
+  }
+});
+
+test("feature reporter fails when onEnd runs without onBegin", async () => {
+  const errors: string[] = [];
+  const reporter = new ToolcraftFeatureVerificationReporter({
+    requestSource: '{"mode":"all","version":1}',
+    writeError: (source) => errors.push(source),
+    writeOutput: () => {},
+  });
+
+  await expect(reporter.onEnd(result)).resolves.toEqual({ status: "failed" });
+  expect(errors.join("\n")).toMatch(/complete onBegin lifecycle/iu);
+});

package/templates/starter/e2e/toolcraft-feature-verification-reporter.ts

@@ -0,0 +1,223 @@
+import type {
+  FullConfig,
+  FullResult,
+  Reporter,
+  Suite,
+} from "@playwright/test/reporter";
+
+import {
+  createToolcraftFeatureVerificationSelection,
+  starterAcceptance,
+  starterControlSectionInventory,
+} from "../src/app/starter-acceptance";
+import { starterSchema } from "../src/app/starter-schema";
+
+export const TOOLCRAFT_FEATURE_VERIFICATION_REQUEST_ENV =
+  "TOOLCRAFT_FEATURE_VERIFICATION_REQUEST";
+
+type ToolcraftFeatureVerificationRequest =
+  | Readonly<{
+      acceptanceIds: readonly string[];
+      mode: "ids";
+      version: 1;
+    }>
+  | Readonly<{
+      mode: "all";
+      version: 1;
+    }>;
+
+type ToolcraftFeatureVerificationReporterState =
+  | Readonly<{ kind: "idle" }>
+  | Readonly<{ error: unknown; kind: "preparation-failed" }>
+  | Readonly<{
+      kind: "ready";
+      plan: ReturnType<typeof createToolcraftFeatureVerificationSelection>;
+    }>;
+
+type ToolcraftFeatureVerificationReporterOptions = Readonly<{
+  createSelection?: typeof createToolcraftFeatureVerificationSelection;
+  requestSource?: string;
+  writeError?: (source: string) => void;
+  writeOutput?: (source: string) => void;
+}>;
+
+const compareCodeUnits = (left: string, right: string): number =>
+  left < right ? -1 : left > right ? 1 : 0;
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function requireExactKeys(
+  value: Record<string, unknown>,
+  expected: readonly string[],
+): void {
+  const expectedSet = new Set(expected);
+  const unknown = Reflect.ownKeys(value)
+    .filter((key) => typeof key !== "string" || !expectedSet.has(key))
+    .map(String)
+    .sort(compareCodeUnits);
+  const missing = expected.filter(
+    (key) => !Object.prototype.hasOwnProperty.call(value, key),
+  );
+  if (unknown.length > 0 || missing.length > 0) {
+    throw new Error(
+      [
+        ...(unknown.length > 0
+          ? [`unknown fields: ${unknown.join(", ")}`]
+          : []),
+        ...(missing.length > 0
+          ? [`missing fields: ${missing.join(", ")}`]
+          : []),
+      ].join("; "),
+    );
+  }
+}
+
+export function parseToolcraftFeatureVerificationRequest(
+  source: string | undefined,
+): ToolcraftFeatureVerificationRequest {
+  if (!source) {
+    throw new Error(
+      `${TOOLCRAFT_FEATURE_VERIFICATION_REQUEST_ENV} must contain one versioned JSON request.`,
+    );
+  }
+  let value: unknown;
+  try {
+    value = JSON.parse(source);
+  } catch (error) {
+    throw new Error(
+      `${TOOLCRAFT_FEATURE_VERIFICATION_REQUEST_ENV} must contain valid JSON.`,
+      { cause: error },
+    );
+  }
+  if (!isPlainObject(value)) {
+    throw new Error(
+      `${TOOLCRAFT_FEATURE_VERIFICATION_REQUEST_ENV} must contain a plain object.`,
+    );
+  }
+  if (value.mode === "all") {
+    requireExactKeys(value, ["mode", "version"]);
+    if (value.version !== 1) {
+      throw new Error("Toolcraft feature verification request.version must be 1.");
+    }
+    return Object.freeze({ mode: "all", version: 1 });
+  }
+  if (value.mode !== "ids") {
+    throw new Error(
+      "Toolcraft feature verification request.mode must be ids or all.",
+    );
+  }
+  requireExactKeys(value, ["acceptanceIds", "mode", "version"]);
+  if (value.version !== 1) {
+    throw new Error("Toolcraft feature verification request.version must be 1.");
+  }
+  if (
+    !Array.isArray(value.acceptanceIds) ||
+    value.acceptanceIds.length === 0 ||
+    !value.acceptanceIds.every(
+      (id) => typeof id === "string" && id.length > 0 && id.trim() === id,
+    )
+  ) {
+    throw new Error(
+      "Toolcraft feature verification request.acceptanceIds must be a non-empty array of trimmed strings.",
+    );
+  }
+  if (new Set(value.acceptanceIds).size !== value.acceptanceIds.length) {
+    throw new Error(
+      "Toolcraft feature verification request.acceptanceIds must be unique.",
+    );
+  }
+  return Object.freeze({
+    acceptanceIds: Object.freeze([...value.acceptanceIds]),
+    mode: "ids",
+    version: 1,
+  });
+}
+
+function describeError(error: unknown): string {
+  if (!(error instanceof Error)) return String(error);
+  const cause = error.cause === undefined ? "" : `\nCaused by: ${describeError(error.cause)}`;
+  return `${error.stack ?? `${error.name}: ${error.message}`}${cause}`;
+}
+
+function assertSelectedTitlesExistExactlyOnce(
+  selectedTitles: readonly string[],
+  suite: Suite,
+): void {
+  const availableTitles = suite.allTests().map(({ title }) => title);
+  for (const selectedTitle of selectedTitles) {
+    const count = availableTitles.filter((title) => title === selectedTitle).length;
+    if (count !== 1) {
+      throw new Error(
+        `Selected browser test "${selectedTitle}" must occur exactly once in the Playwright suite; found ${count}.`,
+      );
+    }
+  }
+}
+
+export default class ToolcraftFeatureVerificationReporter implements Reporter {
+  private readonly createSelection: typeof createToolcraftFeatureVerificationSelection;
+  private readonly requestSource: string | undefined;
+  private state: ToolcraftFeatureVerificationReporterState = { kind: "idle" };
+  private readonly writeError: (source: string) => void;
+  private readonly writeOutput: (source: string) => void;
+
+  constructor(options: ToolcraftFeatureVerificationReporterOptions = {}) {
+    this.createSelection =
+      options.createSelection ?? createToolcraftFeatureVerificationSelection;
+    this.requestSource =
+      options.requestSource ?? process.env[TOOLCRAFT_FEATURE_VERIFICATION_REQUEST_ENV];
+    this.writeError = options.writeError ?? ((source) => process.stderr.write(source));
+    this.writeOutput = options.writeOutput ?? ((source) => process.stdout.write(source));
+  }
+
+  onBegin(_config: FullConfig, suite: Suite): void {
+    try {
+      const request = parseToolcraftFeatureVerificationRequest(this.requestSource);
+      const plan = this.createSelection({
+        acceptance: starterAcceptance,
+        ...(request.mode === "all"
+          ? { all: true }
+          : { acceptanceIds: request.acceptanceIds, all: false }),
+        schema: starterSchema,
+        sectionInventory: starterControlSectionInventory,
+      });
+      assertSelectedTitlesExistExactlyOnce(plan.testNames, suite);
+      this.state = { kind: "ready", plan };
+    } catch (error) {
+      this.state = { error, kind: "preparation-failed" };
+    }
+  }
+
+  async onEnd(_result: FullResult): Promise<{ status: "failed" } | void> {
+    switch (this.state.kind) {
+      case "idle":
+        return this.reportFailure(
+          new Error(
+            "Toolcraft feature verification reporter did not receive a complete onBegin lifecycle.",
+          ),
+        );
+      case "preparation-failed":
+        return this.reportFailure(this.state.error);
+      case "ready":
+        this.writeOutput(`${JSON.stringify(this.state.plan)}\n`);
+        return;
+    }
+  }
+
+  private reportFailure(error: unknown): { status: "failed" } {
+    this.writeError(
+      `Toolcraft feature verification collection failed:\n${describeError(error)}\n`,
+    );
+    return { status: "failed" };
+  }
+
+  printsToStdio(): boolean {
+    return true;
+  }
+}

package/templates/starter/package.json

@@ -10,10 +10,12 @@
     "build": "tsc -p tsconfig.json --noEmit && vite build",
     "preview": "node scripts/run-vite-on-free-port.mjs preview",
     "preview:restart": "node scripts/run-vite-on-free-port.mjs preview --toolcraft-restart",
+    "reference:study": "node scripts/create-toolcraft-motion-reference-study.mjs",
     "docs:check": "node scripts/check-toolcraft-docs.mjs",
     "test": "node scripts/check-toolcraft-docs.mjs && node --test scripts/*.test.mjs && vitest run src --passWithNoTests --reporter=default --reporter=./scripts/toolcraft-vitest-runtime-evidence-reporter.mjs",
     "test:generated": "node scripts/check-toolcraft-docs.mjs && node scripts/check-toolcraft-integrity.mjs && node --test scripts/*.test.mjs && vitest run src --passWithNoTests --reporter=default --reporter=./scripts/toolcraft-vitest-runtime-evidence-reporter.mjs",
     "test:browser": "playwright install chromium && playwright test --grep-invert \"browser perf:|toolcraft kernel:\"",
+    "test:feature": "node scripts/run-feature-verification.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "verify:delivery": "node scripts/run-delivery-verification.mjs",
     "verify:perf": "node scripts/run-browser-performance.mjs",

package/templates/starter/scripts/check-toolcraft-docs.mjs

@@ -63,6 +63,7 @@ const requiredWorkflowTerms = [
   "Open exactly one listed document per terminal or tool read",
   "coherent user-visible delivery batch",
   "pnpm verify:delivery",
+  "pnpm test:feature",
 ];
 
 const repoScope = "@repo";

package/templates/starter/scripts/create-toolcraft-motion-reference-study.mjs

@@ -0,0 +1,233 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { captureToolcraftProofProcess } from "./toolcraft-proof-process.mjs";
+import {
+  createToolcraftMotionReferenceId,
+  createToolcraftSha256,
+} from "./toolcraft-motion-reference-artifacts.mjs";
+import {
+  parseToolcraftMotionReferenceArgs,
+  resolveToolcraftMotionReferenceOptions,
+  resolveToolcraftMotionReferenceSourceKind,
+} from "./toolcraft-motion-reference-command-options.mjs";
+import {
+  createToolcraftMotionReferenceContactSheet,
+} from "./toolcraft-motion-reference-contact-sheet.mjs";
+import {
+  createToolcraftMotionEvidenceReviewPlan,
+  stageToolcraftMotionReferenceEvidences,
+} from "./toolcraft-motion-reference-evidence-assembly.mjs";
+import * as imageSource from "./toolcraft-motion-reference-image-source.mjs";
+import {
+  applyToolcraftMotionDeclaredImageTiming,
+} from "./toolcraft-motion-reference-image-timing.mjs";
+import {
+  resolveToolcraftMotionReferenceRoots,
+} from "./toolcraft-motion-reference-roots.mjs";
+import * as mediaSource from "./toolcraft-motion-reference-media-source.mjs";
+import {
+  publishToolcraftMotionReferenceStudies,
+} from "./toolcraft-motion-reference-publication.mjs";
+import {
+  createToolcraftMotionInputError,
+  createToolcraftMotionStageError,
+  formatToolcraftMotionReferenceError,
+  runToolcraftMotionStage,
+} from "./toolcraft-motion-reference-stage.mjs";
+import {
+  TOOLCRAFT_MOTION_REFERENCE_STAGES,
+} from "./toolcraft-motion-reference-stage-registry.mjs";
+
+const scriptDirectory = path.dirname(fileURLToPath(import.meta.url));
+const defaultRootDir = path.dirname(scriptDirectory);
+
+export function createToolcraftMotionReferenceExecutor({
+  captureProcess = captureToolcraftProofProcess,
+  cwd,
+} = {}) {
+  return async ({ args, binary }) => {
+    try {
+      return { stdout: await captureProcess(binary, args, { cwd }) };
+    } catch (error) {
+      return { error, exitCode: 1 };
+    }
+  };
+}
+
+async function detectBinaries(execute) {
+  await Promise.all(["ffmpeg", "ffprobe"].map((binary) =>
+    runToolcraftMotionStage(execute, {
+      args: ["-version"], binary,
+      stage: TOOLCRAFT_MOTION_REFERENCE_STAGES.binaryDetection,
+    })));
+}
+
+function selectSource(kind, dependencies) {
+  switch (kind) {
+    case "video":
+    case "gif":
+    case "screen-recording":
+      return { hashExternally: true, image: false, owner: dependencies.mediaSource };
+    case "contact-sheet":
+      return { hashExternally: false, image: true, owner: dependencies.imageSource };
+    case "frame-sequence":
+      return { hashExternally: false, image: true, owner: dependencies.imageSource };
+    default:
+      throw createToolcraftMotionInputError(
+        "Set --kind to video, gif, screen-recording, frame-sequence, or contact-sheet.",
+      );
+  }
+}
+
+async function defaultHashSource(source, fileSystem) {
+  return createToolcraftSha256(await fileSystem.readFile(source));
+}
+async function hashSourceAtStage(hashSource, source, fileSystem) {
+  try {
+    return await hashSource(source, fileSystem);
+  } catch (error) {
+    throw createToolcraftMotionStageError(
+      TOOLCRAFT_MOTION_REFERENCE_STAGES.sourceHash, error,
+    );
+  }
+}
+
+export async function createToolcraftMotionReferenceStudy(rawOptions, injected = {}) {
+  const dependencies = {
+    createContactSheet: createToolcraftMotionReferenceContactSheet,
+    execute: createToolcraftMotionReferenceExecutor({ cwd: injected.rootDir ?? defaultRootDir }),
+    fileSystem: fs,
+    hashSource: defaultHashSource,
+    imageSource,
+    mediaSource,
+    publishStudies: publishToolcraftMotionReferenceStudies,
+    rootDir: defaultRootDir,
+    ...injected,
+  };
+  const { referenceStudiesRoot: finalRoot, temporaryRoot } =
+    resolveToolcraftMotionReferenceRoots(
+      dependencies.rootDir,
+    );
+  await detectBinaries(dependencies.execute);
+  const kind = await resolveToolcraftMotionReferenceSourceKind(rawOptions, {
+    stat: dependencies.fileSystem.stat,
+  });
+  const selectedSource = selectSource(kind, dependencies);
+  await dependencies.fileSystem.mkdir(temporaryRoot, { mode: 0o700, recursive: true });
+  const workRoot = await dependencies.fileSystem.mkdtemp(
+    path.join(temporaryRoot, "motion-reference-"),
+  );
+  try {
+    const [initialInspection, externalHash] = await Promise.all([
+      selectedSource.owner.inspect({
+        execute: dependencies.execute,
+        fileSystem: dependencies.fileSystem,
+        grid: rawOptions.grid,
+        inputPath: rawOptions.source,
+        sourceKind: kind,
+      }),
+      selectedSource.hashExternally ?
+        hashSourceAtStage(
+          dependencies.hashSource, rawOptions.source, dependencies.fileSystem,
+        ) :
+        Promise.resolve(undefined),
+    ]);
+    const inspectedForResolution = selectedSource.image ?
+      await applyToolcraftMotionDeclaredImageTiming(initialInspection, rawOptions, {
+        readFile: dependencies.fileSystem.readFile,
+      }) : initialInspection;
+    const options = await resolveToolcraftMotionReferenceOptions(
+      { ...rawOptions, kind }, inspectedForResolution,
+    );
+    const inspection = inspectedForResolution;
+    const sourceSha256 = externalHash ?? inspection.sourceSha256;
+    if (!/^[a-f0-9]{64}$/u.test(sourceSha256 ?? "")) {
+      throw new TypeError("Toolcraft motion reference source hash is unavailable.");
+    }
+    const scan = await selectedSource.owner.scan({
+      execute: dependencies.execute, inspection,
+    });
+    const review = createToolcraftMotionEvidenceReviewPlan(inspection, scan, options);
+    const frameDirectory = path.join(workRoot, "frames");
+    await dependencies.fileSystem.mkdir(frameDirectory);
+    const materialized = await selectedSource.owner.materializeReviewedFrames({
+      execute: dependencies.execute, inspection, outputDirectory: frameDirectory,
+      sourceFrameIndices: review.unionSourceFrameIndices,
+    });
+    const materializedByIndex = new Map(materialized.map((frame) =>
+      [frame.sourceFrameIndex, frame]));
+    const provisionalStagingRoot = path.join(workRoot, "studies");
+    await dependencies.fileSystem.mkdir(provisionalStagingRoot);
+    let records = await stageToolcraftMotionReferenceEvidences({
+      dependencies, inspection, materializedByIndex, options, review, scan,
+      sourceSha256, stagingRoot: provisionalStagingRoot,
+    });
+    const referenceId = createToolcraftMotionReferenceId(records[0].evidence);
+    const stagingRoot = path.join(workRoot, `${referenceId}.staging`);
+    await dependencies.fileSystem.rename(provisionalStagingRoot, stagingRoot);
+    records = records.map((record) => ({
+      ...record,
+      stagingDirectory: path.join(
+        stagingRoot, path.basename(record.stagingDirectory),
+      ),
+    }));
+    await dependencies.fileSystem.mkdir(finalRoot, { recursive: true });
+    const studies = [];
+    for (const { evidence, stagingDirectory } of records) {
+      studies.push({
+        contactSheetPath: evidence.contactSheet.path,
+        evidence,
+        evidencePath: path.posix.join("src/app/reference-studies",
+          evidence.studyId, "evidence.json"),
+        finalDirectory: path.join(finalRoot, evidence.studyId),
+        range: evidence.segment ?? (evidence.timingMode === "seconds" ?
+          { endSeconds: evidence.durationSeconds, startSeconds: 0 } : undefined),
+        reviewedFrameCount: evidence.reviewedFrames.length,
+        stagingDirectory,
+        studyId: evidence.studyId,
+      });
+    }
+    const publication = await dependencies.publishStudies(studies.map((study) => ({
+      finalDirectory: study.finalDirectory,
+      stagingDirectory: study.stagingDirectory,
+    })), {
+      lockDirectory: path.join(temporaryRoot, `${referenceId}.lock`),
+      publicationGroup: {
+        evidences: studies.map(({ evidence }) => evidence),
+        referenceStudiesRoot: finalRoot,
+        rootDir: dependencies.rootDir,
+        stagingRoot,
+      },
+      sourceIdentity: referenceId,
+    });
+    return { publication, referenceId, studies: studies.map(({ finalDirectory,
+      stagingDirectory, ...study }) => study) };
+  } finally {
+    await dependencies.fileSystem.rm(workRoot, { force: true, recursive: true });
+  }
+}
+
+export async function main(argv = process.argv.slice(2), injected = {}, io = console) {
+  try {
+    const result = await createToolcraftMotionReferenceStudy(
+      parseToolcraftMotionReferenceArgs(argv), injected,
+    );
+    io.log(`Reference: ${result.referenceId}`);
+    result.studies.forEach((study) => {
+      const range = study.range ?
+        ` range ${study.range.startSeconds}:${study.range.endSeconds}` : "";
+      io.log(`${study.studyId} ${study.evidencePath} ${study.contactSheetPath} ` +
+        `${study.reviewedFrameCount} reviewed${range}`);
+    });
+    return 0;
+  } catch (error) {
+    io.error(formatToolcraftMotionReferenceError(error));
+    return 1;
+  }
+}
+
+if (process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url) {
+  process.exitCode = await main();
+}