Packr
Sign In

@blueforge-studio/sidecar-ops

Sidecar operations for fleet repos: generate promo shots from user flows, capture them light and dark, declare them in blueforge.product.yml and the flow files, check, doctor, and install the package.json scripts

InfoVersionsSupply chainDependenciesReadme

Package Info

Latest Version0.2.1
Licensenone
Keywords-
Repositorygit+https://github.com/blueforge-studio/blueforge-org.git
Author-
Homepagehttps://github.com/blueforge-studio/blueforge-org#readme
Bugs[object Object]

Versions

VersionPublished
0.2.12026-10-21
0.2.02026-10-20
0.1.02026-10-19

Per-version supply chain

VersionSigSBOMAtt
0.2.1
0.2.0
0.1.0

Click a version to view its details.

Supply chain

Provenance

Published by
web:5
When
2026-10-21T13:55:10Z
sha256 (registry-computed)
9074390b616487a6c6a313bcc62a2b33dcafe4d198b885a890923f0b76d91df8

Observed by the registry at publish.

Claimed by the build

The publisher claimed nothing about its build.

Attachments

Signature
none
SBOM
none

Dependencies

Loading dependency graph...

README

@blueforge-studio/sidecar-ops

Sidecar operations for a fleet repo: turn its declared user flows into promo screenshots in light and dark mode, declare them in the sidecars, and check the result. Built on promo-shots (capture), blueforge-sidecar-schemas (0.42 fields: promote, step shot/caption, screenshot variant/flow/step) and visual-audit (checks).

End-to-end

pnpm add -D @blueforge-studio/sidecar-ops playwright && npx playwright install chromium
npx sidecar-ops scripts install           # adds sidecar:shots / sidecar:audit / sidecar:doctor (never overwrites)
npx sidecar-ops doctor                    # how ready the repo is, and what to do next

npx sidecar-ops shots init                # promo.shots.yml from *.user-flows.yml, one shot per UI step
#   edit: map route ids to paths in promo.routes.yml, fill commented-out TODO shots (route: or steps:)
npx sidecar-ops shots capture --base https://your-app.example   # light + dark PNGs → public/promo/, nothing uploaded
npx sidecar-ops shots declare             # blueforge.product.yml screenshots + flow steps `shot:` + `promote: true`
npx sidecar-ops check                     # sidecars validate + visual audit (correctness), exit 0/1/3/4

Commit the PNGs, promo.shots.yml, promo.routes.yml and the sidecar changes in one PR. forge-control uploads the declared screenshots on the next deploy; blueforge.studio serves the dark capture on its dark site and plays each promoted flow step by step.

Commands

Every command takes --repo <dir> (default: cwd) and --json. An unknown flag exits 2 and does nothing.

CommandWhat it does
shots init [--app a] [--product id] [--out promo.shots.yml] [--flows a,b] [--force]Writes a promo-shots file. Route of each step: its path → promo.routes.yml (routes: { web.editor: /editor/demo }) → a feature-spec comment - web.editor-new # … (/editor/new) → TODO (written commented out, so the file stays valid). Auth steps (sign-in, sign-up, password…) and non-UI routes (api., cli., worker., webhook., gw., db., none) are skipped. Paths with parameters (/editor/:worldId) become TODOs: give a concrete path or steps:. Never overwrites without --force.
shots capture [--file f] [--base url] [--out-dir public/promo] [--only ids]Runs promo-shots in dry-run: light and dark per shot, no upload, no token. Writes <id>-light.png / <id>-dark.png and captures.json. Reports each shot ok, sign-in (a password field on screen: declare a promo-shots persona) or failed (reason). Needs Playwright in the repo.
shots declare [--file f] [--dir public/promo] [--dry-run]Upserts assets.screenshots entries (one per theme, sharing id, with path, label, caption, alt, flow, step; one untagged entry when dark equals light), sets each step's shot: "@screenshot/<id>" and caption, and promote: true on flows with a shot. Comments and order are kept; a re-run changes nothing. A file that validated before and would not after stops the command and nothing is written.
check [--vision on|off]sidecar-schemas validation (product sidecar, user-flows files, label and promotion lints) plus visual-audit correctness over the declared images. Exit 0 pass/warn · 1 fail · 3 nothing to audit · 4 error.
doctor [--file f]Flows, promoted flows, UI steps, steps with a shot, unresolved routes, screenshots with/without variant, unpaired themes, missing files, scripts present, and the next steps.
scripts install [--dry-run]Adds sidecar:shots, sidecar:audit, sidecar:doctor and the devDependency. Never overwrites an existing key whose value differs (fleet repos have their own sidecar:check and the like): it is kept and reported kept (existing: …). Only missing keys are added, and keys already holding a sidecar-ops command are brought in line.

Images in the repo

  • Captures are 1440 px wide by default (defaults.viewport in the shots file); keep them at or under that and optimise the PNGs (e.g. oxipng -o 4) before committing.
  • Repos with Git LFS for images commit them through LFS as usual. A repo without .gitattributes / LFS (e.g. world-map-editor) commits them as plain files; sidecar-ops does not add LFS for you.
  • The CI visual audit checks out LFS (lfs: true) and reports an un-fetched pointer as LFS_POINTER.

Not yet

  • Broken <img> detection during capture (visual-audit T2 notes): promo-shots does not report it yet, so no <image>.capture.json is written.
  • Signed-in screens: use promo-shots personas (cookie, header, bearer or localStorage values, always from the environment) in the shots file.