isthmus-cli 0.5.0 → 0.6.0

package/docs/TOOLCHAIN.md

@@ -0,0 +1,101 @@
+# 고정 소스에서 사전 점검 도구 구축
+
+개발 소스의 절차이며 현재 공개된 isthmus 0.5.0에는 새 preflight 기능이 없다.
+이 절차는 로컬 Git 저장소의 **지정한 commit만** 새 디렉터리에 풀어 선택한 도구를 구축한다.
+원본의 미커밋 수정, dist, .build, .dart_tool을 복사하지 않는다. SDK와 전역 의존성 캐시는
+공유할 수 있으므로 빈 머신 전체 설치 시간과 구분한다. 소스 다운로드·발행은 수행하지 않는다.
+
+## 준비
+
+- Node.js 22.18.0 이상, Dart 3.11 이상.
+- 로컬 Git checkout: isthmus·dartograph와 native producer 하나 이상.
+- Swift 분석에는 cartograph와 Swift 6 toolchain, Android 분석에는 kartograph와 JDK 17+가 필요하다.
+  Android만 구축할 때는 Swift toolchain을 호출하지 않는다. JDK 경로는 `JAVA_HOME`으로 지정한다.
+- 선택한 Cartograph commit은 `impact`와 `bridges --messages`를 함께 제공해야 한다.
+  Dartograph는 `bridges --messages`, isthmus는 `preflight --summary/--explain`이 필요하다.
+- 선택한 Kartograph commit은 `impact --graph-file`과 `bridges --messages --graph-file`을 제공해야 한다.
+- 앱의 Swift 인덱스와 실제 Flutter 검증에는 해당 앱의 Flutter/Xcode 환경이 추가로 필요하다.
+  도구 자체를 구축하는 과정은 Flutter SDK를 필수로 요구하지 않는다.
+
+아직 이 기능을 모두 포함한 공개 호환 버전은 확정·발행하지 않았다. 저장소 checkout의
+`docs/COMPETITIVENESS.md`에서 검증 중인 개발 commit과 남은 작업을 확인할 수 있다.
+기능 이름만 보고 기존 발행 버전을 사용하지 않는다. 소스 commit이 로컬 Git에 있어야 하며
+빌드 과정의 npm/pub/SwiftPM/Gradle 의존성 해석은 네트워크를 사용할 수 있다.
+
+## 실행
+
+`build.json`에 실제 로컬 경로와 `git rev-parse <ref>`로 확인한 전체 40자리 commit을 적는다.
+아래 `<...>`는 대체해야 할 값이다. 상대 경로는 JSON 파일의 디렉터리를 기준으로 해석한다.
+destination은 존재하지 않아야 하고 그 부모 디렉터리는 미리 준비한다.
+
+```json
+{
+  "format": "isthmus-toolchain-build",
+  "version": 1,
+  "destination": "../built-isthmus-tools",
+  "repositories": {
+    "isthmus": {"path": "../isthmus", "revision": "<40-character-commit>"},
+    "cartograph": {"path": "../cartograph", "revision": "<40-character-commit>"},
+    "dartograph": {"path": "../dartograph", "revision": "<40-character-commit>"}
+  }
+}
+```
+
+```bash
+node scripts/build-preflight-toolchain.mjs build.json
+```
+
+Android만 필요하면 위 repositories의 `cartograph`를 `kartograph`로 바꾸고 실제 Kotlin
+producer checkout과 commit을 지정한다. 두 native producer를 함께 넣으면 네 도구를 구축한다.
+Kartograph는 Gradle `:cli:installDist`로 만든 배포 스크립트와 runtime JAR을 사용한다.
+
+스크립트는 commit 확인 → source archive → 선택한 native producer 빌드 → Dart AOT 빌드 → npm tarball 생성·
+격리 설치 순서로 실행한다. 기존 destination을 덮어쓰지 않고, 실패 시 자신이 새로 만든
+destination만 정리한다. 각 단계의 로그는 별도의 임시 근거 디렉터리에 남기며 경로를 알린다.
+성공한 디렉터리는 옮기지 않고 그대로 사용한다.
+
+`<destination>/toolchain.json`에는 source commit, SDK 버전, 실행 파일/패키지 hash, 단계별
+시간과 아래 명령 배열이 있다.
+
+- `commands.isthmus`: Node와 설치된 CLI의 경로.
+- `commands.cartograph`: impact와 Basic을 함께 제공하는 실행 파일 경로.
+- `commands.kartograph`: Android 분석용 배포 스크립트 경로(선택한 경우).
+- `commands.dartograph`: AOT 실행 파일 경로.
+
+`artifacts.kartographInputs`는 실행 스크립트와 `lib/` 디렉터리다. 둘 다 capture의 toolInputs에
+사용하며 launcher hash 외에 `hashes.kartographLibraries`로 runtime JAR 묶음도 기록한다.
+
+이 성공은 구축과 CLI 기능 확인이다. 앱 분석의 정확성·모든 런타임 의존성 검증을 뜻하지 않는다.
+
+## 앱 수집 및 CI 연결
+
+[PREFLIGHT.md](PREFLIGHT.md)의 capture 설정에서 위 두 producer 명령을 사용하고 Basic이
+필요하면 `"messages": true`를 지정한다. 서로 다른 Cartograph 실행 파일을 나눠 쓸 필요가 없다.
+실행 파일과 앱 소스·생성 설정·SDK 입력을 `toolInputs`/`inputs`에 선언한다.
+
+```bash
+node <isthmus-source>/scripts/capture-preflight.mjs capture.json
+node <installed-isthmus-main.js> preflight context.json --summary --strict --compact
+```
+
+첫 명령은 기존 설정의 prepare 명령으로 앱 인덱스를 갱신하고 내용 해시가 같은 수집 결과만
+재사용한다. 두 번째 명령의 exit 1은 검토할 결과이며 JSON을 버리지 않는다. 공개 Pigeon의
+prefix와 실행하지 않은 시나리오 등은 의도적으로 공백으로 남을 수 있다.
+
+CI에서는 도구 구축과 앱 수집을 구분한다. 도구는 검증한 commit의 빌드 산출물을 사용하고,
+앱 입력이 바뀔 때 capture를 갱신한다. 저장소의 소비자 성능 검사는 5초 예산을 검사하지만
+producer 및 앱 빌드 시간은 포함하지 않는다. 원격 CI 실행과 최초 외부 사용자의 구축은
+로컬 source archive 검증과 별도로 확인해야 한다.
+
+## 실제 Dart 바인딩 상태 대조
+
+저장소 검증 스크립트는 Flutter의 실제 BasicMessageChannel API를 mock messenger와 함께
+실행해 mutable 필드, 고정 필드, 순차 대입, then/else에서 관찰한 주소를 producer와 대조한다.
+
+```bash
+node scripts/verify-dart-binding-runtime.mjs <flutter> <dartograph-aot>
+```
+
+같은 mutable 필드 호출이 호출 이력에 따라 다른 주소를 쓰면 정적 단일 주소로 확정하지
+않아야 한다. 반대로 고정 필드와 명확한 직선 흐름은 실제 주소를 유지해야 한다.
+이 검증은 Dart/Flutter 바인딩 상태의 실행이며 native IPC나 앱 전체 동작 검증은 아니다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "isthmus-cli",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Join bridge facts across cross-platform application boundaries.",
   "keywords": [
     "flutter",
@@ -28,6 +28,15 @@
   "files": [
     "dist",
     "Skills",
+    "scripts/capture-preflight.mjs",
+    "scripts/run-child.mjs",
+    "scripts/build-preflight-toolchain.mjs",
+    "docs/TOOLCHAIN.md",
+    "docs/PREFLIGHT.md",
+    "docs/RUNTIME.md",
+    "docs/IMPACT.md",
+    "docs/BRIDGE-MESSAGES.md",
+    "docs/GRAPH-EXCHANGE.md",
     "LICENSE",
     "README.md",
     "README.ko.md"
@@ -43,7 +52,7 @@
     "verify:build": "node scripts/verify-build-contract.mjs",
     "verify:cli": "npm run verify:build && node scripts/verify-cli-contract.mjs",
     "verify:package": "npm run verify:build && node scripts/verify-package-contract.mjs",
-    "verify": "npm run typecheck && npm test && npm run test:phase0:join && npm run verify:build && node scripts/verify-cli-contract.mjs && node scripts/verify-package-contract.mjs",
+    "verify": "npm run typecheck && npm test && npm run test:phase0:join && npm run verify:build && node --test scripts/capture-preflight.test.mjs scripts/build-preflight-toolchain.test.mjs scripts/stop-detached-process.test.mjs && node scripts/verify-cli-contract.mjs && node scripts/verify-package-contract.mjs",
     "prepublishOnly": "npm run verify"
   },
   "devDependencies": {

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;
+    }
+  }
+}