@hraness/slopcamera 3.2.7 → 3.3.1

package/apps/desktop/cli/menubar.ts

@@ -0,0 +1,244 @@
+import { closeSync, constants, fstatSync, lstatSync, mkdirSync, mkdtempSync, openSync, readSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import type { Stats } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { CliError } from "./errors";
+import type { CliIo } from "./io";
+import { writeJson, writeLine } from "./io";
+import { ensurePrivateDirectory } from "./paths";
+
+const SETTLE_MS = 400;
+const LABEL = "com.hraness.slopcamera.menubar";
+
+function xml(value: string): string { return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;"); }
+function exists(path: string): boolean { try { const info = lstatSync(path); return isAbsolute(path) && realpathSync(path) === resolve(path) && (info.uid === process.getuid?.() || info.uid === 0) && info.isFile() && (info.mode & 0o111) !== 0 && (info.mode & 0o022) === 0; } catch { return false; } }
+
+/** The directory agents write user-facing outputs into. */
+export function outputsRoot(stateRoot: string): string {
+  const productRoot = stateRoot.endsWith(`${sep}cli`) ? dirname(stateRoot) : stateRoot;
+  return join(productRoot, "outputs");
+}
+export function resolveMenubarBinary(repositoryRoot: string, environment: Readonly<Record<string, string | undefined>> = process.env): string | null {
+  const explicit = environment.SLOPCAMERA_MENUBAR;
+  if (explicit !== undefined) return explicit !== "" && exists(explicit) ? explicit : null;
+  const candidates = [ resolve(dirname(process.execPath), "slopcamera-menubar"), ...(environment.HOME === undefined || environment.HOME === "" ? [] : [installedBinaryPath(environment)]), resolve(repositoryRoot, "desktop", "target", "release", "slopcamera-menubar")];
+  for (const candidate of candidates) if (candidate !== undefined && candidate !== "" && exists(candidate)) return candidate;
+  return null;
+}
+export function launchAgentPath(environment: Readonly<Record<string, string | undefined>> = process.env): string {
+  const home = environment.HOME; if (home === undefined || home === "" || !isAbsolute(home)) throw new CliError("unavailable", "HOME is required for a per-user LaunchAgent.");
+  return join(home, "Library", "LaunchAgents", `${LABEL}.plist`);
+}
+export function installedBinaryPath(environment: Readonly<Record<string, string | undefined>> = process.env): string {
+  const home = environment.HOME; if (home === undefined || home === "" || !isAbsolute(home)) throw new CliError("unavailable", "HOME is required for a per-user menu-bar install.");
+  return join(home, "Library", "Application Support", "Slopcamera", "menubar", "slopcamera-menubar");
+}
+export function launchAgentPlist(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(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`;
+}
+type Environment = Readonly<Record<string, string | undefined>>;
+const MAX_BINARY_BYTES = 128 * 1024 * 1024;
+
+function infoAt(path: string): Stats | null {
+  try { return lstatSync(path); } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+/** Existing shared directories retain their permissions; links are never followed. */
+function checkParents(path: string, environment: Environment, create = false): void {
+  const home = environment.HOME;
+  if (!home || !isAbsolute(home) || realpathSync(home) !== resolve(home)) {
+    throw new CliError("unsafe-path", "HOME must be an absolute physical directory.");
+  }
+  const suffix = relative(home, dirname(path));
+  if (suffix.startsWith(`..${sep}`) || suffix === ".." || isAbsolute(suffix)) {
+    throw new CliError("unsafe-path", "The menu-bar install must remain under HOME.");
+  }
+  let cursor = home;
+  for (const part of ["", ...suffix.split(sep)]) {
+    if (part) cursor = join(cursor, part);
+    let info = infoAt(cursor);
+    if (info === null) {
+      if (!create) return;
+      mkdirSync(cursor, { mode: 0o700 });
+      info = lstatSync(cursor);
+    }
+    if (!info.isDirectory() || info.uid !== process.getuid?.() || (info.mode & 0o022) !== 0) {
+      throw new CliError("unsafe-path", "Menu-bar install directories must be owned physical directories without shared write access.");
+    }
+  }
+}
+
+function assertOwnedFile(path: string): void {
+  const info = infoAt(path);
+  if (info !== null && (!info.isFile() || info.nlink !== 1 || info.uid !== process.getuid?.() || (info.mode & 0o022) !== 0)) {
+    throw new CliError("unsafe-path", "The menu-bar install contains an unsafe file.");
+  }
+}
+
+function readRegular(path: string, maximum: number, executable = false): Buffer {
+  if (!isAbsolute(path) || realpathSync(path) !== resolve(path) || Buffer.byteLength(path) > 4096 || /[\u0000-\u001f\u007f{}"\\]/u.test(path)) {
+    throw new CliError("unsafe-path", "The menu-bar file must have a bounded physical absolute path.");
+  }
+  const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const info = fstatSync(fd);
+    if (!info.isFile() || (info.uid !== process.getuid?.() && info.uid !== 0) || info.size > maximum || info.size === 0 || (info.mode & 0o022) !== 0 || (executable && (info.mode & 0o111) === 0)) {
+      throw new CliError("unsafe-path", "The menu-bar file must be bounded, regular, and protected from shared writes.");
+    }
+    const bytes = Buffer.alloc(info.size + 1);
+    let count = 0;
+    while (count < bytes.length) {
+      const read = readSync(fd, bytes, count, bytes.length - count, count);
+      if (read === 0) break;
+      count += read;
+    }
+    const after = fstatSync(fd);
+    if (count !== info.size || after.size !== info.size || after.mtimeMs !== info.mtimeMs || after.ctimeMs !== info.ctimeMs) {
+      throw new CliError("conflict", "The menu-bar file changed while it was being read.");
+    }
+    return bytes.subarray(0, count);
+  } finally { closeSync(fd); }
+}
+
+function readAgent(path: string, environment: Environment): string | null {
+  checkParents(path, environment);
+  if (infoAt(path) === null) return null;
+  assertOwnedFile(path);
+  return readRegular(path, 16 * 1024).toString("utf8");
+}
+
+/** Configuration state only; it does not claim the launchd service is running. */
+export type LaunchAgentState = "absent" | "installed" | "conflict";
+export type LaunchctlRunner = (args: readonly string[], allowMissing?: boolean) => string | null;
+function launchctl(args: readonly string[], allowMissing = false): string | null {
+  const uid = process.getuid?.();
+  if (uid === undefined) throw new CliError("unavailable", "The current user has no launchd GUI domain.");
+  const result = Bun.spawnSync(["/bin/launchctl", ...args.map((arg) => arg.replaceAll("{uid}", String(uid)))], { stdin: "ignore", stdout: "pipe", stderr: "pipe", timeout: 10_000, maxBuffer: 64 * 1024 });
+  return interpretLaunchctlResult(result, uid, allowMissing);
+}
+export function interpretLaunchctlResult(result: { success: boolean; exitCode: number; stdout: Uint8Array; stderr: Uint8Array }, uid: number, allowMissing: boolean): string | null {
+  if (result.stdout.byteLength + result.stderr.byteLength > 64 * 1024) throw new CliError("unavailable", "launchctl exceeded the bounded response size.");
+  if (result.success && result.exitCode === 0) return Buffer.from(result.stdout).toString();
+  if (allowMissing && result.exitCode === 113 && result.stdout.length === 0 && Buffer.from(result.stderr).toString() === `Bad request.\nCould not find service "${LABEL}" in domain for user gui: ${uid}\n`) return null;
+  throw new CliError("unavailable", "launchctl could not reconcile the Slopcamera menu-bar LaunchAgent. Run menubar install again to retry.");
+}
+
+function loadedOwned(path: string, binary: string, current: string | null, run: LaunchctlRunner): boolean {
+  const output = run(["print", `gui/{uid}/${LABEL}`], true);
+  if (output === null) return false;
+  const uid = process.getuid?.();
+  if (current === null || Buffer.byteLength(output) > 64 * 1024 || !output.startsWith(`gui/${uid}/${LABEL} = {\n`)) {
+    throw new CliError("conflict", "The loaded menu-bar service has an unverified identity.");
+  }
+  const lines = output.split("\n").map(line => line.trim());
+  const field = (key: string): string | null => {
+    const values = lines.filter(line => line.startsWith(`${key} = `));
+    return values.length === 1 ? values[0]!.slice(key.length + 3) : null;
+  };
+  const argumentsStart = lines.indexOf("arguments = {");
+  const argumentsEnd = lines.indexOf("}", argumentsStart + 1);
+  if (field("path") !== path || field("program") !== binary || argumentsStart < 0 || argumentsEnd !== argumentsStart + 2 || lines[argumentsStart + 1] !== binary) {
+    throw new CliError("conflict", "The loaded menu-bar service does not match this install; it was left untouched.");
+  }
+  return true;
+}
+export function launchAgentState(binary: string, environment: Environment = process.env): LaunchAgentState {
+  const content = readAgent(launchAgentPath(environment), environment);
+  if (content === null) return "absent";
+  checkParents(binary, environment);
+  assertOwnedFile(binary);
+  return content === launchAgentPlist(binary) && exists(binary) ? "installed" : "conflict";
+}
+function assertMac(platform: NodeJS.Platform): void {
+  if (platform !== "darwin") throw new CliError("unsupported-plan", "Slopcamera menu-bar LaunchAgents are supported only on macOS.");
+}
+export function installLaunchAgent(binary: string, environment: Environment = process.env, platform: NodeJS.Platform = process.platform, runLaunchctl: LaunchctlRunner = launchctl): LaunchAgentState {
+  assertMac(platform);
+  if (!isAbsolute(binary)) throw new CliError("unsafe-path", "LaunchAgent binary must be an absolute path.");
+  const stable = installedBinaryPath(environment);
+  const path = launchAgentPath(environment);
+  const current = readAgent(path, environment);
+  const expected = launchAgentPlist(stable);
+  checkParents(stable, environment);
+  assertOwnedFile(stable);
+  if (current !== null && current !== expected || current === null && infoAt(stable) !== null) {
+    throw new CliError("conflict", "The existing Slopcamera menu-bar install is not owned by this command.");
+  }
+  const bytes = readRegular(binary, MAX_BINARY_BYTES, true);
+  loadedOwned(path, stable, current, runLaunchctl);
+  checkParents(path, environment, true);
+  checkParents(stable, environment, true);
+  // Unique private staging directories prevent predictable temporary-file clobbering.
+  const binaryStage = mkdtempSync(join(dirname(stable), ".install-"));
+  let agentStage: string | undefined;
+  try {
+    agentStage = mkdtempSync(join(dirname(path), ".slopcamera-install-"));
+    const stagedBinary = join(binaryStage, "binary");
+    const stagedAgent = join(agentStage, "agent.plist");
+    writeFileSync(stagedBinary, bytes, { mode: 0o700, flag: "wx" });
+    writeFileSync(stagedAgent, expected, { mode: 0o600, flag: "wx" });
+    if (readAgent(path, environment) !== current) throw new CliError("conflict", "The menu-bar install changed concurrently.");
+    assertOwnedFile(stable);
+    // Retry bootstrap even when the plist matches: a previous bootstrap may have failed.
+    if (loadedOwned(path, stable, current, runLaunchctl)) runLaunchctl(["bootout", `gui/{uid}/${LABEL}`], true);
+    renameSync(stagedBinary, stable);
+    renameSync(stagedAgent, path);
+    runLaunchctl(["bootstrap", "gui/{uid}", path]);
+    return "installed";
+  } finally {
+    rmSync(binaryStage, { recursive: true });
+    if (agentStage !== undefined) rmSync(agentStage, { recursive: true });
+  }
+}
+export function uninstallLaunchAgent(_binary: string, environment: Environment = process.env, platform: NodeJS.Platform = process.platform, runLaunchctl: LaunchctlRunner = launchctl): LaunchAgentState {
+  assertMac(platform);
+  const stable = installedBinaryPath(environment);
+  const path = launchAgentPath(environment);
+  const current = readAgent(path, environment);
+  if (current === null) return "absent";
+  if (current !== launchAgentPlist(stable)) throw new CliError("conflict", "The existing Slopcamera menu-bar LaunchAgent is not owned by this command.");
+  checkParents(stable, environment);
+  assertOwnedFile(stable);
+  if (loadedOwned(path, stable, current, runLaunchctl)) runLaunchctl(["bootout", `gui/{uid}/${LABEL}`], true);
+  if (readAgent(path, environment) !== current) throw new CliError("conflict", "The menu-bar install changed concurrently.");
+  assertOwnedFile(stable);
+  rmSync(path);
+  if (infoAt(stable) !== null) rmSync(stable);
+  return "absent";
+}
+async function runBinary(binary: string, foreground: boolean): Promise<number> {
+  let child: Bun.Subprocess;
+  try { child = Bun.spawn([binary], foreground ? { stdin: "inherit", stdout: "inherit", stderr: "inherit" } : { stdin: "ignore", stdout: "ignore", stderr: "ignore" }); } catch { throw new CliError("unavailable", "The Slopcamera menu bar could not start."); }
+  if (!foreground) { child.unref(); const settled = await Promise.race([child.exited.then((code) => code as number | null), Bun.sleep(SETTLE_MS).then(() => null)]); if (settled !== null) throw new CliError("unavailable", "The Slopcamera menu bar exited during startup."); return 0; }
+  return await child.exited;
+}
+export async function launchMenubar(io: CliIo, repositoryRoot: string, asJson: boolean, mode: "foreground" | "background" = "foreground"): Promise<void> {
+  const binary = resolveMenubarBinary(repositoryRoot, io.env);
+  if (binary === null) throw new CliError("unavailable", "The Slopcamera menu bar is not installed. Build it separately or set SLOPCAMERA_MENUBAR.");
+  const code = await runBinary(binary, mode === "foreground");
+  if (code !== 0) throw new CliError("unavailable", "The Slopcamera menu bar exited during startup.");
+  if (asJson) writeJson(io, { running: mode === "background", foreground: mode === "foreground" });
+  else writeLine(io, mode === "foreground" ? "Slopcamera menu bar exited." : "Slopcamera menu bar is running.");
+}
+export async function manageMenubar(io: CliIo, repositoryRoot: string, action: "install" | "uninstall" | "status", asJson: boolean): Promise<void> {
+  assertMac(io.platform);
+  const stable = installedBinaryPath(io.env);
+  let state: LaunchAgentState;
+  if (action === "install") {
+    const binary = resolveMenubarBinary(repositoryRoot, io.env);
+    if (binary === null) throw new CliError("unavailable", "The Slopcamera menu bar is not installed. Build it separately or set SLOPCAMERA_MENUBAR.");
+    state = installLaunchAgent(binary, io.env, io.platform);
+  } else {
+    state = action === "uninstall" ? uninstallLaunchAgent(stable, io.env, io.platform) : launchAgentState(stable, io.env);
+  }
+  if (asJson) writeJson(io, { launchAgent: state });
+  else writeLine(io, `Slopcamera menu-bar LaunchAgent: ${state}.`);
+}
+export async function reportOutputsRoot(io: CliIo, stateRoot: string, asJson: boolean): Promise<void> {
+  const directory = outputsRoot(stateRoot);
+  await ensurePrivateDirectory(directory);
+  if (asJson) writeJson(io, { outputs: directory });
+  else writeLine(io, directory);
+}

package/apps/desktop/cli/music-analysis-service.ts

@@ -15,18 +15,25 @@ import {
 } from "../contracts";
 import {
   analyzeMusic,
+  analyzeAudioReactivity,
+  AUDIO_REACTIVITY_MAX_DURATION_US,
+  AUDIO_REACTIVITY_SAMPLE_RATE_HZ,
   canonicalSlopcameraPersistenceDocument,
   canonicalJson,
   canonicalJsonSha256,
+  createNodeBundleFileSystem,
   saveAnalysisArtifact,
   saveVideoProject,
   sha256Hex,
   type MonoPcm,
 } from "../core";
+import { HtmlOverlayAudioReactivitySchema } from "../html-overlay/audio-reactivity";
 import { decodeAlignmentPcm, resolveAudioAnalysisSubject } from "./audio-analysis";
 import { CliError } from "./errors";
 import type { ProcessRunner } from "./io";
+import { SELF_CONTAINED_MEDIA_INPUT_ARGUMENTS } from "./media-ingest-model";
 import { ensurePhysicalPrivateDirectoryWithin } from "./paths";
+import { resolveVerifiedProjectMedia, type PhysicalProjectMediaFingerprint } from "./project-media-integrity";
 import { projectAnalysisPath, type OpenProject } from "./project-service";
 
 export const MUSIC_ANALYSIS_SAMPLE_RATE_HZ = 8_000;
@@ -174,6 +181,60 @@ export async function readMonoFloat32PcmBounded(
   }
 }
 
+const MAX_AUDIO_REACTIVITY_PCM_BYTES = 600 * AUDIO_REACTIVITY_SAMPLE_RATE_HZ * 4;
+
+/** Decode one verified retained soundtrack prefix for the optional bands-v1 sidecar. */
+export async function analyzeRetainedAudioReactivity(options: {
+  readonly repositoryRoot: string;
+  readonly jobDirectory: string;
+  readonly audio: PhysicalProjectMediaFingerprint;
+  readonly durationUs: number;
+  readonly streamIndex: number;
+  readonly ffmpeg: string;
+  readonly run: (argv: readonly [string, ...string[]]) => Promise<unknown>;
+  readonly fence: () => Promise<void>;
+}) {
+  if (!Number.isSafeInteger(options.durationUs) || options.durationUs < 1
+    || options.durationUs > AUDIO_REACTIVITY_MAX_DURATION_US
+    || !Number.isSafeInteger(options.streamIndex) || options.streamIndex < 0) {
+    throw new CliError("invalid-data", "Audio reactivity duration or stream index is outside its bound.");
+  }
+  const verify = async () => {
+    await options.fence();
+    return await resolveVerifiedProjectMedia({ repositoryRoot: options.repositoryRoot,
+      path: options.audio.path, expected: options.audio, label: "Audio reactivity soundtrack" });
+  };
+  const source = await verify();
+  const pcmPath = join(options.jobDirectory, "audio-reactivity.f32le");
+  const fs = createNodeBundleFileSystem(options.jobDirectory);
+  try {
+    await options.run([options.ffmpeg, "-nostdin", "-v", "error", "-n", "-threads", "2",
+      ...SELF_CONTAINED_MEDIA_INPUT_ARGUMENTS, "-i", source, "-map", `0:${options.streamIndex}`,
+      "-vn", "-sn", "-dn", "-t", (options.durationUs / 1_000_000).toFixed(6),
+      "-ac", "1", "-ar", String(AUDIO_REACTIVITY_SAMPLE_RATE_HZ), "-c:a", "pcm_f32le", "-f", "f32le",
+      "-fs", String(MAX_AUDIO_REACTIVITY_PCM_BYTES + 4), pcmPath]);
+    await verify();
+    const before = await fs.inspectFile!("audio-reactivity.f32le", MAX_AUDIO_REACTIVITY_PCM_BYTES);
+    const pcm = await readMonoFloat32PcmBounded(pcmPath, { maxBytes: MAX_AUDIO_REACTIVITY_PCM_BYTES, sampleRateHz: AUDIO_REACTIVITY_SAMPLE_RATE_HZ });
+    const expectedSamples = Math.round(options.durationUs * AUDIO_REACTIVITY_SAMPLE_RATE_HZ / 1_000_000);
+    if (Math.abs(pcm.samples.length - expectedSamples) > 2) {
+      throw new CliError("invalid-data", "Audio reactivity decode did not cover the requested soundtrack prefix.");
+    }
+    const analysis = analyzeAudioReactivity(pcm);
+    await options.fence();
+    const after = await fs.inspectFile!("audio-reactivity.f32le", MAX_AUDIO_REACTIVITY_PCM_BYTES);
+    if (before.bytes !== after.bytes || before.sha256 !== after.sha256) {
+      throw new CliError("conflict", "Audio reactivity PCM changed during analysis.");
+    }
+    return HtmlOverlayAudioReactivitySchema.parse({ kind: "slopcamera.audio-reactivity", schemaVersion: 1,
+      profile: "bands-v1", rateHz: 60, ...analysis,
+      source: { bytes: options.audio.bytes, sha256: options.audio.sha256 },
+      pcm: { sampleCount: pcm.samples.length, sha256: before.sha256 } });
+  } finally {
+    await rm(pcmPath, { force: true });
+  }
+}
+
 export interface WithDecodedMusicPcmOptions {
   readonly ffmpeg: string;
   readonly maxDecodedPcmBytes?: number;

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

@@ -1,3 +1,5 @@
+import { reportUsefulResult, type UsefulResultObserver } from "../../../src/support-completion";
+
 import { constants } from "node:fs";
 import { mkdir, open } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
@@ -16,7 +18,10 @@ import { CliError } from "./errors";
 
 const HEADLESS_SLOPCAMERA_CLI_MODULE = "@hraness/slopcamera/cli";
 
-async function runHeadlessSlopcameraCli(argv: readonly string[]): Promise<void> {
+async function runHeadlessSlopcameraCli(
+  argv: readonly string[],
+  options?: Readonly<{ onUsefulResult?: UsefulResultObserver }>,
+): Promise<void> {
   // Keep this as a runtime package import so the headless CLI retains its own
   // package-relative skill and asset resolution inside an installed bundle.
   const module: unknown = await import(HEADLESS_SLOPCAMERA_CLI_MODULE);
@@ -28,13 +33,14 @@ async function runHeadlessSlopcameraCli(argv: readonly string[]): Promise<void>
   ) {
     throw new CliError("unavailable", "The portable Slopcamera CLI is unavailable.");
   }
-  await module.main(argv);
+  await module.main(argv, options);
 }
 
 export interface PortableSurfaceDependencies {
+  readonly onUsefulResult?: UsefulResultObserver;
   readonly cwd?: () => string;
   readonly log?: (value: string) => void;
-  readonly runHeadless?: (argv: readonly string[]) => Promise<void>;
+  readonly runHeadless?: (argv: readonly string[], options?: Readonly<{ onUsefulResult?: UsefulResultObserver }>) => Promise<void>;
   readonly writeScaffold?: (path: string, html: string) => Promise<void>;
 }
 function optionValue(argv: readonly string[], name: string): string | undefined {
@@ -187,6 +193,7 @@ async function runHtmlScaffold(
     createHtmlOverlayScaffold(kind),
   );
   (dependencies.log ?? console.log)(`Created ${outputPath}`);
+  reportUsefulResult(dependencies.onUsefulResult);
   return 0;
 }
 
@@ -228,14 +235,20 @@ export async function runPortableSurface(
     )
     || (
       argv[0] === "image"
-      && (argv[1] === "vectorize" || argv[1] === "generate")
+      && (
+        argv[1] === "vectorize" ||
+        argv[1] === "generate" ||
+        argv[1] === "icon" ||
+        argv[1] === "gallery"
+      )
     );
   if (!delegatesToHeadless) return undefined;
 
   const previousExitCode = process.exitCode;
   process.exitCode = undefined;
   try {
-    await (dependencies.runHeadless ?? runHeadlessSlopcameraCli)(argv);
+    await (dependencies.runHeadless ?? runHeadlessSlopcameraCli)(argv,
+      dependencies.onUsefulResult === undefined ? {} : { onUsefulResult: dependencies.onUsefulResult });
     return process.exitCode ?? 0;
   } finally {
     process.exitCode = previousExitCode;

package/apps/desktop/cli/spatial-asset-service.ts

@@ -0,0 +1,124 @@
+import { lstat, realpath } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+
+import type { ApplicationContext } from "../application/context";
+import { admitSpatialAssetFile, SpatialAssetAdmissionError } from "../application/spatial-asset-admission";
+import { SpatialAssetAdmissionV1Schema } from "../contracts/spatial-asset";
+import type { SpatialAssetCommand } from "./args";
+import { CliError } from "./errors";
+import { displayPath, ensurePhysicalPrivateDirectoryWithin, resolveSafePath } from "./paths";
+import { publishSpatialSource } from "./spatial-scene-service";
+
+function isWithin(root: string, candidate: string): boolean {
+  const pathRelative = relative(root, candidate);
+  return pathRelative === "" || (!pathRelative.startsWith("..") && !isAbsolute(pathRelative));
+}
+
+function isMissing(error: unknown): boolean {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+
+/** A source root must exist and be physical before bounding one file below it. */
+async function physicalSourceRoot(path: string): Promise<string> {
+  let details;
+  try { details = await lstat(path); }
+  catch (error) {
+    if (isMissing(error)) throw new CliError("not-found", `--source-root is not a directory: ${path}`);
+    throw error;
+  }
+  if (details.isSymbolicLink() || !details.isDirectory()) {
+    throw new CliError("unsafe-path", `--source-root must be a physical directory without symlinks: ${path}`);
+  }
+  return await realpath(path);
+}
+
+/**
+ * Admit one explicit local GLB below --source-root (default: the project root),
+ * publish its exact bytes and derived facts beside --output, and write the
+ * deterministic admission document without replacing any existing path.
+ */
+export async function executeSpatialAssetCommand(
+  application: ApplicationContext,
+  command: SpatialAssetCommand,
+  adapter: Readonly<{ signal?: AbortSignal }>,
+): Promise<unknown> {
+  const repositoryRoot = application.paths.repositoryRoot;
+  const signal = adapter.signal ?? new AbortController().signal;
+  const fence = async () => {
+    signal.throwIfAborted();
+    await application.hostResourceLease?.assertOwned();
+    signal.throwIfAborted();
+  };
+  try {
+    signal.throwIfAborted();
+    const sourceRoot = await physicalSourceRoot(resolve(repositoryRoot, command.sourceRoot ?? "."));
+    const source = resolve(sourceRoot, command.file);
+    let physicalSource: string;
+    try { physicalSource = await realpath(source); }
+    catch (error) {
+      if (isMissing(error)) throw new CliError("not-found", `Admitted asset does not exist: ${command.file}`);
+      throw error;
+    }
+    if (!isWithin(sourceRoot, physicalSource)) {
+      throw new CliError("unsafe-path", `Admitted asset escapes --source-root: ${command.file}`);
+    }
+    if (physicalSource !== source) {
+      throw new CliError("unsafe-path", `Admitted asset must be a physical file without symlink components: ${command.file}`);
+    }
+    if (!(await lstat(physicalSource)).isFile()) {
+      throw new CliError("invalid-data", `Admitted asset is not a regular file: ${command.file}`);
+    }
+    const output = await resolveSafePath(repositoryRoot, command.output);
+    try {
+      await lstat(output);
+      throw new CliError("conflict", "Scene asset admission output already exists. Choose a new path to retain both revisions.");
+    } catch (error) {
+      if (error instanceof CliError) throw error;
+      if (!isMissing(error)) throw error;
+    }
+    const outputParent = relative(repositoryRoot, dirname(output));
+    const assetRoot = outputParent === ""
+      ? repositoryRoot
+      : await ensurePhysicalPrivateDirectoryWithin(repositoryRoot, outputParent);
+    const result = await admitSpatialAssetFile({
+      filePath: physicalSource, assetRoot,
+      ...(command.assetId === undefined ? {} : { assetId: command.assetId }),
+      metersPerUnit: command.metersPerUnit, sourceUp: command.sourceUp,
+      signal, beforePublication: fence,
+    });
+    const document = SpatialAssetAdmissionV1Schema.parse({
+      kind: "slopcamera.spatial-asset-admission", schemaVersion: 1,
+      manifest: result.manifest, factsManifest: result.factsManifest, facts: result.facts,
+      bounds: result.bounds, entity: result.entity, artifacts: result.artifacts,
+      operations: result.operations,
+    });
+    try {
+      await publishSpatialSource(output, document, fence);
+    } catch (error) {
+      const failure = error instanceof CliError ? error : new CliError("conflict", "Scene asset admission output publication failed.");
+      throw new CliError(signal.aborted ? "cancelled" : failure.code, failure.message, {
+        ...failure.details, published: [result.artifacts.payload, result.artifacts.facts], output: command.output,
+      });
+    }
+    return {
+      output: displayPath(repositoryRoot, output),
+      assetId: result.manifest.assetId,
+      factsAssetId: result.factsManifest.assetId,
+      entityId: result.entity.entityId,
+      bounds: result.bounds,
+      artifacts: result.artifacts,
+      document,
+    };
+  } catch (error) {
+    if (error instanceof SpatialAssetAdmissionError) {
+      throw new CliError(signal.aborted ? "cancelled" : "conflict", error.message, {
+        published: error.published, attempted: error.attempted, output: command.output,
+      });
+    }
+    if (signal.aborted && !(error instanceof CliError)) {
+      throw new CliError("cancelled", "Scene asset admission cancelled; retain its source and any publication evidence.");
+    }
+    if (error instanceof RangeError) throw new CliError("invalid-data", error.message);
+    throw error;
+  }
+}