isthmus-cli 0.5.0 → 0.7.0

package/scripts/build-preflight-toolchain.mjs

@@ -0,0 +1,186 @@
+import { createHash } from 'node:crypto';
+import { lstat, mkdir, mkdtemp, readFile, readdir, realpath, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runChild } from './run-child.mjs';
+
+const names = ['isthmus', 'cartograph', 'dartograph', 'kartograph'];
+
+/** 변경 중인 작업 트리 대신 명시한 immutable commit의 소스만 구축한다. */
+export function parseToolchainManifest(input) {
+  if (!record(input) || input.format !== 'isthmus-toolchain-build' || input.version !== 1 ||
+    !text(input.destination) || !record(input.repositories) ||
+    Object.keys(input.repositories).some((name) => !names.includes(name))) throw new Error('Invalid toolchain build manifest.');
+  if (input.repositories.cartograph === undefined && input.repositories.kartograph === undefined) {
+    throw new Error('Configure at least one native producer repository.');
+  }
+  const repositories = {};
+  for (const name of names) {
+    const entry = input.repositories[name];
+    if ((name === 'cartograph' || name === 'kartograph') && entry === undefined) continue;
+    if (!record(entry) || !text(entry.path) || typeof entry.revision !== 'string' || !/^[a-f0-9]{40}$/u.test(entry.revision)) {
+      throw new Error('Each toolchain repository requires a local path and full commit id.');
+    }
+    repositories[name] = { path: entry.path, revision: entry.revision };
+  }
+  return { format: input.format, version: 1, destination: input.destination, repositories };
+}
+
+/** 새 디렉터리에 source archive·실행 파일·설치된 CLI와 재사용할 명령 목록을 만든다. */
+export async function buildToolchain(input, base = process.cwd(), onStep = () => {}) {
+  const config = parseToolchainManifest(input);
+  const selectedNames = names.filter((name) => config.repositories[name] !== undefined);
+  const destination = resolve(base, config.destination);
+  if (await exists(destination)) throw new Error('Toolchain destination already exists; choose a new directory.');
+  const repositories = {};
+  // source commit 오류를 발견했을 때 SDK 준비나 destination 쓰기를 시작하지 않는다.
+  for (const name of selectedNames) {
+    const path = await realpath(resolve(base, config.repositories[name].path));
+    const revision = config.repositories[name].revision;
+    const result = runChild('git', ['-c', 'core.fsmonitor=false', '-C', path, 'rev-parse', '--verify', `${revision}^{commit}`]);
+    if (result.status !== 0 || result.stdout.trim() !== revision) throw new Error(`Unable to resolve ${name} commit.`);
+    repositories[name] = { path, revision };
+  }
+  const evidence = await mkdtemp(join(tmpdir(), 'isthmus-toolchain-build-evidence-'));
+  const steps = [];
+  const started = performance.now();
+  let created = false;
+  const environment = { ...process.env, CI: 'true', FLUTTER_SUPPRESS_ANALYTICS: 'true',
+    GIT_TERMINAL_PROMPT: '0', LLVM_PROFILE_FILE: join(evidence, 'profile-%p.profraw') };
+  async function command(label, executable, args, cwd = destination, timeout = 600_000) {
+    onStep(label);
+    const began = performance.now();
+    const result = runChild(executable, args, { cwd, timeout, env: environment, maxBuffer: 32 * 1024 * 1024 });
+    const log = join(evidence, `${steps.length}-${label}.log`);
+    await writeFile(log, `${result.stdout ?? ''}\n${result.stderr ?? ''}`, { mode: 0o600 });
+    steps.push({ label, milliseconds: Math.round(performance.now() - began), exitCode: result.status });
+    if (result.status !== 0 || result.error) throw new Error(`Toolchain step failed: ${label}; see ${log}`);
+    return result.stdout.trim();
+  }
+  try {
+    await mkdir(destination, { mode: 0o700 }); created = true;
+    for (const name of selectedNames) {
+      const source = join(destination, 'sources', name);
+      const archive = join(evidence, `${name}.tar`);
+      await mkdir(source, { recursive: true });
+      await command(`${name}-archive`, 'git', ['-c', 'core.fsmonitor=false', '-C', repositories[name].path,
+        'archive', '--format=tar', '--output', archive, repositories[name].revision]);
+      await command(`${name}-extract`, 'tar', ['-xf', archive, '-C', source]);
+      repositories[name].checkout = source;
+    }
+    const commands = {};
+    const nativeFiles = [];
+    const artifacts = {};
+    let swiftVersion;
+    let javaVersion;
+    const dartVersion = await command('dart-version', 'dart', ['--version']);
+    if (repositories.cartograph !== undefined) {
+      swiftVersion = await command('swift-version', 'swift', ['--version']);
+      const native = repositories.cartograph.checkout;
+      await command('cartograph-build', 'swift', ['build', '--package-path', native, '--configuration', 'debug', '--skip-update']);
+      const reported = await command('cartograph-bin-path', 'swift', ['build', '--package-path', native, '--configuration', 'debug', '--show-bin-path']);
+      const candidates = [join(native, '.build/out/Products/Debug/cartograph'), join(reported, 'cartograph')];
+      const binaries = [...new Set(await Promise.all(candidates.map(async (path) => {
+        try { return await realpath(path); } catch { return undefined; }
+      })))].filter(Boolean);
+      if (binaries.length !== 1) throw new Error('Swift build did not identify one cartograph executable.');
+      const cartograph = binaries[0];
+      await command('cartograph-impact-help', cartograph, ['impact', '--help']);
+      const messageHelp = await command('cartograph-messages-help', cartograph, ['bridges', '--help']);
+      if (!messageHelp.includes('--messages')) throw new Error('The cartograph commit does not support message facts.');
+      commands.cartograph = [cartograph];
+      nativeFiles.push(['cartograph', cartograph]);
+    }
+    if (repositories.kartograph !== undefined) {
+      javaVersion = await command('java-version', process.env.JAVA_HOME ? join(process.env.JAVA_HOME, 'bin/java') : 'java', ['--version']);
+      const kotlinRoot = repositories.kartograph.checkout;
+      await command('kartograph-build', join(kotlinRoot, 'gradlew'), ['--no-daemon', ':cli:installDist'], kotlinRoot);
+      const kartograph = join(kotlinRoot, 'cli/build/install/kartograph/bin/kartograph');
+      const libraryRoot = join(kotlinRoot, 'cli/build/install/kartograph/lib');
+      await command('kartograph-impact-help', kartograph, ['impact', '--help']);
+      const bridgeHelp = await command('kartograph-messages-help', kartograph, ['bridges', '--help']);
+      if (!bridgeHelp.includes('--messages') || !bridgeHelp.includes('--graph-file')) {
+        throw new Error('The kartograph commit does not support indexed message facts.');
+      }
+      commands.kartograph = [kartograph];
+      nativeFiles.push(['kartograph', kartograph]);
+      artifacts.kartographInputs = [kartograph, libraryRoot];
+    }
+    const dartRoot = repositories.dartograph.checkout;
+    await command('dartograph-dependencies', 'dart', ['pub', 'get'], dartRoot);
+    await mkdir(join(destination, 'bin'));
+    const dartograph = join(destination, 'bin/dartograph');
+    await command('dartograph-build', 'dart', ['compile', 'exe', 'bin/dartograph.dart', '-o', dartograph], dartRoot);
+    const dartHelp = await command('dartograph-messages-help', dartograph, ['--help']);
+    if (!dartHelp.includes('--messages')) throw new Error('The dartograph commit does not support message facts.');
+    const nodeRoot = repositories.isthmus.checkout;
+    await command('isthmus-dependencies', 'npm', ['ci'], nodeRoot);
+    await command('isthmus-build', 'npm', ['run', 'build'], nodeRoot);
+    const packed = JSON.parse(await command('isthmus-pack', 'npm', ['pack', '--ignore-scripts', '--json', '--pack-destination', destination], nodeRoot));
+    if (packed.length !== 1 || packed[0].name !== 'isthmus-cli') throw new Error('Unexpected isthmus package artifact.');
+    const install = join(destination, 'installed');
+    await command('isthmus-install', 'npm', ['install', '--prefix', install, '--offline', '--ignore-scripts', '--no-audit', '--no-fund', join(destination, packed[0].filename)]);
+    const isthmus = join(install, 'node_modules/isthmus-cli/dist/cli/main.js');
+    const help = await command('isthmus-preflight-help', process.execPath, [isthmus, 'preflight', '--help']);
+    if (!help.includes('--summary') || !help.includes('--explain')) throw new Error('The isthmus commit does not support bounded preflight views.');
+    if (repositories.kartograph !== undefined) {
+      const context = join(evidence, 'android-context.json');
+      await writeFile(context, JSON.stringify({ format: 'isthmus-preflight-context', version: 1,
+        project: destination, revision: 'toolchain-capability', selection: {}, bindings: [], analyses: [], limitations: [],
+        bridges: ['dart', 'kotlin'].map((platform) => ({ format: 'bridge-facts', version: 1, platform, target: null,
+          project: destination, generatedAt: '1970-01-01T00:00:00Z', tool: { name: platform, version: 'capability' },
+          facts: [], limitations: [] })) }), { mode: 0o600 });
+      const report = JSON.parse(await command('isthmus-kotlin-preflight', process.execPath, [isthmus, 'preflight', context, '--summary']));
+      if (report.format !== 'isthmus-preflight-summary') throw new Error('The isthmus commit does not support Kotlin preflight inputs.');
+    }
+    commands.isthmus = [process.execPath, isthmus];
+    commands.dartograph = [dartograph];
+    const hashes = {};
+    for (const [name, path] of [...nativeFiles, ['dartograph', dartograph], ['isthmusPackage', join(destination, packed[0].filename)]]) {
+      hashes[name] = createHash('sha256').update(await readFile(path)).digest('hex');
+    }
+    if (artifacts.kartographInputs) {
+      const libraries = artifacts.kartographInputs[1];
+      const hash = createHash('sha256');
+      const jars = (await readdir(libraries)).filter((name) => name.endsWith('.jar')).sort();
+      if (jars.length === 0) throw new Error('Kartograph distribution has no runtime libraries.');
+      for (const name of jars) hash.update(name).update('\0').update(createHash('sha256').update(await readFile(join(libraries, name))).digest());
+      hashes.kartographLibraries = hash.digest('hex');
+    }
+    const result = { format: 'isthmus-built-toolchain', version: 1, destination, repositories, commands, hashes,
+      ...(Object.keys(artifacts).length === 0 ? {} : { artifacts }),
+      environment: { node: process.version, platform: process.platform, arch: process.arch,
+        ...(swiftVersion === undefined ? {} : { swift: swiftVersion }), ...(javaVersion === undefined ? {} : { java: javaVersion }), dart: dartVersion },
+      scope: 'committed-source-build-and-cli-capabilities', milliseconds: Math.round(performance.now() - started), evidence, steps };
+    await writeFile(join(destination, 'toolchain.json'), JSON.stringify(result, null, 2), { mode: 0o600 });
+    return result;
+  } catch (error) {
+    await writeFile(join(evidence, 'failure.json'), JSON.stringify({ steps, failed: true }, null, 2), { mode: 0o600 });
+    if (created) await rm(destination, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+function record(value) { return value !== null && typeof value === 'object' && !Array.isArray(value); }
+function text(value) { return typeof value === 'string' && value.length > 0 && !/[\u0000-\u001f]/u.test(value); }
+async function exists(path) {
+  try { await lstat(path); return true; } catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  if (process.argv.length !== 3) {
+    process.stderr.write('Usage: build-preflight-toolchain.mjs <build-manifest.json>\n'); process.exitCode = 64;
+  } else {
+    try {
+      const path = resolve(process.argv[2]);
+      const result = await buildToolchain(JSON.parse(await readFile(path, 'utf8')), dirname(path),
+        (step) => process.stderr.write(`Toolchain: ${step}\n`));
+      process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    } catch (error) {
+      const message = error instanceof SyntaxError ? 'Build manifest or package metadata is not valid JSON.'
+        : typeof error.code === 'string' ? 'Unable to access a required toolchain file or process.' : error.message;
+      process.stderr.write(`Toolchain build failed: ${message}\n`); process.exitCode = 1;
+    }
+  }
+}

package/scripts/capture-preflight.mjs

@@ -0,0 +1,380 @@
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { lstat, mkdir, mkdtemp, readFile, readdir, realpath, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CaptureConfigValidationError, validateCaptureConfig } from '../dist/exchange/capture-config.js';
+import { parseImpactSelection } from '../dist/exchange/impact-selection.js';
+import { isProjectRelativePath, isSafeNonEmptyString, parseBridgeFactsDocument } from '../dist/exchange/parse.js';
+import { parsePreflightContext } from '../dist/exchange/preflight-context.js';
+import { parseMessageBridgeDocument } from '../dist/exchange/messages.js';
+import { adaptCartographImpact, adaptDartographImpact } from '../dist/exchange/producer-impact.js';
+import { adaptKartographImpact } from '../dist/exchange/kartograph-impact.js';
+import { createPreflightReport, hasPreflightBlockers } from '../dist/report/preflight.js';
+import { encodeSortedJson } from '../dist/report/sorted-json.js';
+import { writeTextAtomically } from '../dist/cli/atomic-write.js';
+import { runChild } from './run-child.mjs';
+
+/** workflow 실패는 자식 출력·입력 경로를 오류 본문에 싣지 않는다. */
+class CaptureError extends Error {}
+
+/** 명시한 소스·설정·도구 입력이 같은 동안 수집한 producer 결과만 캐시한다. */
+export async function capturePreflight(config, { execute = runChild } = {}) {
+  const started = performance.now();
+  const project = await realpath(config.project);
+  // 검증 정본은 제품(`isthmus doctor`)과 공유한다. 계약 위반은 워크플로 오류로 감싼다.
+  try { validateCaptureConfig(config, project); }
+  catch (error) {
+    if (error instanceof CaptureConfigValidationError) throw new CaptureError(error.message);
+    throw error;
+  }
+  const natives = [['swift', 'cartograph'], ['kotlin', 'kartograph']].filter(([, name]) => config[name] !== undefined);
+  const producerNames = ['dartograph', ...natives.map(([, name]) => name)];
+  const output = resolve(project, config.output);
+  const cachePath = resolve(project, config.cache);
+  const selection = {};
+  for (const platform of Object.keys(config.selection ?? {})) {
+    if (platform !== 'dart' && !natives.some(([language]) => language === platform)) {
+      throw new CaptureError('Selection requires a configured producer for its platform.');
+    }
+    selection[platform] = parseImpactSelection({ format: 'isthmus-changes', version: 1, ...config.selection[platform] });
+  }
+  const timings = [];
+  async function run(command, args, step, accepted = [0]) {
+    const start = performance.now();
+    const result = await execute(command[0], [...command.slice(1), ...args], {
+      cwd: project, timeout: 300_000, maxBuffer: 64 * 1024 * 1024,
+      env: { ...process.env, CI: 'true', DART_SUPPRESS_ANALYTICS: 'true', FLUTTER_SUPPRESS_ANALYTICS: 'true' },
+    });
+    timings.push({ step, milliseconds: Math.round(performance.now() - start) });
+    if (result.error || result.signal || !accepted.includes(result.status)) throw new CaptureError(`Preflight producer step failed: ${step}.`);
+    return result.stdout;
+  }
+  async function json(command, args, step, accepted) {
+    const text = await run(command, args, step, accepted);
+    try { return JSON.parse(text); }
+    catch { throw new CaptureError(`Preflight producer did not return JSON: ${step}.`); }
+  }
+  const limitations = [];
+  let selectionBase = null;
+  if (config.since !== undefined) {
+    selectionBase = (await run(['git'], ['rev-parse', '--verify', '--end-of-options', `${config.since}^{commit}`], 'git-base')).trim();
+    if (!/^[a-f0-9]{40,64}$/.test(selectionBase)) throw new CaptureError('Git did not resolve a commit for the selection.');
+    const diff = await run(['git'], ['diff', '--name-status', '-z', '--find-renames', selectionBase, '--'], 'git-changes');
+    const untracked = await run(['git'], ['ls-files', '--others', '--exclude-standard', '-z'], 'git-untracked');
+    const paths = gitChangePaths(diff);
+    for (const path of nulFields(untracked)) if (/\.(dart|swift|m|mm|kt|java)$/.test(path)) paths.add(path);
+    const files = { dart: [], swift: [], kotlin: [] };
+    let outsideModel = 0;
+    for (const path of paths) {
+      if (!isProjectRelativePath(path)) throw new CaptureError('Git returned an unsupported source path.');
+      if (path.endsWith('.dart')) files.dart.push(path);
+      else if (/\.(swift|m|mm)$/.test(path)) files.swift.push(path);
+      else if (/\.(kt|java)$/.test(path)) files.kotlin.push(path);
+      else outsideModel++;
+    }
+    for (const platform of ['dart', 'swift', 'kotlin']) if (files[platform].length) {
+      if (platform !== 'dart' && !natives.some(([language]) => language === platform)) {
+        limitations.push(`unconfigured-platform-changes: ${files[platform].length} ${platform} source change(s) require separate review`);
+        continue;
+      }
+      selection[platform] = parseImpactSelection({ format: 'isthmus-changes', version: 1, files: files[platform], symbols: [] });
+    }
+    if (outsideModel) limitations.push(`unmodeled-changes: ${outsideModel} tracked configuration/resource change(s) require separate review`);
+  }
+  const tools = {};
+  for (const name of producerNames) {
+    const value = (await run(config[name], ['--version'], `${name}-version`)).trim();
+    const version = value.replace(new RegExp(`^${name} `), '');
+    if (!/^\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?$/.test(version)) throw new CaptureError('Unsupported producer version response.');
+    tools[name] = { name, version };
+  }
+  const messageCommands = config.messages === undefined ? undefined : Object.fromEntries(producerNames
+    .map((name) => [name, config.messages === true ? config[name] : config.messages[name] ?? config[name]]));
+  if (messageCommands) for (const name of producerNames) {
+    if (JSON.stringify(messageCommands[name]) === JSON.stringify(config[name])) continue;
+    const value = (await run(messageCommands[name], ['--version'], `${name}-messages-version`)).trim();
+    const version = value.replace(new RegExp(`^${name} `), '');
+    if (!/^\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?$/.test(version)) throw new CaptureError('Unsupported message producer version response.');
+    tools[`${name}Messages`] = { name, version };
+  }
+  const eventCommands = config.events === undefined ? undefined : Object.fromEntries(producerNames
+    .map((name) => [name, config.events === true ? config[name] : config.events[name] ?? config[name]]));
+  if (eventCommands) for (const name of producerNames) {
+    if (JSON.stringify(eventCommands[name]) === JSON.stringify(config[name])) continue;
+    const value = (await run(eventCommands[name], ['--version'], `${name}-events-version`)).trim();
+    const version = value.replace(new RegExp(`^${name} `), '');
+    if (!/^\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?$/.test(version)) throw new CaptureError('Unsupported event producer version response.');
+    tools[`${name}Events`] = { name, version };
+  }
+  const keyConfig = { project, inputs: config.inputs, toolInputs: config.toolInputs, prepare: config.prepare,
+    dartograph: config.dartograph, cartograph: config.cartograph ?? null, kartograph: config.kartograph ?? null,
+    // 입력 선택의 한계만 지문에 넣는다. 수집 결과로 추가되는 한계는 입력 변경이 아니다.
+    kartographSnapshot: config.kartographSnapshot ?? null, selection, selectionBase, limitations: [...limitations],
+    indexStore: config.indexStore ?? null, messageCommands: messageCommands ?? null, eventCommands: eventCommands ?? null, tools,
+    host: { node: process.version, platform: process.platform, arch: process.arch },
+    toolchainEnvironment: digest(Object.fromEntries(['PATH', 'SDKROOT', 'DEVELOPER_DIR', 'FLUTTER_ROOT', 'DART_SDK', 'SWIFT_EXEC',
+      'JAVA_HOME', 'ANDROID_HOME', 'ANDROID_SDK_ROOT', 'GRADLE_USER_HOME']
+      .map((name) => [name, process.env[name] ?? null]))) };
+  async function fingerprint() {
+    const entries = [];
+    let bytes = 0;
+    async function visit(path, label) {
+      if (entries.length >= 100_000) throw new CaptureError('Fingerprint inputs exceed the capture budget.');
+      let stat;
+      try { stat = await lstat(path); }
+      catch (error) {
+        if (error.code === 'ENOENT') { entries.push([label, 'missing']); return; }
+        throw new CaptureError('Unable to read a declared fingerprint input.');
+      }
+      if (stat.isSymbolicLink()) throw new CaptureError('Fingerprint inputs must not contain symbolic links.');
+      if (stat.isDirectory()) {
+        entries.push([label, 'directory']);
+        for (const name of (await readdir(path)).sort()) await visit(join(path, name), `${label}/${name}`);
+      } else if (stat.isFile()) {
+        bytes += stat.size;
+        if (bytes > 512 * 1024 * 1024 || entries.length >= 100_000) throw new CaptureError('Fingerprint inputs exceed the capture budget.');
+        const hash = createHash('sha256');
+        for await (const data of createReadStream(path)) hash.update(data);
+        entries.push([label, hash.digest('hex')]);
+      } else throw new CaptureError('Fingerprint input is not a regular file or directory.');
+    }
+    for (const path of [...config.inputs].sort()) await visit(resolve(project, path), `source:${path}`);
+    if (config.kartographSnapshot !== undefined) {
+      await visit(resolve(project, config.kartographSnapshot), 'kartograph:snapshot');
+    }
+    for (const path of [...config.toolInputs].sort()) await visit(resolve(project, path), `tool:${path}`);
+    // 같은 버전 문자열의 개발 빌드도 adapter·수집 정책이 바뀌면 다시 수집한다.
+    await visit(fileURLToPath(new URL('../dist', import.meta.url)), 'isthmus:dist');
+    await visit(fileURLToPath(import.meta.url), 'isthmus:capture');
+    await visit(fileURLToPath(new URL('./run-child.mjs', import.meta.url)), 'isthmus:runner');
+    return { key: digest({ config: keyConfig, entries }), entries };
+  }
+  let state = await fingerprint();
+  let cached;
+  try { cached = JSON.parse(await readFile(cachePath, 'utf8')); }
+  catch (error) { if (error.code !== 'ENOENT' && !(error instanceof SyntaxError)) throw new CaptureError('Unable to read preflight cache.'); }
+  if (cached?.format === 'isthmus-preflight-cache' && cached.version === 1 && cached.key === state.key &&
+    cached.contextHash === digest(cached.context) && cached.evidence?.revision === cached.context.revision &&
+    cached.evidenceHash === digest(cached.evidence)) {
+    try {
+      const context = parsePreflightContext(cached.context);
+      if (context.project === project && context.revision === `sha256:${state.key}`) {
+        const confirmed = await fingerprint();
+        if (confirmed.key !== state.key) throw new CaptureError('Declared inputs changed during capture.');
+        await publish(`${output}.sources.json`, cached.evidence);
+        await publish(output, context);
+        return { cached: true, fingerprintScope: 'declared-inputs', context, report: createPreflightReport(context),
+          timings, milliseconds: Math.round(performance.now() - started) };
+      }
+    } catch (error) { if (error instanceof CaptureError) throw error; }
+  }
+  for (const [index, command] of config.prepare.entries()) await run(command, [], `prepare-${index + 1}`);
+  state = await fingerprint();
+  const scratch = await mkdtemp(join(tmpdir(), 'isthmus-preflight-input-'));
+  try {
+    const nativeArgs = ['--project', project, ...(config.indexStore === undefined ? [] : ['--index-store', resolve(project, config.indexStore)])];
+    const kotlinArgs = ['--project', project, ...(config.kartographSnapshot === undefined ? []
+      : ['--graph-file', resolve(project, config.kartographSnapshot)])];
+    const bridges = [
+      parseBridgeFactsDocument(await json(config.dartograph, ['bridges', '--format', 'json', '--project', project, project], 'dart-bridges')),
+    ];
+    const messages = messageCommands === undefined && eventCommands === undefined ? undefined : [
+      ...(messageCommands === undefined ? [] : [
+        parseMessageBridgeDocument(await json(messageCommands.dartograph, ['bridges', '--messages', '--format', 'json', '--project', project, project], 'dart-messages')),
+      ]),
+      ...(eventCommands === undefined ? [] : [
+        parseMessageBridgeDocument(await json(eventCommands.dartograph, ['bridges', '--events', '--format', 'json', '--project', project, project], 'dart-events')),
+      ]),
+    ];
+    for (const [platform, name] of natives) {
+      const args = platform === 'swift' ? nativeArgs : kotlinArgs;
+      bridges.push(parseBridgeFactsDocument(await json(config[name],
+        ['bridges', '--target', 'flutter', '--format', 'json', ...args], `${platform}-bridges`)));
+      if (messageCommands) messages.push(parseMessageBridgeDocument(await json(messageCommands[name],
+        ['bridges', '--messages', '--target', 'flutter', '--format', 'json', ...args], `${platform}-messages`)));
+      if (eventCommands) messages.push(parseMessageBridgeDocument(await json(eventCommands[name],
+        ['bridges', '--events', '--target', 'flutter', '--format', 'json', ...args], `${platform}-events`)));
+    }
+    const analyses = [];
+    const artifacts = {};
+    const metadata = (platform, requested, trigger) => ({ id: `${platform}-${analyses.length}`, project, requested,
+      tool: tools[platform === 'dart' ? 'dartograph' : platform === 'swift' ? 'cartograph' : 'kartograph'],
+      ...(trigger === undefined ? {} : { trigger }) });
+    async function dartImpact(requested, trigger) {
+      if (analyses.length >= 256) throw new CaptureError('Preflight analysis count exceeds its budget.');
+      let flags;
+      if (requested.files.length > 0) {
+        const path = join(scratch, 'changed.json');
+        await writeFile(path, JSON.stringify(requested.files), { mode: 0o600 });
+        flags = ['--changed', path];
+      } else flags = ['--symbol', requested.symbols[0]];
+      const raw = await json(config.dartograph, ['impact', ...flags, '--format', 'json', '--limit', '50000', project], 'dart-impact');
+      const meta = metadata('dart', requested, trigger);
+      artifacts[meta.id] = raw;
+      analyses.push(adaptDartographImpact(raw, meta));
+    }
+    if (selection.swift) {
+      // Cartograph는 파일·심볼 선택을 한 번에 혼용하지 않으므로 각각 요청한다.
+      const selections = [
+        ...(selection.swift.files.length ? [{ files: selection.swift.files, symbols: [] }] : []),
+        ...(selection.swift.symbols.length ? [{ files: [], symbols: selection.swift.symbols }] : []),
+      ];
+      for (const requested of selections) {
+        const raw = await json(config.cartograph, ['impact', ...nativeArgs, '--format', 'json', '--limit', '10000',
+          ...requested.files.flatMap((path) => ['--file', resolve(project, path)]),
+          ...(requested.symbols.length ? ['--', ...requested.symbols] : [])], 'swift-impact', [0, 64]);
+        const meta = metadata('swift', requested);
+        artifacts[meta.id] = raw;
+        analyses.push(adaptCartographImpact(raw, meta));
+      }
+    }
+    if (selection.dart) {
+      if (selection.dart.files.length > 0) await dartImpact({ files: selection.dart.files, symbols: [] });
+      for (const symbol of selection.dart.symbols) await dartImpact({ files: [], symbols: [symbol] });
+    }
+    if (selection.kotlin) {
+      const requested = selection.kotlin;
+      const raw = await json(config.kartograph, ['impact', '--graph-file', resolve(project, config.kartographSnapshot),
+        '--limit', '10000', '--depth', '128', ...requested.files.flatMap((path) => ['--file', path]),
+        ...requested.symbols.flatMap((symbol) => ['--symbol', symbol])], 'kotlin-impact', [0, 64]);
+      const meta = metadata('kotlin', requested);
+      artifacts[meta.id] = raw;
+      analyses.push(adaptKartographImpact(raw, meta));
+    }
+    const dartFacts = [...bridges[0].facts,
+      ...(messages ?? []).filter((document) => document.platform === 'dart').flatMap((document) => document.facts)];
+    const names = [...new Set(dartFacts.flatMap((fact) => fact.symbol ? [fact.symbol.qualifiedName] : []))].sort();
+    const subjects = new Map();
+    const conflictingBindings = new Set();
+    const candidateRequests = new Map();
+    let candidateWork = 0;
+    const subjectKey = (requested, path) => JSON.stringify([requested, path]);
+    async function querySubjects(requests, label) {
+      const path = join(scratch, 'queries.json');
+      await writeFile(path, JSON.stringify(requests), { mode: 0o600 });
+      const document = await json(config.dartograph, ['query', '--batch', path, '--depth', '1', '--limit', '1', project], 'dart-bindings', [0, 64]);
+      if (document.format !== 'symbol-query-batch' || document.version !== 1 || !Array.isArray(document.results) ||
+        document.results.length !== requests.length || document.results.some((row, index) => row?.requested !== requests[index])) {
+        throw new CaptureError('Dart caller query responses do not match the requests.');
+      }
+      artifacts[label] = document;
+      return document.results;
+    }
+    function rememberSubject(requested, result, exact = false) {
+      if (result.status !== 'found') return;
+      const subject = result.result?.subject;
+      const location = subject?.location;
+      const source = typeof location?.path === 'string' && location.path.startsWith('project:') ? location.path.slice(8) : undefined;
+      if (!isSafeNonEmptyString(subject?.usr) || !isSafeNonEmptyString(subject?.qualifiedName) ||
+        !isProjectRelativePath(source) || !Number.isSafeInteger(location.line) || location.line < 1 ||
+        !Number.isSafeInteger(location.column) || location.column < 1) return;
+      if (exact && subject.usr !== result.requested) throw new CaptureError('Dart caller candidate identity changed during resolution.');
+      const key = subjectKey(requested, source);
+      if (conflictingBindings.has(key)) return;
+      const symbol = { id: subject.usr, qualifiedName: subject.qualifiedName,
+        location: { path: source, line: location.line, column: location.column } };
+      if (subjects.has(key) && encodeSortedJson(subjects.get(key)) !== encodeSortedJson(symbol)) {
+        subjects.delete(key); conflictingBindings.add(key); return;
+      }
+      subjects.set(key, symbol);
+    }
+    for (let offset = 0; offset < names.length; offset += 1000) {
+      for (const result of await querySubjects(names.slice(offset, offset + 1000), `bindings-${offset}`)) {
+        rememberSubject(result.requested, result);
+        if (result.status !== 'ambiguous' || !Array.isArray(result.candidates)) continue;
+        for (const candidate of result.candidates) {
+          if (++candidateWork > 100_000) throw new CaptureError('Dart caller candidates exceed the capture budget.');
+          if (!isSafeNonEmptyString(candidate?.usr)) throw new CaptureError('Invalid Dart caller candidate identity.');
+          let requests = candidateRequests.get(candidate.usr);
+          if (requests === undefined) {
+            if (candidateRequests.size >= 50_000) throw new CaptureError('Dart caller candidates exceed the capture budget.');
+            requests = new Set(); candidateRequests.set(candidate.usr, requests);
+          }
+          requests.add(result.requested);
+        }
+      }
+    }
+    // 이름이 같은 main 등의 경로를 추측하지 않고 실제 ID를 재조회해 fact 파일과 대조한다.
+    const candidateIds = [...candidateRequests.keys()].sort();
+    let unresolvedCandidates = 0;
+    for (let offset = 0; offset < candidateIds.length; offset += 1000) {
+      for (const result of await querySubjects(candidateIds.slice(offset, offset + 1000), `bindings-candidates-${offset}`)) {
+        if (result.status !== 'found') unresolvedCandidates++;
+        for (const requested of candidateRequests.get(result.requested)) rememberSubject(requested, result, true);
+      }
+    }
+    if (unresolvedCandidates > 0) limitations.push(`unresolved-dart-candidates: ${unresolvedCandidates} producer candidate identity(s) could not be resolved on requery`);
+    const bindings = dartFacts.flatMap((fact) => {
+      const symbol = subjects.get(subjectKey(fact.symbol?.qualifiedName, fact.location.path));
+      return symbol?.location.path === fact.location.path
+        ? [{ platform: 'dart', location: fact.location, requested: fact.symbol.qualifiedName, symbol }] : [];
+    });
+    const makeContext = () => parsePreflightContext({ format: 'isthmus-preflight-context', version: 1, project,
+      revision: `sha256:${state.key}`, selection, bridges, ...(messages === undefined ? {} : { messages }), bindings, analyses, limitations });
+    const initial = createPreflightReport(makeContext());
+    const reached = new Set([...initial.roots, ...initial.affected.map(({ subject }) => subject)]
+      .filter((subject) => subject.kind === 'symbol' && subject.platform === 'dart').map(({ symbol }) => symbol.id));
+    const supplied = new Set(analyses.filter(({ platform }) => platform === 'dart').flatMap(({ roots }) => roots.map(({ id }) => id)));
+    for (const id of [...new Set(bindings.map(({ symbol }) => symbol.id))].sort()) {
+      if (reached.has(id) && !supplied.has(id)) await dartImpact({ files: [], symbols: [id] }, id);
+    }
+    const context = makeContext();
+    const report = createPreflightReport(context);
+    const confirmed = await fingerprint();
+    if (confirmed.key !== state.key) throw new CaptureError('Declared inputs changed during capture.');
+    const evidence = { format: 'isthmus-capture-evidence', version: 1, revision: context.revision,
+      fingerprintScope: 'declared-inputs', inputs: state.entries, tools, artifacts, timings };
+    await publish(`${output}.sources.json`, evidence);
+    await publish(cachePath, { format: 'isthmus-preflight-cache', version: 1, key: state.key, context, contextHash: digest(context),
+      evidence, evidenceHash: digest(evidence) });
+    await publish(output, context);
+    return { cached: false, fingerprintScope: 'declared-inputs', context, report, timings, milliseconds: Math.round(performance.now() - started) };
+  } finally { await rm(scratch, { recursive: true, force: true }); }
+}
+
+function digest(value) { return createHash('sha256').update(encodeSortedJson(value, true)).digest('hex'); }
+
+function nulFields(text) {
+  if (text === '') return [];
+  if (!text.endsWith('\0')) throw new CaptureError('Git returned an incomplete path list.');
+  return text.slice(0, -1).split('\0');
+}
+
+/** rename·copy는 두 경로를 모두 보존하며 이름에 공백이 있어도 재분할하지 않는다. */
+function gitChangePaths(text) {
+  const fields = nulFields(text);
+  const paths = new Set();
+  for (let index = 0; index < fields.length;) {
+    const status = fields[index++];
+    if (!/^(?:[AMDUTX]|[RC]\d{1,3})$/.test(status)) throw new CaptureError('Git returned an unsupported change status.');
+    const count = /^[RC]/.test(status) ? 2 : 1;
+    for (let cursor = 0; cursor < count; cursor++) {
+      if (index >= fields.length) throw new CaptureError('Git returned an incomplete change.');
+      paths.add(fields[index++]);
+    }
+  }
+  return paths;
+}
+
+async function publish(path, value) {
+  await mkdir(dirname(path), { recursive: true });
+  await writeTextAtomically(path, encodeSortedJson(value, true));
+}
+
+
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    if (process.argv.length !== 3) throw new CaptureError('Usage: node scripts/capture-preflight.mjs <capture.json>');
+    const config = JSON.parse(await readFile(process.argv[2], 'utf8'));
+    const result = await capturePreflight(config);
+    process.stdout.write(encodeSortedJson({ cached: result.cached, revision: result.context.revision,
+      fingerprintScope: result.fingerprintScope, summary: result.report.summary, timings: result.timings, milliseconds: result.milliseconds }, true));
+    process.exitCode = hasPreflightBlockers(result.report) ? 1 : 0;
+  } catch (error) {
+    process.stderr.write(`${error instanceof CaptureError ? error.message : 'Preflight capture failed; check configuration and producer compatibility.'}\n`);
+    process.exitCode = 2;
+  }
+}

package/scripts/run-child.mjs

@@ -0,0 +1,17 @@
+import { spawnSync } from 'node:child_process';
+
+const defaultTimeout = 60_000;
+const defaultMaxBuffer = 16 * 1024 * 1024;
+
+/** 검증 자식 프로세스를 제한시간과 충분한 출력 버퍼 안에서 실행한다. */
+export function runChild(command, arguments_, options = {}) {
+  return spawnSync(command, arguments_, {
+    cwd: options.cwd,
+    encoding: 'utf8',
+    env: options.env,
+    input: options.input,
+    timeout: options.timeout ?? defaultTimeout,
+    maxBuffer: options.maxBuffer ?? defaultMaxBuffer,
+    stdio: options.stdio,
+  });
+}