astroshot 0.2.1

package/README.md

@@ -0,0 +1,87 @@
+# `astroshot`
+
+One command for deterministic React, Ink, and arbitrary terminal screenshots —
+plus **journey movies** into `.astroshot/`.
+
+```bash
+npx astroshot --help
+npx astroshot init react
+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
+npx astroshot movie which-source "ratatui truecolor dashboard"
+```
+
+No registry flags, no scope configuration, no `--registry` override.
+
+## What this package is
+
+`astroshot` is the public, unscoped entry point for
+[`@archastro/astroshot`](https://www.npmjs.com/package/@archastro/astroshot).
+It ships the unified CLI and all three capture engines
+(`@archastro/react-shot`, `@archastro/tui-shot`, `@archastro/movie-harness`)
+*inside its own tarball* using npm `bundleDependencies`.
+
+That matters because many developers have a `~/.npmrc` that maps the whole
+`@archastro` scope to a private registry:
+
+```
+@archastro:registry=https://npm.pkg.github.com
+```
+
+With that config, `npx @archastro/astroshot` fails with **E404** — npm never
+asks the public registry for the package at all. Because this package bundles
+everything scoped, nothing scoped is fetched at install time, so a plain
+`npx astroshot` works regardless of scope configuration.
+
+The scoped packages remain fully supported and unchanged; use them directly if
+you prefer, or if you already have the scope pointed at the public registry.
+
+## Install
+
+```bash
+# one-off
+npx astroshot --help
+
+# project dev dependency
+npm install --save-dev astroshot
+```
+
+Install the shared Chromium runtime once before browser-backed captures:
+
+```bash
+npx astroshot install-browser
+```
+
+On Linux CI images that also need Chromium's system libraries, add
+`--with-deps`.
+
+## Peer dependencies you supply
+
+This package deliberately does **not** pin your framework versions. Install the
+peers for the modes you use:
+
+| Mode | Peers |
+|------|-------|
+| `astroshot react` | `react`, `react-dom` (>=18) |
+| `astroshot ink` | `ink@^7.1`, `react@^19` |
+| `astroshot pty`, `astroshot movie` | none |
+
+```bash
+npm install --save-dev ink@^7.1 react@^19
+```
+
+`node-pty` is an **optional** dependency. PTY and movie-PTY capture need it;
+every other mode works without it, so an environment that cannot build the
+native addon still installs successfully.
+
+## Documentation
+
+Full fixture APIs, the PTY action contract, manifest formats, and movie sources
+are documented in the
+[repository README](https://github.com/ArchAstro/astroshots#readme) and in
+[`@archastro/astroshot`](https://www.npmjs.com/package/@archastro/astroshot).
+
+Fixtures, imported modules, and PTY commands execute with the current user's
+permissions. Review untrusted files before capture and never include
+credentials or private customer data in fixtures or generated images.

package/bin/astroshot.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * Unscoped `astroshot` entry point.
+ *
+ * This package exists so `npx astroshot ...` works with no registry flags. The
+ * @archastro packages ship *inside* this tarball through bundleDependencies, so
+ * a developer whose ~/.npmrc maps @archastro to a private registry can still
+ * install and run the CLI. See docs/UNSCOPED-CLI-DESIGN.md.
+ *
+ * The only job of this file is to hand every argument to the real CLI and
+ * faithfully return its stdout, stderr, exit code, and terminating signal.
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const CLI_RELATIVE_PATH = path.join(
+  "@archastro",
+  "astroshot",
+  "bin",
+  "astroshot.mjs",
+);
+
+/**
+ * Look for the bundled CLI next to this package first (the published layout
+ * puts it in ./node_modules), then walk up through parent node_modules
+ * directories so the workspace checkout resolves its symlinked sibling.
+ */
+function resolveCli() {
+  const searched = [];
+  let directory = packageRoot;
+  for (;;) {
+    const candidate = path.join(directory, "node_modules", CLI_RELATIVE_PATH);
+    searched.push(candidate);
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(directory);
+    if (parent === directory) break;
+    directory = parent;
+  }
+  return { searched };
+}
+
+const cli = resolveCli();
+if (typeof cli !== "string") {
+  console.error(
+    "astroshot: the bundled @archastro/astroshot CLI is missing from this " +
+      "installation. Reinstall with `npm install astroshot`.\nLooked in:\n" +
+      cli.searched.map((entry) => `  ${entry}`).join("\n"),
+  );
+  process.exit(1);
+}
+
+// stdio: "inherit" hands the real file descriptors to the CLI, so stdout and
+// stderr stay unbuffered, interleaved, and TTY-aware exactly as if the user had
+// run @archastro/astroshot directly.
+const result = spawnSync(process.execPath, [cli, ...process.argv.slice(2)], {
+  stdio: "inherit",
+});
+
+if (result.error) {
+  console.error(`astroshot could not start the CLI: ${result.error.message}`);
+  process.exit(1);
+}
+// Re-raise the child's signal so `kill`/Ctrl-C semantics survive the hop.
+if (result.signal) {
+  process.kill(process.pid, result.signal);
+}
+process.exit(result.status ?? 1);

package/node_modules/@archastro/astroshot/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ArchAstro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/node_modules/@archastro/astroshot/README.md

@@ -0,0 +1,96 @@
+# `@archastro/astroshot`
+
+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 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
+compatibility.
+
+Ink fixtures require project-local peers:
+
+```bash
+npm install --save-dev ink@^7.1 react@^19
+```
+
+Install the shared Chromium runtime once:
+
+```bash
+npx astroshot install-browser
+```
+
+Use `react batch <manifest>` or `ink batch <manifest>` for maintained fixture
+sets. Run `<mode> --help` for mode-specific options.
+
+Fixture types are available from the unified package:
+
+```tsx
+import type { ReactShotFixture } from "@archastro/astroshot/react";
+import type { InkShotFixture } from "@archastro/astroshot/ink";
+```
+
+PTY YAML and JSON files launch `command` directly, without a shell. Their
+`actions` can wait for visible text, send named keys or literal text, and
+pause for bounded durations. Paths in `cwd` are relative to the fixture.
+On Windows, point `command` at an `.exe`; `.cmd` and `.bat` files are rejected
+because running them would introduce an implicit shell.
+
+Fixtures, imported modules, and PTY commands execute with the current user's
+permissions. Review untrusted files before capture and never include
+credentials or private customer data in fixtures or generated images.

package/node_modules/@archastro/astroshot/bin/astroshot.mjs

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+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, 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]
+  astroshot react <fixture.tsx> -o <out.png> [options]
+  astroshot react shot <fixture.tsx> -o <out.png> [options]
+  astroshot react batch <manifest.yaml|json> [options]
+  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 (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.`);
+}
+
+function modeHelp(mode) {
+  if (mode === "react") {
+    console.log(`astroshot react — deterministic React component screenshots
+
+Usage:
+  astroshot init react [fixture.tsx] [--force]
+  astroshot react <fixture.tsx> -o <out.png> [options]
+  astroshot react batch <manifest.yaml|json> [options]
+
+Options:
+  -o, --out <path>       Output PNG path
+  --root <dir>           Package root for imports and aliases
+  --config <path>        Fixture configuration path
+  --width <px>           Override viewport width
+  --height <px>          Override viewport height
+  --headed               Show Chromium for debugging
+  -h, --help             Show this help`);
+    return;
+  }
+
+  if (mode === "ink") {
+    console.log(`astroshot ink — deterministic Ink component screenshots
+
+Usage:
+  astroshot init ink [fixture.tsx] [--force]
+  astroshot ink <fixture.tsx> -o <out.png> [options]
+  astroshot ink batch <manifest.yaml|json> [options]
+
+Options:
+  -o, --out <path>       Output PNG path
+  --cols <count>         Override terminal columns
+  --rows <count>         Override terminal rows
+  --scale <factor>       Override PNG device scale factor
+  --out-dir <path>       Override batch output directory
+  --headed               Show Chromium for debugging
+  -h, --help             Show this help`);
+    return;
+  }
+
+  console.log(`astroshot pty — screenshots of arbitrary terminal programs
+
+Usage:
+  astroshot init pty [fixture.yaml] [--force]
+  astroshot pty <fixture.yaml|json> -o <out.png> [options]
+
+Options:
+  -o, --out <path>       Output PNG path
+  --cols <count>         Override terminal columns
+  --rows <count>         Override terminal rows
+  --scale <factor>       Override PNG device scale factor
+  --headed               Show Chromium for debugging
+  -h, --help             Show this help`);
+}
+
+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";
+  const entry = fileURLToPath(import.meta.resolve(packageName));
+  const packageRoot = path.dirname(path.dirname(entry));
+  return path.join(packageRoot, "bin", executable);
+}
+
+function runEngine(mode, arguments_) {
+  const engineMode = mode === "react" ? "react" : "tui";
+  const engineArguments =
+    mode === "pty" ? ["pty", ...arguments_] : arguments_;
+  const normalized =
+    mode !== "pty" &&
+    engineArguments[0] &&
+    /\.[cm]?tsx?$/.test(engineArguments[0])
+      ? ["shot", ...engineArguments]
+      : engineArguments;
+  const result = spawnSync(
+    process.execPath,
+    [engineBin(engineMode), ...normalized],
+    { stdio: "inherit" },
+  );
+  if (result.error) {
+    console.error(`astroshot could not start ${mode} capture: ${result.error.message}`);
+    process.exit(1);
+  }
+  if (result.signal) process.kill(process.pid, result.signal);
+  process.exit(result.status ?? 1);
+}
+
+function initHelp() {
+  console.log(`astroshot init — generate a fixture template
+
+Usage:
+  astroshot init react [fixture.tsx] [--force]
+  astroshot init ink [fixture.tsx] [--force]
+  astroshot init pty [fixture.yaml] [--force]
+
+Defaults:
+  react.shot.tsx
+  ink.shot.tsx
+  pty.shot.yaml
+
+Existing files are never replaced unless --force is passed.`);
+}
+
+function runInit(arguments_) {
+  if (
+    arguments_.length === 0 ||
+    arguments_[0] === "help" ||
+    arguments_[0] === "-h" ||
+    arguments_[0] === "--help"
+  ) {
+    initHelp();
+    process.exit(arguments_.length === 0 ? 1 : 0);
+  }
+
+  const mode = arguments_[0];
+  const rest = arguments_.slice(1);
+  const force = rest.includes("--force") || rest.includes("-f");
+  const unknownFlags = rest.filter(
+    (value) => value.startsWith("-") && value !== "--force" && value !== "-f",
+  );
+  if (unknownFlags.length) {
+    throw new Error(`Unknown init flag: ${unknownFlags[0]}`);
+  }
+  const positionals = rest.filter((value) => !value.startsWith("-"));
+  if (positionals.length > 1) {
+    throw new Error("init accepts at most one output path");
+  }
+  const result = writeFixtureTemplate({
+    mode,
+    outputPath: positionals[0],
+    force,
+  });
+  console.log(`Created ${result.label} fixture: ${result.absolutePath}`);
+}
+
+const [command, ...arguments_] = process.argv.slice(2);
+
+if (command === "-v" || command === "--version") {
+  const packageJSON = JSON.parse(
+    fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+  );
+  console.log(packageJSON.version);
+  process.exit(0);
+}
+
+if (!command || command === "help" || command === "-h" || command === "--help") {
+  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_]);
+}
+
+if (command === "init") {
+  try {
+    runInit(arguments_);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+if (command === "react" || command === "ink" || command === "tui" || command === "pty") {
+  const canonicalMode = command === "tui" ? "ink" : command;
+  if (
+    arguments_.length === 0 ||
+    arguments_[0] === "help" ||
+    arguments_[0] === "-h" ||
+    arguments_[0] === "--help"
+  ) {
+    modeHelp(canonicalMode);
+    process.exit(arguments_.length === 0 ? 1 : 0);
+  }
+  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);