shipscreens 0.1.5 → 0.1.6

package/README.md

@@ -1,6 +1,6 @@
 # ShipScreens CLI
 
-Build store screenshots as a build step.
+Use this when app-dev CI or MCP-enabled agents need deterministic store screenshot reruns as a build step.
 
 ## Quickstart
 ```bash
@@ -19,6 +19,7 @@ npx playwright install --with-deps chromium
 ```bash
 npx --yes shipscreens@latest validate
 npx --yes shipscreens@latest lock
+npx --yes shipscreens@latest copy check --strict --write-pseudo-csv out/copy-pseudo.csv --write-report-json out/copy-check-report.json
 npx --yes shipscreens@latest build --out out --zip
 npx --yes shipscreens@latest verify --out out --zip --profile appstore
 npx --yes shipscreens@latest stage --from out --out out/stage --profile appstore
@@ -31,6 +32,12 @@ Docs: https://shipscreens.com/tools/agent-cli/
 npx --yes shipscreens@latest mcp serve
 ```
 
+Fastest workspace bootstrap:
+```bash
+npx --yes shipscreens@latest mcp init --client cursor
+# use claude | vscode | gemini for other clients
+```
+
 ## Claude Code local setup (.mcp.json)
 ```json
 {
@@ -55,6 +62,31 @@ Windows users can force `npx` through `cmd /c`:
 }
 ```
 
+## Cursor project setup (.cursor/mcp.json)
+```json
+{
+  "mcpServers": {
+    "shipscreens": {
+      "command": "npx",
+      "args": ["--yes", "shipscreens@latest", "mcp", "serve"]
+    }
+  }
+}
+```
+
+## VS Code Copilot workspace setup (.vscode/mcp.json)
+```json
+{
+  "servers": {
+    "shipscreens": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["--yes", "shipscreens@latest", "mcp", "serve"]
+    }
+  }
+}
+```
+
 Gemini CLI setup (`.gemini/settings.json` in project or `~/.gemini/settings.json`):
 ```json
 {
@@ -66,3 +98,7 @@ Gemini CLI setup (`.gemini/settings.json` in project or `~/.gemini/settings.json
   }
 }
 ```
+
+## OpenAI Responses API note
+- Default `tool_choice=auto` lets the model decide whether to call tools.
+- Use `tool_choice=required` when the workflow must force a ShipScreens tool call.

package/bin/shipscreens.js

@@ -16,8 +16,10 @@ import { runAuth } from '../cli/commands/auth.js';
 import { runInit } from '../cli/commands/init.js';
 import { runWizard } from '../cli/commands/wizard.js';
 import { runCopyImport } from '../cli/commands/copyImport.js';
+import { runCopyCheck } from '../cli/commands/copyCheck.js';
 import { resolveCliAuth } from '../cli/auth.js';
 import { listTemplateIds, resolveTemplateConfig } from '../cli/templateConfig.js';
+import { listMcpBootstrapClients, runMcpInit } from '../cli/mcpBootstrap.js';
 import { runMcpServer } from '../cli/mcpServer.js';
 import { loadShipScreensConfig } from '../cli/loadConfig.js';
 import { collectAssetReferences } from '../cli/assetRefs.js';
@@ -30,6 +32,7 @@ import {
 
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const DEMO_SCREENS_DIR = path.join(PACKAGE_ROOT, 'cli', 'assets', 'demo-screens');
+const MCP_BOOTSTRAP_CLIENT_LIST = listMcpBootstrapClients().join('|');
 
 function printHelp() {
   console.log(`ShipScreens CLI
@@ -37,20 +40,22 @@ function printHelp() {
 Usage:
   shipscreens init [--dir <path>] [--slides <n>] [--locales <id,id>] [--devices <id,id>] [--force] [--wizard] [--style <value>] [--template <id>]
   shipscreens wizard [--dir <path>] [--force] [--style <value>] [--template <id>] [--defaults]
-  shipscreens demo [--out <dir>] [--slides <n>] [--locales <id,id>] [--devices <id,id>] [--template <id>] [--mode <raw|rendered>] [--zip-out <path>] [--profile <appstore|playstore|any>] [--force]
-  shipscreens agent-run [--dir <path>] [--slides <n>] [--locales <id,id>] [--devices <id,id>] [--style <value>] [--template <id>] [--mode <raw|rendered>] [--out <dir>] [--zip] [--profile <appstore|playstore|any>] [--require-pro] [--force]
+  shipscreens demo [--out <dir>] [--slides <n>] [--locales <id,id>] [--devices <id,id>] [--template <id>] [--mode <raw|rendered>] [--zip-out <path>] [--profile <appstore|playstore|any>] [--variant <id>] [--force]
+  shipscreens agent-run [--dir <path>] [--slides <n>] [--locales <id,id>] [--devices <id,id>] [--style <value>] [--template <id>] [--mode <raw|rendered>] [--out <dir>] [--zip] [--profile <appstore|playstore|any>] [--variant <id>] [--require-pro] [--force]
   shipscreens devices [--json]
   shipscreens templates [--json]
   shipscreens validate [-c shipscreens.config.yml]
   shipscreens lock [-c shipscreens.config.yml] [--out shipscreens.lock.json] [--check]
-  shipscreens build [-c shipscreens.config.yml] [--mode shipscreens|rendered|raw|frameit] [--format dir|zip] [--out <dir>] [--zip] [--zip-out <path>] [--clean]
-  shipscreens verify [-c shipscreens.config.yml] [--out <dir>] [--zip] [--zip-out <path>] [--profile appstore|playstore|any]
-  shipscreens stage [-c shipscreens.config.yml] [--from <dir>] --out <dir> [--profile appstore|playstore|any]
+  shipscreens build [-c shipscreens.config.yml] [--mode shipscreens|rendered|raw|frameit] [--format dir|zip] [--out <dir>] [--zip] [--zip-out <path>] [--variant <id>] [--clean]
+  shipscreens verify [-c shipscreens.config.yml] [--out <dir>] [--zip] [--zip-out <path>] [--profile appstore|playstore|any] [--variant <id>]
+  shipscreens stage [-c shipscreens.config.yml] [--from <dir>] --out <dir> [--profile appstore|playstore|any] [--variant <id>]
   shipscreens export framefile [-c shipscreens.config.yml] [--ios-dir fastlane/screenshots] [--strings-encoding utf8|utf16le|utf16be] [--framefile-strategy merge|overwrite] [--check]
-  shipscreens plan [-c shipscreens.config.yml] [--out <dir>] [--zip-out <path>] [--profile appstore|playstore|any] [--json]
+  shipscreens plan [-c shipscreens.config.yml] [--out <dir>] [--zip-out <path>] [--profile appstore|playstore|any] [--variant <id>] [--json]
   shipscreens copy import [-c shipscreens.config.yml] [--csv <path>] [--import-mode merge|replace]
+  shipscreens copy check [-c shipscreens.config.yml] [--pseudo-locale <id>] [--pseudo-expand <n>] [--max-header-units <n>] [--max-sub-units <n>] [--max-token-length <n>] [--write-pseudo-csv <path>] [--write-report-json <path>] [--strict]
   shipscreens auth <login|finish|status|logout> [--domain <cognito-domain>] [--client-id <id>] [--api-base <url>] [--port <port>] [--manual] [--redirect-url <url>]
   shipscreens mcp serve
+  shipscreens mcp init --client <${MCP_BOOTSTRAP_CLIENT_LIST}> [--dir <path>] [--package-spec <spec>] [--windows-cmd-shim] [--force]
 
 Commands:
   init       Create a starter config + placeholder PNGs + copy.csv
@@ -67,8 +72,9 @@ Commands:
   export     Export helper files for other tools
   plan       Print a deterministic build/stage plan (JSON)
   copy       Import locale copy from copy.csv into shipscreens.config.yml
+    check    Run pseudo-locale + long-string checks for submission quality
   auth       Manage CLI sign-in (required to remove watermarks in CLI exports)
-  mcp        Start a stdio MCP server that exposes ShipScreens tools
+  mcp        Start a stdio MCP server or write workspace-local MCP config
 
 Options:
   -c, --config <path>   Path to shipscreens.config.yml (default: ./shipscreens.config.yml)
@@ -83,9 +89,18 @@ Options:
   --defaults            Skip the style prompt in wizard (use default/no style)
   --csv <path>          Path to copy.csv for copy import (default: ./copy.csv)
   --import-mode <mode>  CSV import mode (merge|replace, default: merge)
+  --pseudo-locale <id>  Locale id prefix for pseudo-locale checks (default: qps-ploc)
+  --pseudo-expand <n>   Pseudo-locale expansion ratio (default: 0.35)
+  --max-header-units <n>  Visual-width budget for headers (default: 34)
+  --max-sub-units <n>   Visual-width budget for subtitles (default: 54)
+  --max-token-length <n>  Long-token budget before wrap risk warning (default: 22)
+  --write-pseudo-csv <path>  Write pseudo-locale CSV rows for manual QA
+  --write-report-json <path>  Write full copy-check report JSON for CI/QA artifacts
+  --strict              Fail copy check when warnings are found
   --out <path>          Lock output file path (lock) or output root directory (build/verify/stage)
   --zip-out <path>      ZIP output file path (default: <out>/fastlane_assets.zip)
   --profile <appstore|playstore|any>  Strict verification/staging rules per store (default: any)
+  --variant <id>        ASO experiment variant scope (writes under variants/<id>/...).
   --from <dir>          Source output root for staging (default: config dir)
   --check               Verify outputs are valid/up-to-date (no write)
   --json                Emit machine-readable JSON (most commands; plan always emits JSON)
@@ -102,6 +117,9 @@ Options:
   --android-dir <path>  Android output directory (default: fastlane/metadata/android)
   --strings-encoding <utf8|utf16le|utf16be>  Encoding for generated .strings (export framefile / build --mode frameit) (default: utf8)
   --framefile-strategy <merge|overwrite>  How to handle fastlane/screenshots/Framefile.json (export framefile / build --mode frameit) (default: merge)
+  --client <id>        MCP bootstrap target (${MCP_BOOTSTRAP_CLIENT_LIST}) for "mcp init"
+  --package-spec <spec>  Package spec used in generated MCP config (default: shipscreens@latest)
+  --windows-cmd-shim   Use "cmd /c npx ..." in the generated MCP config
   -h, --help            Show help
 
 Quickstart (no browser):
@@ -110,6 +128,7 @@ Quickstart (no browser):
   shipscreens verify --out out --zip --profile appstore
 
 MCP quickstart:
+  shipscreens mcp init --client cursor
   shipscreens mcp serve
 `);
 }
@@ -180,6 +199,15 @@ async function pathExists(targetPath) {
   }
 }
 
+function parseNumericFlag(name, value) {
+  if (value == null || value === '') return undefined;
+  const num = Number(value);
+  if (!Number.isFinite(num)) {
+    throw new Error(`Invalid --${name} value: ${value}`);
+  }
+  return num;
+}
+
 async function loadDemoScreenPngs() {
   try {
     const entries = await fs.readdir(DEMO_SCREENS_DIR);
@@ -243,6 +271,7 @@ async function main() {
       'strings-encoding': { type: 'string' },
       'framefile-strategy': { type: 'string' },
       profile: { type: 'string' },
+      variant: { type: 'string' },
       from: { type: 'string' },
       json: { type: 'boolean' },
       'require-pro': { type: 'boolean' },
@@ -265,6 +294,17 @@ async function main() {
       defaults: { type: 'boolean' },
       csv: { type: 'string' },
       'import-mode': { type: 'string' },
+      'pseudo-locale': { type: 'string' },
+      'pseudo-expand': { type: 'string' },
+      'max-header-units': { type: 'string' },
+      'max-sub-units': { type: 'string' },
+      'max-token-length': { type: 'string' },
+      'write-pseudo-csv': { type: 'string' },
+      'write-report-json': { type: 'string' },
+      strict: { type: 'boolean' },
+      client: { type: 'string' },
+      'package-spec': { type: 'string' },
+      'windows-cmd-shim': { type: 'boolean' },
       help: { type: 'boolean', short: 'h' },
     },
   });
@@ -345,11 +385,37 @@ async function main() {
 
   if (command === 'mcp') {
     const subcommand = positionals[1] || 'serve';
-    if (subcommand !== 'serve') {
-      throw new Error(`Unknown mcp command: ${subcommand}`);
+    if (subcommand === 'serve') {
+      await runMcpServer();
+      return;
     }
-    await runMcpServer();
-    return;
+    if (subcommand === 'init') {
+      const result = await runMcpInit({
+        client: values.client,
+        dir: values.dir,
+        packageSpec: values['package-spec'],
+        windowsCmdShim: values['windows-cmd-shim'],
+        force: values.force,
+      });
+      const commandSummary = [result.command, ...result.args].join(' ');
+      emitPayload(
+        'mcp init',
+        result,
+        [
+          `OK: wrote ${result.clientLabel} MCP config -> ${result.configPath}`,
+          `- settings key: ${result.settingsKey}`,
+          result.transport ? `- transport: ${result.transport}` : null,
+          `- command: ${commandSummary}`,
+          `- merged existing config: ${result.mergedExistingConfig ? 'yes' : 'no'}`,
+          `- shipscreens entry changed: ${result.shipscreensEntryChanged ? 'yes' : 'no'}`,
+          `- total servers at key: ${result.serverCount}`,
+        ]
+          .filter(Boolean)
+          .join('\n')
+      );
+      return;
+    }
+    throw new Error(`Unknown mcp command: ${subcommand}`);
   }
 
   if (command === 'wizard') {
@@ -493,6 +559,7 @@ async function main() {
       mode,
       outDir: buildOutDir,
       zipOut,
+      variant: values.variant,
       clean: true,
       cliAuthToken,
       cliAuthProfile,
@@ -504,6 +571,7 @@ async function main() {
       zipOut,
       zip: true,
       profile,
+      variant: values.variant,
     });
 
     const stageResult = await runStage({
@@ -511,6 +579,7 @@ async function main() {
       fromDir: buildOutDir,
       outDir: stageOutDir,
       profile,
+      variant: values.variant,
     });
 
     const summary = [
@@ -532,6 +601,7 @@ async function main() {
         stageOutDir,
         mode,
         profile,
+        variant: values.variant || null,
         init: initResult,
         build: result,
         verify: verifyResult,
@@ -637,6 +707,7 @@ async function main() {
       iosDir: values['ios-dir'],
       androidDir: values['android-dir'],
       zipOut,
+      variant: values.variant,
       stringsEncoding: values['strings-encoding'],
       framefileStrategy: values['framefile-strategy'],
       clean: values.clean,
@@ -652,6 +723,7 @@ async function main() {
       zipOut,
       zip,
       profile,
+      variant: values.variant,
     });
 
     const summary = [
@@ -671,6 +743,7 @@ async function main() {
         format,
         mode,
         profile,
+        variant: values.variant || null,
         requirePro,
         build: result,
         verify: verifyResult,
@@ -705,6 +778,41 @@ async function main() {
       );
       return;
     }
+    if (subcommand === 'check') {
+      const result = await runCopyCheck({
+        configPath,
+        pseudoLocale: values['pseudo-locale'],
+        pseudoExpand: parseNumericFlag('pseudo-expand', values['pseudo-expand']),
+        maxHeaderUnits: parseNumericFlag('max-header-units', values['max-header-units']),
+        maxSubUnits: parseNumericFlag('max-sub-units', values['max-sub-units']),
+        maxTokenLength: parseNumericFlag('max-token-length', values['max-token-length']),
+        writePseudoCsv: values['write-pseudo-csv'],
+        writeReportJson: values['write-report-json'],
+      });
+
+      const sample = result.issues.slice(0, 8);
+      const lines = [
+        `OK: copy check (${result.locales} locale(s) x ${result.slides} slide(s))`,
+        `- issues: ${result.issueCount}`,
+        `- pseudo locale: ${result.pseudoLocale} (expand=${result.pseudoExpand})`,
+        `- limits: header=${result.limits.headerUnits}, sub=${result.limits.subUnits}, token=${result.limits.tokenLength}`,
+      ];
+      if (result.pseudoCsvPath) lines.push(`- pseudo csv: ${result.pseudoCsvPath}`);
+      if (result.reportJsonPath) lines.push(`- report json: ${result.reportJsonPath}`);
+      if (sample.length) {
+        lines.push('- sample warnings:');
+        sample.forEach((issue) => {
+          lines.push(`  - [${issue.type}] slide ${issue.slide} ${issue.localeId} ${issue.field}: ${issue.detail}`);
+        });
+      }
+
+      if (values.strict && result.issueCount > 0) {
+        throw new Error(`copy check failed (--strict): ${result.issueCount} issue(s)\n${lines.join('\n')}`);
+      }
+
+      emitPayload('copy check', result, lines.join('\n'));
+      return;
+    }
     throw new Error(`Unknown copy command: ${subcommand || '(missing)'}`);
   }
 
@@ -750,6 +858,7 @@ async function main() {
       iosDir: values['ios-dir'],
       androidDir: values['android-dir'],
       zipOut,
+      variant: values.variant,
       stringsEncoding: values['strings-encoding'],
       framefileStrategy: values['framefile-strategy'],
       clean: values.clean,
@@ -766,7 +875,15 @@ async function main() {
     if (result.zipPath) summary.push(`zip -> ${result.zipPath}`);
     emitPayload(
       'build',
-      { configPath, format, mode: values.mode || 'rendered', outDir: outDir || null, zipOut: zipOut || null, ...result },
+      {
+        configPath,
+        format,
+        mode: values.mode || 'rendered',
+        outDir: outDir || null,
+        zipOut: zipOut || null,
+        variant: values.variant || null,
+        ...result,
+      },
       summary.join(', ')
     );
     return;
@@ -783,6 +900,7 @@ async function main() {
       zipOut: rawZipOut || undefined,
       zip: values.zip || Boolean(rawZipOut),
       profile: values.profile,
+      variant: values.variant,
     });
     const summary = [
       `OK: verified`,
@@ -799,6 +917,7 @@ async function main() {
         outDir: rawOut || null,
         zipOut: rawZipOut || null,
         profile: values.profile || null,
+        variant: values.variant || null,
         ...result,
       },
       summary.join(', ')
@@ -814,6 +933,7 @@ async function main() {
       fromDir: rawFrom || undefined,
       outDir: rawOut || undefined,
       profile: values.profile,
+      variant: values.variant,
     });
     const details = result.iosVariant ? `, ios=${result.iosVariant}` : '';
     emitPayload(
@@ -832,6 +952,7 @@ async function main() {
       androidDir: values['android-dir'],
       zipOut: values['zip-out'],
       profile: values.profile,
+      variant: values.variant,
     });
     process.stdout.write(JSON.stringify(plan, null, 2) + '\n');
     return;

package/cli/auth.js

@@ -198,6 +198,10 @@ async function refreshTokens({ domain, clientId, refreshToken }) {
   return resp.json();
 }
 
+function isInvalidGrantError(error) {
+  return /invalid_grant/i.test(String(error?.message || error || ''));
+}
+
 async function fetchProfile({ apiBase, token }) {
   if (!token) return null;
   const resp = await fetch(`${apiBase}/me`, {
@@ -392,7 +396,15 @@ export async function resolveCliAuth({ requirePro = false } = {}) {
       throw new Error('SHIPSCREENS_COGNITO_DOMAIN is required when using SHIPSCREENS_REFRESH_TOKEN.');
     }
     const clientId = process.env.SHIPSCREENS_CLIENT_ID || DEFAULT_CLIENT_ID;
-    const tokens = await refreshTokens({ domain, clientId, refreshToken: envRefresh });
+    let tokens;
+    try {
+      tokens = await refreshTokens({ domain, clientId, refreshToken: envRefresh });
+    } catch (error) {
+      if (!requirePro) {
+        return { token: null, profile: null, source: 'env_refresh_invalid' };
+      }
+      throw error;
+    }
     const token = tokens.id_token;
     const profile = await fetchProfile({ apiBase: DEFAULT_API_BASE, token }).catch(() => null);
     if (requirePro && !profile?.isPro) {
@@ -413,16 +425,24 @@ export async function resolveCliAuth({ requirePro = false } = {}) {
   let updated = false;
   if (isExpired(session.expires_at)) {
     if (session.refresh_token && session.domain && session.client_id) {
-      const tokens = await refreshTokens({
-        domain: session.domain,
-        clientId: session.client_id,
-        refreshToken: session.refresh_token,
-      });
-      token = tokens.id_token;
-      session.id_token = tokens.id_token;
-      session.access_token = tokens.access_token;
-      session.expires_at = resolveExpiry(tokens.expires_in);
-      updated = true;
+      try {
+        const tokens = await refreshTokens({
+          domain: session.domain,
+          clientId: session.client_id,
+          refreshToken: session.refresh_token,
+        });
+        token = tokens.id_token;
+        session.id_token = tokens.id_token;
+        session.access_token = tokens.access_token;
+        session.expires_at = resolveExpiry(tokens.expires_in);
+        updated = true;
+      } catch (error) {
+        if (requirePro) throw error;
+        token = null;
+        if (isInvalidGrantError(error)) {
+          await clearAuth();
+        }
+      }
     } else {
       token = null;
     }

package/cli/commands/build.js

@@ -9,6 +9,7 @@ import { startRendererServer } from '../rendererServer.js';
 import { getPackageRoot } from '../packageRoot.js';
 import { writeFastlaneZip } from '../fastlaneZip.js';
 import { resolveOutRoot, resolveOutputPath, resolveZipOutPath } from '../outputPaths.js';
+import { applyVariantOutRoot, resolveVariantScope } from '../variantScope.js';
 import { runExportFramefile } from './exportFramefile.js';
 import {
   cleanBuildOutputs,
@@ -70,10 +71,13 @@ export async function runBuild({
   clean = false,
   cliAuthToken,
   cliAuthProfile,
+  variant,
 } = {}) {
   await runValidate({ configPath });
   const { config, configDir } = await loadShipScreensConfig(configPath);
-  const outRoot = resolveOutRoot({ configDir, outDir });
+  const baseOutRoot = resolveOutRoot({ configDir, outDir });
+  const variantScope = resolveVariantScope({ variantFlag: variant, config });
+  const outRoot = applyVariantOutRoot({ outRoot: baseOutRoot, variantId: variantScope.id });
   if (!process.env.VITE_API_ENDPOINT) {
     process.env.VITE_API_ENDPOINT = process.env.SHIPSCREENS_API_ENDPOINT || 'https://api.shipscreens.com';
   }
@@ -201,6 +205,8 @@ export async function runBuild({
       iosDir: resolvedIosDir,
       androidDir: resolvedAndroidDir,
       zipPath: resolvedZipOut,
+      variant: variantScope.id,
+      variantSource: variantScope.source,
       locales: locales.length,
       slides: slideCount,
       iosDevices: iosDevices.length,
@@ -354,6 +360,8 @@ export async function runBuild({
     iosDir: resolvedIosDir,
     androidDir: resolvedAndroidDir,
     zipPath: resolvedZipOut,
+    variant: variantScope.id,
+    variantSource: variantScope.source,
     locales: locales.length,
     slides: slideCount,
     iosDevices: iosDevices.length,