shipscreens 0.1.0

package/cli/schema.js

@@ -0,0 +1,290 @@
+import { z } from 'zod';
+import { isDisallowedPath, normalizeRepoRelativePath } from './pathUtils.js';
+
+export const SHIPSCREENS_CONFIG_SCHEMA_VERSION = 1;
+
+const HexColor = z
+  .string()
+  .regex(/^#([0-9a-f]{3}|[0-9a-f]{6})$/i, 'Expected hex color like #fff or #ffffff');
+
+const LocaleId = z
+  .string()
+  .min(1)
+  .max(64)
+  .regex(/^[A-Za-z0-9-]+$/, 'Expected a BCP-47 style locale id (e.g. en-US)');
+
+const DeviceId = z
+  .string()
+  .min(1)
+  .max(64)
+  .regex(/^[a-z0-9_-]+$/i, 'Expected a device id like iphone69 or pixel8');
+
+const LayoutMode = z.enum(['top', 'bottom', 'split']);
+const BadgeType = z.enum(['none', 'stars', 'award', 'download', 'googleplay']);
+const FrameColor = z.enum(['black', 'silver', 'titanium', 'blue', 'gold']);
+const FontName = z.enum(['Inter', 'Roboto', 'Montserrat', 'Playfair Display', 'Merriweather', 'System']);
+const Orientation = z.enum(['portrait', 'landscape']);
+
+const RepoRelativePath = z
+  .string()
+  .min(1)
+  .max(2048)
+  .refine((value) => !isDisallowedPath(value), 'Expected a project-relative file path (no URLs/absolute paths)')
+  .transform((value) => normalizeRepoRelativePath(value))
+  .refine((value) => value.length > 0, 'Expected a repo-relative file path');
+
+const Background = z
+  .union([
+    z
+      .object({
+        type: z.literal('solid'),
+        color: HexColor,
+      })
+      .strict(),
+    z
+      .object({
+        type: z.literal('transparent'),
+      })
+      .strict(),
+    z
+      .object({
+        type: z.literal('gradient'),
+        start: HexColor,
+        end: HexColor,
+        angle: z.number().min(0).max(360).optional(),
+      })
+      .strict(),
+    z
+      .object({
+        type: z.literal('image'),
+        path: RepoRelativePath,
+        blur: z.number().min(0).max(64).optional(),
+        opacity: z.number().min(0).max(100).optional(),
+      })
+      .strict(),
+  ])
+  .default({ type: 'solid', color: '#ffffff' });
+
+const Badge = z
+  .object({
+    id: z.string().min(1).max(64).regex(/^[a-z0-9_-]+$/i, 'Expected a badge id like rating_5star'),
+    path: RepoRelativePath,
+  })
+  .strict();
+
+const Assets = z
+  .object({
+    background: Background.optional(),
+    logo: z
+      .object({
+        path: RepoRelativePath,
+      })
+      .strict()
+      .optional(),
+    badges: z.array(Badge).optional(),
+  })
+  .strict()
+  .optional();
+
+const Style = z
+  .object({
+    textColor: HexColor.optional(),
+    layoutMode: LayoutMode.optional(),
+    topSpacing: z.number().min(0).max(30).optional(),
+    deviceScale: z.number().min(0.5).max(2.0).optional(),
+    frameColor: FrameColor.optional(),
+    selectedFont: FontName.optional(),
+    badgeType: BadgeType.optional(),
+    headerSize: z.number().min(24).max(200).optional(),
+    subHeaderSize: z.number().min(12).max(120).optional(),
+    orientation: Orientation.optional(),
+  })
+  .strict()
+  .optional();
+
+const SlideLayoutOverride = z
+  .object({
+    layoutMode: LayoutMode.optional(),
+    topSpacing: z.number().min(0).max(30).optional(),
+    deviceScale: z.number().min(0.5).max(2.0).optional(),
+  })
+  .strict()
+  .optional();
+
+const SlideText = z
+  .object({
+    header: z.string(),
+    sub: z.string(),
+  })
+  .strict();
+
+const Slide = z
+  .object({
+    id: z.union([z.number().int().positive(), z.string().min(1).max(64)]),
+    screenshot: z
+      .object({
+        path: RepoRelativePath,
+      })
+      .strict(),
+    screenshotsByLocale: z.record(LocaleId, RepoRelativePath).optional(),
+    copy: z
+      .union([
+        z
+          .object({
+            title: z.string().min(1),
+            subtitle: z.string().min(1).optional(),
+          })
+          .strict(),
+        z.record(LocaleId, SlideText),
+      ])
+      .optional(),
+    text: z.record(LocaleId, SlideText),
+    layoutOverride: SlideLayoutOverride,
+  })
+  .strict();
+
+const OutputCompat = z
+  .object({
+    directory: z.string().min(1).optional(),
+    androidDirectory: z.string().min(1).optional(),
+    mode: z.enum(['locale', 'device']).optional(),
+    ios: z
+      .object({
+        type: z.enum(['fastlane_screenshots']).optional(),
+        path: z.string().min(1),
+      })
+      .strict()
+      .optional(),
+    android: z
+      .object({
+        type: z.enum(['fastlane_supply']).optional(),
+        path: z.string().min(1),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict()
+  .transform((output) => {
+    const directory = output.directory || output.ios?.path || 'fastlane/screenshots';
+    const androidDirectory = output.androidDirectory || output.android?.path || 'fastlane/metadata/android';
+    const mode = output.mode || 'locale';
+    return { directory, androidDirectory, mode };
+  });
+
+export const ShipScreensConfigSchema = z
+  .object({
+    schemaVersion: z.literal(SHIPSCREENS_CONFIG_SCHEMA_VERSION).optional(),
+    version: z.literal(SHIPSCREENS_CONFIG_SCHEMA_VERSION).optional(),
+    output: OutputCompat.optional(),
+    locales: z
+      .array(
+        z
+          .object({
+            id: LocaleId,
+            name: z.string().min(1).optional(),
+          })
+          .strict()
+      )
+      .min(1),
+    devices: z
+      .array(
+        z
+          .object({
+            id: DeviceId,
+            platform: z.enum(['ios', 'android']).optional(),
+            androidBucket: z
+              .enum([
+                'phoneScreenshots',
+                'sevenInchScreenshots',
+                'tenInchScreenshots',
+                'tvScreenshots',
+                'wearScreenshots',
+              ])
+              .optional(),
+            label: z.string().min(1).optional(),
+          })
+          .strict()
+      )
+      .min(1),
+    assets: Assets,
+    style: Style,
+    slides: z.array(Slide).min(1),
+  })
+  .strict()
+  .superRefine((config, ctx) => {
+    if (config.schemaVersion == null && config.version == null) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `Missing schemaVersion (or version): expected ${SHIPSCREENS_CONFIG_SCHEMA_VERSION}`,
+        path: ['schemaVersion'],
+      });
+    }
+    if (config.schemaVersion != null && config.version != null && config.schemaVersion !== config.version) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `schemaVersion (${config.schemaVersion}) must match version (${config.version})`,
+        path: ['version'],
+      });
+    }
+
+    const unique = (items, label, keyFn) => {
+      const seen = new Set();
+      items.forEach((item, idx) => {
+        const key = keyFn(item);
+        if (seen.has(key)) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `Duplicate ${label}: ${key}`,
+            path: [label, idx, 'id'],
+          });
+        }
+        seen.add(key);
+      });
+    };
+
+    unique(config.locales, 'locales', (l) => l.id);
+    unique(config.devices, 'devices', (d) => d.id);
+    if (config.assets?.badges) unique(config.assets.badges, 'assets.badges', (b) => b.id);
+    unique(config.slides, 'slides', (s) => String(s.id));
+
+    const localeIds = new Set(config.locales.map((l) => l.id));
+
+    config.slides.forEach((slide, slideIdx) => {
+      for (const localeId of Object.keys(slide.text || {})) {
+        if (!localeIds.has(localeId)) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `Slide references unknown locale: ${localeId}`,
+            path: ['slides', slideIdx, 'text', localeId],
+          });
+        }
+      }
+
+      for (const localeId of config.locales.map((l) => l.id)) {
+        if (!slide.text?.[localeId]) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `Missing slide text for locale: ${localeId}`,
+            path: ['slides', slideIdx, 'text'],
+          });
+        }
+      }
+
+      if (slide.screenshotsByLocale) {
+        for (const localeId of Object.keys(slide.screenshotsByLocale)) {
+          if (!localeIds.has(localeId)) {
+            ctx.addIssue({
+              code: z.ZodIssueCode.custom,
+              message: `screenshotsByLocale references unknown locale: ${localeId}`,
+              path: ['slides', slideIdx, 'screenshotsByLocale', localeId],
+            });
+          }
+        }
+      }
+    });
+  })
+  .transform((config) => {
+    const schemaVersion = config.schemaVersion ?? config.version ?? SHIPSCREENS_CONFIG_SCHEMA_VERSION;
+    const { version, ...rest } = config;
+    return { ...rest, schemaVersion };
+  });

package/cli/snapshotFromConfig.js

@@ -0,0 +1,116 @@
+import path from 'node:path';
+import { fileToDataUrl } from './dataUrl.js';
+
+function toLocaleState(locale) {
+  return {
+    id: locale.id,
+    name: locale.name || locale.id,
+    flag: '',
+  };
+}
+
+export async function buildSnapshotFromConfig({ config, configDir }) {
+  const locales = (config.locales || []).map(toLocaleState);
+  const localeIds = locales.map((l) => l.id);
+
+  const bgType = config.assets?.background?.type || 'solid';
+  const normalizedBgType =
+    bgType === 'image'
+      ? 'image'
+      : bgType === 'gradient'
+      ? 'gradient'
+      : bgType === 'transparent'
+      ? 'transparent'
+      : 'solid';
+  const style = config.style || {};
+  const snapshot = {
+    bgType: normalizedBgType,
+    bgColor: '#ffffff',
+    gradientStart: '#e0c3fc',
+    gradientEnd: '#8ec5fc',
+    gradientAngle: 135,
+    bgBlur: 0,
+    bgOpacity: 0,
+    deviceScale: 1.0,
+    orientation: 'portrait',
+    deviceId: config.devices?.[0]?.id || 'iphone69',
+    topSpacing: 8,
+    badgeType: 'none',
+    layoutMode: 'top',
+    frameColor: 'black',
+    locales,
+    currentLocaleId: localeIds[0] || 'en-US',
+    activeSlideIndex: 0,
+    slides: [],
+    textColor: '#1e293b',
+    headerSize: 96,
+    subHeaderSize: 48,
+    selectedFont: 'Inter',
+    selectedBatchDevices: (config.devices || []).map((d) => d.id),
+    bgImage: null,
+    logoImage: null,
+  };
+
+  if (style.textColor) snapshot.textColor = style.textColor;
+  if (style.layoutMode) snapshot.layoutMode = style.layoutMode;
+  if (typeof style.topSpacing === 'number') snapshot.topSpacing = style.topSpacing;
+  if (typeof style.deviceScale === 'number') snapshot.deviceScale = style.deviceScale;
+  if (style.frameColor) snapshot.frameColor = style.frameColor;
+  if (style.selectedFont) snapshot.selectedFont = style.selectedFont;
+  if (style.badgeType) snapshot.badgeType = style.badgeType;
+  if (typeof style.headerSize === 'number') snapshot.headerSize = style.headerSize;
+  if (typeof style.subHeaderSize === 'number') snapshot.subHeaderSize = style.subHeaderSize;
+  if (style.orientation) snapshot.orientation = style.orientation;
+
+  if (config.assets?.background?.type === 'solid') {
+    snapshot.bgType = 'solid';
+    snapshot.bgColor = config.assets.background.color;
+  } else if (config.assets?.background?.type === 'transparent') {
+    snapshot.bgType = 'transparent';
+  } else if (config.assets?.background?.type === 'gradient') {
+    snapshot.bgType = 'gradient';
+    snapshot.gradientStart = config.assets.background.start;
+    snapshot.gradientEnd = config.assets.background.end;
+    if (typeof config.assets.background.angle === 'number') snapshot.gradientAngle = config.assets.background.angle;
+  } else if (config.assets?.background?.type === 'image') {
+    snapshot.bgType = 'image';
+    snapshot.bgImage = await fileToDataUrl(path.resolve(configDir, config.assets.background.path));
+    if (typeof config.assets.background.blur === 'number') snapshot.bgBlur = config.assets.background.blur;
+    if (typeof config.assets.background.opacity === 'number') {
+      const opacity = config.assets.background.opacity;
+      snapshot.bgOpacity = opacity <= 1 ? opacity * 100 : opacity;
+    }
+  }
+
+  if (config.assets?.logo?.path) {
+    snapshot.logoImage = await fileToDataUrl(path.resolve(configDir, config.assets.logo.path));
+  }
+
+  const slides = [];
+  for (const slide of config.slides || []) {
+    const texts = {};
+    for (const localeId of localeIds) {
+      const slideText = slide.text?.[localeId] || { header: '', sub: '' };
+      texts[localeId] = { header: slideText.header || '', sub: slideText.sub || '' };
+    }
+
+    const screenshotsByLocale = {};
+    if (slide.screenshotsByLocale) {
+      for (const [localeId, relPath] of Object.entries(slide.screenshotsByLocale)) {
+        screenshotsByLocale[localeId] = await fileToDataUrl(path.resolve(configDir, relPath));
+      }
+    }
+
+    slides.push({
+      id: slide.id,
+      screenshot: await fileToDataUrl(path.resolve(configDir, slide.screenshot.path)),
+      screenshotsByLocale,
+      texts,
+      layoutOverride: slide.layoutOverride,
+    });
+  }
+
+  snapshot.slides = slides;
+  if (slides.length) snapshot.activeSlideIndex = 0;
+  return snapshot;
+}

package/cli/staticServer.js

@@ -0,0 +1,102 @@
+import http from 'node:http';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const MIME_BY_EXT = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.svg': 'image/svg+xml; charset=utf-8',
+  '.ico': 'image/x-icon',
+  '.txt': 'text/plain; charset=utf-8',
+  '.map': 'application/json; charset=utf-8',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+};
+
+async function fileExists(filePath) {
+  try {
+    const stat = await fs.stat(filePath);
+    return stat.isFile();
+  } catch {
+    return false;
+  }
+}
+
+function safeJoin(rootDir, relPath) {
+  const abs = path.resolve(rootDir, relPath);
+  const rel = path.relative(rootDir, abs);
+  if (rel === '' || rel === '.') return abs;
+  if (rel.startsWith('..') || path.isAbsolute(rel)) throw new Error('Path traversal');
+  return abs;
+}
+
+export async function startStaticServer({ distDir }) {
+  const indexPath = path.join(distDir, 'index.html');
+  if (!(await fileExists(indexPath))) {
+    throw new Error(`Missing renderer build output: ${indexPath}`);
+  }
+
+  const server = http.createServer(async (req, res) => {
+    try {
+      const method = req.method || 'GET';
+      if (method !== 'GET' && method !== 'HEAD') {
+        res.writeHead(405, { 'content-type': 'text/plain; charset=utf-8' });
+        res.end('Method Not Allowed');
+        return;
+      }
+
+      const url = new URL(req.url || '/', 'http://localhost');
+      if (url.pathname === '/app') {
+        res.writeHead(302, { location: '/app/' });
+        res.end();
+        return;
+      }
+
+      if (!url.pathname.startsWith('/app/')) {
+        res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+        res.end('Not Found');
+        return;
+      }
+
+      const relPath = decodeURIComponent(url.pathname.replace(/^\/app\//, ''));
+      const candidatePath = relPath ? safeJoin(distDir, relPath) : indexPath;
+      const resolvedPath = (await fileExists(candidatePath)) ? candidatePath : indexPath;
+
+      const ext = path.extname(resolvedPath).toLowerCase();
+      const contentType = MIME_BY_EXT[ext] || 'application/octet-stream';
+
+      const body = await fs.readFile(resolvedPath);
+      res.writeHead(200, { 'content-type': contentType });
+      if (method === 'HEAD') {
+        res.end();
+        return;
+      }
+      res.end(body);
+    } catch (err) {
+      res.writeHead(500, { 'content-type': 'text/plain; charset=utf-8' });
+      res.end(err?.message || String(err));
+    }
+  });
+
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const address = server.address();
+  const port = typeof address === 'object' && address ? address.port : 0;
+  const baseUrl = `http://127.0.0.1:${port}`;
+
+  return {
+    baseUrl,
+    close: async () => {
+      await new Promise((resolve, reject) => {
+        server.close((err) => (err ? reject(err) : resolve()));
+      });
+    },
+    mode: 'static',
+  };
+}
+

package/cli/templateConfig.js

@@ -0,0 +1,51 @@
+import { OFFICIAL_TEMPLATES } from '../src/constants/devices.js';
+
+const normalizeKey = (value) => String(value || '').trim().toLowerCase();
+
+export const listTemplateIds = () => OFFICIAL_TEMPLATES.map((template) => template.id);
+
+export const resolveTemplateById = (raw) => {
+  const normalized = normalizeKey(raw);
+  if (!normalized) return null;
+  return (
+    OFFICIAL_TEMPLATES.find((template) => normalizeKey(template.id) === normalized) ||
+    OFFICIAL_TEMPLATES.find((template) => normalizeKey(template.name) === normalized)
+  );
+};
+
+export const buildTemplateConfig = (template) => {
+  if (!template?.settings) return { style: undefined, assets: undefined };
+  const settings = template.settings;
+  const style = {};
+  if (settings.textColor) style.textColor = settings.textColor;
+  if (settings.layoutMode) style.layoutMode = settings.layoutMode;
+  if (typeof settings.topSpacing === 'number') style.topSpacing = settings.topSpacing;
+  if (typeof settings.deviceScale === 'number') style.deviceScale = settings.deviceScale;
+  if (settings.frameColor) style.frameColor = settings.frameColor;
+  if (settings.selectedFont) style.selectedFont = settings.selectedFont;
+  if (settings.badgeType) style.badgeType = settings.badgeType;
+
+  const assets = {};
+  if (settings.bgType === 'solid' && settings.bgColor) {
+    assets.background = { type: 'solid', color: settings.bgColor };
+  } else if (settings.bgType === 'gradient') {
+    assets.background = {
+      type: 'gradient',
+      start: settings.gradientStart || '#e0c3fc',
+      end: settings.gradientEnd || '#8ec5fc',
+      angle: typeof settings.gradientAngle === 'number' ? settings.gradientAngle : 135,
+    };
+  }
+
+  return {
+    style: Object.keys(style).length ? style : undefined,
+    assets: Object.keys(assets).length ? assets : undefined,
+  };
+};
+
+export const resolveTemplateConfig = (raw) => {
+  const template = resolveTemplateById(raw);
+  if (!template) return null;
+  const { style, assets } = buildTemplateConfig(template);
+  return { template, style, assets };
+};

package/cli/viteServer.js

@@ -0,0 +1,40 @@
+import path from 'node:path';
+
+export async function startViteServer({ rootDir }) {
+  let createServer;
+  try {
+    ({ createServer } = await import('vite'));
+  } catch (err) {
+    throw new Error(
+      `Vite is required to run the renderer in dev mode.\n` +
+        `Install dependencies and try again.\n` +
+        `${err?.message || String(err)}`
+    );
+  }
+
+  const server = await createServer({
+    root: rootDir,
+    configFile: path.join(rootDir, 'vite.config.js'),
+    logLevel: 'error',
+    server: {
+      host: '127.0.0.1',
+      port: 5173,
+      strictPort: false,
+    },
+  });
+
+  await server.listen();
+
+  const address = server.httpServer?.address?.();
+  const port = typeof address === 'object' && address ? address.port : 5173;
+  const baseUrl = `http://127.0.0.1:${port}`;
+
+  return {
+    baseUrl,
+    close: async () => {
+      await server.close();
+    },
+    mode: 'vite',
+  };
+}
+