@archastro/astroshot 0.2.1 → 0.2.2

package/README.md

@@ -13,6 +13,10 @@ npx astroshot demo
 # Check Node, watched folders, app install/run state, Chromium, and macOS
 # Screen Recording. Each failure prints the exact fix command. Read-only.
 npx astroshot doctor
+
+# Review the stream in your terminal (Ghostty, kitty, or WezTerm draw the
+# pictures; ffmpeg plays movies). Same review.json as the macOS app.
+npx astroshot review
 ```
 
 `demo` accepts `--feature <name>`, `--root <dir>`, and `--json`. `doctor`

package/bin/astroshot.mjs

@@ -8,12 +8,14 @@ import path from "node:path";
 import { writeFixtureTemplate } from "./templates.mjs";
 import { demoHelp, runDemo } from "./demo.mjs";
 import { doctorHelp, runDoctor } from "./doctor.mjs";
+import { readWatchConfiguration } from "./mac-preferences.mjs";
 
 function help() {
   console.log(`astroshot — one CLI for React, Ink, PTY stills, and movies
 
 Usage:
-  astroshot demo [--feature <name>] [--root <dir>]
+  astroshot review [<dir>...] [--root <dir>] [--no-graphics]
+  astroshot demo [--feature <name>] [--root <dir>] [--dry-run] [--clean]
   astroshot doctor [--root <dir>] [--json]
   astroshot init react [fixture.tsx] [--force]
   astroshot init ink [fixture.tsx] [--force]
@@ -28,6 +30,7 @@ Usage:
   astroshot install-browser [--with-deps]
 
 Start here:
+  review             Review the .astroshot/ stream in your terminal (Kitty graphics)
   demo               Write a complete .astroshot/ example set (no prerequisites)
   doctor             Check Node, watched folders, app, Chromium, permissions
 
@@ -104,6 +107,11 @@ Options:
 }
 
 function engineBin(mode) {
+  if (mode === "review") {
+    const entry = fileURLToPath(import.meta.resolve("@archastro/astroshot-review"));
+    const packageRoot = path.dirname(path.dirname(entry));
+    return path.join(packageRoot, "bin", "astroshot-review.mjs");
+  }
   if (mode === "movie") {
     const entry = fileURLToPath(import.meta.resolve("@archastro/movie-harness"));
     // package exports "." → dist/index.js → package root is two levels up from dist
@@ -189,6 +197,49 @@ function runInit(arguments_) {
   console.log(`Created ${result.label} fixture: ${result.absolutePath}`);
 }
 
+/**
+ * `astroshot review`: the terminal tray. Without explicit roots it watches
+ * the same folders as the Astroshots app so both surfaces show one stream.
+ */
+function runReview(arguments_) {
+  // `astroshot review help` mirrors the other modes; anything else is
+  // forwarded verbatim so a folder literally named "help" still works.
+  const wantsHelp =
+    arguments_[0] === "help" ||
+    arguments_.includes("-h") ||
+    arguments_.includes("--help");
+  const forwarded = wantsHelp ? ["--help"] : [...arguments_];
+  const hasRoots =
+    forwarded.includes("--root") ||
+    forwarded.some((value) => !value.startsWith("-"));
+  if (!hasRoots && !wantsHelp) {
+    const configuration = readWatchConfiguration();
+    if (configuration.available && configuration.roots.length > 0) {
+      for (const root of configuration.roots) forwarded.push("--root", root);
+      forwarded.push("--roots-source", "app");
+    }
+  }
+  let engine;
+  try {
+    engine = engineBin("review");
+  } catch (error) {
+    console.error(
+      `astroshot could not find the review tray engine (@archastro/astroshot-review): ${error instanceof Error ? error.message : error}`,
+    );
+    console.error("Reinstall @archastro/astroshot (or the unscoped astroshot package) and retry.");
+    process.exit(1);
+  }
+  const result = spawnSync(process.execPath, [engine, ...forwarded], {
+    stdio: "inherit",
+  });
+  if (result.error) {
+    console.error(`astroshot could not start the review tray: ${result.error.message}`);
+    process.exit(1);
+  }
+  if (result.signal) process.kill(process.pid, result.signal);
+  process.exit(result.status ?? 1);
+}
+
 const [command, ...arguments_] = process.argv.slice(2);
 
 if (command === "-v" || command === "--version") {
@@ -254,6 +305,10 @@ if (command === "react" || command === "ink" || command === "tui" || command ===
   runEngine(canonicalMode, arguments_);
 }
 
+if (command === "review" || command === "tray") {
+  runReview(arguments_);
+}
+
 if (command === "movie") {
   // Always forward to movie-harness (including --help / which-source).
   const result = spawnSync(

package/bin/demo.mjs

@@ -30,6 +30,8 @@ Options:
   --feature <name>   Feature directory under .astroshot/ (default: ${DEFAULT_DEMO_FEATURE})
   --root <dir>       Worktree root (default: git root, else cwd)
   --json             Print the written paths as JSON
+  --dry-run          Print planned paths without writing
+  --clean            Accepted; does not delete yet
   -h, --help         Show this help
 
 Writes two stills, one movie poster + video pair, and manifest.json using
@@ -112,14 +114,24 @@ export function loadDemoFixtures(fixturesDirectory = FIXTURES_DIR) {
   return index;
 }
 
+function publicDemoResult(plan) {
+  return {
+    root: plan.root,
+    feature: plan.feature,
+    featureDirectory: plan.featureDirectory,
+    manifestPath: plan.manifestPath,
+    runId: plan.runId,
+    shots: plan.shots,
+    files: plan.files,
+  };
+}
+
 /**
- * Write the demo set and return the paths, without printing anything.
- *
- * Each invocation is its own run: a new `run_id` with a fresh shot list, while
- * earlier numbered frames stay on disk as prior-run evidence. That matches the
- * documented lifecycle used by astroshot-capture and the movie harness.
+ * Read-only plan of the next demo write: same root/feature resolve, kebab-case
+ * check, fixtures, next sequence, and file names (including manifest.json).
+ * Does not mkdir or write.
  */
-export function writeDemo({
+export function planDemo({
   root,
   feature = DEFAULT_DEMO_FEATURE,
   fixturesDirectory = FIXTURES_DIR,
@@ -130,7 +142,6 @@ export function writeDemo({
   const featureDirectory = path.join(resolvedRoot, ".astroshot", feature);
   const index = loadDemoFixtures(fixturesDirectory);
 
-  fs.mkdirSync(featureDirectory, { recursive: true });
   const startSequence = nextSequence(featureDirectory);
   const stamp = now.toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z");
   // The first sequence of this run keeps the id unique when two runs land in
@@ -140,11 +151,16 @@ export function writeDemo({
 
   const shots = [];
   const files = [];
+  const copies = [];
   index.shots.forEach((fixture, offset) => {
     const sequence = String(startSequence + offset).padStart(4, "0");
     const posterName = `${sequence}-${fixture.slug}.png`;
-    copyAtomic(path.join(fixturesDirectory, fixture.asset), path.join(featureDirectory, posterName));
-    files.push(path.join(featureDirectory, posterName));
+    const posterPath = path.join(featureDirectory, posterName);
+    copies.push({
+      source: path.join(fixturesDirectory, fixture.asset),
+      destination: posterPath,
+    });
+    files.push(posterPath);
 
     const shot = {
       id: sequence,
@@ -159,8 +175,12 @@ export function writeDemo({
     if (fixture.video) {
       const videoExtension = path.extname(fixture.video) || ".webm";
       const videoName = `${sequence}-${fixture.slug}${videoExtension}`;
-      copyAtomic(path.join(fixturesDirectory, fixture.video), path.join(featureDirectory, videoName));
-      files.push(path.join(featureDirectory, videoName));
+      const videoPath = path.join(featureDirectory, videoName);
+      copies.push({
+        source: path.join(fixturesDirectory, fixture.video),
+        destination: videoPath,
+      });
+      files.push(videoPath);
       shot.kind = "movie";
       shot.video = videoName;
       shot.duration_ms = fixture.duration_ms;
@@ -181,7 +201,6 @@ export function writeDemo({
       "Synthetic proof set written by `astroshot demo` — stills plus one journey movie.",
     shots,
   };
-  writeAtomic(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
   files.push(manifestPath);
 
   return {
@@ -189,12 +208,31 @@ export function writeDemo({
     feature,
     featureDirectory,
     manifestPath,
+    manifest,
     runId,
     shots,
     files,
+    copies,
   };
 }
 
+/**
+ * Write the demo set and return the paths, without printing anything.
+ *
+ * Each invocation is its own run: a new `run_id` with a fresh shot list, while
+ * earlier numbered frames stay on disk as prior-run evidence. That matches the
+ * documented lifecycle used by astroshot-capture and the movie harness.
+ */
+export function writeDemo(options = {}) {
+  const plan = planDemo(options);
+  fs.mkdirSync(plan.featureDirectory, { recursive: true });
+  for (const { source, destination } of plan.copies) {
+    copyAtomic(source, destination);
+  }
+  writeAtomic(plan.manifestPath, `${JSON.stringify(plan.manifest, null, 2)}\n`);
+  return publicDemoResult(plan);
+}
+
 function coverageAdvice(root) {
   const configuration = readWatchConfiguration();
   const coverage = evaluateWatchCoverage(root, configuration);
@@ -231,7 +269,13 @@ function coverageAdvice(root) {
 }
 
 export function runDemo(argv, { log = console.log } = {}) {
-  const options = { feature: DEFAULT_DEMO_FEATURE, root: undefined, json: false };
+  const options = {
+    feature: DEFAULT_DEMO_FEATURE,
+    root: undefined,
+    json: false,
+    dryRun: false,
+    clean: false,
+  };
   for (let index = 0; index < argv.length; index += 1) {
     const token = argv[index];
     if (token === "-h" || token === "--help" || token === "help") {
@@ -242,6 +286,14 @@ export function runDemo(argv, { log = console.log } = {}) {
       options.json = true;
       continue;
     }
+    if (token === "--dry-run") {
+      options.dryRun = true;
+      continue;
+    }
+    if (token === "--clean") {
+      options.clean = true;
+      continue;
+    }
     if (token === "--feature" || token === "--root") {
       const value = argv[index + 1];
       if (!value || value.startsWith("-")) {
@@ -254,18 +306,22 @@ export function runDemo(argv, { log = console.log } = {}) {
     throw new Error(`Unknown demo argument: ${token}`);
   }
 
-  const result = writeDemo(options);
+  const result = options.dryRun
+    ? publicDemoResult(planDemo(options))
+    : writeDemo(options);
   if (options.json) {
     log(JSON.stringify({ ...result, advice: coverageAdvice(result.root) }, null, 2));
     return 0;
   }
 
-  const movies = result.shots.filter((shot) => shot.kind === "movie").length;
-  const stills = result.shots.length - movies;
   log(`astroshot demo → ${result.featureDirectory}`);
   for (const file of result.files) {
     log(`  ${path.relative(result.root, file)}`);
   }
+  if (options.dryRun) return 0;
+
+  const movies = result.shots.filter((shot) => shot.kind === "movie").length;
+  const stills = result.shots.length - movies;
   log("");
   log(
     `Wrote ${stills} still${stills === 1 ? "" : "s"}, ${movies} movie${movies === 1 ? "" : "s"} (poster + video), and manifest.json.`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@archastro/astroshot",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "One CLI for deterministic React, terminal, and movie UI captures",
   "keywords": [
     "react",
@@ -72,8 +72,9 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@archastro/movie-harness": "0.2.1",
-    "@archastro/react-shot": "0.2.1",
-    "@archastro/tui-shot": "0.2.1"
+    "@archastro/astroshot-review": "0.2.2",
+    "@archastro/movie-harness": "0.2.2",
+    "@archastro/react-shot": "0.2.2",
+    "@archastro/tui-shot": "0.2.2"
   }
 }