@su-record/vibe 3.1.0 → 3.2.1

package/hooks/scripts/__tests__/run-ledger.test.js

@@ -18,6 +18,11 @@ import { execFileSync, spawnSync } from 'child_process';
 import { fileURLToPath } from 'url';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PASS_RESULTS = [{ command: 'npm test', exitCode: 0 }];
+
+function verifyOptions(ledger, results = PASS_RESULTS) {
+  return { runId: ledger.runId, verificationResults: results };
+}
 
 // 테스트 격리용 임시 디렉토리
 let tmpDir;
@@ -59,7 +64,7 @@ describe('run-ledger: round-trip', () => {
   it('recordRunStart는 verifyPassed를 false로 리셋', async () => {
     const { recordRunStart, recordVerify, readLedger } = await importLedger();
     recordRunStart(tmpDir, 'f1');
-    recordVerify(tmpDir, true);
+    recordVerify(tmpDir, true, verifyOptions(readLedger(tmpDir)));
     // 두 번째 run — 리셋
     recordRunStart(tmpDir, 'f2');
     const ledger = readLedger(tmpDir);
@@ -72,7 +77,7 @@ describe('run-ledger: round-trip', () => {
     const { recordRunStart, recordVerify, readLedger } = await importLedger();
     recordRunStart(tmpDir, 'feat');
     const before = new Date().toISOString();
-    recordVerify(tmpDir, true);
+    recordVerify(tmpDir, true, verifyOptions(readLedger(tmpDir)));
     const ledger = readLedger(tmpDir);
     expect(ledger.verifyPassed).toBe(true);
     expect(ledger.verifyAt).toBeDefined();
@@ -82,10 +87,133 @@ describe('run-ledger: round-trip', () => {
   it('recordVerify(fail) → verifyPassed=false', async () => {
     const { recordRunStart, recordVerify, readLedger } = await importLedger();
     recordRunStart(tmpDir, 'feat');
-    recordVerify(tmpDir, false);
+    recordVerify(tmpDir, false, verifyOptions(readLedger(tmpDir), []));
     const ledger = readLedger(tmpDir);
     expect(ledger.verifyPassed).toBe(false);
   });
+
+  it('recordVerify → 안정된 runId 경로에 evidence.json 원자 기록', async () => {
+    const { recordRunStart, recordVerify, readLedger } = await importLedger();
+    recordRunStart(tmpDir, 'feat');
+    const started = readLedger(tmpDir);
+    fs.mkdirSync(path.join(tmpDir, '.vibe', 'specs'), { recursive: true });
+    fs.writeFileSync(path.join(tmpDir, '.vibe', 'specs', 'feat.md'), '# SPEC');
+    expect(recordVerify(tmpDir, true, verifyOptions(started))).toBe(true);
+
+    const after = readLedger(tmpDir);
+    expect(after.runId).toBe(started.runId);
+    const evidencePath = path.join(tmpDir, '.vibe', 'runs', after.runId, 'evidence.json');
+    expect(fs.existsSync(evidencePath)).toBe(true);
+    const evidence = JSON.parse(fs.readFileSync(evidencePath, 'utf-8'));
+    expect(evidence).toMatchObject({
+      schemaVersion: '1.0.0',
+      runId: after.runId,
+      specPath: '.vibe/specs/feat.md',
+      judges: {
+        deterministic: { authority: 'blocking', verifyPassed: true },
+        model: { authority: 'advisory-only', canComplete: false },
+        humanTaste: { authority: 'release-only', canComplete: false },
+      },
+    });
+  });
+
+  it('레거시 ledger도 runId를 보강하고 누락된 검증 결과는 빈 배열로 기록', async () => {
+    const p = path.join(tmpDir, '.vibe', 'metrics', 'run-ledger.json');
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify({ runStarted: '2026-01-01T00:00:00.000Z' }));
+    const { recordVerify, readLedger } = await importLedger();
+    expect(recordVerify(tmpDir, false)).toBe(true);
+    const ledger = readLedger(tmpDir);
+    const evidencePath = path.join(tmpDir, '.vibe', 'runs', ledger.runId, 'evidence.json');
+    const evidence = JSON.parse(fs.readFileSync(evidencePath, 'utf-8'));
+    expect(evidence.specPath).toBeNull();
+    expect(evidence.judges.deterministic.verificationResults).toEqual([]);
+  });
+
+  it('기존 verificationResults의 command와 exitCode를 evidence에 보존', async () => {
+    const { recordRunStart, recordVerify, readLedger } = await importLedger();
+    recordRunStart(tmpDir, 'feat');
+    const p = path.join(tmpDir, '.vibe', 'metrics', 'run-ledger.json');
+    const ledger = readLedger(tmpDir);
+    fs.writeFileSync(p, JSON.stringify({
+      ...ledger,
+      verificationResults: [{ command: 'npm test', exitCode: 0 }],
+    }));
+    recordVerify(tmpDir, true, verifyOptions(ledger, [
+      { command: 'npm test', exitCode: 0 },
+    ]));
+    const evidencePath = path.join(tmpDir, '.vibe', 'runs', ledger.runId, 'evidence.json');
+    const evidence = JSON.parse(fs.readFileSync(evidencePath, 'utf-8'));
+    expect(evidence.judges.deterministic.verificationResults)
+      .toEqual([{ command: 'npm test', exitCode: 0 }]);
+  });
+
+  it('새 run은 이전 run의 검증 결과를 제거', async () => {
+    const { recordRunStart, recordVerify, readLedger } = await importLedger();
+    recordRunStart(tmpDir, 'first');
+    const first = readLedger(tmpDir);
+    recordVerify(tmpDir, true, verifyOptions(first, [{ command: 'old-test', exitCode: 0 }]));
+
+    recordRunStart(tmpDir, 'second');
+    const second = readLedger(tmpDir);
+    expect(second.verificationResults).toBeUndefined();
+    recordVerify(tmpDir, true, verifyOptions(second));
+    const evidencePath = path.join(tmpDir, '.vibe', 'runs', second.runId, 'evidence.json');
+    const evidence = JSON.parse(fs.readFileSync(evidencePath, 'utf-8'));
+    expect(evidence.judges.deterministic.verificationResults).toEqual(PASS_RESULTS);
+  });
+
+  it('조작된 runId는 프로젝트 밖에 evidence를 기록하지 않음', async () => {
+    const ledgerPath = path.join(tmpDir, '.vibe', 'metrics', 'run-ledger.json');
+    const escapedDir = path.join(path.dirname(tmpDir), `escaped-${path.basename(tmpDir)}`);
+    fs.mkdirSync(path.dirname(ledgerPath), { recursive: true });
+    fs.writeFileSync(ledgerPath, JSON.stringify({
+      runId: `../../../${path.basename(escapedDir)}`,
+      runStarted: new Date().toISOString(),
+      verifyPassed: false,
+    }));
+    const { recordVerify } = await importLedger();
+    expect(recordVerify(tmpDir, true, {
+      runId: `../../../${path.basename(escapedDir)}`,
+      verificationResults: PASS_RESULTS,
+    })).toBe(false);
+    expect(fs.existsSync(path.join(escapedDir, 'evidence.json'))).toBe(false);
+  });
+
+  it('evidence 기록 실패 시 ledger를 통과 상태로 바꾸지 않음', async () => {
+    const { recordRunStart, recordVerify, readLedger } = await importLedger();
+    recordRunStart(tmpDir, 'feat');
+    const ledger = readLedger(tmpDir);
+    const runPath = path.join(tmpDir, '.vibe', 'runs', ledger.runId);
+    fs.mkdirSync(path.dirname(runPath), { recursive: true });
+    fs.writeFileSync(runPath, 'occupied');
+
+    expect(recordVerify(tmpDir, true, verifyOptions(ledger))).toBe(false);
+    expect(readLedger(tmpDir).verifyPassed).toBe(false);
+  });
+
+  it('다른 runId의 verify 결과를 현재 run에 적용하지 않음', async () => {
+    const { recordRunStart, recordVerify, readLedger } = await importLedger();
+    recordRunStart(tmpDir, 'feat');
+    expect(recordVerify(tmpDir, true, {
+      runId: 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa',
+      verificationResults: PASS_RESULTS,
+    })).toBe(false);
+    expect(readLedger(tmpDir).verifyPassed).toBe(false);
+  });
+
+  it('분할 SPEC의 _index.md를 evidence 경로로 기록', async () => {
+    const { recordRunStart, recordVerify, readLedger } = await importLedger();
+    const specDir = path.join(tmpDir, '.vibe', 'specs', 'large-feature');
+    fs.mkdirSync(specDir, { recursive: true });
+    fs.writeFileSync(path.join(specDir, '_index.md'), '# Master SPEC');
+    recordRunStart(tmpDir, 'large-feature');
+    const ledger = readLedger(tmpDir);
+    recordVerify(tmpDir, true, verifyOptions(ledger));
+    const evidencePath = path.join(tmpDir, '.vibe', 'runs', ledger.runId, 'evidence.json');
+    const evidence = JSON.parse(fs.readFileSync(evidencePath, 'utf-8'));
+    expect(evidence.specPath).toBe('.vibe/specs/large-feature/_index.md');
+  });
 });
 
 // ──────────────────────────────────────────────────────────────────
@@ -101,7 +229,7 @@ describe('run-ledger: verifyAt > runStarted', () => {
     const patched = { ...ledger, runStarted: new Date(Date.now() - 1000).toISOString() };
     fs.writeFileSync(p, JSON.stringify(patched), 'utf-8');
 
-    recordVerify(tmpDir, true);
+    recordVerify(tmpDir, true, verifyOptions(readLedger(tmpDir)));
     const after = readLedger(tmpDir);
     expect(after.verifyAt > after.runStarted).toBe(true);
     expect(after.verifyPassed).toBe(true);
@@ -170,6 +298,12 @@ describe('run-ledger: vibe.run 감지 헬퍼', () => {
     expect(extractRunFeature('$vibe.run auth-login ultrawork')).toBe('auth-login');
   });
 
+  it('extractRunFeature: 따옴표를 제거해 SPEC 경로용 기능명을 반환', async () => {
+    const { extractRunFeature } = await importLedger();
+    expect(extractRunFeature('/vibe.run "auth-login"')).toBe('auth-login');
+    expect(extractRunFeature("$vibe.run 'auth-login'")).toBe('auth-login');
+  });
+
   it('extractRunFeature: 기능명 없으면 null', async () => {
     const { extractRunFeature } = await importLedger();
     expect(extractRunFeature('/vibe.run --phase 1')).toBeNull();
@@ -200,11 +334,17 @@ describe('run-ledger: stopWarned', () => {
 describe('verify-ledger CLI', () => {
   const CLI = path.resolve(__dirname, '..', 'verify-ledger.js');
 
+  function cliArgs(status, ledger, results = PASS_RESULTS) {
+    const resultsPath = path.join(tmpDir, 'verification-results.json');
+    fs.writeFileSync(resultsPath, JSON.stringify(results));
+    return [CLI, status, ledger.runId, resultsPath];
+  }
+
   it('pass 인자 → verifyPassed=true, exit 0', async () => {
-    const { recordRunStart } = await importLedger();
+    const { recordRunStart, readLedger } = await importLedger();
     recordRunStart(tmpDir, 'feat');
 
-    const result = spawnSync('node', [CLI, 'pass'], {
+    const result = spawnSync('node', cliArgs('pass', readLedger(tmpDir)), {
       encoding: 'utf-8',
       timeout: 5000,
       env: { ...process.env, CLAUDE_PROJECT_DIR: tmpDir },
@@ -212,16 +352,15 @@ describe('verify-ledger CLI', () => {
     expect(result.status).toBe(0);
     expect(result.stdout).toContain('verifyPassed=true');
 
-    const { readLedger } = await importLedger();
     const ledger = readLedger(tmpDir);
     expect(ledger.verifyPassed).toBe(true);
   });
 
   it('fail 인자 → verifyPassed=false, exit 0', async () => {
-    const { recordRunStart } = await importLedger();
+    const { recordRunStart, readLedger } = await importLedger();
     recordRunStart(tmpDir, 'feat');
 
-    const result = spawnSync('node', [CLI, 'fail'], {
+    const result = spawnSync('node', cliArgs('fail', readLedger(tmpDir), []), {
       encoding: 'utf-8',
       timeout: 5000,
       env: { ...process.env, CLAUDE_PROJECT_DIR: tmpDir },
@@ -229,7 +368,6 @@ describe('verify-ledger CLI', () => {
     expect(result.status).toBe(0);
     expect(result.stdout).toContain('verifyPassed=false');
 
-    const { readLedger } = await importLedger();
     const ledger = readLedger(tmpDir);
     expect(ledger.verifyPassed).toBe(false);
   });
@@ -242,6 +380,19 @@ describe('verify-ledger CLI', () => {
     });
     expect(result.status).toBe(0);
   });
+
+  it('기록 실패는 exit 0을 유지하되 stderr 경고로 노출', () => {
+    const projectFile = path.join(tmpDir, 'not-a-directory');
+    fs.writeFileSync(projectFile, 'occupied');
+    const result = spawnSync('node', [CLI, 'pass'], {
+      encoding: 'utf-8',
+      timeout: 5000,
+      env: { ...process.env, CLAUDE_PROJECT_DIR: projectFile },
+    });
+    expect(result.status).toBe(0);
+    expect(result.stderr).toContain('evidence.json write failed');
+    expect(result.stdout).not.toContain('recorded:');
+  });
 });
 
 // ──────────────────────────────────────────────────────────────────

package/hooks/scripts/__tests__/step-counter.test.js

@@ -435,4 +435,25 @@ describe('step-counter PostToolUse hook', () => {
       expect(files).toHaveLength(1);
     });
   });
+
+  // ───────── A2/D2: 64KB 초과 stdin 페이로드 (구 단일 버퍼 리더 절단 버그 회귀) ─────────
+  describe('stdin 64KB 초과 페이로드 — 절단 없이 처리', () => {
+    it('페이로드가 64KB를 넘어도 JSON 전체를 읽어 target_file을 정확히 기록', () => {
+      // 구현이 64KB 단일 버퍼로 되돌아가면 JSON이 중간에 잘려 파싱 실패 →
+      // stdinPayload=null → jsonl 라인 자체가 기록되지 않는다.
+      const padding = 'x'.repeat(80000); // 총 페이로드 > 64KB 보장
+      runCounter({
+        payload: {
+          tool_name: 'Edit',
+          tool_input: { file_path: 'src/foo.ts', padding },
+          tool_response: {},
+        },
+        projectDir,
+      });
+      const lines = readJsonl(runJsonl);
+      expect(lines).toHaveLength(1);
+      expect(lines[0].target_file).toBe('src/foo.ts');
+      expect(lines[0].tool).toBe('Edit');
+    });
+  });
 });

package/hooks/scripts/__tests__/utils-npm-root.test.js

@@ -15,10 +15,11 @@ import { spawnSync } from 'child_process';
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
-import { fileURLToPath } from 'url';
+import { fileURLToPath, pathToFileURL } from 'url';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const UTILS_PATH = path.resolve(__dirname, '..', 'utils.js');
+// Windows 절대경로(C:\...)는 ESM import 지정자가 될 수 없으므로 file:// URL로 변환
+const UTILS_URL = pathToFileURL(path.resolve(__dirname, '..', 'utils.js')).href;
 
 function makeTempCacheFile() {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'vibe-npm-root-test-'));
@@ -30,8 +31,8 @@ function makeTempCacheFile() {
  * VIBE_NPM_ROOT_CACHE_FILE 환경 변수로 캐시 파일 경로를 주입한다.
  */
 function runGetNpmRoot(cacheFilePath) {
-  return spawnSync('node', ['--input-type=module', '--eval',
-    `import { getGlobalNpmPath } from '${UTILS_PATH}';
+  return spawnSync(process.execPath, ['--input-type=module', '--eval',
+    `import { getGlobalNpmPath } from '${UTILS_URL}';
      process.stdout.write(getGlobalNpmPath() || '');`
   ], {
     encoding: 'utf-8',

package/hooks/scripts/auto-format.js

@@ -24,15 +24,6 @@ const PYTHON_EXT_RE = /\.py$/;
 const GO_EXT_RE = /\.go$/;
 const FORMAT_TIMEOUT_MS = 5000;
 
-function getFilePath(ctx) {
-  try {
-    const input = JSON.parse(ctx.toolInput || '{}');
-    return input.file_path || input.path || '';
-  } catch {
-    return '';
-  }
-}
-
 // PATH 직접 스캔 — `which` execSync는 매 파일 저장마다 자식 프로세스를 동기
 // spawn하므로, fs.existsSync로 대체하고 프로세스 내 캐싱한다.
 const _binCache = new Map();
@@ -109,13 +100,13 @@ async function formatFile(filePath) {
 
 /**
  * in-process 진입점 — 포맷 실행. finding 문자열 배열 반환.
- * @param {{ toolInput: string }} ctx
+ * @param {{ filePath: string }} ctx
  * @returns {Promise<{ exitCode: number, findings: string[] }>}
  */
 export async function run(ctx) {
   const findings = [];
   try {
-    const filePath = getFilePath(ctx);
+    const filePath = ctx.filePath;
     if (filePath) {
       const finding = await formatFile(filePath);
       if (finding) findings.push(finding);

package/hooks/scripts/auto-test.js

@@ -33,15 +33,6 @@ const DEBOUNCE_COOLDOWN_MS = 120_000;
 /** debounce 상태 파일 경로 */
 const DEBOUNCE_STATE_FILE = path.join(PROJECT_DIR, '.vibe', 'metrics', 'auto-test-state.json');
 
-function getFilePath(ctx) {
-  try {
-    const input = JSON.parse(ctx.toolInput || '{}');
-    return input.file_path || input.path || '';
-  } catch {
-    return '';
-  }
-}
-
 function isTestFile(filePath) {
   return TEST_SUFFIXES.some(s => filePath.includes(s));
 }
@@ -163,13 +154,13 @@ function updateDebounceState(testFile, srcFile) {
 
 /**
  * in-process 진입점 — 테스트 실행. findings 반환.
- * @param {{ toolInput: string }} ctx
+ * @param {{ filePath: string }} ctx
  * @returns {Promise<{ exitCode: number, findings: string[] }>}
  */
 export async function run(ctx) {
   const findings = [];
   try {
-    const filePath = getFilePath(ctx);
+    const filePath = ctx.filePath;
     if (!filePath || !CODE_EXT_RE.test(filePath)) return { exitCode: 0, findings };
 
     const mode = getTestMode();

package/hooks/scripts/clone-extract.js

@@ -78,6 +78,11 @@ const CSS_PROPS = [
   'mask-image', 'mask-size', 'mask-position', 'clip-path',
 ];
 
+const SUB_URL_LIMIT = 200;
+const SUB_EXCLUDE_TEXT_RE = /^(?:검색|search|top|home|kor|eng|chn|vtn|language|언어|개인정보|privacy|문의|제안|sitemap|사이트맵|youtube|뉴스룸|newsroom|cookie|닫기|partner|파트너)$/i;
+const SUB_EXCLUDE_PATH_RE = /\/(?:search|sitemap|privacy|contact|inquiry|cookie|login|auth|policy)(?:\/|$)/i;
+const SUB_EXCLUDE_EXT_RE = /\.(?:pdf|zip|jpe?g|png|gif|webp|svg|mp4|mov|avi|docx?|xlsx?|pptx?)$/i;
+
 // ─── CLI parse ──────────────────────────────────────────────────────
 function parseArgs(argv) {
   const [, , cmd, urlArg, ...rest] = argv;
@@ -104,6 +109,74 @@ function parseViewport(v) {
   };
 }
 
+function localePrefixOf(rawUrl) {
+  const first = new URL(rawUrl).pathname.split('/').filter(Boolean)[0];
+  if (!first || !/^[a-z]{2,3}(?:-[a-z]{2})?$/i.test(first)) return null;
+  return `/${first}`;
+}
+
+function normalizeSubUrl(startUrl, href) {
+  if (!href || typeof href !== 'string') return null;
+  try {
+    const target = new URL(href, startUrl);
+    if (target.protocol !== 'http:' && target.protocol !== 'https:') return null;
+    target.hash = '';
+    target.search = '';
+    target.pathname = target.pathname.replace(/\/+$/, '') || '/';
+    return target;
+  } catch {
+    return null;
+  }
+}
+
+function isSameMenuScope(target, start, localePrefix) {
+  if (target.origin !== start.origin) return false;
+  if (!localePrefix) return true;
+  return target.pathname === localePrefix || target.pathname.startsWith(`${localePrefix}/`);
+}
+
+function isExcludedSubLink(target, text) {
+  const label = String(text || '').trim();
+  if (SUB_EXCLUDE_TEXT_RE.test(label)) return true;
+  if (SUB_EXCLUDE_PATH_RE.test(target.pathname)) return true;
+  return SUB_EXCLUDE_EXT_RE.test(target.pathname);
+}
+
+function collectSubUrls(startUrl, links, limit = SUB_URL_LIMIT) {
+  const start = normalizeSubUrl(startUrl, startUrl);
+  if (!start) return [];
+  const localePrefix = localePrefixOf(start.href);
+  const urls = [start.href];
+  const seen = new Set(urls);
+
+  for (const link of links) {
+    if (urls.length >= limit) break;
+    const target = normalizeSubUrl(start.href, link.href);
+    if (!target || seen.has(target.href)) continue;
+    if (!isSameMenuScope(target, start, localePrefix)) continue;
+    if (isExcludedSubLink(target, link.text)) continue;
+    seen.add(target.href);
+    urls.push(target.href);
+  }
+
+  return urls;
+}
+
+function findSitemapUrl(startUrl, links) {
+  const start = normalizeSubUrl(startUrl, startUrl);
+  if (!start) return null;
+  const localePrefix = localePrefixOf(start.href);
+
+  for (const link of links) {
+    const label = String(link.text || '').trim();
+    if (!/sitemap|사이트맵/i.test(`${label} ${link.href}`)) continue;
+    const target = normalizeSubUrl(start.href, link.href);
+    if (target && isSameMenuScope(target, start, localePrefix)) return target.href;
+  }
+
+  return null;
+}
+
 // ─── Puppeteer dynamic loader (optional dep) ────────────────────────
 async function loadPuppeteer() {
   try {
@@ -905,6 +978,14 @@ const SEO_EXTRACT = `(function () {
   return Array.from(new Set(icons.concat(og)));
 })`;
 
+const SUB_LINK_EXTRACT = `(function () {
+  const links = Array.from(document.querySelectorAll('a[href]')).map((a) => ({
+    href: a.getAttribute('href'),
+    text: (a.innerText || a.textContent || '').replace(/\\s+/g, ' ').trim(),
+  }));
+  return { links };
+})`;
+
 // HTML sanitization: strip scripts/analytics before saving
 function sanitizeHtml(html) {
   return html
@@ -914,6 +995,65 @@ function sanitizeHtml(html) {
     .replace(/\son[a-z]+='[^']*'/gi, '');
 }
 
+async function newClonePage(browser) {
+  const page = await browser.newPage();
+  await page.setViewport({ width: 1440, height: 900, deviceScaleFactor: 1 });
+  await page.setUserAgent(
+    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 ' +
+    '(KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+  );
+  await page.setCacheEnabled(false);
+  return page;
+}
+
+async function discoverSubUrls({ url, opts }) {
+  if (!url) throw new Error('URL is required');
+  if (!opts.out) throw new Error('--out=<file> is required');
+
+  if (!opts.ignoreRobots) {
+    const blocked = await checkRobots(url);
+    if (blocked) {
+      throw new Error(
+        `robots.txt disallows ${url}. Pass --ignore-robots only with the site owner's permission.`,
+      );
+    }
+  }
+
+  const puppeteer = await loadPuppeteer();
+  const browser = await puppeteer.launch({
+    headless: 'new',
+    args: ['--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage'],
+  });
+
+  try {
+    const page = await newClonePage(browser);
+    await page.goto(url, { waitUntil: 'networkidle2', timeout: 90000 });
+    await wait(800);
+
+    let source = 'menu';
+    let sourceUrl = url;
+    let { links } = await page.evaluate(`(${SUB_LINK_EXTRACT})()`);
+    const sitemapUrl = findSitemapUrl(url, links);
+    if (sitemapUrl) {
+      await page.goto(sitemapUrl, { waitUntil: 'networkidle2', timeout: 90000 });
+      await wait(800);
+      source = 'sitemap';
+      sourceUrl = sitemapUrl;
+      ({ links } = await page.evaluate(`(${SUB_LINK_EXTRACT})()`));
+    }
+
+    const urls = collectSubUrls(url, links);
+    fs.mkdirSync(path.dirname(opts.out), { recursive: true });
+    fs.writeFileSync(
+      opts.out,
+      JSON.stringify({ meta: { url, source, sourceUrl, count: urls.length }, urls }, null, 2),
+    );
+    process.stdout.write(`[clone-extract] suburls ${urls.length} → ${opts.out}\n`);
+  } finally {
+    await browser.close();
+  }
+}
+
 // ─── Main capture flow ──────────────────────────────────────────────
 async function capture({ url, opts }) {
   if (!url) throw new Error('URL is required');
@@ -954,14 +1094,8 @@ async function capture({ url, opts }) {
   });
 
   try {
-    const page = await browser.newPage();
+    const page = await newClonePage(browser);
     await page.setViewport(viewport);
-    await page.setUserAgent(
-      'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 ' +
-      '(KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
-    );
-    // disable cache to get fresh assets
-    await page.setCacheEnabled(false);
 
     await page.goto(url, { waitUntil: 'networkidle2', timeout: 90000 });
     await scrollToBottom(page);
@@ -1140,16 +1274,18 @@ const isMain = process.argv[1] && process.argv[1].replace(/\\/g, '/').endsWith('
 if (isMain) {
   const { cmd, url, opts } = parseArgs(process.argv);
 
-  if (cmd !== 'capture') {
+  if (cmd !== 'capture' && cmd !== 'suburls') {
     console.error('Usage: node clone-extract.js capture <URL> --out=<dir> --viewport=WxH[@DPR] --bp=mo|pc [--stealth] [--ignore-robots] [--no-interact] [--wait=ms]');
+    console.error('       node clone-extract.js suburls <URL> --out=<file> [--ignore-robots]');
     process.exit(1);
   }
 
-  capture({ url, opts }).catch((err) => {
+  const run = cmd === 'suburls' ? discoverSubUrls : capture;
+  run({ url, opts }).catch((err) => {
     console.error(`[clone-extract] FAIL: ${err.message}`);
     if (process.env.DEBUG) console.error(err.stack);
     process.exit(1);
   });
 }
 
-export { diffStyles };
+export { collectSubUrls, diffStyles };