@ttmg/cli 0.4.1 → 0.4.3

package/dist/public/assets/layers-DDrUeTNf.js

@@ -0,0 +1 @@
+import{c as a}from"./index-wqj8y8SZ.js";const o=[["path",{d:"m9 18 6-6-6-6",key:"mthhwq"}]],c=a("chevron-right",o);const e=[["path",{d:"M12.83 2.18a2 2 0 0 0-1.66 0L2.6 6.08a1 1 0 0 0 0 1.83l8.58 3.91a2 2 0 0 0 1.66 0l8.58-3.9a1 1 0 0 0 0-1.83z",key:"zw3jo"}],["path",{d:"M2 12a1 1 0 0 0 .58.91l8.6 3.91a2 2 0 0 0 1.65 0l8.58-3.9A1 1 0 0 0 22 12",key:"1wduqc"}],["path",{d:"M2 17a1 1 0 0 0 .58.91l8.6 3.91a2 2 0 0 0 1.65 0l8.58-3.9A1 1 0 0 0 22 17",key:"kqbvx6"}]],h=a("layers",e);export{c as C,h as L};

package/dist/public/assets/list-checks-C4ci4EKo.js

@@ -0,0 +1 @@
+import{c}from"./index-wqj8y8SZ.js";const e=[["path",{d:"M13 5h8",key:"a7qcls"}],["path",{d:"M13 12h8",key:"h98zly"}],["path",{d:"M13 19h8",key:"c3s6r1"}],["path",{d:"m3 17 2 2 4-4",key:"1jhpwq"}],["path",{d:"m3 7 2 2 4-4",key:"1obspn"}]],t=c("list-checks",e);export{t as L};

package/dist/public/assets/{sparkles-Bv2GxrFr.js → sparkles-PwlPP_sT.js}

@@ -1 +1 @@
-import{c as a}from"./index-CCKb9Y-j.js";const e=[["path",{d:"M11.017 2.814a1 1 0 0 1 1.966 0l1.051 5.558a2 2 0 0 0 1.594 1.594l5.558 1.051a1 1 0 0 1 0 1.966l-5.558 1.051a2 2 0 0 0-1.594 1.594l-1.051 5.558a1 1 0 0 1-1.966 0l-1.051-5.558a2 2 0 0 0-1.594-1.594l-5.558-1.051a1 1 0 0 1 0-1.966l5.558-1.051a2 2 0 0 0 1.594-1.594z",key:"1s2grr"}],["path",{d:"M20 2v4",key:"1rf3ol"}],["path",{d:"M22 4h-4",key:"gwowj6"}],["circle",{cx:"4",cy:"20",r:"2",key:"6kqj1y"}]],l=a("sparkles",e);export{l as S};
+import{c as a}from"./index-wqj8y8SZ.js";const e=[["path",{d:"M11.017 2.814a1 1 0 0 1 1.966 0l1.051 5.558a2 2 0 0 0 1.594 1.594l5.558 1.051a1 1 0 0 1 0 1.966l-5.558 1.051a2 2 0 0 0-1.594 1.594l-1.051 5.558a1 1 0 0 1-1.966 0l-1.051-5.558a2 2 0 0 0-1.594-1.594l-5.558-1.051a1 1 0 0 1 0-1.966l5.558-1.051a2 2 0 0 0 1.594-1.594z",key:"1s2grr"}],["path",{d:"M20 2v4",key:"1rf3ol"}],["path",{d:"M22 4h-4",key:"gwowj6"}],["circle",{cx:"4",cy:"20",r:"2",key:"6kqj1y"}]],l=a("sparkles",e);export{l as S};

package/dist/public/assets/triangle-alert-BAadCxAv.js

@@ -0,0 +1 @@
+import{c as e}from"./index-wqj8y8SZ.js";const a=[["path",{d:"m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3",key:"wmoenq"}],["path",{d:"M12 9v4",key:"juzpu7"}],["path",{d:"M12 17h.01",key:"p32p05"}]],o=e("triangle-alert",a);export{o as T};

package/dist/public/assets/{zap-CjkC_qWZ.js → zap-CgIIDLY4.js}

@@ -1 +1 @@
-import{c as a}from"./index-CCKb9Y-j.js";const o=[["path",{d:"M4 14a1 1 0 0 1-.78-1.63l9.9-10.2a.5.5 0 0 1 .86.46l-1.92 6.02A1 1 0 0 0 13 10h7a1 1 0 0 1 .78 1.63l-9.9 10.2a.5.5 0 0 1-.86-.46l1.92-6.02A1 1 0 0 0 11 14z",key:"1xq2db"}]],e=a("zap",o);export{e as Z};
+import{c as a}from"./index-wqj8y8SZ.js";const o=[["path",{d:"M4 14a1 1 0 0 1-.78-1.63l9.9-10.2a.5.5 0 0 1 .86.46l-1.92 6.02A1 1 0 0 0 13 10h7a1 1 0 0 1 .78 1.63l-9.9 10.2a.5.5 0 0 1-.86-.46l1.92-6.02A1 1 0 0 0 11 14z",key:"1xq2db"}]],e=a("zap",o);export{e as Z};

package/dist/public/index.html

@@ -12,8 +12,8 @@
       rel="stylesheet"
     />
     <title>TikTok Mini Games DevTool</title>
-    <script type="module" crossorigin src="/assets/index-CCKb9Y-j.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-BJZ4gOGZ.css">
+    <script type="module" crossorigin src="/assets/index-wqj8y8SZ.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-BRJFt3oz.css">
   </head>
   <!--
     Theme attributes (`theme-mode` for Semi UI + `data-theme` for our

package/dist/scripts/docs/README.md

@@ -0,0 +1,80 @@
+# DevTool documentation screenshots
+
+This directory keeps the local pipeline for DevTool usage-guide screenshots and generated guide drafts.
+
+## Main scenario file
+
+`scenarios/devtool-guide.mjs` is the first stable scenario manifest. Each recipe describes:
+
+- the current Lark source document for the usage guide
+- the DevTool route to open
+- the page state or fixture expected by the screenshot
+- the capture selector and viewport
+- the usage-guide section that consumes the screenshot
+- bilingual notes used by `render.js`
+- acceptance checks that should stay true when the page changes
+- the documentation contract, screenshot inventory, and release checks used for guide review
+
+## Commands
+
+Render the guide draft and indexes without opening the browser:
+
+```bash
+npm run docs:devtool:render
+```
+
+Capture screenshots from a running local DevTool page:
+
+```bash
+npm run docs:devtool:capture
+```
+
+Check that screenshots are fresh enough for publishing:
+
+```bash
+npm run docs:devtool:check
+```
+
+`docs:devtool:capture` assumes the IDE is available at `http://localhost:5173`. Start or change the local DevTool URL before running it if your port is different.
+
+## Doc mode fixture
+
+Screenshot routes append `docMode=1&docScenario=<scenario id>`. In this mode the IDE uses stable fixture data for platform and project requests, so usage-guide screenshots do not depend on the current login account, local Node connection, platform availability, or a connected device.
+
+Doc mode is only enabled by the URL parameter above or `localStorage.TTMG_DOCS_CAPTURE=1`. Normal DevTool usage still goes through the real local service and platform APIs.
+
+Pages that enter the guide should expose stable screenshot anchors such as:
+
+```tsx
+<main data-doc-shot="start-debug-qr-idle">
+```
+
+The scenario manifest should target these anchors through `capture.selector` instead of relying on layout CSS classes.
+
+## Outputs
+
+The default output directory is `artifacts/devtool-guide/`.
+
+- `manifest.json`: scenario snapshot used for this run
+- `screenshot-index.json`: screenshot-to-route/section mapping for later doc updates
+- `doc-version.json`: version snapshot for the guide source, scenario fingerprint, CLI version, ttmg-pack version, and generated artifacts
+- `quality-gate.json`: review contract, release checks, and screenshot inventory for the current guide refresh
+- `capture-report.json`: screenshot freshness evidence from the latest capture run
+- `index.md`: bilingual usage-guide draft referencing screenshots in `assets/`
+
+`manifest.json`, `screenshot-index.json`, `doc-version.json`, and `quality-gate.json` include `guideSource` so each generated draft can be traced back to the current Lark guide instead of relying on a one-off screenshot note.
+
+The render step is safe to run without screenshots. The capture step should be run only when the local DevTool page is already available.
+
+## Freshness contract
+
+DevTool screenshots are considered publishable only when:
+
+- `capture-report.json` exists in the output directory
+- its scenario fingerprint matches the current `scenarios/devtool-guide.mjs`
+- every expected `recipe + locale` screenshot exists under `assets/`
+- screenshot files are newer than the scenario manifest
+- `capture-report.json` and screenshot files are newer than the latest `manifest.json` / `screenshot-index.json` / `doc-version.json` / `quality-gate.json`
+- the capture report is within the freshness window used by `docs:devtool:check`
+
+If any of these checks fail, rerun `npm run docs:devtool:capture` from the current DevTool build before updating the usage guide.

package/dist/scripts/docs/capture.js

@@ -1,5 +1,6 @@
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
 const { pathToFileURL } = require('url');
 const chromeLauncher = require('chrome-launcher');
 const CDP = require('chrome-remote-interface');
@@ -42,6 +43,27 @@ function localizeValue(value, lang) {
   );
 }
 
+function stableStringify(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map(stableStringify).join(',')}]`;
+  }
+  if (!value || typeof value !== 'object') {
+    return JSON.stringify(value);
+  }
+  return `{${Object.keys(value)
+    .sort()
+    .map(key => `${JSON.stringify(key)}:${stableStringify(value[key])}`)
+    .join(',')}}`;
+}
+
+function createScenarioFingerprint({ schemaVersion, locales, guideTitle, guideSource, recipes }) {
+  return crypto
+    .createHash('sha256')
+    .update(stableStringify({ schemaVersion, locales, guideTitle, guideSource, recipes }))
+    .digest('hex')
+    .slice(0, 16);
+}
+
 function escapeForEval(value) {
   return JSON.stringify(value).replace(/<\//g, '<\\/');
 }
@@ -229,17 +251,35 @@ async function captureFullPage(Page, Runtime, Emulation, outputPath, viewport) {
 async function loadRecipes(recipesPath) {
   const module = await import(pathToFileURL(recipesPath).href);
   return {
+    schemaVersion: module.schemaVersion || 1,
     recipes: module.recipes || module.default || [],
     locales: module.locales || ['zh-CN', 'en-US'],
+    guideTitle: module.guideTitle || 'TikTok 小游戏调试工具使用指南',
+    guideSource: module.guideSource || null,
     defaultLocalStorage: module.defaultLocalStorage || {},
   };
 }
 
+function getRecipeViewport(recipe) {
+  return recipe.viewport || recipe.capture?.viewport || { width: 1440, height: 1400 };
+}
+
+function getRecipeWaitFor(recipe) {
+  return recipe.waitFor || {
+    selector: recipe.capture?.selector || 'body',
+    timeoutMs: 20000,
+  };
+}
+
+function createLocalizedRecipeUrl(baseUrl, route, locale) {
+  const url = new URL(route, baseUrl);
+  url.searchParams.set('docLang', locale);
+  return url.toString();
+}
+
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   const baseUrl = args['base-url'];
-  const recipesPath = path.resolve(args.recipes);
-  const outputDir = path.resolve(args['output-dir']);
 
   if (!baseUrl) {
     throw new Error('Missing required argument: --base-url');
@@ -251,9 +291,34 @@ async function main() {
     throw new Error('Missing required argument: --output-dir');
   }
 
-  const { recipes, locales, defaultLocalStorage } = await loadRecipes(recipesPath);
+  const recipesPath = path.resolve(args.recipes);
+  const outputDir = path.resolve(args['output-dir']);
+  const { schemaVersion, recipes, locales, guideTitle, guideSource, defaultLocalStorage } = await loadRecipes(recipesPath);
+  const normalizedLocales = locales.map(normalizeLang);
+  const scenarioFingerprint = createScenarioFingerprint({
+    schemaVersion,
+    recipes,
+    locales: normalizedLocales,
+    guideTitle,
+    guideSource,
+  });
   const assetsDir = path.join(outputDir, 'assets');
   fs.mkdirSync(assetsDir, { recursive: true });
+  const reportPath = path.join(outputDir, 'capture-report.json');
+  if (fs.existsSync(reportPath)) {
+    fs.rmSync(reportPath);
+  }
+  const captureReport = {
+    schemaVersion: 1,
+    title: guideTitle,
+    guideSource,
+    scenarioFingerprint,
+    baseUrl,
+    recipesPath,
+    generatedAt: new Date().toISOString(),
+    outputDir,
+    screenshots: [],
+  };
 
   const chrome = await chromeLauncher.launch({
     chromeFlags: [
@@ -280,7 +345,7 @@ async function main() {
       }),
     ]);
 
-    for (const locale of locales.map(normalizeLang)) {
+    for (const locale of normalizedLocales) {
       const baseHeaders = {
         'Accept-Language': locale,
         'X-TTMG-Docs-Lang': locale,
@@ -296,7 +361,8 @@ async function main() {
       await seedLocalStorage(Runtime, localizedStorage);
 
       for (const recipe of recipes) {
-        const viewport = recipe.viewport || { width: 1440, height: 1400 };
+        const viewport = getRecipeViewport(recipe);
+        const waitFor = getRecipeWaitFor(recipe);
         const requestHeaders = {
           ...baseHeaders,
           ...(recipe.requestHeaders || {}),
@@ -305,17 +371,35 @@ async function main() {
           headers: requestHeaders,
         });
         await setViewport(Emulation, viewport.width, viewport.height);
-        await navigateAndWait(client, Page, `${baseUrl}${recipe.route}`);
-        await waitForSelector(Runtime, recipe.waitFor.selector, recipe.waitFor.timeoutMs || 20000);
+        await navigateAndWait(client, Page, createLocalizedRecipeUrl(baseUrl, recipe.route, locale));
+        await waitForSelector(Runtime, waitFor.selector, waitFor.timeoutMs || 20000);
         await stabilizePage(Runtime);
         await wait(500);
 
         const fileName = `${recipe.id}.${locale}.png`;
         const outputPath = path.join(assetsDir, fileName);
         await captureFullPage(Page, Runtime, Emulation, outputPath, viewport);
+        const stats = fs.statSync(outputPath);
+        captureReport.screenshots.push({
+          id: `${recipe.id}.${locale}`,
+          recipeId: recipe.id,
+          locale,
+          route: recipe.route,
+          selector: recipe.capture?.selector || recipe.selector || 'body',
+          viewport,
+          path: `assets/${fileName}`,
+          bytes: stats.size,
+          capturedAt: new Date().toISOString(),
+        });
         console.log(`[ttmg-docs] captured ${fileName}`);
       }
     }
+    fs.writeFileSync(
+      reportPath,
+      `${JSON.stringify(captureReport, null, 2)}\n`,
+      'utf8',
+    );
+    console.log(`[ttmg-docs] wrote capture report into ${outputDir}`);
   } finally {
     if (client) {
       await client.close();

package/dist/scripts/docs/check.js

@@ -0,0 +1,184 @@
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { pathToFileURL } = require('url');
+
+function parseArgs(argv) {
+  return argv.reduce((acc, arg) => {
+    if (!arg.startsWith('--')) {
+      return acc;
+    }
+    const [key, value] = arg.slice(2).split('=');
+    acc[key] = value === undefined ? true : value;
+    return acc;
+  }, {});
+}
+
+function normalizeLang(value) {
+  return String(value || '').toLowerCase().includes('en') ? 'en-US' : 'zh-CN';
+}
+
+function stableStringify(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map(stableStringify).join(',')}]`;
+  }
+  if (!value || typeof value !== 'object') {
+    return JSON.stringify(value);
+  }
+  return `{${Object.keys(value)
+    .sort()
+    .map(key => `${JSON.stringify(key)}:${stableStringify(value[key])}`)
+    .join(',')}}`;
+}
+
+function createScenarioFingerprint({ schemaVersion, locales, guideTitle, guideSource, recipes }) {
+  return crypto
+    .createHash('sha256')
+    .update(stableStringify({ schemaVersion, locales, guideTitle, guideSource, recipes }))
+    .digest('hex')
+    .slice(0, 16);
+}
+
+async function loadRecipes(recipesPath) {
+  const module = await import(pathToFileURL(recipesPath).href);
+  return {
+    schemaVersion: module.schemaVersion || 1,
+    recipes: module.recipes || module.default || [],
+    locales: (module.locales || ['zh-CN', 'en-US']).map(normalizeLang),
+    guideTitle: module.guideTitle || 'TikTok 小游戏调试工具使用指南',
+    guideSource: module.guideSource || null,
+  };
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function assertFreshEnough(report, maxAgeHours) {
+  if (!maxAgeHours) {
+    return;
+  }
+  const maxAgeMs = Number(maxAgeHours) * 60 * 60 * 1000;
+  const generatedAt = new Date(report.generatedAt).getTime();
+  if (!Number.isFinite(generatedAt)) {
+    fail('capture-report.json has invalid generatedAt');
+  }
+  const ageMs = Date.now() - generatedAt;
+  if (ageMs > maxAgeMs) {
+    fail(`DevTool screenshots are stale: capture-report is older than ${maxAgeHours} hours`);
+  }
+}
+
+function assertFileFreshAgainstRecipe(filePath, recipesPath) {
+  const screenshotStat = fs.statSync(filePath);
+  const recipeStat = fs.statSync(recipesPath);
+  if (screenshotStat.mtimeMs + 1000 < recipeStat.mtimeMs) {
+    fail(`Screenshot is older than scenario manifest: ${filePath}`);
+  }
+}
+
+function assertReportFreshAgainstArtifact(report, artifactPath) {
+  if (!fs.existsSync(artifactPath)) {
+    return;
+  }
+  const reportGeneratedAt = new Date(report.generatedAt).getTime();
+  const artifactStat = fs.statSync(artifactPath);
+  if (reportGeneratedAt + 1000 < artifactStat.mtimeMs) {
+    fail(`capture-report.json is older than ${path.basename(artifactPath)}. Re-run docs:devtool:capture.`);
+  }
+}
+
+function assertScreenshotFreshAgainstArtifact(filePath, artifactPath) {
+  if (!fs.existsSync(artifactPath)) {
+    return;
+  }
+  const screenshotStat = fs.statSync(filePath);
+  const artifactStat = fs.statSync(artifactPath);
+  if (screenshotStat.mtimeMs + 1000 < artifactStat.mtimeMs) {
+    fail(`Screenshot is older than ${path.basename(artifactPath)}: ${filePath}`);
+  }
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.recipes) {
+    fail('Missing required argument: --recipes');
+  }
+  if (!args['output-dir']) {
+    fail('Missing required argument: --output-dir');
+  }
+
+  const recipesPath = path.resolve(args.recipes);
+  const outputDir = path.resolve(args['output-dir']);
+  const reportPath = path.join(outputDir, 'capture-report.json');
+  const manifestPath = path.join(outputDir, 'manifest.json');
+  const screenshotIndexPath = path.join(outputDir, 'screenshot-index.json');
+  const docVersionPath = path.join(outputDir, 'doc-version.json');
+  const qualityGatePath = path.join(outputDir, 'quality-gate.json');
+
+  if (!fs.existsSync(reportPath)) {
+    fail('Missing capture-report.json. Run docs:devtool:capture before publishing screenshots.');
+  }
+
+  const { schemaVersion, recipes, locales, guideTitle, guideSource } = await loadRecipes(recipesPath);
+  const expectedFingerprint = createScenarioFingerprint({ schemaVersion, recipes, locales, guideTitle, guideSource });
+  const report = readJson(reportPath);
+
+  if (report.scenarioFingerprint !== expectedFingerprint) {
+    fail('DevTool screenshots are stale: capture-report does not match the current scenario manifest.');
+  }
+
+  assertFreshEnough(report, args['max-age-hours']);
+  assertReportFreshAgainstArtifact(report, manifestPath);
+  assertReportFreshAgainstArtifact(report, screenshotIndexPath);
+  assertReportFreshAgainstArtifact(report, docVersionPath);
+  assertReportFreshAgainstArtifact(report, qualityGatePath);
+
+  for (const optionalJson of [manifestPath, screenshotIndexPath, docVersionPath, qualityGatePath]) {
+    if (!fs.existsSync(optionalJson)) continue;
+    const data = readJson(optionalJson);
+    if (data.scenarioFingerprint && data.scenarioFingerprint !== expectedFingerprint) {
+      fail(`${path.basename(optionalJson)} does not match the current scenario manifest.`);
+    }
+  }
+
+  const capturedById = new Map((report.screenshots || []).map(item => [item.id, item]));
+  const expectedIds = [];
+  for (const recipe of recipes) {
+    for (const locale of locales) {
+      expectedIds.push(`${recipe.id}.${locale}`);
+    }
+  }
+
+  for (const id of expectedIds) {
+    const item = capturedById.get(id);
+    if (!item) {
+      fail(`Missing screenshot capture record: ${id}`);
+    }
+    const screenshotPath = path.join(outputDir, item.path);
+    if (!fs.existsSync(screenshotPath)) {
+      fail(`Missing screenshot file: ${item.path}`);
+    }
+    const stats = fs.statSync(screenshotPath);
+    if (stats.size < 1024) {
+      fail(`Screenshot file looks invalid or empty: ${item.path}`);
+    }
+    assertFileFreshAgainstRecipe(screenshotPath, recipesPath);
+    assertScreenshotFreshAgainstArtifact(screenshotPath, manifestPath);
+    assertScreenshotFreshAgainstArtifact(screenshotPath, screenshotIndexPath);
+    assertScreenshotFreshAgainstArtifact(screenshotPath, docVersionPath);
+    assertScreenshotFreshAgainstArtifact(screenshotPath, qualityGatePath);
+  }
+
+  console.log(`[ttmg-docs] screenshot freshness check passed: ${expectedIds.length} screenshots`);
+}
+
+main().catch(error => {
+  console.error('[ttmg-docs] screenshot freshness check failed');
+  console.error(error);
+  process.exit(1);
+});