@archastro/astroshot 0.1.0 → 0.2.1

package/README.md

@@ -1,23 +1,63 @@
 # `@archastro/astroshot`
 
-One command for deterministic React, Ink, and arbitrary terminal screenshots.
+One command for deterministic React, Ink, and arbitrary terminal screenshots —
+plus **journey movies** into `.astroshot/`.
+
+## Start here (no prerequisites)
+
+```bash
+# Write a real .astroshot/ set: stills + movie poster/video + manifest.json.
+# No Chromium download, no assets of your own; works with the app closed.
+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
+```
+
+`demo` accepts `--feature <name>`, `--root <dir>`, and `--json`. `doctor`
+accepts `--root <dir>`, `--json`, and `--skip-screen`, and exits non-zero when a
+required check fails. Watched-folder coverage comes from the Astroshots app's
+own live configuration, so an "empty tray" resolves to one of: first-launch
+setup never completed, this project is outside every watched folder, or the
+project is watched and the problem is elsewhere.
+
+## Capture
 
 ```bash
-npx --@archastro:registry=https://registry.npmjs.org \
-  @archastro/astroshot init react
-npx --@archastro:registry=https://registry.npmjs.org \
-  @archastro/astroshot init ink
-npx --@archastro:registry=https://registry.npmjs.org \
-  @archastro/astroshot init pty
-
-npx --@archastro:registry=https://registry.npmjs.org \
-  @archastro/astroshot react ./react.shot.tsx -o ./react.png
-npx --@archastro:registry=https://registry.npmjs.org \
-  @archastro/astroshot ink ./ink.shot.tsx -o ./ink.png
-npx --@archastro:registry=https://registry.npmjs.org \
-  @archastro/astroshot pty ./pty.shot.yaml -o ./terminal.png
+npx astroshot init react
+npx astroshot init ink
+npx astroshot init pty
+
+npx astroshot react ./react.shot.tsx -o ./react.png
+npx astroshot ink ./ink.shot.tsx -o ./ink.png
+npx astroshot pty ./pty.shot.yaml -o ./terminal.png
 ```
 
+## Movies (`astroshot movie`)
+
+Same binary. Agents: **run `astroshot movie which-source "…"` first**.
+
+| You need to record… | `--source` |
+|---------------------|------------|
+| Web / SPA / agent-browser | `browser` |
+| TUI / CLI / truecolor terminal | `pty` (never desktop of Terminal.app) |
+| Native macOS app window | `desktop.window` |
+| Your own PNG sequence | `frames` |
+
+```bash
+astroshot movie --help
+astroshot movie which-source "ratatui truecolor dashboard"
+astroshot movie run --source browser --feature web --slug home --url https://example.com
+astroshot movie run --source desktop.window --feature app --slug onboard \
+  --bundle-id com.example.App --duration-ms 4000
+astroshot movie list-windows   # macOS
+```
+
+`desktop.window` uses macOS `/usr/sbin/screencapture` (already on the system)
+plus a Swift window list shipped in the package — no separate capture binary
+download. Requires Screen Recording permission for your terminal/IDE.
+
 Use `react` for isolated browser components, `ink` for in-process Ink fixture
 trees, and `pty` for executable terminal applications such as Ratatui, Bubble
 Tea, Textual, and curses programs. `tui` remains an alias for `ink` for
@@ -32,8 +72,7 @@ npm install --save-dev ink@^7.1 react@^19
 Install the shared Chromium runtime once:
 
 ```bash
-npx --@archastro:registry=https://registry.npmjs.org \
-  @archastro/astroshot install-browser
+npx astroshot install-browser
 ```
 
 Use `react batch <manifest>` or `ink batch <manifest>` for maintained fixture

package/bin/astroshot.mjs

@@ -6,11 +6,15 @@ import { fileURLToPath } from "node:url";
 import path from "node:path";
 
 import { writeFixtureTemplate } from "./templates.mjs";
+import { demoHelp, runDemo } from "./demo.mjs";
+import { doctorHelp, runDoctor } from "./doctor.mjs";
 
 function help() {
-  console.log(`astroshot — one CLI for React, Ink, and PTY screenshots
+  console.log(`astroshot — one CLI for React, Ink, PTY stills, and movies
 
 Usage:
+  astroshot demo [--feature <name>] [--root <dir>]
+  astroshot doctor [--root <dir>] [--json]
   astroshot init react [fixture.tsx] [--force]
   astroshot init ink [fixture.tsx] [--force]
   astroshot init pty [fixture.yaml] [--force]
@@ -20,15 +24,27 @@ Usage:
   astroshot ink <fixture.tsx> -o <out.png> [options]
   astroshot ink batch <manifest.yaml|json> [options]
   astroshot pty <fixture.yaml|json> -o <out.png> [options]
+  astroshot movie <command> [options]
   astroshot install-browser [--with-deps]
 
+Start here:
+  demo               Write a complete .astroshot/ example set (no prerequisites)
+  doctor             Check Node, watched folders, app, Chromium, permissions
+
 Commands:
-  react              Capture an isolated React component
-  ink                Capture an Ink component fixture
-  pty                Capture any executable in a pseudoterminal
+  react              Capture an isolated React component (still PNG)
+  ink                Capture an Ink component fixture (still PNG)
+  pty                Capture any executable in a pseudoterminal (still PNG)
+  movie              Record a journey movie into .astroshot/ (poster + video)
   init               Generate a React, Ink, or PTY fixture template
   install-browser    Install the shared Chromium runtime
 
+Movie sources (see "astroshot movie which-source"):
+  browser            Web / agent-browser / Playwright viewport
+  pty                Truecolor TUI/CLI (never screenshot Terminal.app)
+  desktop.window     Native macOS app window (uses OS screencapture)
+  frames             Push your own PNG/JPEG sequence
+
 Compatibility: "astroshot tui" remains an alias for "astroshot ink".
 Run "astroshot <mode> --help" for mode options.`);
 }
@@ -88,6 +104,12 @@ Options:
 }
 
 function engineBin(mode) {
+  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
+    const packageRoot = path.dirname(path.dirname(entry));
+    return path.join(packageRoot, "bin", "astroshot-movie.mjs");
+  }
   const packageName =
     mode === "react" ? "@archastro/react-shot" : "@archastro/tui-shot";
   const executable = mode === "react" ? "react-shot.mjs" : "tui-shot.mjs";
@@ -182,6 +204,28 @@ if (!command || command === "help" || command === "-h" || command === "--help")
   process.exit(command ? 0 : 1);
 }
 
+if (command === "demo") {
+  try {
+    process.exit(runDemo(arguments_));
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : error);
+    console.error("");
+    console.error(demoHelp());
+    process.exit(1);
+  }
+}
+
+if (command === "doctor") {
+  try {
+    process.exit(runDoctor(arguments_));
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : error);
+    console.error("");
+    console.error(doctorHelp());
+    process.exit(1);
+  }
+}
+
 if (command === "install-browser") {
   runEngine("react", ["install-browser", ...arguments_]);
 }
@@ -210,6 +254,23 @@ if (command === "react" || command === "ink" || command === "tui" || command ===
   runEngine(canonicalMode, arguments_);
 }
 
+if (command === "movie") {
+  // Always forward to movie-harness (including --help / which-source).
+  const result = spawnSync(
+    process.execPath,
+    [engineBin("movie"), ...arguments_],
+    { stdio: "inherit" },
+  );
+  if (result.error) {
+    console.error(
+      `astroshot could not start movie harness: ${result.error.message}`,
+    );
+    process.exit(1);
+  }
+  if (result.signal) process.kill(process.pid, result.signal);
+  process.exit(result.status ?? 1);
+}
+
 console.error(`Unknown command: ${command}`);
 help();
 process.exit(1);

package/bin/demo.mjs

@@ -0,0 +1,275 @@
+/**
+ * `astroshot demo` — seed a real .astroshot/<feature>/ set with zero
+ * prerequisites.
+ *
+ * The payload is bundled PNG/WebM bytes under fixtures/demo/, so this command
+ * needs no managed Chromium, no ffmpeg, and no user-supplied assets. It only
+ * writes files, so it also works while the macOS app is closed; the caller is
+ * told where to look.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+import {
+  evaluateWatchCoverage,
+  readWatchConfiguration,
+} from "./mac-preferences.mjs";
+
+const FIXTURES_DIR = fileURLToPath(new URL("../fixtures/demo/", import.meta.url));
+export const DEFAULT_DEMO_FEATURE = "astroshot-demo";
+
+export function demoHelp() {
+  return `astroshot demo — write a complete .astroshot/ example set (no prerequisites)
+
+Usage:
+  astroshot demo [options]
+
+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
+  -h, --help         Show this help
+
+Writes two stills, one movie poster + video pair, and manifest.json using
+bundled fixtures. No Chromium download, no ffmpeg, no assets of your own.
+Re-running starts a fresh run and appends new numbered frames.
+
+After it runs, open the Astroshots menu-bar icon → Shots. If nothing appears,
+run "astroshot doctor".`;
+}
+
+function resolveRoot(explicitRoot) {
+  if (explicitRoot) return path.resolve(explicitRoot);
+  try {
+    return execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return process.cwd();
+  }
+}
+
+function assertKebabCase(value, label) {
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(value)) {
+    throw new Error(
+      `${label} must be kebab-case [a-z0-9-]+, got ${JSON.stringify(value)}`,
+    );
+  }
+}
+
+function nextSequence(featureDirectory) {
+  let max = 0;
+  const entries = fs.existsSync(featureDirectory)
+    ? fs.readdirSync(featureDirectory)
+    : [];
+  for (const name of entries) {
+    const match = /^(\d{4})-/.exec(name);
+    if (match) max = Math.max(max, Number(match[1]));
+  }
+  return max + 1;
+}
+
+function writeAtomic(filePath, contents) {
+  const temporary = path.join(
+    path.dirname(filePath),
+    `.${path.basename(filePath)}.tmp.${process.pid}.${Date.now()}`,
+  );
+  fs.writeFileSync(temporary, contents);
+  fs.renameSync(temporary, filePath);
+}
+
+function copyAtomic(source, destination) {
+  const temporary = path.join(
+    path.dirname(destination),
+    `.${path.basename(destination)}.tmp.${process.pid}.${Date.now()}`,
+  );
+  fs.copyFileSync(source, temporary);
+  fs.renameSync(temporary, destination);
+}
+
+export function loadDemoFixtures(fixturesDirectory = FIXTURES_DIR) {
+  const indexPath = path.join(fixturesDirectory, "fixtures.json");
+  if (!fs.existsSync(indexPath)) {
+    throw new Error(
+      `bundled demo fixtures are missing at ${fixturesDirectory}. Reinstall @archastro/astroshot.`,
+    );
+  }
+  const index = JSON.parse(fs.readFileSync(indexPath, "utf8"));
+  if (!Array.isArray(index.shots) || index.shots.length === 0) {
+    throw new Error(`bundled demo fixtures are empty: ${indexPath}`);
+  }
+  for (const shot of index.shots) {
+    for (const asset of [shot.asset, shot.video].filter(Boolean)) {
+      const assetPath = path.join(fixturesDirectory, asset);
+      if (!fs.existsSync(assetPath)) {
+        throw new Error(`bundled demo asset is missing: ${assetPath}`);
+      }
+    }
+  }
+  return index;
+}
+
+/**
+ * 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({
+  root,
+  feature = DEFAULT_DEMO_FEATURE,
+  fixturesDirectory = FIXTURES_DIR,
+  now = new Date(),
+} = {}) {
+  assertKebabCase(feature, "feature");
+  const resolvedRoot = resolveRoot(root);
+  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
+  // the same second from the same process.
+  const runId = `${feature}-${stamp}-${process.pid}-${String(startSequence).padStart(4, "0")}`;
+  const capturedAt = now.toISOString();
+
+  const shots = [];
+  const files = [];
+  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 shot = {
+      id: sequence,
+      file: posterName,
+      slug: fixture.slug,
+      title: fixture.title,
+      description: fixture.description,
+      captured_at: capturedAt,
+      viewport: index.viewport,
+    };
+
+    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));
+      shot.kind = "movie";
+      shot.video = videoName;
+      shot.duration_ms = fixture.duration_ms;
+      shot.source = fixture.source ?? "frames";
+      if (Array.isArray(fixture.chapters)) shot.chapters = fixture.chapters;
+    }
+
+    shots.push(shot);
+  });
+
+  const manifestPath = path.join(featureDirectory, "manifest.json");
+  const manifest = {
+    version: 1,
+    feature,
+    run_id: runId,
+    status: "pass",
+    description:
+      "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 {
+    root: resolvedRoot,
+    feature,
+    featureDirectory,
+    manifestPath,
+    runId,
+    shots,
+    files,
+  };
+}
+
+function coverageAdvice(root) {
+  const configuration = readWatchConfiguration();
+  const coverage = evaluateWatchCoverage(root, configuration);
+  switch (coverage.state) {
+    case "inside-root":
+      return [
+        `Watched by Astroshots via ${coverage.matchedRoot}.`,
+        "Open the Astroshots menu-bar icon → Shots to see these frames.",
+      ];
+    case "setup-incomplete":
+      return [
+        "Astroshots has no watched folders yet, so it will not pick these up.",
+        "Fix: open Astroshots and choose a folder, or menu-bar icon → gear → Add folders…",
+        "Then re-check with: astroshot doctor",
+      ];
+    case "outside-roots":
+      return [
+        `This project is outside every watched folder (${coverage.roots.join(", ")}).`,
+        "Fix: Astroshots menu-bar icon → gear → Add folders… and add a parent of this project.",
+        "Then re-check with: astroshot doctor",
+      ];
+    case "unsupported":
+      return [
+        "The Astroshots app is macOS-only; the files above still follow the .astroshot contract.",
+      ];
+    default:
+      // Unknown — do not claim the user has no watched folders.
+      return [
+        "Could not read Astroshots' watched folders, so whether this project is",
+        "watched is unknown (the files above were still written correctly).",
+        "Check with: astroshot doctor",
+      ];
+  }
+}
+
+export function runDemo(argv, { log = console.log } = {}) {
+  const options = { feature: DEFAULT_DEMO_FEATURE, root: undefined, json: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === "-h" || token === "--help" || token === "help") {
+      log(demoHelp());
+      return 0;
+    }
+    if (token === "--json") {
+      options.json = true;
+      continue;
+    }
+    if (token === "--feature" || token === "--root") {
+      const value = argv[index + 1];
+      if (!value || value.startsWith("-")) {
+        throw new Error(`${token} requires a value`);
+      }
+      options[token === "--feature" ? "feature" : "root"] = value;
+      index += 1;
+      continue;
+    }
+    throw new Error(`Unknown demo argument: ${token}`);
+  }
+
+  const result = 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)}`);
+  }
+  log("");
+  log(
+    `Wrote ${stills} still${stills === 1 ? "" : "s"}, ${movies} movie${movies === 1 ? "" : "s"} (poster + video), and manifest.json.`,
+  );
+  for (const line of coverageAdvice(result.root)) log(line);
+  return 0;
+}