@lumy-pack/scene-sieve 0.0.9 → 0.0.11

package/dist/cli.mjs

@@ -9,42 +9,6 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
-// src/utils/logger.ts
-import pc from "picocolors";
-function setDebugMode(enabled) {
-  debugMode = enabled;
-}
-function timestamp() {
-  return (/* @__PURE__ */ new Date()).toLocaleTimeString("en-US", { hour12: false });
-}
-var debugMode, logger;
-var init_logger = __esm({
-  "src/utils/logger.ts"() {
-    "use strict";
-    debugMode = false;
-    logger = {
-      info(message) {
-        console.log(`${pc.blue("info")} ${message}`);
-      },
-      success(message) {
-        console.log(`
-${pc.green("done")} ${message}`);
-      },
-      warn(message) {
-        console.warn(`${pc.yellow("warn")} ${message}`);
-      },
-      error(message) {
-        console.error(`${pc.red("error")} ${message}`);
-      },
-      debug(message) {
-        if (debugMode) {
-          console.log(`${pc.gray(`[${timestamp()}] debug`)} ${message}`);
-        }
-      }
-    };
-  }
-});
-
 // src/constants.ts
 import { tmpdir } from "os";
 import { join } from "path";
@@ -86,6 +50,42 @@ var init_constants = __esm({
   }
 });
 
+// src/utils/logger.ts
+import pc from "picocolors";
+function setDebugMode(enabled) {
+  debugMode = enabled;
+}
+function timestamp() {
+  return (/* @__PURE__ */ new Date()).toLocaleTimeString("en-US", { hour12: false });
+}
+var debugMode, logger;
+var init_logger = __esm({
+  "src/utils/logger.ts"() {
+    "use strict";
+    debugMode = false;
+    logger = {
+      info(message) {
+        console.log(`${pc.blue("info")} ${message}`);
+      },
+      success(message) {
+        console.log(`
+${pc.green("done")} ${message}`);
+      },
+      warn(message) {
+        console.warn(`${pc.yellow("warn")} ${message}`);
+      },
+      error(message) {
+        console.error(`${pc.red("error")} ${message}`);
+      },
+      debug(message) {
+        if (debugMode) {
+          console.log(`${pc.gray(`[${timestamp()}] debug`)} ${message}`);
+        }
+      }
+    };
+  }
+});
+
 // src/core/dbscan.ts
 function dbscan(points, imageWidth, imageHeight, alpha, minPts) {
   if (points.length === 0) {
@@ -1248,10 +1248,7 @@ function computeSegmentPlan(totalDuration, maxSegmentDuration, maxFrames, fps) {
   }
   return segments;
 }
-function mergeSegmentFrames(segmentResults) {
-  if (segmentResults.length === 0) {
-    return { frames: [], edges: [], animations: [] };
-  }
+function collectAllFrames(segmentResults) {
   const allFrames = [];
   for (const result of segmentResults) {
     for (const frame of result.frames) {
@@ -1266,19 +1263,24 @@ function mergeSegmentFrames(segmentResults) {
       });
     }
   }
-  allFrames.sort((a, b) => a.frame.timestamp - b.frame.timestamp);
-  const effectiveFps = segmentResults[0].segment.effectiveFps;
+  return allFrames;
+}
+function deduplicateFrames(frames, effectiveFps) {
+  frames.sort((a, b) => a.frame.timestamp - b.frame.timestamp);
   const dupThreshold = 1 / (effectiveFps * 2);
-  const uniqueFrames = [];
-  for (const entry of allFrames) {
-    if (uniqueFrames.length > 0) {
-      const last = uniqueFrames[uniqueFrames.length - 1];
+  const unique = [];
+  for (const entry of frames) {
+    if (unique.length > 0) {
+      const last = unique[unique.length - 1];
       if (Math.abs(entry.frame.timestamp - last.frame.timestamp) < dupThreshold) {
         continue;
       }
     }
-    uniqueFrames.push(entry);
+    unique.push(entry);
   }
+  return unique;
+}
+function remapFrameIds(uniqueFrames) {
   const globalIdMap = /* @__PURE__ */ new Map();
   const frames = uniqueFrames.map((entry, globalId) => {
     globalIdMap.set(`${entry.segmentIndex}:${entry.localId}`, globalId);
@@ -1288,6 +1290,9 @@ function mergeSegmentFrames(segmentResults) {
       extractPath: entry.frame.extractPath
     };
   });
+  return { frames, globalIdMap };
+}
+function remapEdges(segmentResults, globalIdMap) {
   const edges = [];
   const edgeMap = /* @__PURE__ */ new Map();
   for (const result of segmentResults) {
@@ -1319,6 +1324,9 @@ function mergeSegmentFrames(segmentResults) {
       }
     }
   }
+  return edges;
+}
+function remapAnimations(segmentResults, globalIdMap) {
   const animations = [];
   for (const result of segmentResults) {
     for (const anim of result.animations) {
@@ -1336,6 +1344,18 @@ function mergeSegmentFrames(segmentResults) {
       });
     }
   }
+  return animations;
+}
+function mergeSegmentFrames(segmentResults) {
+  if (segmentResults.length === 0) {
+    return { frames: [], edges: [], animations: [] };
+  }
+  const effectiveFps = segmentResults[0].segment.effectiveFps;
+  const allFrames = collectAllFrames(segmentResults);
+  const uniqueFrames = deduplicateFrames(allFrames, effectiveFps);
+  const { frames, globalIdMap } = remapFrameIds(uniqueFrames);
+  const edges = remapEdges(segmentResults, globalIdMap);
+  const animations = remapAnimations(segmentResults, globalIdMap);
   return { frames, edges, animations };
 }
 function buildSegmentContext(segment, frames, segmentWorkspacePath, resolvedOptions, onProgress) {
@@ -1637,12 +1657,41 @@ var init_orchestrator = __esm({
 // src/cli.ts
 import { createRequire as createRequire2 } from "module";
 import { Command } from "commander";
-import { render } from "ink";
-import React2 from "react";
+
+// ../shared/src/respond.ts
+function respond(command, data, startTime, version2) {
+  const response = {
+    ok: true,
+    command,
+    data,
+    meta: {
+      version: version2,
+      durationMs: Date.now() - startTime,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  };
+  process.stdout.write(JSON.stringify(response) + "\n");
+}
+function respondError(command, code, message, startTime, version2, details) {
+  const response = {
+    ok: false,
+    command,
+    error: { code, message, ...details !== void 0 ? { details } : {} },
+    meta: {
+      version: version2,
+      durationMs: Date.now() - startTime,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  };
+  process.stdout.write(JSON.stringify(response) + "\n");
+  process.exitCode = 1;
+}
 
 // src/commands/Sieve.tsx
+import { existsSync } from "fs";
 import { Box as Box2, Text as Text3, useApp } from "ink";
-import { useEffect, useState } from "react";
+import { render } from "ink";
+import React, { useEffect, useState } from "react";
 
 // src/components/PhaseStep.tsx
 import { Box, Text as Text2 } from "ink";
@@ -1703,6 +1752,10 @@ var PhaseStep = ({ phase }) => {
   ] });
 };
 
+// src/commands/Sieve.tsx
+init_constants();
+init_orchestrator();
+
 // src/core/run-in-worker.ts
 import { dirname, join as join6 } from "path";
 import { fileURLToPath } from "url";
@@ -1741,6 +1794,145 @@ async function runPipelineInWorker(options, onProgress) {
 
 // src/commands/Sieve.tsx
 init_workspace();
+
+// src/errors.ts
+var SieveErrorCode = {
+  INVALID_INPUT: "INVALID_INPUT",
+  FILE_NOT_FOUND: "FILE_NOT_FOUND",
+  INVALID_FORMAT: "INVALID_FORMAT",
+  PIPELINE_ERROR: "PIPELINE_ERROR",
+  WORKER_ERROR: "WORKER_ERROR",
+  UNKNOWN: "UNKNOWN"
+};
+function classifyError(error) {
+  const msg = error.message.toLowerCase();
+  if (error.code === "ENOENT" || msg.includes("not found")) {
+    return SieveErrorCode.FILE_NOT_FOUND;
+  } else if (msg.includes("no video stream") || msg.includes("invalid format")) {
+    return SieveErrorCode.INVALID_FORMAT;
+  } else if (msg.includes("worker")) {
+    return SieveErrorCode.WORKER_ERROR;
+  } else {
+    return SieveErrorCode.PIPELINE_ERROR;
+  }
+}
+
+// src/utils/command-registry.ts
+var SIEVE_COMMAND = {
+  name: "scene-sieve",
+  description: "Extract key frames from video and GIF files",
+  usage: "scene-sieve <input> [options]",
+  arguments: [
+    {
+      name: "input",
+      description: "Input video or GIF file path",
+      required: true
+    }
+  ],
+  options: [
+    {
+      flag: "-n, --count <number>",
+      description: "Max number of frames to keep (default: 20)",
+      type: "number"
+    },
+    {
+      flag: "-t, --threshold <number>",
+      description: "Normalized threshold 0~1 (default: 0.5; keeps frames above ratio of max change)",
+      type: "number"
+    },
+    {
+      flag: "-o, --output <path>",
+      description: "Output directory path",
+      type: "string"
+    },
+    {
+      flag: "--fps <number>",
+      description: "Max FPS for frame extraction",
+      type: "number",
+      default: "5"
+    },
+    {
+      flag: "-mf, --max-frames <number>",
+      description: "Max frames to extract (auto-reduces FPS for long videos)",
+      type: "number",
+      default: "300"
+    },
+    {
+      flag: "-s, --scale <number>",
+      description: "Scale size for vision analysis",
+      type: "number",
+      default: "720"
+    },
+    {
+      flag: "-q, --quality <number>",
+      description: "JPEG output quality 1-100",
+      type: "number",
+      default: "80"
+    },
+    {
+      flag: "-it, --iou-threshold <number>",
+      description: "IoU threshold for animation tracking (0-1) (default: 0.9)",
+      type: "number"
+    },
+    {
+      flag: "-at, --anim-threshold <number>",
+      description: "Min consecutive frames for animation (default: 5)",
+      type: "number"
+    },
+    {
+      flag: "--max-segment-duration <number>",
+      description: "Max segment duration in seconds for long video splitting (default: 300)",
+      type: "number"
+    },
+    {
+      flag: "--concurrency <number>",
+      description: "Number of segments to process in parallel (default: 2)",
+      type: "number"
+    },
+    {
+      flag: "--debug",
+      description: "Enable debug mode (preserve temp workspace)",
+      type: "boolean"
+    },
+    {
+      flag: "--json",
+      description: "Output structured JSON to stdout",
+      type: "boolean"
+    },
+    {
+      flag: "--describe",
+      description: "Output JSON schema of available options",
+      type: "boolean"
+    }
+  ],
+  examples: [
+    "scene-sieve video.mp4",
+    "scene-sieve video.mp4 -n 10",
+    "scene-sieve video.mp4 -t 0.3 -o ./output",
+    "scene-sieve video.mp4 --json",
+    "scene-sieve --describe"
+  ]
+};
+
+// src/utils/parse-options.ts
+function parsePipelineOptions(opts) {
+  return {
+    ...opts.threshold !== void 0 ? { threshold: parseFloat(opts.threshold) } : {},
+    ...opts.count !== void 0 ? { count: parseInt(opts.count, 10) } : {},
+    outputPath: opts.output,
+    fps: parseInt(opts.fps, 10),
+    maxFrames: parseInt(opts.maxFrames, 10),
+    scale: parseInt(opts.scale, 10),
+    quality: parseInt(opts.quality, 10),
+    iouThreshold: opts.iouThreshold !== void 0 ? parseFloat(opts.iouThreshold) : void 0,
+    animationThreshold: opts.animThreshold !== void 0 ? parseInt(opts.animThreshold, 10) : void 0,
+    maxSegmentDuration: opts.maxSegmentDuration !== void 0 ? parseInt(opts.maxSegmentDuration, 10) : void 0,
+    concurrency: opts.concurrency !== void 0 ? parseInt(opts.concurrency, 10) : void 0,
+    debug: opts.debug ?? false
+  };
+}
+
+// src/commands/Sieve.tsx
 import { jsx as jsx3, jsxs as jsxs3 } from "react/jsx-runtime";
 var PHASE_DEFS = [
   { key: "INIT", label: "Initializing workspace", hasProgress: false },
@@ -1760,6 +1952,78 @@ function createInitialPhases() {
 function phaseKeyToIndex(phase) {
   return PHASE_DEFS.findIndex((d) => d.key === phase);
 }
+function registerSieveCommand(program2, version2) {
+  const cmd = SIEVE_COMMAND;
+  program2.argument("<input>", cmd.arguments[0].description).option("-n, --count <number>", cmd.options.find((o) => o.flag.includes("--count")).description).option(
+    "-t, --threshold <number>",
+    cmd.options.find((o) => o.flag.includes("--threshold")).description
+  ).option("-o, --output <path>", cmd.options.find((o) => o.flag.includes("--output")).description).option("--fps <number>", cmd.options.find((o) => o.flag.includes("--fps")).description, String(DEFAULT_FPS)).option(
+    "-mf, --max-frames <number>",
+    cmd.options.find((o) => o.flag.includes("--max-frames")).description,
+    String(DEFAULT_MAX_FRAMES)
+  ).option(
+    "-s, --scale <number>",
+    cmd.options.find((o) => o.flag.includes("--scale")).description,
+    String(DEFAULT_SCALE)
+  ).option(
+    "-q, --quality <number>",
+    cmd.options.find((o) => o.flag.includes("--quality")).description,
+    String(DEFAULT_QUALITY)
+  ).option(
+    "-it, --iou-threshold <number>",
+    cmd.options.find((o) => o.flag.includes("--iou-threshold")).description
+  ).option(
+    "-at, --anim-threshold <number>",
+    cmd.options.find((o) => o.flag.includes("--anim-threshold")).description
+  ).option(
+    "--max-segment-duration <number>",
+    cmd.options.find((o) => o.flag.includes("--max-segment-duration")).description
+  ).option(
+    "--concurrency <number>",
+    cmd.options.find((o) => o.flag.includes("--concurrency")).description
+  ).option("--debug", cmd.options.find((o) => o.flag.includes("--debug")).description).option("--json", cmd.options.find((o) => o.flag.includes("--json")).description).option("--describe", cmd.options.find((o) => o.flag.includes("--describe")).description).action(async (input, opts) => {
+    const parsed = parsePipelineOptions(opts);
+    if (opts.json) {
+      const startTime = Date.now();
+      if (!existsSync(input)) {
+        respondError("extract", SieveErrorCode.FILE_NOT_FOUND, `File not found: ${input}`, startTime, version2);
+        return;
+      }
+      try {
+        const result = await runPipeline({
+          mode: "file",
+          inputPath: input,
+          ...parsed,
+          onProgress: (phase, percent) => {
+            process.stderr.write(JSON.stringify({ phase, percent }) + "\n");
+          }
+        });
+        const data = {
+          success: result.success,
+          originalFrames: result.originalFramesCount,
+          selectedFrames: result.prunedFramesCount,
+          outputFiles: result.outputFiles,
+          animations: result.animations ?? [],
+          video: result.video ?? null
+        };
+        respond("extract", data, startTime, version2);
+      } catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        respondError("extract", classifyError(err), err.message, startTime, version2);
+      }
+      return;
+    }
+    const { outputPath, ...viewOpts } = parsed;
+    const { waitUntilExit } = render(
+      React.createElement(SieveView, {
+        input,
+        ...viewOpts,
+        output: outputPath
+      })
+    );
+    await waitUntilExit();
+  });
+}
 var SieveView = (props) => {
   const { exit } = useApp();
   const [phases, setPhases] = useState(createInitialPhases);
@@ -1915,58 +2179,32 @@ var SieveView = (props) => {
 };
 
 // src/cli.ts
-init_constants();
 var require3 = createRequire2(import.meta.url);
 var { version } = require3("../package.json");
 var program = new Command();
-program.name("scene-sieve").description("Extract key frames from video and GIF files").version(version).argument("<input>", "Input video or GIF file path").option("-n, --count <number>", "Max number of frames to keep (default: 20)").option(
-  "-t, --threshold <number>",
-  "Normalized threshold 0~1 (default: 0.5; keeps frames above ratio of max change)"
-).option("-o, --output <path>", "Output directory path").option("--fps <number>", "Max FPS for frame extraction", String(DEFAULT_FPS)).option(
-  "-mf, --max-frames <number>",
-  "Max frames to extract (auto-reduces FPS for long videos)",
-  String(DEFAULT_MAX_FRAMES)
-).option(
-  "-s, --scale <number>",
-  "Scale size for vision analysis",
-  String(DEFAULT_SCALE)
-).option(
-  "-q, --quality <number>",
-  "JPEG output quality 1-100",
-  String(DEFAULT_QUALITY)
-).option(
-  "-it, --iou-threshold <number>",
-  `IoU threshold for animation tracking (0-1) (default: ${IOU_THRESHOLD})`
-).option(
-  "-at, --anim-threshold <number>",
-  `Min consecutive frames for animation (default: ${ANIMATION_FRAME_THRESHOLD})`
-).option(
-  "--max-segment-duration <number>",
-  `Max segment duration in seconds for long video splitting (default: ${DEFAULT_MAX_SEGMENT_DURATION})`
-).option(
-  "--concurrency <number>",
-  `Number of segments to process in parallel (default: ${DEFAULT_SEGMENT_CONCURRENCY})`
-).option("--debug", "Enable debug mode (preserve temp workspace)").action(async (input, opts) => {
-  const { waitUntilExit } = render(
-    React2.createElement(SieveView, {
-      input,
-      ...opts.threshold !== void 0 ? { threshold: parseFloat(opts.threshold) } : {},
-      ...opts.count !== void 0 ? { count: parseInt(opts.count, 10) } : {},
-      output: opts.output,
-      fps: parseInt(opts.fps, 10),
-      maxFrames: parseInt(opts.maxFrames, 10),
-      scale: parseInt(opts.scale, 10),
-      quality: parseInt(opts.quality, 10),
-      iouThreshold: opts.iouThreshold !== void 0 ? parseFloat(opts.iouThreshold) : void 0,
-      animationThreshold: opts.animThreshold !== void 0 ? parseInt(opts.animThreshold, 10) : void 0,
-      maxSegmentDuration: opts.maxSegmentDuration !== void 0 ? parseInt(opts.maxSegmentDuration, 10) : void 0,
-      concurrency: opts.concurrency !== void 0 ? parseInt(opts.concurrency, 10) : void 0,
-      debug: opts.debug ?? false
-    })
+program.name("scene-sieve").description("Extract key frames from video and GIF files").version(version);
+registerSieveCommand(program, version);
+if (process.argv.includes("--describe")) {
+  const startTime = Date.now();
+  respond(
+    "describe",
+    {
+      name: SIEVE_COMMAND.name,
+      version,
+      description: SIEVE_COMMAND.description,
+      arguments: SIEVE_COMMAND.arguments,
+      options: SIEVE_COMMAND.options
+    },
+    startTime,
+    version
   );
-  await waitUntilExit();
-});
+  process.exit(0);
+}
 program.parseAsync(process.argv).catch((error) => {
-  console.error("Fatal error:", error.message);
+  if (process.argv.includes("--json")) {
+    respondError("extract", SieveErrorCode.UNKNOWN, error.message, Date.now(), version);
+  } else {
+    console.error("Fatal error:", error.message);
+  }
   process.exit(1);
 });

package/dist/commands/Sieve.d.ts

@@ -1,3 +1,4 @@
+import type { Command } from 'commander';
 import React from 'react';
 export interface SieveViewProps {
     input: string;
@@ -14,4 +15,5 @@ export interface SieveViewProps {
     concurrency?: number;
     debug: boolean;
 }
+export declare function registerSieveCommand(program: Command, version: string): void;
 export declare const SieveView: React.FC<SieveViewProps>;

package/dist/errors.d.ts

@@ -0,0 +1,10 @@
+export declare const SieveErrorCode: {
+    readonly INVALID_INPUT: "INVALID_INPUT";
+    readonly FILE_NOT_FOUND: "FILE_NOT_FOUND";
+    readonly INVALID_FORMAT: "INVALID_FORMAT";
+    readonly PIPELINE_ERROR: "PIPELINE_ERROR";
+    readonly WORKER_ERROR: "WORKER_ERROR";
+    readonly UNKNOWN: "UNKNOWN";
+};
+export type SieveErrorCode = (typeof SieveErrorCode)[keyof typeof SieveErrorCode];
+export declare function classifyError(error: Error): SieveErrorCode;

package/dist/index.cjs

@@ -1192,10 +1192,7 @@ function computeSegmentPlan(totalDuration, maxSegmentDuration, maxFrames, fps) {
   }
   return segments;
 }
-function mergeSegmentFrames(segmentResults) {
-  if (segmentResults.length === 0) {
-    return { frames: [], edges: [], animations: [] };
-  }
+function collectAllFrames(segmentResults) {
   const allFrames = [];
   for (const result of segmentResults) {
     for (const frame of result.frames) {
@@ -1210,19 +1207,24 @@ function mergeSegmentFrames(segmentResults) {
       });
     }
   }
-  allFrames.sort((a, b) => a.frame.timestamp - b.frame.timestamp);
-  const effectiveFps = segmentResults[0].segment.effectiveFps;
+  return allFrames;
+}
+function deduplicateFrames(frames, effectiveFps) {
+  frames.sort((a, b) => a.frame.timestamp - b.frame.timestamp);
   const dupThreshold = 1 / (effectiveFps * 2);
-  const uniqueFrames = [];
-  for (const entry of allFrames) {
-    if (uniqueFrames.length > 0) {
-      const last = uniqueFrames[uniqueFrames.length - 1];
+  const unique = [];
+  for (const entry of frames) {
+    if (unique.length > 0) {
+      const last = unique[unique.length - 1];
       if (Math.abs(entry.frame.timestamp - last.frame.timestamp) < dupThreshold) {
         continue;
       }
     }
-    uniqueFrames.push(entry);
+    unique.push(entry);
   }
+  return unique;
+}
+function remapFrameIds(uniqueFrames) {
   const globalIdMap = /* @__PURE__ */ new Map();
   const frames = uniqueFrames.map((entry, globalId) => {
     globalIdMap.set(`${entry.segmentIndex}:${entry.localId}`, globalId);
@@ -1232,6 +1234,9 @@ function mergeSegmentFrames(segmentResults) {
       extractPath: entry.frame.extractPath
     };
   });
+  return { frames, globalIdMap };
+}
+function remapEdges(segmentResults, globalIdMap) {
   const edges = [];
   const edgeMap = /* @__PURE__ */ new Map();
   for (const result of segmentResults) {
@@ -1263,6 +1268,9 @@ function mergeSegmentFrames(segmentResults) {
       }
     }
   }
+  return edges;
+}
+function remapAnimations(segmentResults, globalIdMap) {
   const animations = [];
   for (const result of segmentResults) {
     for (const anim of result.animations) {
@@ -1280,6 +1288,18 @@ function mergeSegmentFrames(segmentResults) {
       });
     }
   }
+  return animations;
+}
+function mergeSegmentFrames(segmentResults) {
+  if (segmentResults.length === 0) {
+    return { frames: [], edges: [], animations: [] };
+  }
+  const effectiveFps = segmentResults[0].segment.effectiveFps;
+  const allFrames = collectAllFrames(segmentResults);
+  const uniqueFrames = deduplicateFrames(allFrames, effectiveFps);
+  const { frames, globalIdMap } = remapFrameIds(uniqueFrames);
+  const edges = remapEdges(segmentResults, globalIdMap);
+  const animations = remapAnimations(segmentResults, globalIdMap);
   return { frames, edges, animations };
 }
 function buildSegmentContext(segment, frames, segmentWorkspacePath, resolvedOptions, onProgress) {

package/dist/index.mjs

@@ -1152,10 +1152,7 @@ function computeSegmentPlan(totalDuration, maxSegmentDuration, maxFrames, fps) {
   }
   return segments;
 }
-function mergeSegmentFrames(segmentResults) {
-  if (segmentResults.length === 0) {
-    return { frames: [], edges: [], animations: [] };
-  }
+function collectAllFrames(segmentResults) {
   const allFrames = [];
   for (const result of segmentResults) {
     for (const frame of result.frames) {
@@ -1170,19 +1167,24 @@ function mergeSegmentFrames(segmentResults) {
       });
     }
   }
-  allFrames.sort((a, b) => a.frame.timestamp - b.frame.timestamp);
-  const effectiveFps = segmentResults[0].segment.effectiveFps;
+  return allFrames;
+}
+function deduplicateFrames(frames, effectiveFps) {
+  frames.sort((a, b) => a.frame.timestamp - b.frame.timestamp);
   const dupThreshold = 1 / (effectiveFps * 2);
-  const uniqueFrames = [];
-  for (const entry of allFrames) {
-    if (uniqueFrames.length > 0) {
-      const last = uniqueFrames[uniqueFrames.length - 1];
+  const unique = [];
+  for (const entry of frames) {
+    if (unique.length > 0) {
+      const last = unique[unique.length - 1];
       if (Math.abs(entry.frame.timestamp - last.frame.timestamp) < dupThreshold) {
         continue;
       }
     }
-    uniqueFrames.push(entry);
+    unique.push(entry);
   }
+  return unique;
+}
+function remapFrameIds(uniqueFrames) {
   const globalIdMap = /* @__PURE__ */ new Map();
   const frames = uniqueFrames.map((entry, globalId) => {
     globalIdMap.set(`${entry.segmentIndex}:${entry.localId}`, globalId);
@@ -1192,6 +1194,9 @@ function mergeSegmentFrames(segmentResults) {
       extractPath: entry.frame.extractPath
     };
   });
+  return { frames, globalIdMap };
+}
+function remapEdges(segmentResults, globalIdMap) {
   const edges = [];
   const edgeMap = /* @__PURE__ */ new Map();
   for (const result of segmentResults) {
@@ -1223,6 +1228,9 @@ function mergeSegmentFrames(segmentResults) {
       }
     }
   }
+  return edges;
+}
+function remapAnimations(segmentResults, globalIdMap) {
   const animations = [];
   for (const result of segmentResults) {
     for (const anim of result.animations) {
@@ -1240,6 +1248,18 @@ function mergeSegmentFrames(segmentResults) {
       });
     }
   }
+  return animations;
+}
+function mergeSegmentFrames(segmentResults) {
+  if (segmentResults.length === 0) {
+    return { frames: [], edges: [], animations: [] };
+  }
+  const effectiveFps = segmentResults[0].segment.effectiveFps;
+  const allFrames = collectAllFrames(segmentResults);
+  const uniqueFrames = deduplicateFrames(allFrames, effectiveFps);
+  const { frames, globalIdMap } = remapFrameIds(uniqueFrames);
+  const edges = remapEdges(segmentResults, globalIdMap);
+  const animations = remapAnimations(segmentResults, globalIdMap);
   return { frames, edges, animations };
 }
 function buildSegmentContext(segment, frames, segmentWorkspacePath, resolvedOptions, onProgress) {

package/dist/pipeline-worker.mjs

@@ -1155,10 +1155,7 @@ function computeSegmentPlan(totalDuration, maxSegmentDuration, maxFrames, fps) {
   }
   return segments;
 }
-function mergeSegmentFrames(segmentResults) {
-  if (segmentResults.length === 0) {
-    return { frames: [], edges: [], animations: [] };
-  }
+function collectAllFrames(segmentResults) {
   const allFrames = [];
   for (const result of segmentResults) {
     for (const frame of result.frames) {
@@ -1173,19 +1170,24 @@ function mergeSegmentFrames(segmentResults) {
       });
     }
   }
-  allFrames.sort((a, b) => a.frame.timestamp - b.frame.timestamp);
-  const effectiveFps = segmentResults[0].segment.effectiveFps;
+  return allFrames;
+}
+function deduplicateFrames(frames, effectiveFps) {
+  frames.sort((a, b) => a.frame.timestamp - b.frame.timestamp);
   const dupThreshold = 1 / (effectiveFps * 2);
-  const uniqueFrames = [];
-  for (const entry of allFrames) {
-    if (uniqueFrames.length > 0) {
-      const last = uniqueFrames[uniqueFrames.length - 1];
+  const unique = [];
+  for (const entry of frames) {
+    if (unique.length > 0) {
+      const last = unique[unique.length - 1];
       if (Math.abs(entry.frame.timestamp - last.frame.timestamp) < dupThreshold) {
         continue;
       }
     }
-    uniqueFrames.push(entry);
+    unique.push(entry);
   }
+  return unique;
+}
+function remapFrameIds(uniqueFrames) {
   const globalIdMap = /* @__PURE__ */ new Map();
   const frames = uniqueFrames.map((entry, globalId) => {
     globalIdMap.set(`${entry.segmentIndex}:${entry.localId}`, globalId);
@@ -1195,6 +1197,9 @@ function mergeSegmentFrames(segmentResults) {
       extractPath: entry.frame.extractPath
     };
   });
+  return { frames, globalIdMap };
+}
+function remapEdges(segmentResults, globalIdMap) {
   const edges = [];
   const edgeMap = /* @__PURE__ */ new Map();
   for (const result of segmentResults) {
@@ -1226,6 +1231,9 @@ function mergeSegmentFrames(segmentResults) {
       }
     }
   }
+  return edges;
+}
+function remapAnimations(segmentResults, globalIdMap) {
   const animations = [];
   for (const result of segmentResults) {
     for (const anim of result.animations) {
@@ -1243,6 +1251,18 @@ function mergeSegmentFrames(segmentResults) {
       });
     }
   }
+  return animations;
+}
+function mergeSegmentFrames(segmentResults) {
+  if (segmentResults.length === 0) {
+    return { frames: [], edges: [], animations: [] };
+  }
+  const effectiveFps = segmentResults[0].segment.effectiveFps;
+  const allFrames = collectAllFrames(segmentResults);
+  const uniqueFrames = deduplicateFrames(allFrames, effectiveFps);
+  const { frames, globalIdMap } = remapFrameIds(uniqueFrames);
+  const edges = remapEdges(segmentResults, globalIdMap);
+  const animations = remapAnimations(segmentResults, globalIdMap);
   return { frames, edges, animations };
 }
 function buildSegmentContext(segment, frames, segmentWorkspacePath, resolvedOptions, onProgress) {

package/dist/utils/command-registry.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Central command registry for scene-sieve CLI.
+ * Single source of truth for command metadata, used by --describe and --help.
+ */
+export interface CommandOption {
+    flag: string;
+    description: string;
+    type?: 'boolean' | 'string' | 'number';
+    default?: string;
+}
+export interface CommandArgument {
+    name: string;
+    description: string;
+    required: boolean;
+}
+export interface CommandInfo {
+    name: string;
+    description: string;
+    usage: string;
+    arguments?: CommandArgument[];
+    options?: CommandOption[];
+    examples?: string[];
+}
+export declare const SIEVE_COMMAND: CommandInfo;

package/dist/utils/parse-options.d.ts

@@ -0,0 +1,21 @@
+import type { SieveOptionsBase } from '../types/index.js';
+/**
+ * Common pipeline options parsed from CLI opts (Commander string values → typed values).
+ * Does NOT include mode-specific fields (mode, inputPath, onProgress).
+ */
+export type ParsedPipelineOptions = Pick<Required<SieveOptionsBase>, 'fps' | 'maxFrames' | 'scale' | 'quality' | 'debug'> & Pick<SieveOptionsBase, 'count' | 'threshold' | 'outputPath' | 'iouThreshold' | 'animationThreshold' | 'maxSegmentDuration' | 'concurrency'>;
+export interface RawCliOptions {
+    count?: string;
+    threshold?: string;
+    output?: string;
+    fps: string;
+    maxFrames: string;
+    scale: string;
+    quality: string;
+    iouThreshold?: string;
+    animThreshold?: string;
+    maxSegmentDuration?: string;
+    concurrency?: string;
+    debug?: boolean;
+}
+export declare function parsePipelineOptions(opts: RawCliOptions): ParsedPipelineOptions;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumy-pack/scene-sieve",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "description": "CLI tool for extracting key frames from video and GIF files",
   "keywords": [
     "cli",
@@ -33,7 +33,7 @@
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
-  "bin": "./dist/cli.mjs",
+  "bin": "dist/cli.mjs",
   "files": [
     "dist",
     "!dist/tsconfig.tsbuildinfo"
@@ -66,6 +66,7 @@
     "sharp": "^0.33.0"
   },
   "devDependencies": {
+    "@lumy-pack/shared": "0.0.1",
     "@types/node": "^20.11.0",
     "@types/react": "^18.0.0",
     "@vitest/coverage-v8": "^3.2.4"