@hraness/slopcamera 3.6.0 → 3.8.0

package/apps/desktop/cli/legacy-login.ts

@@ -0,0 +1,184 @@
+import { createHash } from "node:crypto";
+import { closeSync, constants, fstatSync, lstatSync, openSync, readdirSync, readSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+
+import {
+  MAX_LOGIN_ITEM_BYTES,
+  retireLegacyLoginItem,
+  type LegacyLoginItem,
+  type Retired,
+} from "@hraness/desktop-foundation/retire";
+
+import { CliError } from "./errors";
+
+/**
+ * Login items earlier Slopcamera releases wrote to start the retired menu
+ * bar. Newest first: the desktop-foundation helper's item, the name that
+ * helper used before, and the plist the CLI itself wrote before that.
+ */
+export const LEGACY_LOGIN_LABELS = [
+  "app.hraness.slopcamera",
+  "app.hraness.companion.slopcamera",
+  "com.hraness.slopcamera.menubar",
+] as const;
+
+const OLD_CLI_LABEL = "com.hraness.slopcamera.menubar";
+const MENU_BINARY = /\/slopcamera-menubar$/u;
+const LOCAL_APP = /\/Slopcamera\.app\/Contents\/MacOS\/[^/]+$/u;
+
+function xml(value: string): string {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
+}
+
+function unxml(value: string): string {
+  return value.replaceAll("&lt;", "<").replaceAll("&gt;", ">").replaceAll("&quot;", '"').replaceAll("&apos;", "'").replaceAll("&amp;", "&");
+}
+
+/** The exact plist the old `slopcamera menubar install` wrote. */
+export function oldCliPlist(binary: string): string {
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0"><dict><key>Label</key><string>${xml(OLD_CLI_LABEL)}</string><key>ProgramArguments</key><array><string>${xml(binary)}</string></array><key>RunAtLoad</key><true/><key>KeepAlive</key><false/><key>ProcessType</key><string>Interactive</string><key>LimitLoadToSessionType</key><string>Aqua</string></dict></plist>\n`;
+}
+
+function programArguments(text: string): string[] {
+  const array = /<key>ProgramArguments<\/key><array>((?:<string>[^<]*<\/string>)*)<\/array>/u.exec(text);
+  if (array === null) return [];
+  return [...array[1]!.matchAll(/<string>([^<]*)<\/string>/gu)].map(match => unxml(match[1]!));
+}
+
+/**
+ * True only for an item Slopcamera wrote for its menu bar. The helper's
+ * items carry a header with the SHA-256 of the body, so an edited file is
+ * not ours. The old CLI item must match what that CLI wrote byte for byte.
+ */
+export function isSlopcameraMenubarItem(item: LegacyLoginItem): boolean {
+  if (item.label === OLD_CLI_LABEL) {
+    const [program, ...rest] = programArguments(item.text);
+    return program !== undefined && rest.length === 0 && MENU_BINARY.test(program) && item.text === oldCliPlist(program);
+  }
+  const newline = item.text.indexOf("\n");
+  if (newline < 0) return false;
+  const body = item.text.slice(newline + 1);
+  const digest = createHash("sha256").update(body).digest("hex");
+  if (item.text.slice(0, newline + 1) !== `<!-- hraness-companion autostart slopcamera sha256:${digest} -->\n`) return false;
+  if (!body.includes(`<key>Label</key><string>${xml(item.label)}</string>`)) return false;
+  const [program] = programArguments(body);
+  return program !== undefined && (MENU_BINARY.test(program) || LOCAL_APP.test(program));
+}
+
+export type LegacyLoginState = "none" | "found" | "not-ours";
+
+export interface LegacyLoginReport {
+  readonly state: LegacyLoginState;
+  /** The label of the item found, when there is one. */
+  readonly label?: string;
+}
+
+function readSmallFile(path: string): string | undefined {
+  let fd: number | undefined;
+  try {
+    fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const info = fstatSync(fd);
+    if (!info.isFile() || info.size > MAX_LOGIN_ITEM_BYTES || info.uid !== process.getuid?.()) return undefined;
+    const bytes = Buffer.alloc(info.size);
+    let count = 0;
+    while (count < bytes.length) {
+      const read = readSync(fd, bytes, count, bytes.length - count, count);
+      if (read === 0) break;
+      count += read;
+    }
+    return bytes.subarray(0, count).toString("utf8");
+  } catch {
+    return undefined;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+function launchAgents(home: string | undefined): string | undefined {
+  return home === undefined || home === "" || !isAbsolute(home) ? undefined : join(home, "Library", "LaunchAgents");
+}
+
+/** Reads the LaunchAgents folder and reports the old menu bar item. Changes nothing. */
+export function inspectLegacyLogin(home: string | undefined): LegacyLoginReport {
+  const directory = launchAgents(home);
+  if (directory === undefined) return { state: "none" };
+  let foreign: string | undefined;
+  for (const label of LEGACY_LOGIN_LABELS) {
+    const path = join(directory, `${label}.plist`);
+    try {
+      lstatSync(path);
+    } catch {
+      continue;
+    }
+    const text = readSmallFile(path);
+    if (text !== undefined && isSlopcameraMenubarItem({ label, path, text })) return { state: "found", label };
+    foreign ??= label;
+  }
+  return foreign === undefined ? { state: "none" } : { state: "not-ours", label: foreign };
+}
+
+export interface RetireDependencies {
+  readonly bootout?: (label: string) => Promise<void>;
+  readonly now?: () => Date;
+}
+
+/**
+ * Stops the old menu bar starting at login: boots out its label and renames
+ * the plist to `<name>.retired-<ms>`. Nothing is deleted, no process is
+ * signalled by pid, and items Slopcamera did not write are left alone.
+ */
+export async function retireLegacyLogin(home: string | undefined, dependencies: RetireDependencies = {}): Promise<Retired[]> {
+  if (launchAgents(home) === undefined) throw new CliError("unavailable", "HOME must be an absolute directory to look for the old menu bar login item.");
+  const retired: Retired[] = [];
+  // One call retires the first match; repeat so every old copy is moved aside.
+  for (let attempt = 0; attempt < LEGACY_LOGIN_LABELS.length; attempt += 1) {
+    const labels = LEGACY_LOGIN_LABELS.filter(label => !retired.some(item => item.label === label));
+    const result = await retireLegacyLoginItem({
+      home: home!,
+      labels,
+      accepts: isSlopcameraMenubarItem,
+      ...(dependencies.bootout === undefined ? {} : { bootout: dependencies.bootout }),
+      ...(dependencies.now === undefined ? {} : { now: dependencies.now }),
+    });
+    if (result === null) break;
+    retired.push(result);
+  }
+  return retired;
+}
+
+export interface RetiredLegacyLogin {
+  readonly label: string;
+  readonly path: string;
+  /** Puts the item back and loads it, undoing `slopcamera legacy retire`. */
+  readonly restore: string;
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+/** Login items `legacy retire` moved aside, with the command that restores each. Changes nothing. */
+export function retiredLegacyLogins(home: string | undefined): RetiredLegacyLogin[] {
+  const directory = launchAgents(home);
+  if (directory === undefined) return [];
+  let names: string[];
+  try {
+    names = readdirSync(directory);
+  } catch {
+    return [];
+  }
+  const found: RetiredLegacyLogin[] = [];
+  for (const label of LEGACY_LOGIN_LABELS) {
+    const prefix = `${label}.plist.retired-`;
+    for (const name of names.filter(item => item.startsWith(prefix) && /^[0-9]{1,16}$/u.test(item.slice(prefix.length))).sort()) {
+      const path = join(directory, name);
+      const original = join(directory, `${label}.plist`);
+      found.push({
+        label,
+        path,
+        restore: `mv -n ${shellQuote(path)} ${shellQuote(original)} && launchctl bootstrap gui/$(id -u) ${shellQuote(original)}`,
+      });
+    }
+  }
+  return found;
+}

package/apps/desktop/cli/main.ts

@@ -5,6 +5,7 @@ import { runProductSupportCommand, showProductSupportInvitation, standaloneSuppo
 import { parseCliArgs } from "./args";
 import { runCli } from "./commands";
 import { asCliError, CliError, EXIT_CODE } from "./errors";
+import { isRegistryCommand, runRegistry } from "./registry";
 import { BunProcessRunner, processIo } from "./io";
 import { resolveRepositoryPaths } from "./paths";
 import {
@@ -42,6 +43,13 @@ export async function main(
     return await runProductSupportCommand(argv.slice(1),
       supportEnvironment === undefined ? {} : { env: supportEnvironment });
   }
+  if (isRegistryCommand(argv)) {
+    // status, tui, commands, legacy retire and outputs list|open|reveal
+    // answer in the shared desktop-foundation envelope.
+    return await runRegistry(argv, { stdout: process.stdout, stderr: process.stderr, env: process.env }, {
+      env: process.env, platform: process.platform, now: () => new Date(),
+    });
+  }
   const unifiedArgv = canonicalizeUnifiedCliArgs(argv);
   const portableExitCode = await runPortableSurface(unifiedArgv, portableDependencies);
   if (portableExitCode !== undefined) return portableExitCode;
@@ -55,6 +63,7 @@ export async function main(
   }
   const paths = await resolveRepositoryPaths(processIo.cwd(), processIo.env);
   if (earlyCommand.kind === "html-render" || earlyCommand.kind === "spatial-world" || earlyCommand.kind === "spatial-asset" || earlyCommand.kind === "spatial-design" || earlyCommand.kind === "directing" || earlyCommand.kind === "studio"
+    || earlyCommand.kind === "html-film"
     || earlyCommand.kind === "spatial-scene" && (earlyCommand.action === "render" || earlyCommand.action === "camera-track" || earlyCommand.action === "render-audit" || earlyCommand.action === "review")) {
     const controller = new AbortController();
     const cancel = () => controller.abort(new CliError("cancelled", "Command interrupted."));

package/apps/desktop/cli/outputs.ts

@@ -0,0 +1,19 @@
+import { dirname, join, sep } from "node:path";
+
+import type { CliIo } from "./io";
+import { writeJson, writeLine } from "./io";
+import { ensurePrivateDirectory } from "./paths";
+
+/** The directory agents write user-facing outputs into. */
+export function outputsDirectory(stateRoot: string): string {
+  const productRoot = stateRoot.endsWith(`${sep}cli`) ? dirname(stateRoot) : stateRoot;
+  return join(productRoot, "outputs");
+}
+
+/** `slopcamera outputs`: creates the private outputs folder and prints its path. */
+export async function reportOutputsRoot(io: CliIo, stateRoot: string, asJson: boolean): Promise<void> {
+  const directory = outputsDirectory(stateRoot);
+  await ensurePrivateDirectory(directory);
+  if (asJson) writeJson(io, { outputs: directory });
+  else writeLine(io, directory);
+}

package/apps/desktop/cli/portable-surface.ts

@@ -15,6 +15,10 @@ import {
   type HtmlOverlayScaffoldKind,
 } from "../html-overlay";
 import { CliError } from "./errors";
+import {
+  createHtmlFilmProject, HTML_FILM_ASPECTS, HTML_FILM_TEMPLATES,
+  type HtmlFilmAspect, type HtmlFilmInitResult, type HtmlFilmTemplate,
+} from "./html-film-init";
 
 const HEADLESS_SLOPCAMERA_CLI_MODULE = "@hraness/slopcamera/cli";
 
@@ -42,6 +46,7 @@ export interface PortableSurfaceDependencies {
   readonly log?: (value: string) => void;
   readonly runHeadless?: (argv: readonly string[], options?: Readonly<{ onUsefulResult?: UsefulResultObserver }>) => Promise<void>;
   readonly writeScaffold?: (path: string, html: string) => Promise<void>;
+  readonly createFilm?: typeof createHtmlFilmProject;
 }
 function optionValue(argv: readonly string[], name: string): string | undefined {
   const indexes = argv.flatMap((value, index) => value === name ? [index] : []);
@@ -215,6 +220,53 @@ function runHtmlCatalog(
   return 0;
 }
 
+const HTML_INIT_USAGE = "Use slopcamera html init <dir> --template launch-film [--aspect 16:9|1:1|9:16] [--json].";
+
+async function runHtmlInit(
+  argv: readonly string[],
+  dependencies: PortableSurfaceDependencies,
+): Promise<number> {
+  let directory: string | undefined;
+  let template: string | undefined;
+  let aspect: string | undefined;
+  let json = false;
+  for (let index = 2; index < argv.length; index += 1) {
+    const value = argv[index]!;
+    if (value === "--json") {
+      if (json) throw new CliError("usage", "--json may be supplied at most once.");
+      json = true;
+    } else if (value === "--template" || value === "--aspect") {
+      const next = argv[index + 1];
+      if (next === undefined || next.startsWith("--")) throw new CliError("usage", `${value} requires a value.`);
+      if ((value === "--template" ? template : aspect) !== undefined) throw new CliError("usage", `${value} may be supplied at most once.`);
+      if (value === "--template") template = next;
+      else aspect = next;
+      index += 1;
+    } else if (value.startsWith("-") || directory !== undefined) {
+      throw new CliError("usage", HTML_INIT_USAGE);
+    } else {
+      directory = value;
+    }
+  }
+  if (directory === undefined || template === undefined) throw new CliError("usage", HTML_INIT_USAGE);
+  if (!(HTML_FILM_TEMPLATES as readonly string[]).includes(template)) {
+    throw new CliError("usage", `Unknown film template ${template}. Use one of: ${HTML_FILM_TEMPLATES.join(", ")}.`);
+  }
+  const selectedAspect = aspect ?? "16:9";
+  if (!(HTML_FILM_ASPECTS as readonly string[]).includes(selectedAspect)) {
+    throw new CliError("usage", `--aspect must be one of ${HTML_FILM_ASPECTS.join(", ")}.`);
+  }
+  const result: HtmlFilmInitResult = await (dependencies.createFilm ?? createHtmlFilmProject)(
+    resolve((dependencies.cwd ?? process.cwd)(), directory),
+    { template: template as HtmlFilmTemplate, aspect: selectedAspect as HtmlFilmAspect },
+  );
+  (dependencies.log ?? console.log)(json
+    ? JSON.stringify(result)
+    : [`Created ${result.directory} from ${result.template} (${result.aspect})`, ...result.next.map(line => `next ${line}`)].join("\n"));
+  reportUsefulResult(dependencies.onUsefulResult);
+  return 0;
+}
+
 export async function runPortableSurface(
   argvInput: readonly string[],
   dependencies: PortableSurfaceDependencies = {},
@@ -222,8 +274,10 @@ export async function runPortableSurface(
   const argv = canonicalizeUnifiedCliArgs(argvInput);
   if (argv[0] === "style" && (argv.includes("--help") || argv.includes("-h"))) return undefined;
   if (argv[0] === "html") {
-    if (argv[1] === "render" || argv.includes("--help") || argv.includes("-h")) return undefined;
+    if (argv[1] === "render" || argv[1] === "still" || argv[1] === "preview" || argv[1] === "deliver"
+      || argv.includes("--help") || argv.includes("-h")) return undefined;
     if (argv[1] === "catalog") return runHtmlCatalog(argv, dependencies);
+    if (argv[1] === "init") return await runHtmlInit(argv, dependencies);
     return await runHtmlScaffold(argv, dependencies);
   }
   const delegatesToHeadless = argv[0] === "diagram"

package/apps/desktop/cli/registry.ts

@@ -0,0 +1,314 @@
+import { lstatSync } from "node:fs";
+import { join } from "node:path";
+
+import {
+  defineRegistry,
+  HranessError,
+  okEnvelope,
+  runCli as runRegistryCli,
+  type CliIO,
+  type ErrorCode,
+  type Registry,
+  type Verb,
+} from "@hraness/desktop-foundation/registry";
+import { chooseMode, renderSnapshot, runTui, type TuiIO } from "@hraness/desktop-foundation/tui";
+
+import { SLOPCAMERA_VERSION } from "../../../src/version";
+import { listOutputs, OUTPUTS_LIMIT, statusEnvelope, statusViews, STATUS_SCHEMA, type StatusOutputs } from "./desktop-status";
+import type { ProcessRunner } from "./io";
+import { CliError } from "./errors";
+import { BunProcessRunner } from "./io";
+import { readActivityStatus } from "./activity-status";
+import { inspectLegacyLogin, retireLegacyLogin, type RetireDependencies } from "./legacy-login";
+import { outputsDirectory } from "./outputs";
+import { defaultCliStateRoot } from "./paths";
+import { CLI_VERBS, type VerbRow } from "./verbs";
+
+/**
+ * The verbs `slopcamera` answers through the desktop-foundation registry:
+ * `status`, `tui`, `commands`, `legacy retire` and `outputs list|open|reveal`.
+ * Every other verb keeps its own parser in `args.ts`; the registry still
+ * lists it with its class so `commands --json` covers the whole CLI.
+ */
+export const PRODUCT = "slopcamera";
+export const OUTPUTS_LIST_LIMIT = 200;
+
+/** First words (and `outputs` sub-verbs) the registry answers. */
+export function isRegistryCommand(argv: readonly string[]): boolean {
+  const [first, second] = argv;
+  if (first === "status" || first === "tui" || first === "commands" || first === "legacy") return true;
+  return first === "outputs" && (second === "list" || second === "open" || second === "reveal");
+}
+
+export interface RegistryDependencies {
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly platform: NodeJS.Platform;
+  readonly now: () => Date;
+  readonly stateRoot?: string;
+  readonly version?: string;
+  readonly runner?: ProcessRunner;
+  readonly retire?: RetireDependencies;
+  readonly stdoutIsTerminal?: boolean;
+  readonly tuiIo?: TuiIO;
+}
+
+function stateRootOf(deps: RegistryDependencies): string {
+  return deps.stateRoot ?? defaultCliStateRoot(deps.platform, deps.env);
+}
+
+/** Loads everything `status` and `tui` show. Reads only; creates nothing. */
+export function loadStatus(deps: RegistryDependencies) {
+  const stateRoot = stateRootOf(deps);
+  return statusEnvelope({
+    version: deps.version ?? SLOPCAMERA_VERSION,
+    status: readActivityStatus(stateRoot),
+    outputs: listOutputs(outputsDirectory(stateRoot), OUTPUTS_LIMIT),
+    legacyLogin: inspectLegacyLogin(deps.env.HOME),
+    now: deps.now(),
+  });
+}
+
+function schemaFor(path: readonly string[]): string {
+  return `${PRODUCT}.${path.join(".")}/1`;
+}
+
+/**
+ * One output by its file name, as `outputs list` prints it. Only a plain
+ * name of a regular, visible file directly in the outputs folder is
+ * accepted, so the verb can never open anything else.
+ */
+export function outputPath(root: string, name: string | undefined): string {
+  if (name === undefined || name === "") throw new HranessError("usage", "Name one output, as `slopcamera outputs list` prints it.");
+  if (name.includes("/") || name.includes("\\") || name.startsWith(".") || name.includes("\0") || name.length > 255) {
+    throw new HranessError("usage", "Give the output's file name only, as `slopcamera outputs list` prints it.");
+  }
+  const path = join(root, name);
+  let regular = false;
+  try {
+    regular = lstatSync(path).isFile();
+  } catch {
+    regular = false;
+  }
+  if (!regular) {
+    throw new HranessError("not-found", `No output named ${JSON.stringify(name)}.`, undefined, [
+      { command: `${PRODUCT} outputs list --json`, why: "List the outputs by name.", audience: "agent" },
+    ]);
+  }
+  return path;
+}
+
+async function finder(deps: RegistryDependencies, argv: readonly [string, ...string[]]): Promise<void> {
+  if (deps.platform !== "darwin") {
+    throw new HranessError("unsupported-platform", "Opening Finder works on macOS only. Nothing opened.", undefined, [
+      { command: `${PRODUCT} outputs --json`, why: "Print the outputs folder to open it yourself.", audience: "agent" },
+    ]);
+  }
+  const result = await (deps.runner ?? new BunProcessRunner()).run(argv, { maxOutputBytes: 4_096 });
+  if (result.exitCode !== 0) throw new HranessError("internal", "Finder didn't open. Try again.");
+}
+
+interface OutputsListData {
+  readonly root: string;
+  readonly total: number;
+  readonly outputs: StatusOutputs["latest"];
+}
+
+interface OpenedData {
+  readonly opened: string;
+  readonly reveal: boolean;
+}
+
+// defineRegistry takes a heterogeneous verb list typed Verb<any, any>[] upstream.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function implemented(deps: RegistryDependencies): Verb<any, any>[] {
+  const stateRoot = () => stateRootOf(deps);
+  const status: Verb<Record<string, never>, number> = {
+    path: ["status"],
+    opClass: "read",
+    schema: STATUS_SCHEMA,
+    summary: "What Slopcamera is doing, credits, newest outputs and old login items",
+    output: "raw",
+    input: () => ({}),
+    async run(_input, ctx) {
+      const envelope = loadStatus(deps);
+      if (ctx.json) {
+        ctx.io.stdout.write(`${JSON.stringify(envelope)}\n`);
+      } else if (envelope.ok) {
+        ctx.io.stdout.write(renderSnapshot(statusViews(deps.now), envelope.data));
+        for (const next of envelope.next ?? []) ctx.io.stdout.write(`next: ${next.command}  (${next.why})\n`);
+      }
+      return 0;
+    },
+  };
+  const tui: Verb<{ snapshot: boolean; width?: number }, number> = {
+    path: ["tui"],
+    opClass: "read",
+    schema: STATUS_SCHEMA,
+    summary: "The status screen; --snapshot prints it once, --json prints the status",
+    flags: ["snapshot"],
+    valueFlags: ["width"],
+    usage: "[--snapshot|--json] [--width N]",
+    output: "raw",
+    input(argv) {
+      if (argv.positionals.length > 0) throw new HranessError("usage", "tui takes no arguments.");
+      const width = argv.flags.width;
+      if (width === undefined) return { snapshot: argv.flags.snapshot === true };
+      if (typeof width !== "string" || !/^[0-9]{1,4}$/u.test(width) || Number(width) < 20 || Number(width) > 400) {
+        throw new HranessError("usage", "--width takes a number of columns from 20 to 400.");
+      }
+      return { snapshot: argv.flags.snapshot === true, width: Number(width) };
+    },
+    async run(input, ctx) {
+      const mode = chooseMode(ctx.json, input.snapshot, deps.stdoutIsTerminal ?? process.stdout.isTTY === true);
+      return await runTui({
+        load: async () => loadStatus(deps),
+        views: statusViews(deps.now),
+        mode,
+        ...(input.width === undefined ? {} : { width: input.width }),
+        io: deps.tuiIo ?? { stdout: { write: (text: string) => ctx.io.stdout.write(text), ...(process.stdout.columns === undefined ? {} : { columns: process.stdout.columns }) }, stdin: process.stdin },
+      });
+    },
+  };
+  const legacyRetire: Verb<Record<string, never>, { retired: { label: string; from: string; to: string }[]; loginItem: ReturnType<typeof inspectLegacyLogin> }> = {
+    path: ["legacy", "retire"],
+    opClass: "operate",
+    schema: schemaFor(["legacy", "retire"]),
+    summary: "Stop the old menu bar opening at login, keeping its file",
+    input(argv) {
+      if (argv.positionals.length > 0) throw new HranessError("usage", "legacy retire takes no arguments.");
+      return {};
+    },
+    async run() {
+      if (deps.platform !== "darwin") return { retired: [], loginItem: { state: "none" } };
+      const retired = await retireLegacyLogin(deps.env.HOME, deps.retire ?? {});
+      return { retired, loginItem: inspectLegacyLogin(deps.env.HOME) };
+    },
+    text(output) {
+      const moved = output.retired.map(item => `Moved ${item.from} to ${item.to}. The old menu bar no longer opens at login.`);
+      if (output.loginItem.state === "not-ours") moved.push("A menu bar login item was changed outside Slopcamera, so it was left alone.");
+      return moved.length === 0 ? "Nothing to retire. The old menu bar doesn't open at login." : moved.join("\n");
+    },
+  };
+  const outputsList: Verb<Record<string, never>, OutputsListData> = {
+    path: ["outputs", "list"],
+    opClass: "read",
+    schema: schemaFor(["outputs", "list"]),
+    summary: "List the files in the outputs folder, newest first",
+    input(argv) {
+      if (argv.positionals.length > 0) throw new HranessError("usage", "outputs list takes no arguments.");
+      return {};
+    },
+    async run() {
+      const listed = listOutputs(outputsDirectory(stateRoot()), OUTPUTS_LIST_LIMIT);
+      return { root: listed.root, total: listed.total, outputs: listed.latest };
+    },
+    text(output) {
+      if (output.outputs.length === 0) return `No outputs yet in ${output.root}`;
+      return output.outputs.map(item => `${item.name}\t${item.bytes}\t${item.modifiedAt}`).join("\n");
+    },
+  };
+  const openVerb = (reveal: boolean): Verb<{ name?: string }, OpenedData> => ({
+    path: ["outputs", reveal ? "reveal" : "open"],
+    opClass: "operate",
+    schema: schemaFor(["outputs", reveal ? "reveal" : "open"]),
+    summary: reveal ? "Show one output in Finder" : "Open the outputs folder, or one output, on this Mac",
+    usage: reveal ? "<name>" : "[<name>]",
+    input(argv) {
+      if (argv.positionals.length > 1) throw new HranessError("usage", "Name at most one output.");
+      const name = argv.positionals[0];
+      if (reveal && name === undefined) throw new HranessError("usage", "Name the output to show, as `slopcamera outputs list` prints it.");
+      return name === undefined ? {} : { name };
+    },
+    async run(input) {
+      const root = outputsDirectory(stateRoot());
+      if (input.name === undefined) {
+        let folder = false;
+        try {
+          folder = lstatSync(root).isDirectory();
+        } catch {
+          folder = false;
+        }
+        if (!folder) {
+          throw new HranessError("not-found", "There's no outputs folder yet. Agents create it when they save their first output.", undefined, [
+            { command: `${PRODUCT} outputs --json`, why: "Create the outputs folder and print its path.", audience: "agent" },
+          ]);
+        }
+        await finder(deps, ["/usr/bin/open", "--", root]);
+        return { opened: root, reveal: false };
+      }
+      const path = outputPath(root, input.name);
+      await finder(deps, reveal ? ["/usr/bin/open", "-R", "--", path] : ["/usr/bin/open", "--", path]);
+      return { opened: path, reveal };
+    },
+    text(output) {
+      return output.reveal ? `Showed ${output.opened} in Finder.` : `Opened ${output.opened}.`;
+    },
+  });
+  return [status, tui, legacyRetire, outputsList, openVerb(false), openVerb(true)];
+}
+
+/** A verb `args.ts` parses and runs; the registry only lists it. */
+function listed(row: VerbRow): Verb<unknown, unknown> {
+  return {
+    path: row.path,
+    opClass: row.opClass,
+    schema: schemaFor(row.path),
+    summary: row.summary,
+    input: () => {
+      throw new HranessError("internal", `slopcamera ${row.path.join(" ")} is run by the main parser.`);
+    },
+    run: async () => undefined,
+  };
+}
+
+/** The shared envelope codes a Slopcamera error keeps as is. */
+const SHARED_CODES = new Set<ErrorCode>(["usage", "not-found", "conflict", "internal"]);
+
+/**
+ * Answers a Slopcamera application error with a declared envelope code: the
+ * shared code when there is one, otherwise `slopcamera.<code>`. Without this
+ * the registry reports every such error as an unexpected internal failure.
+ */
+export function asHranessError(error: unknown): unknown {
+  if (!(error instanceof CliError)) return error;
+  const shared = error.code as ErrorCode;
+  const code: ErrorCode = SHARED_CODES.has(shared) ? shared : `${PRODUCT}.${error.code}`;
+  return new HranessError(code, error.message);
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function withDeclaredErrors(verb: Verb<any, any>): Verb<any, any> {
+  return {
+    ...verb,
+    input(argv) {
+      try {
+        return verb.input(argv);
+      } catch (error) {
+        throw asHranessError(error);
+      }
+    },
+    async run(input, ctx) {
+      try {
+        return await verb.run(input, ctx);
+      } catch (error) {
+        throw asHranessError(error);
+      }
+    },
+  };
+}
+
+export function slopcameraRegistry(deps: RegistryDependencies): Registry {
+  const own = implemented(deps).map(withDeclaredErrors);
+  const ownPaths = new Set(own.map(verb => verb.path.join(" ")));
+  return defineRegistry(PRODUCT, [
+    ...own,
+    ...CLI_VERBS.filter(row => !ownPaths.has(row.path.join(" "))).map(listed),
+  ]);
+}
+
+/** Runs a registry command line and returns its exit status. */
+export async function runRegistry(argv: readonly string[], io: CliIO, deps: RegistryDependencies): Promise<number> {
+  return await runRegistryCli(slopcameraRegistry(deps), argv, io);
+}
+
+export { okEnvelope };