@telepat/rilo 0.1.0 → 0.1.6

package/src/cli/index.js

@@ -14,6 +14,7 @@ import {
 } from '../store/projectStore.js';
 import { openSettings } from './commands/settingsFlow.js';
 import { openHome } from './commands/openHome.js';
+import { startPreview } from './commands/preview.js';
 import { applyStoredSettings } from '../config/env.js';
 
 function getArg(flag) {
@@ -50,6 +51,7 @@ Rilo — Story-first vertical video generation
 
 USAGE
   rilo --project <name> [--story-file <path>] [--force]
+  rilo preview [--port <n>] [--host <host>] [--no-open] [--expose --unsafe-no-auth]
   rilo settings
   rilo home
   rilo --help
@@ -62,6 +64,7 @@ COMMANDS
     --project <name>         Project identifier (required); creates projects/<name>/
     --story-file <path>      Path to story text file (required on first run)
     --force                  Force restart from earlier stages (use after config changes)
+    --full-run               Skip the pause after keyframe generation and run all the way through
 
   rilo settings
     Configure API tokens, timeouts, and binary paths interactively
@@ -69,9 +72,19 @@ COMMANDS
   rilo home
     Open ~/.rilo, the default home for projects and output files
 
+  rilo preview [--port <n>] [--host <host>] [--no-open] [--expose --unsafe-no-auth]
+    Start API, worker, and dashboard preview for local use
+
+    --port <n>               API/dashboard port (default: 3000)
+    --host <host>            Host bind address (default: 127.0.0.1)
+    --no-open                Do not auto-open browser
+    --expose                 Bind preview for external/container access
+    --unsafe-no-auth         Allow unauthenticated exposed preview (required with --expose)
+
 FLAGS
   --help                     Show this help message
   --version                  Show version information
+  --full-run                 Skip the keyframe review pause and run all pipeline stages
 
 EXAMPLES
   # First run: create project and generate
@@ -89,6 +102,12 @@ EXAMPLES
   # Open the default Rilo home folder
   rilo home
 
+  # Run local dashboard/API preview
+  rilo preview
+
+  # Expose preview over container or tunnel (unsafe)
+  rilo preview --expose --unsafe-no-auth --host 0.0.0.0 --port 3000
+
   # Using npx (no installation needed)
   npx @telepat/rilo --project wedding-case --story-file ./story.txt
   npx @telepat/rilo home
@@ -115,6 +134,9 @@ SETTINGS
   Configure via interactive menu:
     rilo settings
 
+  Recommended install:
+    npm install -g @telepat/rilo
+
   Or with environment variables:
     export RILO_REPLICATE_API_TOKEN=r8_xxxxx
     export RILO_MAX_RETRIES=5
@@ -129,7 +151,7 @@ SETTINGS
 INVOCATION METHODS
   Global install:        rilo --project <name> --story-file <path>
   No install (npx):      npx @telepat/rilo --project <name> --story-file <path>
-  Local development:     npm run dev -- --project <name> --story-file <path>
+  Contributor workflow:  npm run dev -- --project <name> --story-file <path>
 `;
     console.log(helpText);
     return;
@@ -146,6 +168,12 @@ INVOCATION METHODS
     return;
   }
 
+  if (process.argv[2] === 'preview') {
+    await applyStoredSettings();
+    await startPreview();
+    return;
+  }
+
   // Merge stored settings (config.json + keystore) into env before running
   await applyStoredSettings();
 
@@ -156,6 +184,7 @@ INVOCATION METHODS
 
   const project = resolveProjectName(projectArg);
   const forceRestart = hasFlag('--force');
+  const fullRun = hasFlag('--full-run');
   const storyFile = getArg('--story-file');
 
   await ensureProject(project);
@@ -173,7 +202,17 @@ INVOCATION METHODS
   }
 
   const job = createJob({ story, project });
-  const result = await runPipeline(job.id, { forceRestart });
+  const result = await runPipeline(job.id, { forceRestart, pauseAfterKeyframes: !fullRun });
+
+  if (result.status === 'paused') {
+    console.log(JSON.stringify({
+      jobId: result.id,
+      project,
+      status: 'paused',
+      message: `Keyframes generated. Review assets in projects/${project}/assets/, then run again to continue to video generation.`
+    }, null, 2));
+    return;
+  }
 
   if (result.status !== 'completed') {
     throw new Error(`Generation failed: ${result.error || 'unknown error'}`);

package/src/pipeline/orchestrator.js

@@ -571,9 +571,10 @@ export async function regenerateProjectAsset(projectName, target, options = {})
   }
 
   const updatedAt = new Date().toISOString();
+  const nextStatus = targetType === 'keyframe' ? JobStatus.PAUSED : (runState.status || JobStatus.COMPLETED);
   await deps.persistArtifacts(project, artifacts);
   await deps.writeProjectRunState(project, {
-    status: runState.status || JobStatus.COMPLETED,
+    status: nextStatus,
     error: runState.error || null,
     steps,
     artifacts,
@@ -629,6 +630,9 @@ export async function runPipeline(jobId, options = {}) {
     const projectDir = deps.getProjectDir(project);
     const targetDurationSec = resolveTargetDurationSec(projectConfig);
     const plannedShots = resolveShotCount(projectConfig);
+    const shouldPause = options.pauseAfterKeyframes !== undefined
+      ? Boolean(options.pauseAfterKeyframes)
+      : Boolean(projectConfig.pauseAfterKeyframes);
     const safeStory = deps.preprocessStory(job.payload.story);
     analyticsProjectDir = projectDir;
     const analyticsRunId = deps.createRunId();
@@ -1326,6 +1330,12 @@ export async function runPipeline(jobId, options = {}) {
       await finishStageAnalytics(JobStep.KEYFRAMES, { executed: true, status: 'succeeded', details: { mode: 'partial_regen', changedShots: changed } });
       await finishStageAnalytics(JobStep.SEGMENTS, { executed: true, status: 'succeeded', details: { mode: 'partial_regen' } });
       currentJob = getJob(jobId);
+
+      if (shouldPause) {
+        const paused = updateJob(jobId, { status: JobStatus.PAUSED });
+        await persistCheckpoint(paused, null, deps);
+        return paused;
+      }
     }
 
     if (!currentJob.steps[JobStep.KEYFRAMES]) {
@@ -1387,6 +1397,12 @@ export async function runPipeline(jobId, options = {}) {
       await persistCheckpoint(getJob(jobId), null, deps);
       await finishStageAnalytics(JobStep.KEYFRAMES, { executed: true, status: 'succeeded' });
       currentJob = getJob(jobId);
+
+      if (shouldPause) {
+        const paused = updateJob(jobId, { status: JobStatus.PAUSED });
+        await persistCheckpoint(paused, null, deps);
+        return paused;
+      }
     } else if (
       currentJob.artifacts.keyframeUrls.length > 0 &&
       (!currentJob.artifacts.keyframePaths || currentJob.artifacts.keyframePaths.length === 0)

package/src/store/projectStore.js

@@ -53,6 +53,7 @@ export const DEFAULT_PROJECT_CONFIG = {
   aspectRatio: '9:16',
   targetDurationSec: DEFAULT_VIDEO_CONFIG.durationSec,
   finalDurationMode: 'match_audio',
+  pauseAfterKeyframes: true,
   subtitleOptions: {
     ...DEFAULT_SUBTITLE_OPTIONS
   },
@@ -513,6 +514,10 @@ export function validateProjectConfig(config) {
 
   validateSubtitleOptions(config.subtitleOptions);
 
+  if (typeof config.pauseAfterKeyframes !== 'boolean') {
+    throw new Error('Invalid project config: pauseAfterKeyframes must be a boolean');
+  }
+
   const hasWidth = config.keyframeWidth !== undefined;
   const hasHeight = config.keyframeHeight !== undefined;
   if (hasWidth !== hasHeight) {

package/src/types/job.js

@@ -2,7 +2,8 @@ export const JobStatus = {
   PENDING: 'pending',
   RUNNING: 'running',
   FAILED: 'failed',
-  COMPLETED: 'completed'
+  COMPLETED: 'completed',
+  PAUSED: 'paused'
 };
 
 export const JobStep = {