@hitslop/shots 0.1.0

package/SKILL.md

@@ -0,0 +1,536 @@
+---
+name: shots
+description: >
+  Use this skill when the user wants to generate or iterate on
+  App Store marketing screenshots. Triggers: "app store screenshots",
+  "marketing screenshots", "store listing images", "screenshot generation",
+  "app store assets", "shots", ".shots". Handles initialization of a
+  .shots/ workspace, AI image generation via GPT Image 2 through multiple
+  providers (OpenAI direct, fal.ai, or Replicate), sharp-based cropping/resizing
+  to App Store dimensions (1284x2778), App Store scraping for metadata/ASO,
+  and a style registry for prompt templates.
+  Do NOT use for general image generation, social media graphics, Google Play
+  screenshots, or non-App Store marketing assets.
+---
+
+# Shots
+
+AI-powered App Store screenshot generator. One command to set up, research, and generate.
+
+## Quick Start
+
+```bash
+npx -y @hitslop/shots@latest                    # Open .shots, prep assets, launch an agent
+npx -y @hitslop/shots@latest studio             # Open the local workspace UI
+npx -y @hitslop/shots@latest scrape <url>       # Scrape App Store metadata
+npx -y @hitslop/shots@latest install <style>    # Install a bundled style
+npx -y @hitslop/shots@latest styles             # List available styles
+npx -y @hitslop/shots@latest generate --prompt "..."  # Generate screenshots
+npx -y @hitslop/shots@latest feedback <shot-id> --text "..."  # Save feedback without regenerating
+```
+
+## Workspace Prep
+
+When launched from `npx -y @hitslop/shots@latest`, start by preparing the workspace before generating:
+
+1. Read `.shots/config.json`
+2. Inspect `.shots/app-screenshots/` and `.shots/inspo/`
+3. If app source code/docs exist in the current repo, inspect them
+4. Use App Store metadata already in config when present
+5. Use live web research when it helps fill missing product context
+6. Write as much of `.shots/config.json` as you can confidently
+7. Ask the user concise follow-up questions only for missing or uncertain fields
+8. Draft benefits/panels and get approval before running `generate`
+
+The workspace may not be inside a product repo. Use whatever context exists instead of blocking on missing source code.
+
+When updating `config.json`:
+
+- Fill confident fields directly instead of leaving placeholders
+- Preserve clearly intentional user-provided values unless new evidence is stronger
+- Use app screenshots and inspo for visual understanding, not for copying existing marketing copy
+
+## Benefit Discovery
+
+After the workspace is grounded, discover what the app does and draft benefit-driven headlines before generating screenshots.
+
+### Phase 1: Codebase Analysis
+
+Scan the project in priority order to understand what the app does:
+
+1. **README / docs** — Top-level description, value proposition, feature list
+2. **Onboarding flows** — Files matching `*onboard*`, `*welcome*`, `*tutorial*`
+3. **Navigation / routing** — Tab bars, route definitions, navigation stacks
+4. **Models / schemas** — What data the app manages (database models, API types)
+5. **UI entry points** — `App.tsx`, `index.tsx`, main activity, root layout
+6. **`.shots/config.json` ASO data** — Already-scraped description, genres, ratings, reviews
+
+If no repo exists, replace codebase analysis with:
+
+1. `.shots/config.json`
+2. App Store listing metadata and screenshots
+3. `.shots/app-screenshots/`
+4. `.shots/inspo/`
+5. Live web research about the product and positioning
+
+### Phase 2: Draft Benefits
+
+For each major feature discovered, draft a headline using one of three approaches:
+
+| Approach | What it does | Example |
+|----------|-------------|---------|
+| **Paint a moment** | Captures a specific micro-moment | "Check your coffee without opening the app" |
+| **State an outcome** | Describes the end state achieved | "A home for every coffee you buy" |
+| **Kill a pain** | Names the frustration eliminated | "Never waste a great bag of coffee" |
+
+Draft 6-8 benefits covering the app's key features. Each benefit needs:
+- `headline` — Action-verb headline, 3-5 words per line
+- `subtitle` — Supporting line that grants permission or reframes
+- `approach` — Which of the three approaches above (`moment`, `outcome`, or `pain`)
+- `panelType` — From the Panel Styles table below (BoldClaim, ProductTour, etc.)
+- `feature` — Brief description of the backing feature/screen
+- `arcPosition` — Where it sits in the narrative arc (`hero`, `differentiator`, `core`, `trust`, `closer`)
+
+### Phase 3: Clarifying Questions
+
+Before finalizing, ask the user only for the highest-value unknowns that you could not resolve confidently through repo analysis, App Store data, screenshots, inspo, or web research. Prioritize:
+1. What is the **#1 thing** your app does better than alternatives?
+2. What is the **most mentioned feature** in your reviews?
+3. What should the **first screenshot** convey to someone scrolling the App Store?
+
+### Phase 4: Save to Config
+
+Write the finalized benefits array to `.shots/config.json`. Also write any other confident metadata improvements you discovered. The generate command will use these benefits to auto-build per-panel prompt descriptions.
+
+```json
+{
+  "benefits": [
+    {
+      "headline": "See exactly where $200 went",
+      "subtitle": "Your spending, mapped by moment",
+      "approach": "moment",
+      "panelType": "BoldClaim",
+      "feature": "Spending breakdown dashboard",
+      "arcPosition": "hero"
+    }
+  ]
+}
+```
+
+## Commands
+
+### `npx -y @hitslop/shots@latest` (default)
+
+Initialize or reuse `.shots/`, open the workspace folder, print where to drop app screenshots and inspiration, and optionally launch Claude Code or Codex with this skill.
+
+### `npx -y @hitslop/shots@latest studio`
+
+Start the local Studio UI for the current `.shots/` workspace. Studio is bundled into the CLI package and serves local data only: app screenshots, inspiration, previous screenshots, generated runs, and generated panels.
+
+### `npx -y @hitslop/shots@latest scrape <url>`
+
+Scrape App Store metadata from a URL and populate `.shots/config.json` with ASO data, ratings, and screenshot URLs.
+
+Options:
+- `--download-screenshots` — Also download screenshot images to `.shots/app-screenshots/`
+- `--country <code>` — App Store country code (default: `us`)
+
+### `npx -y @hitslop/shots@latest install <style-name>`
+
+Install a bundled style to `.shots/styles/<name>/` and set it as the active style.
+
+Available styles:
+- `bold-gradient` — Vibrant gradients with punchy headlines
+- `minimal-white` — Clean white backgrounds with precise typography
+- `cinematic-dark` — Rich dark backgrounds with dramatic lighting
+- `frutiger-aero` — Glossy bubbles, aqua glass, bright nature, and retro social/customization energy
+
+### `npx -y @hitslop/shots@latest styles`
+
+List all available styles with descriptions and install status.
+
+### `npx -y @hitslop/shots@latest generate`
+
+Generate App Store screenshots via the composite-then-crop pipeline. When generation finishes, the CLI opens the run folder in `.shots/runs/<shot-id>/`.
+
+Options:
+- `--prompt "..."` — The generation prompt (required)
+- `--references path1.png,path2.png` — Reference images for edit endpoint
+- `--quality high|medium|low` — Generation quality (default: `high`)
+- `--feedback-for <shot-id>` — Iterate on a previous shot
+- `--mock` — Use mock SVG generation instead of calling an API
+- `--style <name>` — Use a specific style (overrides activeStyle in config)
+- `--panels <number>` — Panels per run, max 3 (default: 3). For more panels, run generate multiple times.
+- `--platform iphone|ipad|android` — Final panel platform (default: `iphone`)
+- `--set-name <name>` — Store the run under a logical set name in metadata (default: `default`)
+- `--provider openai|fal|replicate|managed` — Explicit provider choice (default: auto-detect from env vars)
+- `--managed-provider openai|fal` — Backend provider when `--provider managed` is used (default: `openai`)
+- `--mode composite|individual` — Generation mode (default: `composite`)
+
+Managed generation v1 does not support `--references`. Use BYOK `openai` or
+`fal` when reference images are required, or omit `--references` when using
+`--provider managed`.
+
+### `npx -y @hitslop/shots@latest feedback <shot-id> --text "..."`
+
+Append feedback to an existing shot history without creating a new image. Feedback is written to the manifest and, for v2 shots, to `.shots/runs/<shot-id>/feedback.json`.
+
+## Generation Pipeline
+
+1. Read `.shots/config.json` for app context
+2. If a style is active, load its `prompt.md` template and replace `{{placeholders}}`
+3. Build the full prompt with config context + user prompt
+4. Generate via the selected provider (OpenAI, fal.ai, or Replicate — auto-detected from env vars or explicit `--provider`)
+5. **Composite mode** (default): Generate one wide platform-aware image, crop into panels, and export exact final panel dimensions
+6. **Individual mode**: Generate each panel separately, then export exact final panel dimensions
+7. Create `.shots/runs/<shot-id>/` with panels, prompt, references, feedback, and metadata
+8. Update `.shots/manifest.json` with shot metadata (includes `provider` and `mode` fields)
+
+### Platform Dimensions
+
+| Platform | Final panel | Multi-panel composite |
+|----------|-------------|-----------------------|
+| iphone | 1284x2778 | 1152px per panel x 2400 |
+| ipad | 2048x2732 | 2048px per panel x 2732 |
+| android | 1080x1920 | 1080px per panel x 1920 |
+
+Each generate call produces at most 3 panels.
+
+### Multi-run generation
+
+Each generate call produces **at most 3 panels** in a single composite. To create more screenshots, run the generate command multiple times — each run gets its own shot ID and composite.
+
+Example: 6 panels → two runs:
+```bash
+npx -y @hitslop/shots@latest generate --platform iphone --prompt "Panels 1-3: ..." --panels 3
+npx -y @hitslop/shots@latest generate --platform iphone --prompt "Panels 4-6: ..." --panels 3
+```
+
+Each run should have a focused prompt covering only that run's panels. Use `--set-name` to group related runs.
+
+## Style System
+
+Styles are prompt templates that define visual direction. Each style has:
+- `meta.json` — Name, description, visual tone, panel types
+- `prompt.md` — Template with `{{appName}}`, `{{positioning}}`, `{{brandColors.primary}}` etc.
+- `assets/` — Reference images included automatically during generation
+
+### Using styles
+
+1. Install: `npx -y @hitslop/shots@latest install bold-gradient`
+2. Generate: `npx -y @hitslop/shots@latest generate --prompt "Focus on the onboarding flow"`
+3. The style template is used as the prompt foundation, with the user's prompt appended
+
+### Agent behavior with styles
+
+When generating screenshots:
+1. Check `.shots/styles/` for installed styles
+2. Check `config.activeStyle` for the currently selected style
+3. If styles exist but none is active, ask the user which to use
+4. Use the style's `prompt.md` as the prompt foundation
+5. Replace `{{placeholders}}` with config values
+6. Append the user's specific prompt instructions
+
+## Copywriting Principles
+
+The existing app screenshots are reference for what the app *looks like*, not a template for the copy. Never mirror them — always improve.
+
+### Marketing is prediction installation
+
+Your job isn't to describe features. It's to shift the user's self-concept so buying feels like recognition, not a gamble. Every panel should make someone stop scrolling because it reflects their identity back at them, not because it lists capabilities.
+
+### Three-layer system for each panel's copy
+
+1. **Perception** — Destabilize a cached prediction. Don't argue with "I don't need this." Show an angle they didn't consider. ("You think you're managing your time, but you're actually just reacting to it.")
+2. **Context** — Shift the frame. Make the screenshot feel like a late-night conversation, not a sales pitch. Same info, different context, different behavior.
+3. **Permission** — Remove the imagined consequence. Don't motivate — make action feel inevitable. Reflect back the version of them who already decided.
+
+### Headline writing recipe
+
+For each panel, pick one of three approaches:
+
+1. **Paint a moment** — Capture a specific micro-moment the user will recognize. ("Check your coffee without opening the app")
+2. **State an outcome** — Describe the end state the feature achieves. ("A home for every coffee you buy")
+3. **Kill a pain** — Name the frustration the feature eliminates. ("Never waste a great bag of coffee")
+
+### Iron rules
+
+- **One idea per headline** — if you need "and", it's two panels
+- **3-5 words per line** — must be readable in App Store browse surfaces
+- **Intentional line breaks** — break where the eye naturally pauses
+- **Headlines destabilize**, subtitles grant permission or reframe
+- **Don't describe features** — describe the identity shift the feature enables
+- Copy that converts doesn't inform — it *recognizes*
+
+### Bad-to-better examples
+
+| Bad | Better | Why |
+|-----|--------|-----|
+| "Track your finances" | "See exactly where $200 went" | Specific moment > generic verb |
+| "AI-powered writing" | "Write the email in 30 seconds" | Outcome > technology |
+| "Easy meal planning" | "Sunday dinner, planned by Friday" | Specific moment |
+| "Manage your tasks" | "Done before your coffee gets cold" | Paints a moment |
+
+### Copy rules
+
+- Research the app deeply — understand the emotional job-to-be-done, not just the functional one
+- Read the app's reviews, description, and competitor positioning before writing a single word
+
+## Configuration
+
+`.shots/config.json` contains all app metadata:
+
+```json
+{
+  "appName": "My App",
+  "appStoreUrl": "",
+  "positioning": "",
+  "targetAudience": "",
+  "visualTone": "clean, modern, premium",
+  "brandColors": {
+    "primary": "#1a1a2e",
+    "secondary": "#16213e",
+    "accent": "#0f969c",
+    "text": "#f5f5f5"
+  },
+  "aso": {
+    "title": "", "subtitle": "", "description": "",
+    "keywords": "", "genres": [], "developer": "",
+    "version": "", "releaseNotes": ""
+  },
+  "ratings": { "score": 0, "reviewCount": 0 },
+  "scrapedAssets": { "iconUrl": "", "screenshotUrls": [], "scrapedAt": "" },
+  "activeStyle": ""
+}
+```
+
+## File Structure
+
+```
+.shots/
+  config.json           # App metadata + ASO + style selection
+  manifest.json         # All generated shots
+  inspo/                # Reference images
+  app-screenshots/      # App's current screenshots
+  runs/                 # v2 generated runs with history and artifacts
+    shot-a1b2c3/
+      composite.png
+      screenshots/
+        panel-1.png
+        panel-2.png
+        panel-3.png
+      prompt.md
+      references.json
+      feedback.json
+      metadata.json
+  screenshots/          # Legacy final cropped panels
+  composites/           # Legacy full composites
+  styles/               # Installed style templates
+    bold-gradient/
+      meta.json
+      prompt.md
+      assets/
+```
+
+## Prompt Construction
+
+### Required Prompt Elements
+
+Every prompt MUST specify:
+
+1. **Dimensions**: specify the CLI-provided composite dimensions
+2. **Panel structure**: "with three equal vertical panels"
+3. **Content centering**: "center all content (text, phone mockups, UI elements) horizontally within each panel's column"
+4. **Crop independence**: "each panel must crop cleanly into a standalone portrait App Store screenshot"
+5. **Text safety**: "keep all text legible and at least 80px away from panel edges"
+
+### Prompt Template
+
+```
+Create one {compositeWidth}x{compositeHeight} App Store marketing composite for "{appName}" with three equal vertical panels and no visible seams.
+
+Visual style: {visualTone}
+Brand colors: primary {primary}, accent {accent}, text {textColor}
+
+Panel 1 (left): {panel1Description}
+Panel 2 (center): {panel2Description}
+Panel 3 (right): {panel3Description}
+
+Each panel must crop cleanly into a standalone portrait screenshot at {targetWidth}x{targetHeight}.
+Keep text legible, at least 80px from panel edges.
+Do not include app icons, download buttons, or platform badges.
+{additionalInstructions}
+```
+
+### Panel Styles
+
+Choose the right style for each panel. Not every panel needs a headline + subtitle.
+
+| Style | When to use | Typical content |
+|-------|------------|-----------------|
+| BoldClaim | Opening impact | Large headline, minimal supporting text |
+| QuietProof | Subtle credibility | Stats, ratings, or quiet social proof |
+| BeforeAfter | Transformation | Side-by-side comparison within the panel |
+| ProductTour | Feature showcase | App UI screenshots as the hero visual |
+| TestimonialProof | Social proof | Quote + attribution |
+| DataResult | Metrics highlight | Key numbers or outcomes |
+| ProcessSteps | How-it-works | 2-3 simple steps |
+| ObjectionCollapse | Address doubt | Pre-empt the most common hesitation |
+| IdentityRecognition | User identity | "You already know..." framing |
+| TypographicCloser | Final CTA | Clean typographic closer, one strong idea |
+| FullBleedVisual | Visual impact | Edge-to-edge imagery, minimal text |
+
+### Narrative Arc
+
+Order your panels to tell a story. The arc determines which benefit goes where.
+
+#### Full arc (5+ panels)
+
+| Position | Role | Panel Type | Purpose |
+|----------|------|------------|---------|
+| 1 | Hero | BoldClaim | Stop the scroll. One massive idea. |
+| 2 | Differentiator | IdentityRecognition | Why THIS app, not alternatives |
+| 3+ | Core Feature | ProductTour | Show it working |
+| 2nd-to-last | Trust Signal | QuietProof / DataResult | Social proof or outcomes |
+| Last | Closer | TypographicCloser | One strong closing idea |
+
+#### 4-panel arc
+
+| Position | Role | Panel Type |
+|----------|------|------------|
+| 1 | Hero | BoldClaim |
+| 2 | Differentiator | IdentityRecognition |
+| 3 | Core Feature | ProductTour |
+| 4 | Closer | TypographicCloser |
+
+#### 3-panel arc
+
+| Position | Role | Panel Type |
+|----------|------|------------|
+| 1 | Hero | BoldClaim |
+| 2 | Core Feature | ProductTour |
+| 3 | Closer | TypographicCloser |
+
+When `config.benefits` exists, sort benefits by `arcPosition` and assign them to panels following the arc above. The arc ensures each panel has a clear narrative role rather than listing features in arbitrary order.
+
+### Frutiger Aero Recipe
+
+Use this recipe when generating FrutigerOS or another app where nostalgia,
+customization, social presence, and playful self-expression are the product.
+
+#### Visual direction
+
+- Use glossy aqua glass, translucent rounded panels, floating bubbles, water refraction, rim highlights, saturated grass, bright sky, palm leaves, clownfish/orange accents, chrome, and lens flares.
+- Typography should feel like Frutiger Aero: rounded, inflated, glossy, friendly, and high contrast. If the exact font cannot be rendered, ask for a close bubbly aqua-era imitation.
+- Use reference images such as a tinted app icon and Frutiger Aero collage when available.
+- Keep the real app UI readable inside a large iPhone mockup; do not let bubbles obscure primary UI.
+
+#### Six-panel copy
+
+| Panel | Headline | Subtitle |
+|-------|----------|----------|
+| Home | Your phone got glossy | A retro desktop you can actually live in |
+| Theme editor | Make it yours | Swap glass, icons, wallpapers, and weird little moods |
+| Chat | Chat like it's 2009 | Winks, nudges, status drama, and room energy |
+| Stickers | Decorate everything | Drag in icons, stickers, widgets, and old-web flavor |
+| Friends | Show off your desktop | Friend codes, global rooms, and profiles with personality |
+| Apps | An OS for your aesthetic | Apps, windows, themes, and glossy nostalgia in one place |
+
+Avoid leading with raw inventory counts such as sticker or wallpaper totals. Use
+counts only as secondary proof if the visual already sells the feeling.
+
+### Brand Integration
+
+When `config.json` has brand colors defined, incorporate them:
+
+- Use `primary` for backgrounds or large color blocks
+- Use `accent` for highlights, buttons, or emphasis
+- Use `text` for body copy
+- Maintain sufficient contrast ratios (4.5:1 for body text, 3:1 for large text)
+
+### Iteration Tips
+
+When regenerating with feedback:
+- Be specific about what to change: "make the headline on panel 2 larger" vs "make it better"
+- Reference panel positions: "left panel", "center panel", "right panel"
+- Describe the desired outcome, not just the problem
+- If the layout is good but colors are wrong, say so explicitly to preserve what works
+
+### Anti-patterns
+
+Avoid these common prompt mistakes:
+
+- **Too vague**: "Make nice screenshots" — always specify visual tone and content
+- **Too crowded**: Putting too much text on panels — each panel should convey one idea
+- **Off-center content**: Not centering content within each panel column — elements should be horizontally centered
+- **Generic stock imagery**: The screenshots should feel specific to the app, not generic marketing
+- **Fake UI elements**: Don't add fake status bars, app store badges, or download buttons
+
+## Schema Reference
+
+### Config Interface
+
+```typescript
+interface Config {
+  appName: string;
+  appStoreUrl: string;
+  positioning: string;
+  targetAudience: string;
+  visualTone: string;
+  brandColors: {
+    primary: string;
+    secondary: string;
+    accent: string;
+    text: string;
+  };
+  aso: {
+    title: string;           // 30 chars max
+    subtitle: string;        // 30 chars max
+    description: string;     // 4000 chars max
+    keywords: string;        // 100 chars, comma-separated
+    genres: string[];
+    developer: string;
+    version: string;
+    releaseNotes: string;
+  };
+  ratings: {
+    score: number;           // 0-5
+    reviewCount: number;
+  };
+  scrapedAssets: {
+    iconUrl: string;
+    screenshotUrls: string[];
+    scrapedAt: string;       // ISO 8601
+  };
+  activeStyle: string;       // Currently selected style name
+}
+```
+
+### Shot ID Format
+
+- Prefix: `shot-`
+- Suffix: 6 lowercase alphanumeric characters
+- Example: `shot-a1b2c3`, `shot-x7k9m2`
+
+IDs are unique within a manifest.
+
+### File Path Conventions
+
+All paths in the manifest are **relative to `.shots/`**:
+
+- New run composite: `runs/shot-{suffix}/composite.png`
+- New run screenshots: `runs/shot-{suffix}/screenshots/panel-{panelNumber}.png` (1-indexed)
+- New run prompt: `runs/shot-{suffix}/prompt.md`
+- New run references: `runs/shot-{suffix}/references.json`
+- New run feedback: `runs/shot-{suffix}/feedback.json`
+- Legacy composites: `composites/composite-{suffix}.png`
+- Legacy screenshots: `screenshots/shot-{suffix}-{panelNumber}.png`
+- Reference images: usually `inspo/{filename}`, `app-screenshots/{filename}`, or `styles/{name}/assets/{filename}`
+
+## Requirements
+
+- Node.js 18+
+- One of the following environment variables (not needed with `--mock`):
+  - `OPENAI_API_KEY` — OpenAI direct (exact pixel dimensions)
+  - `FAL_KEY` — fal.ai proxy (exact pixel dimensions, often cheaper)
+  - `REPLICATE_API_TOKEN` — Replicate proxy (uses aspect ratio presets)

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+import { Args, Command, Options } from "@effect/cli";
+import { NodeContext, NodeRuntime } from "@effect/platform-node";
+import { Effect, Option } from "effect";
+import { defaultCommand } from "./commands/default.js";
+import { scrapeCommand } from "./commands/scrape.js";
+import { generateCommand } from "./commands/generate.js";
+import { feedbackCommand } from "./commands/feedback.js";
+import { authLoginCommand, authLogoutCommand, authStatusCommand } from "./commands/auth.js";
+import { cropCommand } from "./commands/crop.js";
+import { initCommand } from "./commands/init.js";
+import { installCommand } from "./commands/install.js";
+import { studioCommand } from "./commands/studio.js";
+import { stylesCommand } from "./commands/styles.js";
+import { viewCommand } from "./commands/view.js";
+// --- init ---
+const initCmd = Command.make("init", {}, () => Effect.tryPromise(() => initCommand())).pipe(Command.withDescription("Create a .shots workspace"));
+// --- scrape <url> ---
+const scrapeCmd = Command.make("scrape", {
+    url: Args.text({ name: "url" }),
+    downloadScreenshots: Options.boolean("download-screenshots"),
+    country: Options.text("country").pipe(Options.withDefault("us")),
+}, ({ url, downloadScreenshots, country }) => Effect.tryPromise(() => scrapeCommand(url, { downloadScreenshots, country }))).pipe(Command.withDescription("Scrape App Store metadata from a URL"));
+// --- styles ---
+const stylesCmd = Command.make("styles", {}, () => Effect.tryPromise(() => stylesCommand())).pipe(Command.withDescription("List bundled and installed screenshot styles"));
+// --- install <style-name> ---
+const installCmd = Command.make("install", {
+    styleName: Args.text({ name: "style-name" }),
+}, ({ styleName }) => Effect.tryPromise(() => installCommand(styleName))).pipe(Command.withDescription("Install a bundled style into .shots/styles"));
+// --- generate ---
+const generateCmd = Command.make("generate", {
+    prompt: Options.text("prompt").pipe(Options.optional),
+    references: Options.text("references").pipe(Options.optional),
+    quality: Options.choice("quality", ["high", "medium", "low"]).pipe(Options.withDefault("high")),
+    feedbackFor: Options.text("feedback-for").pipe(Options.optional),
+    mock: Options.boolean("mock"),
+    style: Options.text("style").pipe(Options.optional),
+    panels: Options.integer("panels").pipe(Options.withDefault(3)),
+    platform: Options.choice("platform", ["iphone", "ipad", "android"]).pipe(Options.withDefault("iphone")),
+    setName: Options.text("set-name").pipe(Options.withDefault("default")),
+    provider: Options.choice("provider", ["openai", "fal", "replicate", "managed"]).pipe(Options.optional),
+    managedProvider: Options.choice("managed-provider", ["openai", "fal"]).pipe(Options.withDefault("openai")),
+    mode: Options.choice("mode", ["composite", "individual"]).pipe(Options.withDefault("composite")),
+}, ({ prompt, references, quality, feedbackFor, mock, style, panels, platform, setName, provider, managedProvider, mode }) => Effect.tryPromise(() => generateCommand({
+    prompt: Option.getOrUndefined(prompt),
+    references: Option.getOrUndefined(references),
+    quality,
+    feedbackFor: Option.getOrUndefined(feedbackFor),
+    mock,
+    style: Option.getOrUndefined(style),
+    panels,
+    platform,
+    setName,
+    provider: Option.getOrUndefined(provider),
+    managedProvider,
+    mode: mode,
+}))).pipe(Command.withDescription("Generate App Store screenshots"));
+// --- crop <run-id> ---
+const cropCmd = Command.make("crop", {
+    runId: Args.text({ name: "run-id" }),
+    platform: Options.choice("platform", ["iphone", "ipad", "android"]).pipe(Options.optional),
+}, ({ runId, platform }) => Effect.tryPromise(() => cropCommand(runId, {
+    platform: Option.getOrUndefined(platform),
+}))).pipe(Command.withDescription("Crop a run composite into exact panels"));
+// --- view [run-id] ---
+const viewCmd = Command.make("view", {
+    runId: Args.text({ name: "run-id" }).pipe(Args.optional),
+}, ({ runId }) => Effect.tryPromise(() => viewCommand(Option.getOrUndefined(runId)))).pipe(Command.withDescription("Open the latest or selected run folder"));
+// --- studio ---
+const studioCmd = Command.make("studio", {
+    host: Options.text("host").pipe(Options.withDefault("127.0.0.1")),
+    port: Options.integer("port").pipe(Options.withDefault(4789)),
+    noOpen: Options.boolean("no-open"),
+}, ({ host, port, noOpen }) => Effect.tryPromise(() => studioCommand({
+    host,
+    port,
+    open: !noOpen,
+}))).pipe(Command.withDescription("Start the local Shots studio"));
+// --- auth ---
+const authStatusCmd = Command.make("status", {}, () => Effect.tryPromise(() => authStatusCommand())).pipe(Command.withDescription("Show BYOK and managed auth status"));
+const authLoginCmd = Command.make("login", {
+    apiKey: Options.text("api-key").pipe(Options.optional),
+    apiUrl: Options.text("api-url").pipe(Options.optional),
+}, ({ apiKey, apiUrl }) => Effect.tryPromise(() => authLoginCommand({
+    apiKey: Option.getOrUndefined(apiKey),
+    apiUrl: Option.getOrUndefined(apiUrl),
+}))).pipe(Command.withDescription("Save a managed Shots CLI API key"));
+const authLogoutCmd = Command.make("logout", {}, () => Effect.tryPromise(() => authLogoutCommand())).pipe(Command.withDescription("Clear managed auth"));
+const authCmd = Command.make("auth", {}, () => Effect.sync(() => undefined)).pipe(Command.withDescription("Manage Shots authentication"), Command.withSubcommands([authStatusCmd, authLoginCmd, authLogoutCmd]));
+// --- feedback <shot-id> --text "..." ---
+const feedbackCmd = Command.make("feedback", {
+    shotId: Args.text({ name: "shot-id" }),
+    text: Options.text("text"),
+}, ({ shotId, text }) => Effect.tryPromise(() => feedbackCommand(shotId, text))).pipe(Command.withDescription("Append feedback to an existing generated shot"));
+// --- root (default — no subcommand) ---
+const shots = Command.make("shots", {}, () => Effect.tryPromise(() => defaultCommand())).pipe(Command.withDescription("AI-powered App Store screenshot generator"), Command.withSubcommands([
+    initCmd,
+    scrapeCmd,
+    generateCmd,
+    cropCmd,
+    viewCmd,
+    studioCmd,
+    authCmd,
+    feedbackCmd,
+    stylesCmd,
+    installCmd,
+]));
+const cli = Command.run(shots, {
+    name: "shots",
+    version: "0.1.0",
+});
+cli(process.argv).pipe(Effect.provide(NodeContext.layer), NodeRuntime.runMain);
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}