shipscreens 0.1.5 → 0.1.7

package/cli/mcpBootstrap.js

@@ -0,0 +1,174 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const CLIENT_SPECS = {
+  claude: {
+    id: 'claude',
+    aliases: ['claude', 'claude-code'],
+    label: 'Claude Code',
+    configPath: '.mcp.json',
+    settingsKey: 'mcpServers',
+    createServer: ({ command, args }) => ({ command, args }),
+  },
+  cursor: {
+    id: 'cursor',
+    aliases: ['cursor'],
+    label: 'Cursor',
+    configPath: path.join('.cursor', 'mcp.json'),
+    settingsKey: 'mcpServers',
+    createServer: ({ command, args }) => ({ command, args }),
+  },
+  vscode: {
+    id: 'vscode',
+    aliases: ['vscode', 'vs-code', 'copilot', 'vscode-copilot', 'github-copilot'],
+    label: 'VS Code Copilot',
+    configPath: path.join('.vscode', 'mcp.json'),
+    settingsKey: 'servers',
+    createServer: ({ command, args }) => ({ type: 'stdio', command, args }),
+  },
+  gemini: {
+    id: 'gemini',
+    aliases: ['gemini', 'gemini-cli'],
+    label: 'Gemini CLI',
+    configPath: path.join('.gemini', 'settings.json'),
+    settingsKey: 'mcpServers',
+    createServer: ({ command, args }) => ({ command, args }),
+  },
+};
+
+const SUPPORTED_CLIENTS = Object.values(CLIENT_SPECS).map((spec) => spec.id);
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+async function pathExists(targetPath) {
+  try {
+    await fs.stat(targetPath);
+    return true;
+  } catch (err) {
+    if (err?.code === 'ENOENT') return false;
+    throw err;
+  }
+}
+
+function normalizeClientId(rawClient) {
+  const normalized = String(rawClient || '')
+    .trim()
+    .toLowerCase();
+  for (const spec of Object.values(CLIENT_SPECS)) {
+    if (spec.aliases.includes(normalized)) {
+      return spec.id;
+    }
+  }
+  return '';
+}
+
+export function listMcpBootstrapClients() {
+  return [...SUPPORTED_CLIENTS];
+}
+
+export function resolveMcpBootstrapClient(rawClient) {
+  const clientId = normalizeClientId(rawClient);
+  return clientId ? CLIENT_SPECS[clientId] : null;
+}
+
+export function createMcpServerCommand({
+  packageSpec = 'shipscreens@latest',
+  windowsCmdShim = false,
+} = {}) {
+  const normalizedPackageSpec = String(packageSpec || 'shipscreens@latest').trim() || 'shipscreens@latest';
+  if (windowsCmdShim) {
+    return {
+      command: 'cmd',
+      args: ['/c', 'npx', '--yes', normalizedPackageSpec, 'mcp', 'serve'],
+    };
+  }
+  return {
+    command: 'npx',
+    args: ['--yes', normalizedPackageSpec, 'mcp', 'serve'],
+  };
+}
+
+export async function runMcpInit({
+  client,
+  dir,
+  packageSpec,
+  windowsCmdShim = false,
+  force = false,
+} = {}) {
+  const clientSpec = resolveMcpBootstrapClient(client);
+  if (!clientSpec) {
+    throw new Error(
+      `Unknown --client "${client || ''}". Supported clients: ${listMcpBootstrapClients().join(', ')}`
+    );
+  }
+
+  const baseDir = path.resolve(process.cwd(), dir || '.');
+  const targetPath = path.join(baseDir, clientSpec.configPath);
+  const commandSpec = createMcpServerCommand({ packageSpec, windowsCmdShim });
+  const nextServer = clientSpec.createServer(commandSpec);
+  const targetExists = await pathExists(targetPath);
+
+  let root = {};
+  let shipscreensEntryChanged = true;
+  if (targetExists) {
+    try {
+      const existingText = await fs.readFile(targetPath, 'utf8');
+      const existingJson = JSON.parse(existingText);
+      if (!isPlainObject(existingJson)) {
+        throw new Error('top-level JSON value must be an object');
+      }
+      root = { ...existingJson };
+      const existingServers = root[clientSpec.settingsKey];
+      if (existingServers == null) {
+        root[clientSpec.settingsKey] = {};
+      } else if (!isPlainObject(existingServers)) {
+        if (!force) {
+          throw new Error(`${clientSpec.settingsKey} must be an object to merge ShipScreens into it`);
+        }
+        root[clientSpec.settingsKey] = {};
+      } else {
+        shipscreensEntryChanged =
+          JSON.stringify(existingServers.shipscreens || null) !== JSON.stringify(nextServer);
+      }
+    } catch (err) {
+      if (!force) {
+        throw new Error(
+          `Failed to merge existing ${clientSpec.configPath}. Pass --force to overwrite. ${err?.message || String(err)}`
+        );
+      }
+      root = {};
+      shipscreensEntryChanged = true;
+    }
+  }
+
+  const mergedRoot = isPlainObject(root) ? { ...root } : {};
+  const existingServerMap = isPlainObject(mergedRoot[clientSpec.settingsKey])
+    ? mergedRoot[clientSpec.settingsKey]
+    : {};
+  mergedRoot[clientSpec.settingsKey] = {
+    ...existingServerMap,
+    shipscreens: nextServer,
+  };
+
+  const serverCount = Object.keys(mergedRoot[clientSpec.settingsKey]).length;
+
+  await fs.mkdir(path.dirname(targetPath), { recursive: true });
+  await fs.writeFile(targetPath, `${JSON.stringify(mergedRoot, null, 2)}\n`, 'utf8');
+
+  return {
+    client: clientSpec.id,
+    clientLabel: clientSpec.label,
+    configPath: targetPath,
+    packageSpec: String(packageSpec || 'shipscreens@latest').trim() || 'shipscreens@latest',
+    settingsKey: clientSpec.settingsKey,
+    command: nextServer.command,
+    args: nextServer.args,
+    transport: nextServer.type || null,
+    windowsCmdShim: Boolean(windowsCmdShim),
+    mergedExistingConfig: targetExists,
+    shipscreensEntryChanged,
+    serverCount,
+  };
+}

package/cli/mcpServer.js

@@ -24,7 +24,7 @@ const TOOL_DEFINITIONS = [
   {
     name: 'shipscreens_templates',
     title: 'List shipped templates',
-    description: 'Returns available template IDs for init/wizard/agent-run.',
+    description: 'Returns available template IDs for init/wizard/write-starter-config/agent-run.',
     inputSchema: {
       type: 'object',
       additionalProperties: false,
@@ -35,6 +35,166 @@ const TOOL_DEFINITIONS = [
     },
     buildArgs: () => ['templates'],
   },
+  {
+    name: 'shipscreens_inspect_release_context',
+    title: 'Inspect release context',
+    description:
+      'Use this first when a coding agent needs release-safe App Store / Google Play screenshots from an existing repo. Summarizes config, Fastlane roots, devices/locales, missing assets, and the next ShipScreens command.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        workingDirectory: { type: 'string' },
+        dir: { type: 'string' },
+        configPath: { type: 'string' },
+        timeoutMs: { type: 'integer', minimum: 1000, maximum: 1800000 },
+      },
+    },
+    buildArgs: (args) => {
+      const commandArgs = ['inspect-release-context'];
+      pushOption(commandArgs, '--dir', args.dir);
+      pushOption(commandArgs, '--config', args.configPath);
+      return commandArgs;
+    },
+  },
+  {
+    name: 'shipscreens_plan_release',
+    title: 'Plan release screenshot run',
+    description:
+      'Use after shipscreens_inspect_release_context to choose the next safe ShipScreens command sequence for an existing repo. Returns blockers, questions, and exact validate/plan/agent-run commands without modifying files.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        workingDirectory: { type: 'string' },
+        dir: { type: 'string' },
+        configPath: { type: 'string' },
+        profile: { type: 'string', enum: ['appstore', 'playstore', 'any'] },
+        mode: { type: 'string', enum: ['raw', 'rendered'] },
+        outDir: { type: 'string' },
+        stageOutDir: { type: 'string' },
+        timeoutMs: { type: 'integer', minimum: 1000, maximum: 1800000 },
+      },
+    },
+    buildArgs: (args) => {
+      const commandArgs = ['plan-release'];
+      pushOption(commandArgs, '--dir', args.dir);
+      pushOption(commandArgs, '--config', args.configPath);
+      pushOption(commandArgs, '--profile', args.profile);
+      pushOption(commandArgs, '--mode', args.mode);
+      pushOption(commandArgs, '--out', args.outDir);
+      pushOption(commandArgs, '--stage-out', args.stageOutDir);
+      return commandArgs;
+    },
+  },
+  {
+    name: 'shipscreens_write_starter_config',
+    title: 'Write starter config',
+    description:
+      'Use when shipscreens_plan_release returns readiness=needs_config. Writes shipscreens.config.yml, copy.csv, and placeholder PNGs non-interactively so the agent can continue toward validate/build/verify/stage.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        workingDirectory: { type: 'string' },
+        dir: { type: 'string' },
+        profile: { type: 'string', enum: ['appstore', 'playstore', 'any'] },
+        slides: { type: 'integer', minimum: 1, maximum: 10 },
+        locales: { type: 'string' },
+        devices: { type: 'string' },
+        template: { type: 'string' },
+        outDir: { type: 'string' },
+        stageOutDir: { type: 'string' },
+        force: { type: 'boolean' },
+        timeoutMs: { type: 'integer', minimum: 1000, maximum: 1800000 },
+      },
+    },
+    buildArgs: (args) => {
+      const commandArgs = ['write-starter-config'];
+      pushOption(commandArgs, '--dir', args.dir);
+      pushOption(commandArgs, '--profile', args.profile);
+      pushOption(commandArgs, '--slides', args.slides);
+      pushOption(commandArgs, '--locales', args.locales);
+      pushOption(commandArgs, '--devices', args.devices);
+      pushOption(commandArgs, '--template', args.template);
+      pushOption(commandArgs, '--out', args.outDir);
+      pushOption(commandArgs, '--stage-out', args.stageOutDir);
+      pushFlag(commandArgs, '--force', args.force);
+      return commandArgs;
+    },
+  },
+  {
+    name: 'shipscreens_capture_screenshots',
+    title: 'Capture device or emulator screenshot',
+    description:
+      'Use when real screenshots are only visible on a connected Android device/emulator, booted iOS simulator, or libimobiledevice iOS device. Captures the current screen into a local source folder before import/build/verify/stage.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        workingDirectory: { type: 'string' },
+        dir: { type: 'string' },
+        platform: { type: 'string', enum: ['auto', 'android', 'ios-simulator', 'ios-device'] },
+        device: { type: 'string' },
+        outDir: { type: 'string' },
+        locale: { type: 'string' },
+        slot: { type: 'integer', minimum: 1, maximum: 99 },
+        name: { type: 'string' },
+        profile: { type: 'string', enum: ['appstore', 'playstore', 'any'] },
+        list: { type: 'boolean' },
+        timeoutMs: { type: 'integer', minimum: 1000, maximum: 1800000 },
+      },
+    },
+    buildArgs: (args) => {
+      const commandArgs = ['capture-screenshots'];
+      pushOption(commandArgs, '--dir', args.dir);
+      pushOption(commandArgs, '--platform', args.platform);
+      pushOption(commandArgs, '--device', args.device);
+      pushOption(commandArgs, '--out', args.outDir);
+      pushOption(commandArgs, '--locale', args.locale);
+      pushOption(commandArgs, '--slot', args.slot);
+      pushOption(commandArgs, '--name', args.name);
+      pushOption(commandArgs, '--profile', args.profile);
+      pushFlag(commandArgs, '--list', args.list);
+      return commandArgs;
+    },
+  },
+  {
+    name: 'shipscreens_import_screenshots',
+    title: 'Import existing screenshots',
+    description:
+      'Use after shipscreens_write_starter_config or when shipscreens_plan_release reports placeholder_assets. Copies existing screenshot files into the configured shipscreens.config.yml asset paths before validate/build/verify/stage.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        workingDirectory: { type: 'string' },
+        dir: { type: 'string' },
+        configPath: { type: 'string' },
+        fromDir: { type: 'string' },
+        locale: { type: 'string' },
+        profile: { type: 'string', enum: ['appstore', 'playstore', 'any'] },
+        outDir: { type: 'string' },
+        stageOutDir: { type: 'string' },
+        force: { type: 'boolean' },
+        allowPartial: { type: 'boolean' },
+        timeoutMs: { type: 'integer', minimum: 1000, maximum: 1800000 },
+      },
+    },
+    buildArgs: (args) => {
+      const commandArgs = ['import-screenshots'];
+      pushOption(commandArgs, '--dir', args.dir);
+      pushOption(commandArgs, '--config', args.configPath);
+      pushOption(commandArgs, '--from', args.fromDir);
+      pushOption(commandArgs, '--locale', args.locale);
+      pushOption(commandArgs, '--profile', args.profile);
+      pushOption(commandArgs, '--out', args.outDir);
+      pushOption(commandArgs, '--stage-out', args.stageOutDir);
+      pushFlag(commandArgs, '--force', args.force);
+      pushFlag(commandArgs, '--allow-partial', args.allowPartial);
+      return commandArgs;
+    },
+  },
   {
     name: 'shipscreens_validate',
     title: 'Validate config',
@@ -160,7 +320,8 @@ const TOOL_DEFINITIONS = [
   {
     name: 'shipscreens_agent_run',
     title: 'Run non-interactive pipeline',
-    description: 'Runs init (if needed) -> validate -> build -> verify in one command.',
+    description:
+      'Use when a coding agent should produce release-safe screenshot outputs. Runs init (if needed) -> validate -> build -> verify, with optional stage and agent proof reports, in one command.',
     inputSchema: {
       type: 'object',
       additionalProperties: false,
@@ -175,6 +336,10 @@ const TOOL_DEFINITIONS = [
         outDir: { type: 'string' },
         zip: { type: 'boolean' },
         profile: { type: 'string', enum: ['appstore', 'playstore', 'any'] },
+        stage: { type: 'boolean' },
+        stageOutDir: { type: 'string' },
+        reportJsonPath: { type: 'string' },
+        reportMarkdownPath: { type: 'string' },
         requirePro: { type: 'boolean' },
         force: { type: 'boolean' },
         timeoutMs: { type: 'integer', minimum: 1000, maximum: 1800000 },
@@ -190,7 +355,11 @@ const TOOL_DEFINITIONS = [
       pushOption(commandArgs, '--mode', args.mode);
       pushOption(commandArgs, '--out', args.outDir);
       pushOption(commandArgs, '--profile', args.profile);
+      pushOption(commandArgs, '--stage-out', args.stageOutDir);
+      pushOption(commandArgs, '--report-json', args.reportJsonPath);
+      pushOption(commandArgs, '--report-md', args.reportMarkdownPath);
       pushFlag(commandArgs, '--zip', args.zip);
+      pushFlag(commandArgs, '--stage', args.stage);
       pushFlag(commandArgs, '--require-pro', args.requirePro);
       pushFlag(commandArgs, '--force', args.force);
       return commandArgs;
@@ -446,7 +615,7 @@ export async function runMcpServer() {
           },
           serverInfo: SERVER_INFO,
           instructions:
-            'Use tools to run deterministic ShipScreens CLI workflows (validate/build/verify/stage/plan) in local or CI contexts.',
+            'Use shipscreens_inspect_release_context first, then shipscreens_plan_release. If readiness=needs_config, call shipscreens_write_starter_config. If no screenshot folder exists but the app is visible on a connected device/emulator, call shipscreens_capture_screenshots for each panel. If placeholder_assets remain, call shipscreens_import_screenshots or replace the PNGs before validate/build/verify/stage/plan/agent-run. Use deterministic ShipScreens workflows for release-safe App Store / Google Play screenshot outputs. Do not use this for translation-only, direct-upload-only, or template-gallery-only tasks.',
         });
         return;
       }

package/cli/schema.js

@@ -20,6 +20,12 @@ const DeviceId = z
   .max(64)
   .regex(/^[a-z0-9_-]+$/i, 'Expected a device id like iphone69 or pixel8');
 
+const VariantId = z
+  .string()
+  .min(1)
+  .max(48)
+  .regex(/^[a-z0-9][a-z0-9_-]{0,47}$/i, 'Expected variant id like ppo_a');
+
 const inferDevicePlatform = (deviceId) => {
   const def = DEVICE_LIBRARY[deviceId];
   const group = String(def?.group || '').toLowerCase();
@@ -207,6 +213,19 @@ export const ShipScreensConfigSchema = z
   .object({
     schemaVersion: z.literal(SHIPSCREENS_CONFIG_SCHEMA_VERSION).optional(),
     version: z.literal(SHIPSCREENS_CONFIG_SCHEMA_VERSION).optional(),
+    variant: VariantId.optional(),
+    experiment: z
+      .object({
+        variant: VariantId,
+      })
+      .strict()
+      .optional(),
+    asoExperiment: z
+      .object({
+        variant: VariantId,
+      })
+      .strict()
+      .optional(),
     output: OutputCompat.optional(),
     locales: z
       .array(

package/cli/variantScope.js

@@ -0,0 +1,58 @@
+import path from 'node:path';
+
+const VARIANT_ID_RE = /^[a-z0-9](?:[a-z0-9_-]{0,47})$/;
+
+const VARIANT_CONFIG_PATHS = [
+  ['asoExperiment', 'variant'],
+  ['experiment', 'variant'],
+  ['variant'],
+];
+
+function getByPath(obj, keys) {
+  let current = obj;
+  for (const key of keys) {
+    if (!current || typeof current !== 'object' || !(key in current)) return undefined;
+    current = current[key];
+  }
+  return current;
+}
+
+export function normalizeVariantId(rawValue, { sourceLabel = 'variant' } = {}) {
+  const value = String(rawValue || '')
+    .trim()
+    .toLowerCase();
+  if (!value) return null;
+  if (value.includes('/') || value.includes('\\') || value.includes('..')) {
+    throw new Error(
+      `Invalid ${sourceLabel} "${rawValue}". Use letters/numbers/-/_ only (no path separators).`
+    );
+  }
+  if (!VARIANT_ID_RE.test(value)) {
+    throw new Error(
+      `Invalid ${sourceLabel} "${rawValue}". Expected pattern: ^[a-z0-9][a-z0-9_-]{0,47}$`
+    );
+  }
+  return value;
+}
+
+export function resolveVariantScope({ variantFlag, config } = {}) {
+  const fromFlag = normalizeVariantId(variantFlag, { sourceLabel: '--variant' });
+  if (fromFlag) {
+    return { id: fromFlag, source: 'flag' };
+  }
+
+  for (const keys of VARIANT_CONFIG_PATHS) {
+    const value = getByPath(config, keys);
+    const normalized = normalizeVariantId(value, { sourceLabel: keys.join('.') });
+    if (normalized) {
+      return { id: normalized, source: keys.join('.') };
+    }
+  }
+
+  return { id: null, source: null };
+}
+
+export function applyVariantOutRoot({ outRoot, variantId } = {}) {
+  if (!variantId) return outRoot;
+  return path.join(outRoot, 'variants', variantId);
+}