shipscreens 0.1.6 → 0.1.7

package/cli/commands/planRelease.js

@@ -0,0 +1,324 @@
+import path from 'node:path';
+import { runInspectReleaseContext } from './inspectReleaseContext.js';
+
+function normalizeProfile(profile, fallback) {
+  const raw = String(profile || fallback || 'any').trim().toLowerCase();
+  if (!['any', 'appstore', 'playstore'].includes(raw)) {
+    throw new Error(`Unknown release plan profile: ${raw} (expected: appstore|playstore|any)`);
+  }
+  return raw;
+}
+
+function shellQuote(value) {
+  const text = String(value);
+  if (/^[A-Za-z0-9_./:=@+-]+$/.test(text)) return text;
+  return JSON.stringify(text);
+}
+
+function commandText(args) {
+  return ['shipscreens', ...args.map(shellQuote)].join(' ');
+}
+
+function createCommand({ id, label, args, reason, required = true }) {
+  return {
+    id,
+    label,
+    command: commandText(args),
+    args,
+    reason,
+    required,
+  };
+}
+
+function hasFileSignal(inspection, kind) {
+  return (inspection.files || []).some((file) => file.kind === kind && file.exists);
+}
+
+function hasImageRoot(inspection) {
+  return (inspection.screenshotRoots || []).some((root) => root.exists && root.imageFiles > 0);
+}
+
+function findImportSourceRoot(inspection) {
+  return (inspection.screenshotRoots || []).find(
+    (root) =>
+      root.exists &&
+      root.imageFiles > 0 &&
+      !['assets', 'config_ios_output', 'config_android_output'].includes(root.kind)
+  );
+}
+
+function firstQuestion(questions) {
+  return Array.isArray(questions) && questions.length ? questions[0] : null;
+}
+
+function inferReadiness({ inspection }) {
+  if (!inspection.config.exists) return 'needs_config';
+  if (!inspection.config.valid) return 'fix_config';
+  if (inspection.missingAssets.length) return 'missing_assets';
+  if (inspection.placeholderAssets?.length) return 'placeholder_assets';
+  if (!hasImageRoot(inspection)) return 'ready_but_needs_source_assets';
+  return 'ready_to_run';
+}
+
+function buildPlan({ inspection, dir, profile, outDir, stageOutDir, mode }) {
+  const dirArgs = dir ? ['--dir', dir] : [];
+  const configArg = dir ? inspection.config.path : inspection.config.relativePath || 'shipscreens.config.yml';
+  const commands = [
+    createCommand({
+      id: 'inspect_release_context',
+      label: 'Inspect release context',
+      args: ['inspect-release-context', ...dirArgs, '--json'],
+      reason: 'Confirm the agent-visible workspace state before writing or building anything.',
+    }),
+  ];
+
+  const blockers = [];
+  const questions = [...(inspection.questions || [])];
+  const readiness = inferReadiness({ inspection });
+
+  if (!inspection.config.exists) {
+    blockers.push('shipscreens.config.yml is missing.');
+    commands.push(
+      createCommand({
+        id: 'create_starter_config',
+        label: 'Create starter config',
+        args: ['write-starter-config', ...dirArgs, '--profile', profile, '--json'],
+        reason:
+          'No config exists yet, so write devices/locales/slides/copy scaffolding non-interactively before build.',
+      })
+    );
+  } else if (!inspection.config.valid) {
+    blockers.push('shipscreens.config.yml exists but is invalid.');
+    commands.push(
+      createCommand({
+        id: 'validate_config',
+        label: 'Validate config',
+        args: ['validate', '--config', configArg],
+        reason: 'Surface schema and path errors before build.',
+      })
+    );
+  } else {
+    commands.push(
+      createCommand({
+        id: 'validate_config',
+        label: 'Validate config',
+        args: ['validate', '--config', configArg],
+        reason: 'Fail fast on config/schema/path drift.',
+      })
+    );
+
+    if (hasFileSignal(inspection, 'copy_csv')) {
+      commands.push(
+        createCommand({
+          id: 'copy_check',
+          label: 'Check copy risk',
+          args: [
+            'copy',
+            'check',
+            '--config',
+            configArg,
+            '--strict',
+            '--write-pseudo-csv',
+            path.posix.join(outDir, 'copy-pseudo.csv'),
+            '--write-report-json',
+            path.posix.join(outDir, 'copy-check-report.json'),
+          ],
+          reason: 'copy.csv exists, so check long strings and pseudo-locale risk before export.',
+          required: false,
+        })
+      );
+    }
+
+    commands.push(
+      createCommand({
+        id: 'preview_plan',
+        label: 'Preview deterministic output plan',
+        args: [
+          'plan',
+          '--config',
+          configArg,
+          '--profile',
+          profile,
+          '--out',
+          outDir,
+          '--json',
+        ],
+        reason: 'Show expected Fastlane roots and filenames before generating outputs.',
+      })
+    );
+
+    if (inspection.missingAssets.length) {
+      blockers.push(`${inspection.missingAssets.length} config-referenced asset path(s) are missing.`);
+    }
+
+    if (inspection.placeholderAssets?.length) {
+      blockers.push(`${inspection.placeholderAssets.length} config-referenced placeholder PNG(s) need real screenshots.`);
+      const sourceRoot = findImportSourceRoot(inspection);
+      if (sourceRoot) {
+        commands.push(
+          createCommand({
+            id: 'import_screenshots',
+            label: 'Import existing screenshots into config asset paths',
+            args: [
+              'import-screenshots',
+              ...dirArgs,
+              '--config',
+              configArg,
+              '--from',
+              sourceRoot.relativePath,
+              '--json',
+            ],
+            reason:
+              'Placeholder PNGs were detected and an existing screenshot root is available, so copy source screenshots into the configured asset paths before build.',
+          })
+        );
+      } else {
+        commands.push(
+          createCommand({
+            id: 'capture_current_screen',
+            label: 'Capture current connected device/emulator screen',
+            args: [
+              'capture-screenshots',
+              ...dirArgs,
+              '--platform',
+              'auto',
+              '--out',
+              'screenshots',
+              '--slot',
+              '1',
+              '--profile',
+              profile,
+              '--json',
+            ],
+            reason:
+              'No source screenshot root was detected. If the app is open on a connected device or emulator, capture each visible panel into screenshots/ before importing.',
+            required: false,
+          })
+        );
+        questions.unshift('Which folder contains the real source screenshots to import into assets/?');
+      }
+    }
+
+    commands.push(
+      createCommand({
+        id: 'agent_run_stage_report',
+        label: 'Build, verify, stage, and report',
+        args: [
+          'agent-run',
+          ...dirArgs,
+          '--mode',
+          mode,
+          '--zip',
+          '--out',
+          outDir,
+          '--stage-out',
+          stageOutDir,
+          '--profile',
+          profile,
+          '--json',
+        ],
+        reason: 'Produce release-safe outputs plus JSON/Markdown proof report for human review.',
+        required: !inspection.missingAssets.length && !inspection.placeholderAssets?.length,
+      })
+    );
+  }
+
+  if (!hasImageRoot(inspection)) {
+    questions.unshift('Where are the current base screenshots or Fastlane output folders?');
+    if (!commands.some((cmd) => cmd.id === 'capture_current_screen')) {
+      commands.push(
+        createCommand({
+          id: 'capture_current_screen',
+          label: 'Capture current connected device/emulator screen',
+          args: [
+            'capture-screenshots',
+            ...dirArgs,
+            '--platform',
+            'auto',
+            '--out',
+            'screenshots',
+            '--slot',
+            '1',
+            '--profile',
+            profile,
+            '--json',
+          ],
+          reason:
+            'Use this when the release screenshots are only visible on a connected device or emulator and no source PNG folder exists yet.',
+          required: false,
+        })
+      );
+    }
+  }
+
+  return {
+    readiness,
+    blockers: [...new Set(blockers)],
+    questions: [...new Set(questions)].filter(Boolean),
+    commands,
+  };
+}
+
+export async function runPlanRelease({ dir, configPath, profile, outDir = 'out/agent', stageOutDir, mode = 'raw' } = {}) {
+  const inspection = await runInspectReleaseContext({ dir, configPath });
+  const inferredProfile = inspection.storeTarget.profile === 'unknown' ? 'any' : inspection.storeTarget.profile;
+  const normalizedProfile = normalizeProfile(profile, inferredProfile);
+  const normalizedMode = String(mode || 'raw').trim().toLowerCase();
+  if (!['raw', 'rendered'].includes(normalizedMode)) {
+    throw new Error(`Unknown release plan mode: ${mode} (expected: raw|rendered)`);
+  }
+  const normalizedOutDir = String(outDir || 'out/agent').trim() || 'out/agent';
+  const normalizedStageOutDir =
+    String(stageOutDir || '').trim() || `${normalizedOutDir.replace(/[\\/]+$/, '') || 'out/agent'}-stage`;
+  const plan = buildPlan({
+    inspection,
+    dir,
+    profile: normalizedProfile,
+    outDir: normalizedOutDir,
+    stageOutDir: normalizedStageOutDir,
+    mode: normalizedMode,
+  });
+
+  return {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    workspace: inspection.workspace,
+    profile: normalizedProfile,
+    profileSource: profile ? 'flag' : inspection.storeTarget.source,
+    mode: normalizedMode,
+    outDir: normalizedOutDir,
+    stageOutDir: normalizedStageOutDir,
+    readiness: plan.readiness,
+    blockers: plan.blockers,
+    questions: plan.questions,
+    commands: plan.commands,
+    inspection: {
+      config: inspection.config,
+      storeTarget: inspection.storeTarget,
+      missingAssets: inspection.missingAssets,
+      placeholderAssets: inspection.placeholderAssets || [],
+      warnings: inspection.warnings,
+      agentHandoff: inspection.agentHandoff,
+    },
+  };
+}
+
+export function renderPlanReleaseSummary(result) {
+  const lines = [
+    'ShipScreens release plan',
+    `- Workspace: ${result.workspace}`,
+    `- Profile: ${result.profile} (${result.profileSource})`,
+    `- Mode: ${result.mode}`,
+    `- Readiness: ${result.readiness}`,
+    '',
+    'Blockers:',
+    ...(result.blockers.length ? result.blockers.map((item) => `- ${item}`) : ['- none']),
+    '',
+    'Questions:',
+    ...(result.questions.length ? result.questions.map((item) => `- ${item}`) : ['- none']),
+    '',
+    'Commands:',
+    ...result.commands.map((cmd, idx) => `${idx + 1}. ${cmd.command}`),
+  ];
+  return `${lines.join('\n')}\n`;
+}

package/cli/commands/writeStarterConfig.js

@@ -0,0 +1,233 @@
+import path from 'node:path';
+import { runInit } from './init.js';
+import { runInspectReleaseContext } from './inspectReleaseContext.js';
+
+const DEFAULT_DEVICES_BY_PROFILE = {
+  any: 'iphone69,pixel8',
+  appstore: 'iphone69',
+  playstore: 'pixel8',
+};
+
+function normalizeProfile(profile, fallback) {
+  const raw = String(profile || fallback || 'any').trim().toLowerCase();
+  if (!['any', 'appstore', 'playstore'].includes(raw)) {
+    throw new Error(`Unknown starter config profile: ${raw} (expected: appstore|playstore|any)`);
+  }
+  return raw;
+}
+
+function toPosixPath(value) {
+  return String(value || '').replaceAll('\\', '/');
+}
+
+function relativeTo(baseDir, targetPath) {
+  const rel = path.relative(baseDir, targetPath);
+  return toPosixPath(rel || '.');
+}
+
+function shellQuote(value) {
+  const text = String(value);
+  if (/^[A-Za-z0-9_./:=@+-]+$/.test(text)) return text;
+  return JSON.stringify(text);
+}
+
+function commandText(args) {
+  return ['shipscreens', ...args.map(shellQuote)].join(' ');
+}
+
+function createCommand({ id, label, args, reason, required = true }) {
+  return {
+    id,
+    label,
+    command: commandText(args),
+    args,
+    reason,
+    required,
+  };
+}
+
+function hasImageRoot(inspection) {
+  return (inspection.screenshotRoots || []).some((root) => root.exists && root.imageFiles > 0);
+}
+
+function defaultStageOutDir(outDir) {
+  const raw = String(outDir || 'out/agent').trim() || 'out/agent';
+  const trimmed = raw.replace(/[\\/]+$/, '');
+  return `${trimmed || 'out/agent'}-stage`;
+}
+
+function buildNextCommands({ dir, profile, outDir, stageOutDir }) {
+  const dirArgs = dir ? ['--dir', dir] : [];
+  return [
+    createCommand({
+      id: 'inspect_release_context',
+      label: 'Inspect created starter config',
+      args: ['inspect-release-context', ...dirArgs, '--json'],
+      reason: 'Confirm the workspace now has config, copy.csv, devices, locales, and asset paths.',
+    }),
+    createCommand({
+      id: 'plan_release',
+      label: 'Plan the release run',
+      args: ['plan-release', ...dirArgs, '--profile', profile, '--json'],
+      reason: 'Return readiness, blockers, questions, and the exact release-safe command sequence.',
+    }),
+    createCommand({
+      id: 'agent_run_stage_report',
+      label: 'Build, verify, stage, and report after replacing placeholders',
+      args: [
+        'agent-run',
+        ...dirArgs,
+        '--mode',
+        'raw',
+        '--zip',
+        '--out',
+        outDir,
+        '--stage-out',
+        stageOutDir,
+        '--profile',
+        profile,
+        '--json',
+      ],
+      reason:
+        'Run this after replacing placeholder PNGs with real screenshots to produce Fastlane-ready roots and proof reports.',
+      required: false,
+    }),
+  ];
+}
+
+export async function runWriteStarterConfig({
+  dir,
+  profile,
+  slides,
+  locales,
+  devices,
+  assets,
+  style,
+  force = false,
+  outDir = 'out/agent',
+  stageOutDir,
+} = {}) {
+  const before = await runInspectReleaseContext({ dir });
+  const inferredProfile = before.storeTarget.profile === 'unknown' ? 'any' : before.storeTarget.profile;
+  const normalizedProfile = normalizeProfile(profile, inferredProfile);
+  const normalizedOutDir = String(outDir || 'out/agent').trim() || 'out/agent';
+  const normalizedStageOutDir = String(stageOutDir || '').trim() || defaultStageOutDir(normalizedOutDir);
+
+  if (before.config.exists && !force) {
+    throw new Error(
+      `${before.config.relativePath || 'shipscreens.config.yml'} already exists. ` +
+        'Run shipscreens plan-release first, or pass --force if you intentionally want to overwrite starter files.'
+    );
+  }
+
+  const effectiveDevices = devices || DEFAULT_DEVICES_BY_PROFILE[normalizedProfile];
+  const initResult = await runInit({
+    dir: dir || '.',
+    slides,
+    locales,
+    devices: effectiveDevices,
+    assets,
+    style,
+    force,
+  });
+  const after = await runInspectReleaseContext({ dir });
+  const targetDir = initResult.dir;
+  const placeholderCount = initResult.locales.length * initResult.slides;
+  const assetRoots = initResult.locales.map((localeId) => ({
+    locale: localeId,
+    path: path.join(targetDir, 'assets', localeId),
+    relativePath: relativeTo(targetDir, path.join(targetDir, 'assets', localeId)),
+  }));
+
+  const warnings = [
+    `Created ${placeholderCount} placeholder PNG(s). Replace them with real screenshots before production export.`,
+  ];
+  if (!hasImageRoot(before)) {
+    warnings.push('No existing source screenshot root was detected before scaffold creation.');
+  }
+
+  const questions = [];
+  if (profile || before.storeTarget.profile !== 'unknown') {
+    questions.push('Are the generated devices/locales/slides correct for this release?');
+  } else {
+    questions.push('Should this release target App Store, Google Play, or both?');
+    questions.push('Are the generated devices/locales/slides correct for this release?');
+  }
+  questions.push('Which real screenshot files should replace the placeholders under assets/?');
+
+  return {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    workspace: targetDir,
+    profile: normalizedProfile,
+    profileSource: profile ? 'flag' : before.storeTarget.source,
+    slides: initResult.slides,
+    locales: initResult.locales,
+    devices: initResult.devices,
+    files: [
+      {
+        kind: 'config',
+        path: initResult.configPath,
+        relativePath: relativeTo(targetDir, initResult.configPath),
+      },
+      {
+        kind: 'copy_csv',
+        path: initResult.csvPath,
+        relativePath: relativeTo(targetDir, initResult.csvPath),
+      },
+      {
+        kind: 'asset_root',
+        path: path.join(targetDir, 'assets'),
+        relativePath: 'assets',
+      },
+    ],
+    assetRoots,
+    placeholderCount,
+    warnings: [...new Set(warnings)],
+    questions: [...new Set(questions)],
+    nextCommands: buildNextCommands({
+      dir,
+      profile: normalizedProfile,
+      outDir: normalizedOutDir,
+      stageOutDir: normalizedStageOutDir,
+    }),
+    inspection: {
+      before: {
+        config: before.config,
+        storeTarget: before.storeTarget,
+        warnings: before.warnings,
+      },
+      after: {
+        config: after.config,
+        storeTarget: after.storeTarget,
+        missingAssets: after.missingAssets,
+        warnings: after.warnings,
+      },
+    },
+  };
+}
+
+export function renderWriteStarterConfigSummary(result) {
+  const lines = [
+    'ShipScreens starter config',
+    `- Workspace: ${result.workspace}`,
+    `- Profile: ${result.profile} (${result.profileSource})`,
+    `- Locales: ${result.locales.join(', ')}`,
+    `- Slides: ${result.slides}`,
+    `- Devices: ${result.devices.map((device) => device.id).join(', ')}`,
+    `- Placeholder PNGs: ${result.placeholderCount}`,
+    '',
+    'Files:',
+    ...result.files.map((file) => `- ${file.relativePath}`),
+    '',
+    'Warnings:',
+    ...(result.warnings.length ? result.warnings.map((item) => `- ${item}`) : ['- none']),
+    '',
+    'Questions:',
+    ...(result.questions.length ? result.questions.map((item) => `- ${item}`) : ['- none']),
+    '',
+    'Next commands:',
+    ...result.nextCommands.map((cmd, idx) => `${idx + 1}. ${cmd.command}`),
+  ];
+  return `${lines.join('\n')}\n`;
+}