byuckchon-frontend-cli 1.0.3 → 1.4.0

package/src/generators/createBcConfig.js

@@ -0,0 +1,58 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * 새 프로젝트 루트에 `bc.config.json` 을 만든다.
+ *
+ * - bc chat / bc gen 등이 이 파일을 읽어 프로젝트 컨텍스트(Figma, API, 컨벤션)를
+ *   AI 에게 자동 주입한다.
+ * - API 키 같은 비밀값은 절대 여기 두지 말 것 (글로벌 설정 또는 .env 사용).
+ */
+export async function createBcConfig(rootDir, config) {
+  const bcConfig = {
+    $schema: 'https://byuckchon.dev/bc.schema.json',
+    ai: {
+      // null 이면 글로벌 기본 모델(=~/.bc/config.json) 을 따름.
+      model: config.aiModel ?? null,
+    },
+    design: {
+      figma: config.figmaUrl?.trim() || null,
+      figmaTokenEnv: 'FIGMA_TOKEN',
+    },
+    api: {
+      openapi: config.openapiUrl?.trim() || null,
+      baseUrl: null,
+    },
+    context: {
+      include: ['src/**/*.{ts,tsx,js,jsx}', 'bc.config.json'],
+      exclude: ['**/*.test.*', '**/__mocks__/**', 'node_modules/**', 'dist/**'],
+      maxFiles: 20,
+    },
+    framework: config.framework,
+    // init 단계에선 사용자가 React/Next 중 골랐고 TS/Tailwind 가 항상 들어가니
+    // 감지 결과를 미리 채워둔다 (bc adopt 의 detected 와 같은 모양).
+    detected: {
+      language: 'ts',
+      styling: {
+        tailwind: true,
+        cssModules: false,
+        styledComponents: false,
+        emotion: false,
+        vanillaExtract: false,
+      },
+      packageManager: 'npm',
+      routing: config.framework === 'next' ? 'app-router' : null,
+      componentDirs: ['src/components'],
+      designTokensFiles: [],
+      hasStorybook: false,
+      hasTests: null,
+      detectedAt: new Date().toISOString(),
+    },
+  };
+
+  await fs.writeFile(
+    path.join(rootDir, 'bc.config.json'),
+    JSON.stringify(bcConfig, null, 2) + '\n',
+    'utf8',
+  );
+}

package/src/generators/createPackageJson.js

@@ -10,7 +10,7 @@ export async function createPackageJson(rootDir, config) {
     name: config.projectName,
     version: '0.0.1',
     private: true,
-    ...(isReact ? { type: 'module' } : {}),
+    type: 'module',
     scripts: isReact
       ? {
           dev: 'vite',

package/src/generators/createProject.js

@@ -4,6 +4,7 @@ import { exec as execCallback } from 'child_process';
 import { promisify } from 'util';
 
 import { createBaseFiles } from './createBaseFiles.js';
+import { createBcConfig } from './createBcConfig.js';
 import { createFolders } from './createFolders.js';
 import { createPackageJson } from './createPackageJson.js';
 import { createReadme } from './createReadme.js';
@@ -24,6 +25,7 @@ export async function createProject(config) {
   await createPackageJson(rootDir, config);
   await createBaseFiles(rootDir, config);
   await createReadme(rootDir, config);
+  await createBcConfig(rootDir, config);
 
   // 최신 버전(latest 포함) 의존성을 실제로 설치해 lockfile까지 생성
   await exec('npm install', { cwd: rootDir });

package/src/history/store.js

@@ -0,0 +1,117 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+
+import { findProjectConfigPath } from '../config/index.js';
+
+/**
+ * 챗 세션을 디스크에 저장/복구한다.
+ *
+ * 저장 위치 우선순위:
+ *   1) 프로젝트 안:  <projectRoot>/.bc/history/<id>.json
+ *      - bc.config.json 이 발견된 경우 그 옆 .bc 폴더 사용
+ *      - 자동으로 .gitignore 에 들어감 (사용자 .gitignore 에 .bc/ 박혀있다는 가정)
+ *   2) 글로벌:       ~/.bc/history/<cwdHash>/<id>.json
+ *      - bc.config.json 이 없는 경우 (예: 빈 폴더에서 bc chat 실행)
+ *
+ * 동기 디스크 IO 는 ink 렌더에 끼지 않게 모두 await.
+ */
+
+function cwdHash(cwd) {
+  return crypto.createHash('sha1').update(cwd).digest('hex').slice(0, 12);
+}
+
+function makeId(date = new Date()) {
+  const pad = (n, w = 2) => String(n).padStart(w, '0');
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}_${pad(
+    date.getHours(),
+  )}-${pad(date.getMinutes())}-${pad(date.getSeconds())}`;
+}
+
+export async function getHistoryDir(cwd = process.cwd()) {
+  const projectConfig = await findProjectConfigPath(cwd);
+  if (projectConfig) {
+    return path.join(path.dirname(projectConfig), '.bc', 'history');
+  }
+  return path.join(os.homedir(), '.bc', 'history', cwdHash(cwd));
+}
+
+export async function createSession({ model, cwd = process.cwd() } = {}) {
+  const dir = await getHistoryDir(cwd);
+  await fs.mkdir(dir, { recursive: true });
+  const id = makeId();
+  const session = {
+    id,
+    startedAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    model,
+    cwd,
+    messages: [],
+  };
+  return { ...session, _file: path.join(dir, `${id}.json`) };
+}
+
+export async function saveSession(session) {
+  const file = session._file;
+  if (!file) throw new Error('session._file 누락');
+  const data = {
+    id: session.id,
+    startedAt: session.startedAt,
+    updatedAt: new Date().toISOString(),
+    model: session.model,
+    cwd: session.cwd,
+    messages: session.messages,
+  };
+  await fs.writeFile(file, JSON.stringify(data, null, 2) + '\n', 'utf8');
+}
+
+export async function listSessions(cwd = process.cwd(), { limit = 20 } = {}) {
+  const dir = await getHistoryDir(cwd);
+  let entries = [];
+  try {
+    entries = await fs.readdir(dir);
+  } catch (e) {
+    if (e.code === 'ENOENT') return [];
+    throw e;
+  }
+  const files = entries.filter((f) => f.endsWith('.json')).sort().reverse();
+  const out = [];
+  for (const name of files.slice(0, limit)) {
+    const file = path.join(dir, name);
+    try {
+      const raw = await fs.readFile(file, 'utf8');
+      const data = JSON.parse(raw);
+      const firstUser = data.messages?.find((m) => m.role === 'user');
+      out.push({
+        id: data.id,
+        file,
+        startedAt: data.startedAt,
+        updatedAt: data.updatedAt,
+        model: data.model,
+        turns: data.messages?.length ?? 0,
+        preview: firstUser?.text?.slice(0, 60) ?? '(빈 세션)',
+      });
+    } catch {
+      /* 잘못된 파일 스킵 */
+    }
+  }
+  return out;
+}
+
+export async function loadSession(idOrFile, cwd = process.cwd()) {
+  let file = idOrFile;
+  if (!file.endsWith('.json') || !path.isAbsolute(file)) {
+    const dir = await getHistoryDir(cwd);
+    file = path.join(dir, idOrFile.endsWith('.json') ? idOrFile : `${idOrFile}.json`);
+  }
+  const raw = await fs.readFile(file, 'utf8');
+  const data = JSON.parse(raw);
+  return { ...data, _file: file };
+}
+
+export async function loadLatestSession(cwd = process.cwd()) {
+  const list = await listSessions(cwd, { limit: 1 });
+  if (list.length === 0) return null;
+  return loadSession(list[0].id, cwd);
+}

package/src/indexer/chunker.js

@@ -0,0 +1,42 @@
+import crypto from 'node:crypto';
+
+/**
+ * 파일을 라인 기반 슬라이딩 윈도우로 청크 분할.
+ *
+ * v1 정책 — 단순하고 결정론적:
+ *   - 한 청크 ≈ 80 라인, 인접 청크끼리 20 라인 겹침.
+ *   - 너무 짧은 파일(80라인 이하)은 통째로 1청크.
+ *   - 청크 텍스트 앞에 "// FILE: <relpath>:start-end" 헤더를 붙여서
+ *     임베딩이 파일 정체성에 가중치를 두도록 한다.
+ *
+ * 더 똑똑한 AST 기반 청킹은 v2 (ts-morph 도입 후) 에서.
+ */
+export function chunkFile({ relPath, content, chunkSize = 80, overlap = 20 }) {
+  const lines = content.split('\n');
+  const total = lines.length;
+  if (total === 0) return [];
+
+  const chunks = [];
+  let start = 0;
+  while (start < total) {
+    const end = Math.min(start + chunkSize, total);
+    const slice = lines.slice(start, end).join('\n');
+    const text = `// FILE: ${relPath}:${start + 1}-${end}\n${slice}`;
+    chunks.push({
+      id: hashId(`${relPath}:${start + 1}-${end}`),
+      file: relPath,
+      startLine: start + 1,
+      endLine: end,
+      text,
+      hash: crypto.createHash('sha1').update(text).digest('hex'),
+    });
+    if (end >= total) break;
+    start = end - overlap;
+    if (start < 0) start = 0;
+  }
+  return chunks;
+}
+
+function hashId(s) {
+  return crypto.createHash('sha1').update(s).digest('hex').slice(0, 16);
+}

package/src/indexer/embed.js

@@ -0,0 +1,57 @@
+import { embed, embedMany } from 'ai';
+import { createOpenAI } from '@ai-sdk/openai';
+
+const DEFAULT_EMBED_MODEL = 'text-embedding-3-small';
+
+/**
+ * 임베딩은 OpenAI 만 지원 (Anthropic 은 임베딩 API 가 없다).
+ *
+ * effective.apiKeys.openai 또는 ENV(OPENAI_API_KEY)/gateway 를 사용.
+ * 키 없으면 명확한 에러로 종료.
+ */
+export function makeEmbeddingModel(effective) {
+  const apiKey = effective.apiKeys?.openai;
+  if (!apiKey && !effective.gateway) {
+    const err = new Error(
+      'OpenAI API 키가 필요합니다 (임베딩 전용).\n' +
+        '  - Anthropic 은 임베딩 API 를 제공하지 않습니다.\n' +
+        '  - `bc config set-key openai <key>` 또는 OPENAI_API_KEY 환경변수로 등록하세요.\n' +
+        '  - text-embedding-3-small 은 1M 토큰당 약 $0.02 로 매우 저렴합니다.',
+    );
+    err.code = 'BC_NO_OPENAI_KEY';
+    throw err;
+  }
+  const openai = createOpenAI({
+    apiKey: apiKey ?? 'gateway',
+    baseURL: effective.gateway ?? undefined,
+  });
+  return openai.embedding(DEFAULT_EMBED_MODEL);
+}
+
+/**
+ * 청크 배열을 받아 임베딩 벡터를 추가해서 돌려준다.
+ * 100개 단위 배치, 각 배치 내부에선 SDK 가 다시 OpenAI 한도에 맞춰 처리.
+ */
+export async function embedChunks(model, chunks, { batchSize = 100, onBatch } = {}) {
+  const out = [];
+  for (let i = 0; i < chunks.length; i += batchSize) {
+    const batch = chunks.slice(i, i + batchSize);
+    const { embeddings } = await embedMany({
+      model,
+      values: batch.map((c) => c.text),
+    });
+    for (let j = 0; j < batch.length; j++) {
+      out.push({ ...batch[j], embedding: embeddings[j] });
+    }
+    if (onBatch) onBatch({ done: out.length, total: chunks.length });
+  }
+  return out;
+}
+
+/** 단건 — 검색 쿼리 임베딩. */
+export async function embedQuery(model, query) {
+  const { embedding } = await embed({ model, value: query });
+  return embedding;
+}
+
+export { DEFAULT_EMBED_MODEL };

package/src/indexer/search.js

@@ -0,0 +1,41 @@
+import { embedQuery, makeEmbeddingModel } from './embed.js';
+import { loadIndex } from './store.js';
+
+/**
+ * 쿼리 텍스트와 모든 청크 사이 cosine similarity 를 계산해 top-K 를 돌려준다.
+ *
+ * @param {string} query
+ * @param {object} effective
+ * @param {object} [opts]
+ * @param {number} [opts.topK=5]
+ * @param {number} [opts.minScore=0]   너무 관련 없는 청크 컷오프 (0~1 스케일)
+ */
+export async function searchIndex(query, effective, { topK = 5, minScore = 0 } = {}) {
+  const idx = await loadIndex();
+  if (!idx || !idx.chunks?.length) return { ok: false, reason: 'no-index' };
+
+  const model = makeEmbeddingModel(effective);
+  const qVec = await embedQuery(model, query);
+
+  const scored = idx.chunks.map((c) => ({
+    chunk: c,
+    score: cosine(qVec, c.embedding),
+  }));
+  scored.sort((a, b) => b.score - a.score);
+  const top = scored.filter((s) => s.score >= minScore).slice(0, topK);
+  return { ok: true, results: top, total: idx.chunks.length };
+}
+
+function cosine(a, b) {
+  if (!a || !b || a.length !== b.length) return 0;
+  let dot = 0;
+  let na = 0;
+  let nb = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    na += a[i] * a[i];
+    nb += b[i] * b[i];
+  }
+  if (na === 0 || nb === 0) return 0;
+  return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}

package/src/indexer/store.js

@@ -0,0 +1,137 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { findProjectConfigPath } from '../config/index.js';
+import { walkProjectFiles, relPath } from './walker.js';
+import { chunkFile } from './chunker.js';
+import { embedChunks, DEFAULT_EMBED_MODEL } from './embed.js';
+
+const INDEX_VERSION = 1;
+
+export async function getIndexPaths(cwd = process.cwd()) {
+  const projectConfig = await findProjectConfigPath(cwd);
+  const projectRoot = projectConfig ? path.dirname(projectConfig) : cwd;
+  const dir = path.join(projectRoot, '.bc', 'index');
+  return {
+    projectRoot,
+    dir,
+    manifest: path.join(dir, 'manifest.json'),
+    chunks: path.join(dir, 'chunks.json'),
+  };
+}
+
+export async function loadIndex(cwd = process.cwd()) {
+  const p = await getIndexPaths(cwd);
+  try {
+    const [manifestRaw, chunksRaw] = await Promise.all([
+      fs.readFile(p.manifest, 'utf8'),
+      fs.readFile(p.chunks, 'utf8'),
+    ]);
+    return {
+      ...JSON.parse(manifestRaw),
+      chunks: JSON.parse(chunksRaw),
+      _paths: p,
+    };
+  } catch (e) {
+    if (e.code === 'ENOENT') return null;
+    throw e;
+  }
+}
+
+async function saveIndex(p, manifest, chunks) {
+  await fs.mkdir(p.dir, { recursive: true });
+  await fs.writeFile(p.chunks, JSON.stringify(chunks), 'utf8');
+  await fs.writeFile(
+    p.manifest,
+    JSON.stringify({ ...manifest, chunkCount: chunks.length }, null, 2) + '\n',
+    'utf8',
+  );
+}
+
+/**
+ * 인덱스 빌드 — 파일 스캔, 청크 분할, 변경된 청크만 임베딩 후 저장.
+ *
+ * @param {object} opts
+ * @param {object} opts.effective  loadEffectiveConfig().effective
+ * @param {object} opts.contextCfg bc.config.json 의 context (include/exclude)
+ * @param {boolean} opts.rebuild   true 면 기존 임베딩 무시하고 전부 재계산
+ * @param {(s:string)=>void} opts.onProgress 진행 메시지 콜백
+ */
+export async function buildIndex({
+  effective,
+  contextCfg = {},
+  rebuild = false,
+  onProgress = () => {},
+} = {}) {
+  const p = await getIndexPaths();
+  const { projectRoot } = p;
+
+  onProgress('  파일 목록 수집 중…');
+  const files = await walkProjectFiles(projectRoot, contextCfg);
+  if (files.length === 0) {
+    return { ok: false, reason: '인덱싱할 파일이 없습니다. bc.config.json 의 context.include 를 확인하세요.' };
+  }
+  onProgress(`  파일 ${files.length}개 발견. 청크 분할 중…`);
+
+  const fileMaxBytes = 100 * 1024;
+  const allChunks = [];
+  for (const abs of files) {
+    let content;
+    try {
+      const stat = await fs.stat(abs);
+      if (stat.size > fileMaxBytes) continue; // 너무 큰 파일은 스킵
+      content = await fs.readFile(abs, 'utf8');
+    } catch {
+      continue;
+    }
+    const r = relPath(projectRoot, abs);
+    for (const c of chunkFile({ relPath: r, content })) allChunks.push(c);
+  }
+  onProgress(`  청크 ${allChunks.length}개 생성.`);
+
+  // 기존 인덱스에서 hash 일치하는 청크의 임베딩을 재사용 (증분 갱신).
+  let reused = 0;
+  let toEmbed = allChunks;
+  if (!rebuild) {
+    const existing = await loadIndex(projectRoot);
+    if (existing && existing.embeddingModel === DEFAULT_EMBED_MODEL) {
+      const byHash = new Map(existing.chunks.map((c) => [c.hash, c.embedding]));
+      toEmbed = [];
+      for (const c of allChunks) {
+        const cached = byHash.get(c.hash);
+        if (cached) {
+          c.embedding = cached;
+          reused++;
+        } else {
+          toEmbed.push(c);
+        }
+      }
+      onProgress(`  ${reused}개 재사용, ${toEmbed.length}개 신규 임베딩 필요.`);
+    }
+  }
+
+  if (toEmbed.length > 0) {
+    onProgress(`  OpenAI 임베딩 중… (model=${DEFAULT_EMBED_MODEL})`);
+    const { makeEmbeddingModel } = await import('./embed.js');
+    const model = makeEmbeddingModel(effective);
+    const embedded = await embedChunks(model, toEmbed, {
+      onBatch: ({ done, total }) => onProgress(`    배치 진행: ${done}/${total}`),
+    });
+    // 새로 임베딩된 청크를 allChunks 에 반영 (hash 일치하는 자리로 머지).
+    const newByHash = new Map(embedded.map((e) => [e.hash, e.embedding]));
+    for (const c of allChunks) {
+      if (!c.embedding) c.embedding = newByHash.get(c.hash);
+    }
+  }
+
+  const manifest = {
+    version: INDEX_VERSION,
+    embeddingModel: DEFAULT_EMBED_MODEL,
+    builtAt: new Date().toISOString(),
+    fileCount: files.length,
+    reused,
+    newlyEmbedded: toEmbed.length - reused < 0 ? toEmbed.length : toEmbed.length,
+  };
+  await saveIndex(p, manifest, allChunks);
+  return { ok: true, manifest, paths: p };
+}

package/src/indexer/walker.js

@@ -0,0 +1,45 @@
+import path from 'node:path';
+
+import fg from 'fast-glob';
+
+/**
+ * bc.config.json 의 context.include / context.exclude 글롭을 따라
+ * 인덱싱 대상 파일 절대경로 목록을 돌려준다.
+ *
+ * - 항상 node_modules / .bc / .git / dist / build / .next 는 제외
+ * - 100KB 넘는 파일은 인덱싱하지 않는다 (대부분 minified/generated)
+ */
+export async function walkProjectFiles(projectRoot, contextCfg = {}) {
+  const include =
+    contextCfg.include?.length
+      ? contextCfg.include
+      : ['src/**/*.{ts,tsx,js,jsx}', 'app/**/*.{ts,tsx,js,jsx}', 'bc.config.json'];
+
+  const baseExclude = [
+    '**/node_modules/**',
+    '**/.bc/**',
+    '**/.git/**',
+    '**/dist/**',
+    '**/build/**',
+    '**/.next/**',
+    '**/.expo/**',
+    '**/coverage/**',
+  ];
+  const userExclude = contextCfg.exclude ?? [];
+
+  const matches = await fg(include, {
+    cwd: projectRoot,
+    absolute: true,
+    onlyFiles: true,
+    ignore: [...baseExclude, ...userExclude],
+    dot: false,
+    suppressErrors: true,
+  });
+
+  // 중복 제거 (include 글롭이 겹칠 수 있음).
+  return Array.from(new Set(matches));
+}
+
+export function relPath(projectRoot, abs) {
+  return path.relative(projectRoot, abs).split(path.sep).join('/');
+}

package/src/openapi/cache.js

@@ -0,0 +1,60 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+import { findProjectConfigPath } from '../config/index.js';
+import { loadOpenApi } from './fetch.js';
+
+const TTL_MS = 60 * 60 * 1000; // 1시간
+
+async function getCacheDir(cwd = process.cwd()) {
+  const projectConfig = await findProjectConfigPath(cwd);
+  const root = projectConfig ? path.dirname(projectConfig) : cwd;
+  return path.join(root, '.bc', 'cache');
+}
+
+function keyFor(input) {
+  return crypto.createHash('sha1').update(String(input)).digest('hex').slice(0, 12);
+}
+
+/**
+ * URL 캐시가 있으면 그걸로, 없거나 만료되었으면 fetch 후 갱신.
+ * 결과는 { doc, cached, source } 형태.
+ *
+ * - 네트워크 실패 시: 만료된 캐시라도 있으면 그걸로 폴백 (offline-friendly).
+ * - 캐시는 .bc/cache/openapi-<hash>.json 에 저장.
+ */
+export async function getCachedOpenApi(input) {
+  const dir = await getCacheDir();
+  const file = path.join(dir, `openapi-${keyFor(input)}.json`);
+
+  let cached = null;
+  let cachedFresh = false;
+  try {
+    const stat = await fs.stat(file);
+    const raw = await fs.readFile(file, 'utf8');
+    cached = JSON.parse(raw);
+    cachedFresh = Date.now() - stat.mtimeMs < TTL_MS;
+  } catch {
+    /* miss */
+  }
+
+  if (cachedFresh && cached) {
+    return { doc: cached, cached: true, source: input };
+  }
+
+  try {
+    const { doc } = await loadOpenApi(input);
+    if (doc) {
+      await fs.mkdir(dir, { recursive: true });
+      await fs.writeFile(file, JSON.stringify(doc), 'utf8');
+      return { doc, cached: false, source: input };
+    }
+    // doc 가 null (YAML) — 캐시 못 쓰지만 fetch 자체는 성공한 케이스
+    return { doc: null, cached: false, source: input };
+  } catch (err) {
+    // 네트워크/파싱 실패 — 만료된 캐시라도 있으면 그걸 돌려준다.
+    if (cached) return { doc: cached, cached: true, source: input, stale: true };
+    throw err;
+  }
+}

package/src/openapi/codegen.js

@@ -0,0 +1,45 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import openapiTS, { astToString } from 'openapi-typescript';
+
+const FILE_HEADER = `// AUTO-GENERATED by \`bc gen api-types\`
+// Do not edit manually. Re-run \`bc gen api-types\` to refresh.
+//
+// Source: __SOURCE__
+// Generated: __DATE__
+
+`;
+
+/**
+ * OpenAPI 입력으로부터 TypeScript 타입 파일을 생성해 디스크에 쓴다.
+ *
+ * @param {object} args
+ * @param {string|object} args.input  URL / 파일 경로 / 이미 파싱된 OpenAPI 객체
+ * @param {string} args.outFile       절대/상대 경로
+ * @param {string} args.sourceLabel   파일 헤더 주석에 표기할 출처 문자열
+ * @returns {{ outFile: string, bytes: number }}
+ */
+export async function generateApiTypes({ input, outFile, sourceLabel }) {
+  // openapi-typescript v7: 입력은 URL 객체, 파싱된 객체, 또는 path 문자열을 받음.
+  // 우리가 받은 input 이 URL 문자열이면 URL 인스턴스로, 파일 경로면 그대로 넘김.
+  let sdkInput = input;
+  if (typeof input === 'string' && /^https?:\/\//.test(input)) {
+    sdkInput = new URL(input);
+  } else if (typeof input === 'string') {
+    sdkInput = path.resolve(input);
+  }
+
+  const ast = await openapiTS(sdkInput);
+  const code = astToString(ast);
+
+  const header = FILE_HEADER
+    .replace('__SOURCE__', sourceLabel ?? String(input))
+    .replace('__DATE__', new Date().toISOString());
+
+  const final = header + code + (code.endsWith('\n') ? '' : '\n');
+
+  await fs.mkdir(path.dirname(outFile), { recursive: true });
+  await fs.writeFile(outFile, final, 'utf8');
+  return { outFile, bytes: Buffer.byteLength(final, 'utf8') };
+}