lua-cli 3.15.1 → 3.15.3

package/node_modules/@lua/shared-source-sync/dist/index.mjs

@@ -0,0 +1,491 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/hash.ts
+import { createHash } from "crypto";
+var FILE_HASH_LENGTH = 16;
+function hashContentTruncated(content) {
+  return createHash("sha256").update(content).digest("hex").slice(0, FILE_HASH_LENGTH);
+}
+__name(hashContentTruncated, "hashContentTruncated");
+function sha256Hex(content) {
+  return createHash("sha256").update(content).digest("hex");
+}
+__name(sha256Hex, "sha256Hex");
+function combineFileHashes(files) {
+  const sorted = [
+    ...files
+  ].sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+  return sha256Hex(sorted.map((f) => f.hash).join("|"));
+}
+__name(combineFileHashes, "combineFileHashes");
+
+// src/filter.ts
+import { extname } from "path";
+var SKIP_DIRECTORIES = /* @__PURE__ */ new Set([
+  "node_modules",
+  "dist",
+  "dist-v2",
+  ".git",
+  ".lua",
+  ".temp",
+  "coverage",
+  ".next",
+  ".turbo"
+]);
+var ARCHIVE_ONLY_SKIP_DIRECTORIES = /* @__PURE__ */ new Set([
+  "build"
+]);
+var DEFAULT_MAX_FILE_BYTES = 256 * 1024;
+function shouldSkipDirectory(name) {
+  return SKIP_DIRECTORIES.has(name);
+}
+__name(shouldSkipDirectory, "shouldSkipDirectory");
+function shouldSkipFile(filePathOrName) {
+  return filePathOrName.includes("node_modules") || filePathOrName.includes(".test.") || filePathOrName.includes(".spec.") || filePathOrName.includes("__tests__") || filePathOrName.endsWith(".d.ts") || filePathOrName.endsWith(".map") || filePathOrName.startsWith(".") || filePathOrName === "package-lock.json" || filePathOrName === "yarn.lock" || filePathOrName === "pnpm-lock.yaml";
+}
+__name(shouldSkipFile, "shouldSkipFile");
+var KIND_BY_EXT = {
+  ".ts": "source",
+  ".tsx": "source",
+  ".js": "source",
+  ".jsx": "source",
+  ".yaml": "config",
+  ".yml": "config",
+  ".json": "config",
+  ".toml": "config"
+};
+function classifyFile(relPath) {
+  return KIND_BY_EXT[extname(relPath)] ?? "other";
+}
+__name(classifyFile, "classifyFile");
+
+// src/walk.ts
+import { readdirSync, readFileSync, statSync } from "fs";
+import { join, sep } from "path";
+function walkWorkspace(rootDir, opts = {}) {
+  const maxBytes = opts.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES;
+  const refs = [];
+  const contentByHash = /* @__PURE__ */ new Map();
+  let totalSize = 0;
+  const visit = /* @__PURE__ */ __name((relPrefix) => {
+    const absDir = relPrefix ? join(rootDir, relPrefix) : rootDir;
+    let entries;
+    try {
+      entries = readdirSync(absDir, {
+        withFileTypes: true
+      });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (shouldSkipDirectory(entry.name)) continue;
+        if (shouldSkipFile(entry.name)) continue;
+        visit(relPrefix ? `${relPrefix}${sep}${entry.name}` : entry.name);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (shouldSkipFile(entry.name)) continue;
+      const rel = (relPrefix ? `${relPrefix}${sep}${entry.name}` : entry.name).split(sep).join("/");
+      const abs = join(rootDir, rel);
+      let stats;
+      try {
+        stats = statSync(abs);
+      } catch {
+        continue;
+      }
+      if (stats.size > maxBytes) continue;
+      let content;
+      try {
+        content = readFileSync(abs);
+      } catch {
+        continue;
+      }
+      const hash = hashContentTruncated(content.toString("utf-8"));
+      refs.push({
+        relativePath: rel,
+        hash,
+        size: stats.size,
+        type: classifyFile(rel)
+      });
+      if (!contentByHash.has(hash)) contentByHash.set(hash, content);
+      totalSize += stats.size;
+    }
+  }, "visit");
+  visit("");
+  refs.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+  const projectHash = combineFileHashes(refs);
+  return {
+    files: refs,
+    projectHash,
+    totalSize,
+    contentByHash
+  };
+}
+__name(walkWorkspace, "walkWorkspace");
+
+// src/http.ts
+var BackupHttpError = class extends Error {
+  static {
+    __name(this, "BackupHttpError");
+  }
+  status;
+  endpoint;
+  body;
+  constructor(message, status, endpoint, body) {
+    super(message), this.status = status, this.endpoint = endpoint, this.body = body;
+    this.name = "BackupHttpError";
+  }
+};
+var BackupHttpClient = class {
+  static {
+    __name(this, "BackupHttpClient");
+  }
+  options;
+  fetchFn;
+  constructor(options) {
+    this.options = options;
+    this.fetchFn = options.fetch ?? fetch;
+  }
+  url(path) {
+    const base = this.options.baseUrl.replace(/\/$/, "");
+    return `${base}/developer/agents/${encodeURIComponent(this.options.agentId)}${path}`;
+  }
+  async json(method, path, body) {
+    const endpoint = this.url(path);
+    const res = await this.fetchFn(endpoint, {
+      method,
+      headers: {
+        Authorization: this.options.authHeader,
+        ...body !== void 0 ? {
+          "Content-Type": "application/json"
+        } : {},
+        Accept: "application/json"
+      },
+      body: body !== void 0 ? JSON.stringify(body) : void 0
+    });
+    if (!res.ok) {
+      let text2;
+      try {
+        text2 = await res.text();
+      } catch {
+        text2 = void 0;
+      }
+      throw new BackupHttpError(`Backup request failed: ${method} ${path} \u2192 ${res.status} ${res.statusText}`, res.status, endpoint, text2);
+    }
+    const text = await res.text();
+    if (!text) return void 0;
+    return JSON.parse(text);
+  }
+  /** `POST /backup/check-blobs` — returns existing vs missing partition. */
+  checkBlobsExist(hashes) {
+    return this.json("POST", "/backup/check-blobs", {
+      hashes
+    });
+  }
+  /** `POST /backup/blob-upload-urls` — presigned S3 PUT URLs. */
+  getBlobUploadUrls(hashes) {
+    return this.json("POST", "/backup/blob-upload-urls", {
+      hashes
+    });
+  }
+  /** `POST /backup/blob-urls` — presigned S3 GET URLs (for restore). */
+  getBlobUrls(hashes) {
+    return this.json("POST", "/backup/blob-urls", {
+      hashes
+    });
+  }
+  /** `POST /backup/manifest` — final step in a push; returns server metadata. */
+  saveManifest(data) {
+    return this.json("POST", "/backup/manifest", data);
+  }
+  /** `GET /backup` — metadata only, no file list. */
+  getMetadata() {
+    return this.json("GET", "/backup");
+  }
+  /** `GET /backup/manifest` — metadata + file list. */
+  getManifest() {
+    return this.json("GET", "/backup/manifest");
+  }
+  /** `GET /backup/check/:hash` — fast freshness probe. */
+  checkBackupExists(hash) {
+    return this.json("GET", `/backup/check/${encodeURIComponent(hash)}`);
+  }
+};
+
+// src/transfer.ts
+import { gunzipSync, gzipSync } from "zlib";
+var DEFAULT_CONCURRENCY = 10;
+async function uploadBlobs(opts) {
+  const fetchFn = opts.fetch ?? fetch;
+  const concurrency = opts.concurrency ?? DEFAULT_CONCURRENCY;
+  const hashes = Object.keys(opts.uploadUrls);
+  for (let i = 0; i < hashes.length; i += concurrency) {
+    const batch = hashes.slice(i, i + concurrency);
+    await Promise.all(batch.map(async (hash) => {
+      const buf = opts.contentByHash.get(hash);
+      if (!buf) {
+        throw new Error(`uploadBlobs: no content for hash ${hash.slice(0, 12)}\u2026`);
+      }
+      const compressed = gzipSync(buf);
+      const res = await fetchFn(opts.uploadUrls[hash], {
+        method: "PUT",
+        body: compressed,
+        headers: {
+          "Content-Type": "application/octet-stream"
+        }
+      });
+      if (!res.ok) {
+        throw new Error(`S3 upload failed for ${hash.slice(0, 12)}\u2026: ${res.status} ${res.statusText}`);
+      }
+    }));
+  }
+  return hashes.length;
+}
+__name(uploadBlobs, "uploadBlobs");
+async function downloadBlobs(opts) {
+  const fetchFn = opts.fetch ?? fetch;
+  const concurrency = opts.concurrency ?? DEFAULT_CONCURRENCY;
+  const out = /* @__PURE__ */ new Map();
+  const entries = Object.entries(opts.urls);
+  for (let i = 0; i < entries.length; i += concurrency) {
+    const batch = entries.slice(i, i + concurrency);
+    const downloaded = await Promise.all(batch.map(async ([hash, url]) => {
+      const res = await fetchFn(url);
+      if (!res.ok) {
+        throw new Error(`S3 download failed for ${hash.slice(0, 12)}\u2026: ${res.status} ${res.statusText}`);
+      }
+      const ab = await res.arrayBuffer();
+      const buf = Buffer.from(ab);
+      if (buf.length >= 2 && buf[0] === 31 && buf[1] === 139) {
+        try {
+          return [
+            hash,
+            gunzipSync(buf)
+          ];
+        } catch {
+          return [
+            hash,
+            buf
+          ];
+        }
+      }
+      return [
+        hash,
+        buf
+      ];
+    }));
+    for (const [hash, buf] of downloaded) out.set(hash, buf);
+  }
+  return out;
+}
+__name(downloadBlobs, "downloadBlobs");
+
+// src/restore.ts
+import { existsSync, mkdirSync, readFileSync as readFileSync2, statSync as statSync2, writeFileSync } from "fs";
+import { dirname, join as join2, resolve, sep as sep2 } from "path";
+function resolveBackupFileTarget(file, targetDir) {
+  const base = resolve(targetDir);
+  const sandboxed = file.external ? join2(base, ".lua", "external", file.relativePath) : join2(base, file.relativePath);
+  const resolved = resolve(sandboxed);
+  if (resolved !== base && !resolved.startsWith(base + sep2)) {
+    throw new Error(`Backup entry escapes target directory: ${file.relativePath}`);
+  }
+  return resolved;
+}
+__name(resolveBackupFileTarget, "resolveBackupFileTarget");
+function restoreFromBlobs(manifest, blobs, targetDir, opts = {}) {
+  let filesWritten = 0;
+  let filesUnchanged = 0;
+  let filesSkipped = 0;
+  for (const file of manifest.files) {
+    const content = blobs.get(file.hash);
+    if (!content) {
+      throw new Error(`Blob not found for hash: ${file.hash} (${file.relativePath})`);
+    }
+    const targetPath = resolveBackupFileTarget(file, targetDir);
+    if (existsSync(targetPath)) {
+      const sameSize = statSync2(targetPath).size === content.length;
+      if (sameSize && readFileSync2(targetPath).equals(content)) {
+        filesUnchanged++;
+        continue;
+      }
+      if (!opts.overwrite) {
+        filesSkipped++;
+        continue;
+      }
+    }
+    mkdirSync(dirname(targetPath), {
+      recursive: true
+    });
+    writeFileSync(targetPath, content);
+    filesWritten++;
+  }
+  return {
+    filesWritten,
+    filesUnchanged,
+    filesSkipped
+  };
+}
+__name(restoreFromBlobs, "restoreFromBlobs");
+
+// src/push.ts
+async function pushAgentBackup(opts) {
+  const snapshot = walkWorkspace(opts.workspaceDir, opts.walkOptions);
+  const client = new BackupHttpClient(opts.http);
+  const uniqueHashes = [
+    ...new Set(snapshot.files.map((f) => f.hash))
+  ];
+  let filesUploaded = 0;
+  if (uniqueHashes.length > 0) {
+    const checked = await client.checkBlobsExist(uniqueHashes);
+    if (checked.missing.length > 0) {
+      const urls = await client.getBlobUploadUrls(checked.missing);
+      filesUploaded = await uploadBlobs({
+        uploadUrls: urls.urls,
+        contentByHash: snapshot.contentByHash,
+        fetch: opts.http.fetch,
+        concurrency: opts.concurrency
+      });
+    }
+  }
+  const metadata = await client.saveManifest({
+    projectHash: snapshot.projectHash,
+    files: snapshot.files,
+    version: opts.version,
+    orgId: opts.orgId,
+    createdBy: opts.createdBy ?? "cli",
+    triggeredBy: opts.triggeredBy
+  });
+  return {
+    projectHash: snapshot.projectHash,
+    fileCount: snapshot.files.length,
+    filesUploaded,
+    activeVersion: metadata.activeVersion,
+    metadata,
+    files: snapshot.files
+  };
+}
+__name(pushAgentBackup, "pushAgentBackup");
+
+// src/pull.ts
+async function pullAgentBackup(opts) {
+  const client = new BackupHttpClient(opts.http);
+  const manifest = await client.getManifest();
+  const uniqueHashes = [
+    ...new Set(manifest.files.map((f) => f.hash))
+  ];
+  const blobs = uniqueHashes.length ? await (async () => {
+    const urls = await client.getBlobUrls(uniqueHashes);
+    return downloadBlobs({
+      urls: urls.urls,
+      fetch: opts.http.fetch,
+      concurrency: opts.concurrency
+    });
+  })() : /* @__PURE__ */ new Map();
+  const result = restoreFromBlobs(manifest, blobs, opts.targetDir, opts.restore);
+  return {
+    ...result,
+    manifest
+  };
+}
+__name(pullAgentBackup, "pullAgentBackup");
+
+// src/archive.ts
+import { mkdirSync as mkdirSync2, readdirSync as readdirSync2, readFileSync as readFileSync3, statSync as statSync3, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname2, join as join3, sep as sep3 } from "path";
+import { gunzipSync as gunzipSync2, gzipSync as gzipSync2 } from "zlib";
+var ARCHIVE_SCHEMA_VERSION = 1;
+function encodeWorkspaceArchive(workspaceDir) {
+  const files = {};
+  try {
+    walk(workspaceDir, "", files);
+  } catch {
+    return null;
+  }
+  if (Object.keys(files).length === 0) return null;
+  const gz = gzipSync2(Buffer.from(JSON.stringify(files), "utf8"));
+  return gz.toString("base64");
+}
+__name(encodeWorkspaceArchive, "encodeWorkspaceArchive");
+function decodeWorkspaceArchive(archive, schemaVersion) {
+  if (schemaVersion !== void 0 && schemaVersion !== ARCHIVE_SCHEMA_VERSION) {
+    throw new Error(`Unsupported archive schema version: ${schemaVersion} (expected ${ARCHIVE_SCHEMA_VERSION})`);
+  }
+  const raw = gunzipSync2(Buffer.from(archive, "base64")).toString("utf8");
+  const parsed = JSON.parse(raw);
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("Decoded archive is not a JSON object map");
+  }
+  return parsed;
+}
+__name(decodeWorkspaceArchive, "decodeWorkspaceArchive");
+function writeArchiveToWorkspace(workspaceDir, files) {
+  for (const [relPath, content] of Object.entries(files)) {
+    if (relPath.includes("..")) {
+      throw new Error(`Refusing to write archived path containing '..': ${relPath}`);
+    }
+    const abs = join3(workspaceDir, relPath);
+    mkdirSync2(dirname2(abs), {
+      recursive: true
+    });
+    writeFileSync2(abs, content, "utf8");
+  }
+}
+__name(writeArchiveToWorkspace, "writeArchiveToWorkspace");
+function walk(root, prefix, out) {
+  const dir = prefix ? join3(root, prefix) : root;
+  const entries = readdirSync2(dir, {
+    withFileTypes: true
+  });
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (shouldSkipDirectory(entry.name) || ARCHIVE_ONLY_SKIP_DIRECTORIES.has(entry.name) || shouldSkipFile(entry.name)) continue;
+      walk(root, prefix ? `${prefix}${sep3}${entry.name}` : entry.name, out);
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    if (shouldSkipFile(entry.name)) continue;
+    const relPath = (prefix ? `${prefix}${sep3}${entry.name}` : entry.name).split(sep3).join("/");
+    const abs = join3(dir, entry.name);
+    if (statSync3(abs).size > DEFAULT_MAX_FILE_BYTES) continue;
+    try {
+      out[relPath] = readFileSync3(abs, "utf8");
+    } catch {
+    }
+  }
+}
+__name(walk, "walk");
+
+// src/skill-source.ts
+var SKILL_SOURCE_EDITORS = [
+  "builder",
+  "cli",
+  "engineer",
+  "system"
+];
+export {
+  ARCHIVE_SCHEMA_VERSION,
+  BackupHttpClient,
+  BackupHttpError,
+  DEFAULT_MAX_FILE_BYTES,
+  FILE_HASH_LENGTH,
+  SKILL_SOURCE_EDITORS,
+  classifyFile,
+  combineFileHashes,
+  decodeWorkspaceArchive,
+  downloadBlobs,
+  encodeWorkspaceArchive,
+  hashContentTruncated,
+  pullAgentBackup,
+  pushAgentBackup,
+  resolveBackupFileTarget,
+  restoreFromBlobs,
+  sha256Hex,
+  shouldSkipDirectory,
+  shouldSkipFile,
+  uploadBlobs,
+  walkWorkspace,
+  writeArchiveToWorkspace
+};

package/node_modules/@lua/shared-source-sync/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@lua/shared-source-sync",
+  "version": "0.0.1",
+  "private": true,
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.8.2",
+    "vitest": "^3.1.1"
+  }
+}

package/node_modules/@lua/shared-source-sync/src/archive.ts

@@ -0,0 +1,98 @@
+/**
+ * Workspace ↔ archive serialization. Wire format:
+ *   gzip(JSON.stringify({ [relPath]: contents })) → base64.
+ * Spec: docs/superpowers/specs/2026-05-02-canonical-tool-source-design.md.
+ *
+ * A JSON map is used (vs tar) so neither the CLI bundle nor the
+ * lua-claude-builder runtime needs a tar dependency. The format is symmetric
+ * across both, so encode/decode go through these helpers — never inline.
+ */
+
+import { mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'fs';
+import { dirname, join, sep } from 'path';
+import { gunzipSync, gzipSync } from 'zlib';
+import { ARCHIVE_ONLY_SKIP_DIRECTORIES, DEFAULT_MAX_FILE_BYTES, shouldSkipDirectory, shouldSkipFile } from './filter';
+
+export const ARCHIVE_SCHEMA_VERSION = 1;
+
+/**
+ * Encode a workspace directory tree into a base64-gzip JSON map. Returns
+ * `null` if the workspace doesn't exist or is empty.
+ */
+export function encodeWorkspaceArchive(workspaceDir: string): string | null {
+  const files: Record<string, string> = {};
+  try {
+    walk(workspaceDir, '', files);
+  } catch {
+    return null;
+  }
+  if (Object.keys(files).length === 0) return null;
+
+  const gz = gzipSync(Buffer.from(JSON.stringify(files), 'utf8'));
+  return gz.toString('base64');
+}
+
+/**
+ * Decode a base64-gzip JSON map back to a `{ relPath: content }` object.
+ * Throws on malformed payloads — callers should treat that as a corrupt
+ * canonical record and surface clearly rather than silently writing nothing.
+ */
+export function decodeWorkspaceArchive(archive: string, schemaVersion?: number): Record<string, string> {
+  if (schemaVersion !== undefined && schemaVersion !== ARCHIVE_SCHEMA_VERSION) {
+    throw new Error(`Unsupported archive schema version: ${schemaVersion} (expected ${ARCHIVE_SCHEMA_VERSION})`);
+  }
+  const raw = gunzipSync(Buffer.from(archive, 'base64')).toString('utf8');
+  const parsed = JSON.parse(raw);
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('Decoded archive is not a JSON object map');
+  }
+  return parsed as Record<string, string>;
+}
+
+/**
+ * Write the contents of a decoded archive into `workspaceDir`. Existing files
+ * are overwritten — caller is responsible for save-pending-changes prompts.
+ * Defense-in-depth: any `relPath` containing `..` is rejected.
+ */
+export function writeArchiveToWorkspace(workspaceDir: string, files: Record<string, string>): void {
+  for (const [relPath, content] of Object.entries(files)) {
+    if (relPath.includes('..')) {
+      throw new Error(`Refusing to write archived path containing '..': ${relPath}`);
+    }
+    const abs = join(workspaceDir, relPath);
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, content, 'utf8');
+  }
+}
+
+function walk(root: string, prefix: string, out: Record<string, string>): void {
+  const dir = prefix ? join(root, prefix) : root;
+  const entries = readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      // Archive-only set lives alongside the shared shouldSkipDirectory
+      // so build/ stays out of per-skill archives without leaking into
+      // the canonical primitive scan (compiler) or the per-agent backup
+      // walker — see filter.ts and PR #402 review for the rationale.
+      if (
+        shouldSkipDirectory(entry.name) ||
+        ARCHIVE_ONLY_SKIP_DIRECTORIES.has(entry.name) ||
+        shouldSkipFile(entry.name)
+      )
+        continue;
+      walk(root, prefix ? `${prefix}${sep}${entry.name}` : entry.name, out);
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    if (shouldSkipFile(entry.name)) continue;
+
+    const relPath = (prefix ? `${prefix}${sep}${entry.name}` : entry.name).split(sep).join('/');
+    const abs = join(dir, entry.name);
+    if (statSync(abs).size > DEFAULT_MAX_FILE_BYTES) continue;
+    try {
+      out[relPath] = readFileSync(abs, 'utf8');
+    } catch {
+      // Binary or unreadable — skip rather than corrupt the archive
+    }
+  }
+}

package/node_modules/@lua/shared-source-sync/src/filter.ts

@@ -0,0 +1,72 @@
+/**
+ * File-inclusion rules used when walking an agent workspace.
+ *
+ * Wire-compat invariant: identical content must produce identical projectHashes
+ * across the CLI compile path and any server-side walker, or the per-agent
+ * backup dedupe falls apart. The CLI compiler re-exports these from here.
+ */
+
+import { extname } from 'path';
+
+const SKIP_DIRECTORIES = new Set([
+  'node_modules',
+  'dist',
+  'dist-v2',
+  '.git',
+  '.lua',
+  '.temp',
+  'coverage',
+  '.next',
+  '.turbo',
+]);
+
+/**
+ * Directories the per-skill workspace archive encoder excludes ON TOP OF
+ * `SKIP_DIRECTORIES`. Kept separate so the archive's denormalized "drop
+ * compiled artifacts" semantics doesn't leak into the canonical primitive
+ * scan (`compiler/utils/common.ts::shouldSkipDirectory`) or the per-agent
+ * backup walker (`walkWorkspace`), both of which must include `build/`
+ * source so developers can keep tool code under custom layouts (Vite,
+ * Next.js, etc.) without it silently disappearing from compile or sync.
+ *
+ * Only `archive.ts::walk` consults this set. Adding entries here is safe;
+ * adding them to `SKIP_DIRECTORIES` is a category error — see PR #402
+ * Bugbot review (2026-05-13) for the regression that caused this split.
+ */
+export const ARCHIVE_ONLY_SKIP_DIRECTORIES = new Set(['build']);
+
+export const DEFAULT_MAX_FILE_BYTES = 256 * 1024;
+
+export function shouldSkipDirectory(name: string): boolean {
+  return SKIP_DIRECTORIES.has(name);
+}
+
+export function shouldSkipFile(filePathOrName: string): boolean {
+  return (
+    filePathOrName.includes('node_modules') ||
+    filePathOrName.includes('.test.') ||
+    filePathOrName.includes('.spec.') ||
+    filePathOrName.includes('__tests__') ||
+    filePathOrName.endsWith('.d.ts') ||
+    filePathOrName.endsWith('.map') ||
+    filePathOrName.startsWith('.') ||
+    filePathOrName === 'package-lock.json' ||
+    filePathOrName === 'yarn.lock' ||
+    filePathOrName === 'pnpm-lock.yaml'
+  );
+}
+
+const KIND_BY_EXT: Record<string, 'source' | 'config'> = {
+  '.ts': 'source',
+  '.tsx': 'source',
+  '.js': 'source',
+  '.jsx': 'source',
+  '.yaml': 'config',
+  '.yml': 'config',
+  '.json': 'config',
+  '.toml': 'config',
+};
+
+export function classifyFile(relPath: string): 'source' | 'config' | 'other' {
+  return KIND_BY_EXT[extname(relPath)] ?? 'other';
+}