appshot-cli 0.9.1 → 1.0.0

package/dist/utils/filename-caption.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filename-caption.d.ts","sourceRoot":"","sources":["../../src/utils/filename-caption.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAS1D"}

package/dist/utils/filename-caption.js

@@ -0,0 +1,19 @@
+import path from 'path';
+/**
+ * Convert a filename to a human-readable caption.
+ * Examples:
+ *   "hello-world.png" → "Hello World"
+ *   "my_screenshot.png" → "My Screenshot"
+ *   "app-home_screen.PNG" → "App Home Screen"
+ */
+export function filenameToCaption(filename) {
+    const name = path.basename(filename, path.extname(filename));
+    return name
+        .replace(/[-_]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .split(' ')
+        .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(' ');
+}
+//# sourceMappingURL=filename-caption.js.map

package/dist/utils/filename-caption.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filename-caption.js","sourceRoot":"","sources":["../../src/utils/filename-caption.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB;IAChD,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC7D,OAAO,IAAI;SACR,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC;SACrB,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;SACpB,IAAI,EAAE;SACN,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;SACzD,IAAI,CAAC,GAAG,CAAC,CAAC;AACf,CAAC"}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const APP_VERSION: string;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,WAAW,QAAyB,CAAC"}

package/dist/version.js

@@ -0,0 +1,5 @@
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+export const APP_VERSION = pkg.version ?? '0.0.0';
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAEvC,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,GAAG,GAAG,OAAO,CAAC,iBAAiB,CAAyB,CAAC;AAE/D,MAAM,CAAC,MAAM,WAAW,GAAG,GAAG,CAAC,OAAO,IAAI,OAAO,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appshot-cli",
-  "version": "0.9.1",
+  "version": "1.0.0",
   "description": "Generate App Store–ready screenshots with frames, gradients, and captions",
   "bin": {
     "appshot": "bin/appshot.js"
@@ -23,13 +23,15 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^7.8.3",
+    "@modelcontextprotocol/sdk": "^1.25.2",
     "commander": "^12.0.0",
     "fuzzy": "^0.1.3",
     "inquirer": "^12.0.0",
     "inquirer-autocomplete-standalone": "^0.8.1",
-    "openai": "^5.13.1",
+    "openai": "^6.16.0",
     "picocolors": "^1.0.0",
-    "sharp": "^0.33.5"
+    "sharp": "^0.33.5",
+    "zod": "^4.3.5"
   },
   "devDependencies": {
     "@types/node": "^24.3.0",
@@ -47,7 +49,8 @@
     "dist",
     "bin",
     "frames",
-    "fonts"
+    "fonts",
+    "skill"
   ],
   "license": "MIT",
   "homepage": "https://github.com/chrisvanbuskirk/appshot",

package/skill/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: appshot
+description: Create and manage App Store screenshot projects using appshot MCP tools. This skill should be used when users want to generate professional App Store screenshots with device frames, gradients, and captions. Triggers include requests to create screenshot projects, add captions, apply styling, or build final screenshots.
+---
+
+# AppShot Screenshot Generator
+
+## Overview
+
+AppShot generates App Store-ready screenshots with device frames, gradient backgrounds, and captions. This skill orchestrates the appshot MCP tools to create complete screenshot projects.
+
+## Available MCP Tools
+
+| Tool | Purpose |
+|------|---------|
+| `appshot.init` | Initialize new project structure |
+| `appshot.captions` | Read/write/auto-generate caption text |
+| `appshot.gradients` | List/apply gradient presets |
+| `appshot.backgrounds` | Configure background images |
+| `appshot.fonts` | List/validate available fonts |
+| `appshot.config` | Modify device-specific settings |
+| `appshot.build` | Generate final screenshots |
+| `appshot.validate` | Check App Store compliance |
+| `appshot.specs` | View App Store specifications |
+| `appshot.doctor` | System diagnostics |
+| `appshot.presets` | App Store preset configurations |
+| `appshot.localize` | AI-powered caption translation |
+| `appshot.languages` | Discover available translations |
+| `appshot.frame` | Apply device frames only |
+| `appshot.export` | Export for Fastlane |
+| `appshot.clean` | Remove generated files |
+
+## Project Workflow
+
+### 1. Initialize Project
+
+```
+appshot.init with force: true
+```
+
+Creates the project structure:
+```
+.appshot/
+├── config.json          # Main configuration
+└── captions/
+    ├── iphone.json      # Caption files per device
+    ├── ipad.json
+    ├── mac.json
+    └── watch.json
+screenshots/
+├── iphone/              # Place screenshots here
+├── ipad/
+├── mac/
+└── watch/
+final/                   # Generated output
+```
+
+### 2. Add Captions
+
+List existing captions:
+```
+appshot.captions with device: "iphone", action: "list"
+```
+
+Set a caption:
+```
+appshot.captions with device: "iphone", action: "set", filename: "home.png", caption: "Welcome Home", language: "en"
+```
+
+Auto-generate captions from filenames:
+```
+appshot.captions with device: "iphone", action: "auto"
+```
+This converts filenames like `home-screen.png` → "Home Screen"
+
+Bulk set multiple captions:
+```
+appshot.captions with device: "iphone", action: "bulk-set", captions: "{\"home.png\": \"Welcome\", \"settings.png\": \"Settings\"}"
+```
+
+Add translations:
+```
+appshot.captions with device: "iphone", action: "set", filename: "home.png", caption: "Bienvenido", language: "es"
+```
+
+### 3. Apply Styling
+
+List gradient presets:
+```
+appshot.gradients with action: "list"
+```
+
+Apply a gradient:
+```
+appshot.gradients with action: "apply", preset: "ocean"
+```
+
+Set background image:
+```
+appshot.backgrounds with action: "set", image: "./bg.jpg", fit: "cover"
+```
+
+Configure device settings:
+```
+appshot.config with device: "iphone", frameScale: 0.85, captionPosition: "above"
+```
+
+### 4. Build Screenshots
+
+Build all devices and languages:
+```
+appshot.build
+```
+
+Build specific devices:
+```
+appshot.build with devices: ["iphone", "ipad"]
+```
+
+Build with App Store presets:
+```
+appshot.build with presets: ["iphone-6-9", "ipad-13"]
+```
+
+### 5. Frame Only (No Background)
+
+Apply device frames without gradients or captions:
+```
+appshot.frame with input: "./screenshots/iphone"
+```
+
+Frame with output directory:
+```
+appshot.frame with input: "./screenshots/iphone", outputDir: "./framed"
+```
+
+Frame recursively:
+```
+appshot.frame with input: "./screenshots", recursive: true
+```
+
+Preview what would be framed:
+```
+appshot.frame with input: "./screenshots/iphone", dryRun: true
+```
+
+### 6. Validate
+
+Check App Store compliance:
+```
+appshot.validate
+```
+
+## Common Scenarios
+
+### New iPhone-Only Project
+
+1. `appshot.init` with `force: true`
+2. User adds screenshots to `screenshots/iphone/`
+3. `appshot.captions` - set captions for each screenshot
+4. `appshot.gradients` - apply preferred gradient
+5. `appshot.build` with `devices: ["iphone"]`
+
+### Multi-Language App Store Submission
+
+1. `appshot.init` with `force: true`
+2. `appshot.captions` - add English captions
+3. `appshot.localize` with `languages: ["es", "fr", "de", "ja"]`
+4. `appshot.build` with `languages: ["en", "es", "fr", "de", "ja"]`
+5. `appshot.validate`
+
+### Quick Styling Update
+
+1. `appshot.gradients` with `action: "list"` to see options
+2. `appshot.gradients` with `action: "apply", preset: "sunset"`
+3. `appshot.build`
+
+### Quick Auto-Caption Project
+
+When filenames are descriptive (e.g., `home-screen.png`, `settings_page.png`):
+
+1. `appshot.init` with `force: true`
+2. User adds screenshots to `screenshots/iphone/`
+3. `appshot.captions` with `device: "iphone", action: "auto"`
+4. `appshot.gradients` with `action: "apply", preset: "ocean"`
+5. `appshot.build` with `devices: ["iphone"]`
+
+Captions are auto-generated from filenames (hyphens/underscores become spaces, title case applied).
+
+### Frame Only (Design Mockups)
+
+For quick device mockups without backgrounds or captions:
+
+1. `appshot.frame` with `input: "./screenshots/iphone", outputDir: "./framed"`
+
+Output has transparent background - perfect for presentations, design comps, or overlaying on custom backgrounds.
+
+## Device Resolutions
+
+### Required for App Store
+- **iPhone 6.9"**: 1290x2796 or 1320x2868
+- **iPad 13"**: 2064x2752 or 2048x2732
+
+### Optional
+- **Mac**: 2880x1800 (16:10)
+- **Watch Ultra**: 410x502
+
+## Configuration Options
+
+### Frame Positioning
+- `frameScale`: 0.1-1.5 (default: 0.9)
+- `framePosition`: 0-100 or "center"
+- `captionPosition`: "above", "below", "overlay"
+
+### Caption Styling
+- `captionSize`: Font size in pixels
+- `marginTop`: Top margin for caption
+- `marginBottom`: Bottom margin for caption
+
+## Resources
+
+- `references/templates.md` - All 8 templates with styles, colors, and recommendations
+- `references/gradients.md` - All 24 gradient presets with colors
+- `references/fonts.md` - All 10 embedded font families
+- `references/troubleshooting.md` - Common errors and solutions

package/skill/references/fonts.md

@@ -0,0 +1,55 @@
+# Embedded Fonts
+
+10 font families bundled with appshot, always available without system installation.
+
+## Modern UI Fonts
+
+| Font | Variants | Best For |
+|------|----------|----------|
+| **Inter** | Regular, Bold, Italic, Bold Italic | Clean, modern interfaces |
+| **Poppins** | Regular, Bold, Italic, Bold Italic | Friendly, geometric headings |
+| **Montserrat** | Regular, Bold, Italic, Bold Italic | Professional, versatile |
+| **DM Sans** | Regular | Modern, geometric |
+
+## Web-Safe Fonts
+
+| Font | Variants | Best For |
+|------|----------|----------|
+| **Roboto** | Regular, Bold, Italic, Bold Italic | Android-style, neutral |
+| **Open Sans** | Regular | Highly readable body text |
+| **Lato** | Regular, Bold, Italic, Bold Italic | Warm, humanist sans-serif |
+| **Work Sans** | Regular | Modern web typography |
+
+## Monospace Fonts
+
+| Font | Variants | Best For |
+|------|----------|----------|
+| **JetBrains Mono** | Regular, Bold, Italic, Bold Italic | Code, technical apps |
+| **Fira Code** | Regular, Bold | Code with ligatures |
+
+## Font Recommendations by App Type
+
+| App Category | Recommended Font |
+|--------------|------------------|
+| Finance/Business | Inter, Montserrat |
+| Social/Lifestyle | Poppins, Lato |
+| Productivity | Open Sans, Work Sans |
+| Developer Tools | JetBrains Mono, Fira Code |
+| Health/Fitness | Roboto, DM Sans |
+
+## Usage
+
+List embedded fonts:
+```
+appshot.fonts with action: "embedded"
+```
+
+Validate a font:
+```
+appshot.fonts with action: "validate", font: "Inter"
+```
+
+Configure font in project:
+```
+appshot.config with device: "iphone", font: "Montserrat Bold"
+```

package/skill/references/gradients.md

@@ -0,0 +1,69 @@
+# Gradient Presets
+
+24 built-in gradient presets organized by category.
+
+## Warm
+
+| ID | Name | Colors | Direction |
+|----|------|--------|-----------|
+| `sunset` | Sunset | #FF5733 → #FFC300 | top-bottom |
+| `sunrise` | Sunrise | #F37335 → #FDC830 | diagonal |
+| `autumn` | Autumn | #D38312 → #A83279 | top-bottom |
+| `peach` | Peach | #FFCCCC → #FF6B6B | top-bottom |
+
+## Cool
+
+| ID | Name | Colors | Direction |
+|----|------|--------|-----------|
+| `ocean` | Ocean | #0077BE → #33CCCC | top-bottom |
+| `arctic` | Arctic | #72EDF2 → #5151E5 | diagonal |
+| `mint` | Mint | #00B09B → #96C93D | left-right |
+| `lavender` | Lavender | #9796F0 → #FBC7D4 | top-bottom |
+
+## Vibrant
+
+| ID | Name | Colors | Direction |
+|----|------|--------|-----------|
+| `rainbow` | Rainbow | #FF0080 → #FF8C00 → #40E0D0 | left-right |
+| `neon` | Neon | #FF006E → #8338EC → #3A86FF | diagonal |
+| `tropical` | Tropical | #FA709A → #FEE140 | top-bottom |
+| `candy` | Candy | #FF61D2 → #FE9090 → #FFCC5C | left-right |
+
+## Subtle
+
+| ID | Name | Colors | Direction |
+|----|------|--------|-----------|
+| `pastel` | Pastel | #E8D8F5 → #D6E6FF | top-bottom |
+| `mist` | Mist | #E0EAFC → #CFDEF3 | top-bottom |
+| `pearl` | Pearl | #F5F5F5 → #E8E8E8 → #F0F0F0 | diagonal |
+| `cloud` | Cloud | #FFFFFF → #F0F0F0 | top-bottom |
+
+## Monochrome
+
+| ID | Name | Colors | Direction |
+|----|------|--------|-----------|
+| `noir` | Noir | #000000 → #434343 | top-bottom |
+| `graphite` | Graphite | #283048 → #859398 | diagonal |
+| `charcoal` | Charcoal | #1C1C1C → #494949 | top-bottom |
+| `silver` | Silver | #B8B8B8 → #E8E8E8 | diagonal |
+
+## Brand
+
+| ID | Name | Colors | Direction |
+|----|------|--------|-----------|
+| `instagram` | Instagram | #833AB4 → #FD1D1D → #FCB045 | diagonal |
+| `twitter` | Twitter Blue | #1DA1F2 → #14171A | top-bottom |
+| `spotify` | Spotify | #1DB954 → #191414 | diagonal |
+| `apple` | Apple | #A1C4FD → #C2E9FB | diagonal |
+
+## Usage
+
+To apply a gradient:
+```
+appshot.gradients with action: "apply", preset: "<id>"
+```
+
+To list gradients by category:
+```
+appshot.gradients with action: "list", category: "warm"
+```

package/skill/references/templates.md

@@ -0,0 +1,170 @@
+# Template Reference
+
+8 professional templates for App Store screenshots.
+
+## Template Selection Guide
+
+| App Type | Recommended Template |
+|----------|---------------------|
+| Developer tools, CLI, OSS | `nerdy` |
+| Business, productivity | `corporate` |
+| Games, entertainment | `playful` |
+| Lifestyle, premium | `elegant` |
+| Finance, fintech | `bold` |
+| Social, consumer | `modern` |
+| Health, wellness | `minimal` |
+| Custom backgrounds | `showcase` |
+
+---
+
+## modern
+
+**Modern Vibrant** - Eye-catching gradient with floating device and clean captions
+
+- **Category:** modern
+- **Background:** Purple-pink diagonal gradient (`#667eea` → `#764ba2` → `#f093fb`)
+- **Caption:** Above device, SF Pro Display, dark text (`#021d2f`)
+- **Best for:** Consumer apps, social apps, general-purpose
+
+```
+appshot.template with template: "modern"
+```
+
+---
+
+## minimal
+
+**Minimal Clean** - Soft pastel background with elegant typography
+
+- **Category:** minimal
+- **Background:** Warm peach gradient (`#ffecd2` → `#fcb69f`)
+- **Caption:** Above device, Helvetica Neue, dark text (`#1b2a3a`)
+- **Best for:** Health apps, wellness, lifestyle
+
+```
+appshot.template with template: "minimal"
+```
+
+---
+
+## bold
+
+**Bold Impact** - Dark dramatic gradient with large device and overlay captions
+
+- **Category:** bold
+- **Background:** Dark purple diagonal gradient (`#0f0c29` → `#302b63` → `#24243e`)
+- **Caption:** Overlay at bottom, SF Pro Display, white text
+- **Best for:** Finance apps, security, premium features
+
+```
+appshot.template with template: "bold"
+```
+
+---
+
+## nerdy
+
+**Nerdy OSS** - Grid-lined midnight background with JetBrains Mono captions
+
+- **Category:** bold
+- **Background:** Auto-detect (uses background.png if present)
+- **Caption:** Overlay at bottom, JetBrains Mono Bold, mint green (`#7CFFCB`)
+- **Best for:** Developer tools, CLI apps, open source projects
+
+```
+appshot.template with template: "nerdy"
+```
+
+**Note:** Place a grid/terminal background image at `screenshots/iphone/background.png` for best results.
+
+---
+
+## elegant
+
+**Elegant Professional** - Sophisticated monochrome with floating device
+
+- **Category:** elegant
+- **Background:** Silver gradient (`#8e9eab` → `#eef2f3`)
+- **Caption:** Below device, Georgia serif, dark text (`#132235`)
+- **Best for:** Luxury apps, premium services, professional tools
+
+```
+appshot.template with template: "elegant"
+```
+
+---
+
+## showcase
+
+**Showcase** - Feature your app with custom backgrounds
+
+- **Category:** professional
+- **Background:** Auto-detect with cyan fallback (`#4facfe` → `#00f2fe`)
+- **Caption:** Above device, SF Pro Display, white text
+- **Best for:** Apps with strong visual branding, custom marketing assets
+
+```
+appshot.template with template: "showcase"
+```
+
+**Tip:** Add your branded background to `screenshots/iphone/background.png`
+
+---
+
+## playful
+
+**Playful Energy** - Bright, fun gradients perfect for games and entertainment apps
+
+- **Category:** playful
+- **Background:** Pink-yellow diagonal gradient (`#fa709a` → `#fee140` → `#fa709a`)
+- **Caption:** Above device, SF Pro Display, white text
+- **Best for:** Games, kids apps, entertainment, social
+
+```
+appshot.template with template: "playful"
+```
+
+---
+
+## corporate
+
+**Corporate Professional** - Clean, professional look for business and productivity apps
+
+- **Category:** professional
+- **Background:** Blue-teal gradient (`#0077BE` → `#33CCCC`)
+- **Caption:** Above device, Helvetica, dark text (`#0f1e2d`)
+- **Best for:** Business apps, B2B, enterprise, productivity
+
+```
+appshot.template with template: "corporate"
+```
+
+---
+
+## Applying Templates
+
+```
+# Apply a template
+appshot.template with template: "nerdy"
+
+# Preview without applying
+appshot.template with preview: "modern"
+
+# List all templates
+appshot.template with list: true
+```
+
+## Customizing After Template
+
+Templates set a starting point. Customize further with:
+
+```
+# Change gradient
+appshot.gradients with action: "apply", preset: "sunset"
+
+# Adjust device positioning
+appshot.config with device: "iphone", frameScale: 0.85, framePosition: 30
+
+# Change caption position
+appshot.config with device: "iphone", captionPosition: "below"
+```