lua-cli 3.15.1 → 3.15.3

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

@@ -0,0 +1,88 @@
+/**
+ * Wire types for the agent project backup feature.
+ *
+ * These mirror `packages/lua-cli/src/interfaces/backup.ts` byte-for-byte so the
+ * CLI and any server-side caller speak the same protocol against the existing
+ * `/developer/agents/:agentId/backup/*` endpoints on lua-api.
+ */
+
+/**
+ * A single file entry in the backup manifest. Carries no content — content is
+ * stored as a blob in S3 under `backups/blobs/<hash>` and dereferenced at
+ * restore time.
+ */
+export interface BackupFileRef {
+  /**
+   * Path used both as identifier and as on-disk restore location.
+   * - In-project: relative to the agent's project root (e.g. `src/index.ts`).
+   * - External (monorepo cross-root): relative to the workspace root; restored
+   *   under `.lua/external/<relativePath>` (see BAC-69).
+   */
+  relativePath: string;
+  /** Truncated SHA-256 (16 hex chars) of the file's raw bytes. Used as the S3 key. */
+  hash: string;
+  /** Original (uncompressed) byte size. */
+  size: number;
+  /** Coarse classification for telemetry and UI grouping. */
+  type: 'source' | 'config' | 'other';
+  /** Defaults to in-project when absent. Cross-root files set this `true`. */
+  external?: boolean;
+}
+
+/** Body of `POST /developer/agents/:agentId/backup/check-blobs`. */
+export interface CheckBlobsRequest {
+  hashes: string[];
+}
+
+/** Response shape from `check-blobs`. */
+export interface CheckBlobsResponse {
+  missing: string[];
+  existing: string[];
+  results: Record<string, boolean>;
+}
+
+/** Body of `POST /developer/agents/:agentId/backup/blob-upload-urls` and `.../blob-urls`. */
+export interface GetBlobUrlsRequest {
+  hashes: string[];
+}
+
+/** Response shape: `{ urls: { <hash>: <presignedUrl> }, expiresIn: <seconds> }`. */
+export interface GetBlobUrlsResponse {
+  urls: Record<string, string>;
+  expiresIn: number;
+}
+
+/** Body of `POST /developer/agents/:agentId/backup/manifest`. */
+export interface SaveManifestRequest {
+  projectHash: string;
+  files: BackupFileRef[];
+  version?: string;
+  createdBy?: string;
+  orgId?: string;
+  triggeredBy?: string;
+}
+
+/** Metadata returned by `GET /developer/agents/:agentId/backup`. */
+export interface BackupMetadata {
+  agentId: string;
+  orgId: string;
+  projectHash: string;
+  fileCount: number;
+  totalSize: number;
+  version?: string;
+  createdBy: string;
+  createdAt: string;
+  /** Monotonic manifest version assigned by the V2 server path. */
+  activeVersion?: number;
+}
+
+/** Full response from `GET /developer/agents/:agentId/backup/manifest`. */
+export interface BackupManifest extends BackupMetadata {
+  files: BackupFileRef[];
+}
+
+/** Response from `GET /developer/agents/:agentId/backup/check/:hash`. */
+export interface BackupExistsResponse {
+  exists: boolean;
+  currentHash?: string;
+}

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

@@ -0,0 +1,91 @@
+/**
+ * Walk an agent workspace from disk and produce a fresh manifest. Used by
+ * both the CLI (via `buildManifestFromDisk`) and server-side callers
+ * (`SourceSyncService`).
+ */
+
+import { readdirSync, readFileSync, statSync, type Dirent } from 'fs';
+import { join, sep } from 'path';
+import { hashContentTruncated, combineFileHashes } from './hash';
+import { classifyFile, shouldSkipDirectory, shouldSkipFile, DEFAULT_MAX_FILE_BYTES } from './filter';
+import type { BackupFileRef } from './types';
+
+export interface WalkOptions {
+  /** Per-file size cap. Files larger than this are skipped (default 256KB). */
+  maxFileBytes?: number;
+}
+
+export interface WalkResult {
+  /** Sorted file references suitable for a backup manifest. */
+  files: BackupFileRef[];
+  /** Deterministic combined hash over the file set. */
+  projectHash: string;
+  /** Sum of original file sizes. */
+  totalSize: number;
+  /**
+   * Raw file content keyed by truncated hash. Caller uses this for the upload
+   * step instead of re-reading from disk. First-write-wins on collision so
+   * dedup is honored.
+   */
+  contentByHash: Map<string, Buffer>;
+}
+
+/**
+ * Walk `rootDir` and return a stable workspace snapshot. 16-char truncated
+ * SHA-256 hashes; path separators normalized to `/` for OS-independent
+ * manifest round-trip.
+ */
+export function walkWorkspace(rootDir: string, opts: WalkOptions = {}): WalkResult {
+  const maxBytes = opts.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES;
+  const refs: BackupFileRef[] = [];
+  const contentByHash = new Map<string, Buffer>();
+  let totalSize = 0;
+
+  const visit = (relPrefix: string): void => {
+    const absDir = relPrefix ? join(rootDir, relPrefix) : rootDir;
+    let entries: Dirent[];
+    try {
+      entries = readdirSync(absDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        // Curated skip list + file-skip rules — catches dotted dirs, __tests__, etc.
+        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: Buffer;
+      try {
+        content = readFileSync(abs);
+      } catch {
+        continue;
+      }
+      // Hash the UTF-8 string form — must match the compiler's `hashContent`
+      // byte-for-byte so the CLI and server walks produce identical hashes.
+      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('');
+  refs.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+  const projectHash = combineFileHashes(refs);
+  return { files: refs, projectHash, totalSize, contentByHash };
+}

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

@@ -0,0 +1,108 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'fs';
+import { gzipSync } from 'zlib';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import {
+  ARCHIVE_SCHEMA_VERSION,
+  decodeWorkspaceArchive,
+  encodeWorkspaceArchive,
+  writeArchiveToWorkspace,
+} from '../src/archive';
+
+describe('canonical-source archive (shared-source-sync)', () => {
+  let workspace: string;
+
+  beforeEach(() => {
+    workspace = mkdtempSync(join(tmpdir(), 'shared-archive-'));
+  });
+
+  afterEach(() => {
+    if (existsSync(workspace)) rmSync(workspace, { recursive: true, force: true });
+  });
+
+  it('exports a stable schema version of 1', () => {
+    expect(ARCHIVE_SCHEMA_VERSION).toBe(1);
+  });
+
+  it('returns null for a non-existent or empty workspace', () => {
+    expect(encodeWorkspaceArchive(join(workspace, 'no-such'))).toBeNull();
+    expect(encodeWorkspaceArchive(workspace)).toBeNull();
+  });
+
+  it('round-trips a small TS workspace', () => {
+    mkdirSync(join(workspace, 'src'));
+    writeFileSync(join(workspace, 'lua.skill.yaml'), 'agent:\n  agentId: a\n');
+    writeFileSync(join(workspace, 'src/tool.ts'), 'export const tool = 1;\n');
+
+    const archive = encodeWorkspaceArchive(workspace);
+    expect(archive).toBeTruthy();
+    const decoded = decodeWorkspaceArchive(archive!);
+    expect(Object.keys(decoded).sort()).toEqual(['lua.skill.yaml', 'src/tool.ts']);
+  });
+
+  it('excludes node_modules, .git, dist, .env, lockfiles', () => {
+    mkdirSync(join(workspace, 'src'));
+    mkdirSync(join(workspace, 'node_modules'));
+    mkdirSync(join(workspace, '.git'));
+    mkdirSync(join(workspace, 'dist'));
+    writeFileSync(join(workspace, 'src/keep.ts'), 'x');
+    writeFileSync(join(workspace, 'node_modules/drop.js'), 'x');
+    writeFileSync(join(workspace, '.git/HEAD'), 'x');
+    writeFileSync(join(workspace, 'dist/bundle.js'), 'x');
+    writeFileSync(join(workspace, '.env'), 'SECRET=1');
+    writeFileSync(join(workspace, 'pnpm-lock.yaml'), '');
+
+    const decoded = decodeWorkspaceArchive(encodeWorkspaceArchive(workspace)!);
+    expect(Object.keys(decoded)).toEqual(['src/keep.ts']);
+  });
+
+  // Regression for Cursor Bugbot PR #402: when the admin-tool-builder
+  // archive's `EXCLUDE_DIRS` was consolidated into shared `SKIP_DIRECTORIES`,
+  // `build` was initially dropped from the list. Per-skill archives then
+  // started sweeping in `build/` (Vite, Next.js, custom) outputs that don't
+  // belong in the canonical source store. Pins the restored exclusion.
+  it('excludes build/, .turbo/, .next/, coverage/, dist-v2/ (build-output dirs)', () => {
+    mkdirSync(join(workspace, 'src'));
+    writeFileSync(join(workspace, 'src/keep.ts'), 'x');
+    for (const dir of ['build', '.turbo', '.next', 'coverage', 'dist-v2']) {
+      mkdirSync(join(workspace, dir));
+      writeFileSync(join(workspace, `${dir}/artifact.js`), 'compiled');
+    }
+
+    const decoded = decodeWorkspaceArchive(encodeWorkspaceArchive(workspace)!);
+    expect(Object.keys(decoded)).toEqual(['src/keep.ts']);
+  });
+
+  it('skips files over 256KB', () => {
+    writeFileSync(join(workspace, 'big.ts'), 'x'.repeat(257 * 1024));
+    writeFileSync(join(workspace, 'small.ts'), 'x');
+    const decoded = decodeWorkspaceArchive(encodeWorkspaceArchive(workspace)!);
+    expect(Object.keys(decoded)).toEqual(['small.ts']);
+  });
+
+  it('writeArchiveToWorkspace rejects path-traversal entries', () => {
+    expect(() => writeArchiveToWorkspace(workspace, { '../escape.ts': 'evil' })).toThrow(/Refusing to write/);
+    expect(() => writeArchiveToWorkspace(workspace, { 'src/../../escape.ts': 'evil' })).toThrow(/Refusing to write/);
+  });
+
+  it('decodeWorkspaceArchive throws on non-object payloads', () => {
+    const bogus = gzipSync(Buffer.from('[1,2,3]', 'utf8')).toString('base64');
+    expect(() => decodeWorkspaceArchive(bogus)).toThrow(/JSON object map/);
+  });
+
+  it('preserves unicode content byte-for-byte through the round-trip', () => {
+    mkdirSync(join(workspace, 'src'));
+    const tricky = "// 漢字 🎯\nexport const s = '\\n';\n";
+    writeFileSync(join(workspace, 'src/tricky.ts'), tricky, 'utf8');
+    const decoded = decodeWorkspaceArchive(encodeWorkspaceArchive(workspace)!);
+
+    const restore = mkdtempSync(join(tmpdir(), 'shared-archive-restore-'));
+    try {
+      writeArchiveToWorkspace(restore, decoded);
+      expect(readFileSync(join(restore, 'src/tricky.ts'), 'utf8')).toBe(tricky);
+    } finally {
+      rmSync(restore, { recursive: true, force: true });
+    }
+  });
+});

package/node_modules/@lua/shared-source-sync/tests/hash.test.ts

@@ -0,0 +1,40 @@
+import { describe, it, expect } from 'vitest';
+import { createHash } from 'crypto';
+import { FILE_HASH_LENGTH, combineFileHashes, hashContentTruncated, sha256Hex } from '../src/hash';
+
+describe('hashContentTruncated', () => {
+  it('produces 16-char hex truncated SHA-256 (wire compatibility)', () => {
+    const content = 'hello world';
+    const expected = createHash('sha256').update(content).digest('hex').slice(0, FILE_HASH_LENGTH);
+    expect(hashContentTruncated(content)).toBe(expected);
+    expect(hashContentTruncated(content)).toHaveLength(16);
+  });
+
+  it('matches across string and equivalent Buffer input', () => {
+    const content = 'export const x = 1;';
+    expect(hashContentTruncated(content)).toBe(hashContentTruncated(Buffer.from(content, 'utf-8')));
+  });
+});
+
+describe('combineFileHashes', () => {
+  it('is order-independent (sorts by relativePath before combining)', () => {
+    const a = [
+      { relativePath: 'src/a.ts', hash: '0000000000000001' },
+      { relativePath: 'src/b.ts', hash: '0000000000000002' },
+    ];
+    const b = [
+      { relativePath: 'src/b.ts', hash: '0000000000000002' },
+      { relativePath: 'src/a.ts', hash: '0000000000000001' },
+    ];
+    expect(combineFileHashes(a)).toBe(combineFileHashes(b));
+  });
+
+  it('produces deterministic full-length SHA-256 over the pipe-joined sorted hashes', () => {
+    const files = [
+      { relativePath: 'src/index.ts', hash: 'abc' },
+      { relativePath: 'src/util.ts', hash: 'def' },
+    ];
+    const expected = sha256Hex('abc|def');
+    expect(combineFileHashes(files)).toBe(expected);
+  });
+});

package/node_modules/@lua/shared-source-sync/tests/http.test.ts

@@ -0,0 +1,77 @@
+import { describe, it, expect, vi } from 'vitest';
+import { BackupHttpClient, BackupHttpError } from '../src/http';
+
+function makeFetchStub(response: { status: number; body?: unknown; statusText?: string }) {
+  return vi.fn(async (_url: any, init?: any) => {
+    return {
+      ok: response.status >= 200 && response.status < 300,
+      status: response.status,
+      statusText: response.statusText ?? 'OK',
+      text: async () => (response.body === undefined ? '' : JSON.stringify(response.body)),
+    } as any;
+  });
+}
+
+describe('BackupHttpClient', () => {
+  it('builds the developer agent backup URL with the agent id encoded', async () => {
+    const fetchStub = makeFetchStub({ status: 200, body: { missing: [], existing: [], results: {} } });
+    const client = new BackupHttpClient({
+      baseUrl: 'https://api.example.com/',
+      authHeader: 'Bearer abc',
+      agentId: 'agent 1',
+      fetch: fetchStub as any,
+    });
+    await client.checkBlobsExist(['h1']);
+    expect(fetchStub).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchStub.mock.calls[0];
+    expect(url).toBe('https://api.example.com/developer/agents/agent%201/backup/check-blobs');
+    expect(init?.method).toBe('POST');
+    expect(init?.headers).toMatchObject({
+      Authorization: 'Bearer abc',
+      'Content-Type': 'application/json',
+    });
+    expect(init?.body).toBe(JSON.stringify({ hashes: ['h1'] }));
+  });
+
+  it('throws BackupHttpError on non-2xx with status preserved', async () => {
+    const fetchStub = makeFetchStub({ status: 403, statusText: 'Forbidden', body: { message: 'nope' } });
+    const client = new BackupHttpClient({
+      baseUrl: 'https://api.example.com',
+      authHeader: 'Bearer x',
+      agentId: 'a',
+      fetch: fetchStub as any,
+    });
+    await expect(client.getManifest()).rejects.toBeInstanceOf(BackupHttpError);
+    try {
+      await client.getManifest();
+      throw new Error('unreachable');
+    } catch (err) {
+      expect(err).toBeInstanceOf(BackupHttpError);
+      expect((err as BackupHttpError).status).toBe(403);
+    }
+  });
+
+  it('returns parsed JSON for saveManifest', async () => {
+    const fetchStub = makeFetchStub({
+      status: 200,
+      body: {
+        agentId: 'a',
+        orgId: 'o',
+        projectHash: 'p',
+        fileCount: 1,
+        totalSize: 10,
+        createdBy: 'cli',
+        createdAt: '2026-05-12T00:00:00Z',
+        activeVersion: 7,
+      },
+    });
+    const client = new BackupHttpClient({
+      baseUrl: 'https://api.example.com',
+      authHeader: 'Bearer x',
+      agentId: 'a',
+      fetch: fetchStub as any,
+    });
+    const meta = await client.saveManifest({ projectHash: 'p', files: [] });
+    expect(meta.activeVersion).toBe(7);
+  });
+});

package/node_modules/@lua/shared-source-sync/tests/push.test.ts

@@ -0,0 +1,162 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { gunzipSync } from 'zlib';
+import { pushAgentBackup } from '../src/push';
+
+type Fetch = ReturnType<typeof vi.fn>;
+
+function makeFakeServerAndS3() {
+  // Track S3 PUT bodies keyed by URL (we use the URL as the "blob hash" surrogate).
+  const s3 = new Map<string, Buffer>();
+  let savedManifest: any = null;
+
+  const fetchStub: Fetch = vi.fn(async (url: string, init?: any) => {
+    if (url.includes('/backup/check-blobs')) {
+      const { hashes } = JSON.parse(init.body);
+      return {
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        text: async () =>
+          JSON.stringify({
+            missing: hashes, // pretend nothing exists yet
+            existing: [],
+            results: Object.fromEntries(hashes.map((h: string) => [h, false])),
+          }),
+      };
+    }
+    if (url.includes('/backup/blob-upload-urls')) {
+      const { hashes } = JSON.parse(init.body);
+      const urls: Record<string, string> = {};
+      for (const h of hashes) urls[h] = `https://s3.example/${h}`;
+      return {
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        text: async () => JSON.stringify({ urls, expiresIn: 3600 }),
+      };
+    }
+    if (url.startsWith('https://s3.example/')) {
+      // S3 PUT
+      const hash = url.replace('https://s3.example/', '');
+      s3.set(hash, Buffer.from(init.body));
+      return { ok: true, status: 200, statusText: 'OK', text: async () => '' };
+    }
+    if (url.includes('/backup/manifest')) {
+      savedManifest = JSON.parse(init.body);
+      return {
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        text: async () =>
+          JSON.stringify({
+            agentId: 'a',
+            orgId: 'o',
+            projectHash: savedManifest.projectHash,
+            fileCount: savedManifest.files.length,
+            totalSize: 0,
+            createdBy: savedManifest.createdBy,
+            createdAt: '2026-05-12T00:00:00Z',
+            activeVersion: 1,
+          }),
+      };
+    }
+    throw new Error(`unexpected URL: ${url}`);
+  });
+
+  return { fetchStub, s3, getSavedManifest: () => savedManifest };
+}
+
+describe('pushAgentBackup', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'shared-source-sync-push-'));
+  });
+  afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+  it('walks workspace, uploads gzipped blobs, saves manifest', async () => {
+    mkdirSync(join(dir, 'src'), { recursive: true });
+    writeFileSync(join(dir, 'src/index.ts'), 'export const x = 1;');
+    writeFileSync(join(dir, 'lua.skill.yaml'), 'agent: {agentId: a}');
+
+    const { fetchStub, s3, getSavedManifest } = makeFakeServerAndS3();
+    const result = await pushAgentBackup({
+      http: {
+        baseUrl: 'https://api.example.com',
+        authHeader: 'Bearer test',
+        agentId: 'a',
+        fetch: fetchStub as any,
+      },
+      workspaceDir: dir,
+      orgId: 'o',
+      triggeredBy: 'unit-test',
+    });
+
+    expect(result.fileCount).toBe(2);
+    expect(result.filesUploaded).toBe(2);
+    expect(result.activeVersion).toBe(1);
+
+    // Manifest was saved with both files
+    const manifest = getSavedManifest();
+    const paths = manifest.files.map((f: any) => f.relativePath).sort();
+    expect(paths).toEqual(['lua.skill.yaml', 'src/index.ts']);
+    expect(manifest.orgId).toBe('o');
+    expect(manifest.triggeredBy).toBe('unit-test');
+    expect(manifest.createdBy).toBe('cli');
+
+    // S3 received gzipped content
+    expect(s3.size).toBe(2);
+    for (const buf of s3.values()) {
+      // Magic bytes for gzip
+      expect(buf[0]).toBe(0x1f);
+      expect(buf[1]).toBe(0x8b);
+      // Decompress to verify it's the original
+      const decoded = gunzipSync(buf).toString('utf-8');
+      expect(['export const x = 1;', 'agent: {agentId: a}']).toContain(decoded);
+    }
+  });
+
+  it('skips upload when server reports all blobs already exist', async () => {
+    writeFileSync(join(dir, 'a.ts'), 'x');
+    const fetchStub: Fetch = vi.fn(async (url: string, init?: any) => {
+      if (url.includes('/check-blobs')) {
+        return {
+          ok: true,
+          status: 200,
+          statusText: 'OK',
+          text: async () => JSON.stringify({ missing: [], existing: ['h'], results: {} }),
+        };
+      }
+      if (url.includes('/manifest')) {
+        return {
+          ok: true,
+          status: 200,
+          statusText: 'OK',
+          text: async () =>
+            JSON.stringify({
+              agentId: 'a',
+              orgId: 'o',
+              projectHash: 'p',
+              fileCount: 1,
+              totalSize: 1,
+              createdBy: 'cli',
+              createdAt: 'now',
+              activeVersion: 2,
+            }),
+        };
+      }
+      throw new Error(`unexpected URL ${url}`);
+    });
+
+    const result = await pushAgentBackup({
+      http: { baseUrl: 'https://api.example.com', authHeader: 'Bearer x', agentId: 'a', fetch: fetchStub as any },
+      workspaceDir: dir,
+      orgId: 'o',
+    });
+    expect(result.filesUploaded).toBe(0);
+    expect(result.activeVersion).toBe(2);
+  });
+});

package/node_modules/@lua/shared-source-sync/tests/walk.test.ts

@@ -0,0 +1,84 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { walkWorkspace } from '../src/walk';
+
+describe('walkWorkspace', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'shared-source-sync-walk-'));
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('includes source files and excludes node_modules / dist / dotfiles / tests', () => {
+    mkdirSync(join(dir, 'src'), { recursive: true });
+    mkdirSync(join(dir, 'node_modules'), { recursive: true });
+    mkdirSync(join(dir, 'dist-v2'), { recursive: true });
+    mkdirSync(join(dir, '__tests__'), { recursive: true });
+    writeFileSync(join(dir, 'src/index.ts'), 'export const a = 1;');
+    writeFileSync(join(dir, 'src/util.ts'), 'export const b = 2;');
+    writeFileSync(join(dir, 'lua.skill.yaml'), 'agent:\n  agentId: foo');
+    writeFileSync(join(dir, 'node_modules/x.ts'), 'dropme');
+    writeFileSync(join(dir, 'dist-v2/out.js'), 'dropme');
+    writeFileSync(join(dir, '__tests__/x.test.ts'), 'dropme');
+    writeFileSync(join(dir, '.eslintrc'), 'dropme');
+    writeFileSync(join(dir, 'package-lock.json'), 'dropme');
+
+    const result = walkWorkspace(dir);
+    const paths = result.files.map((f) => f.relativePath).sort();
+    expect(paths).toEqual(['lua.skill.yaml', 'src/index.ts', 'src/util.ts']);
+  });
+
+  it('dedupes identical content by hash (contentByHash has one entry per unique hash)', () => {
+    writeFileSync(join(dir, 'a.ts'), 'same content');
+    writeFileSync(join(dir, 'b.ts'), 'same content');
+    const result = walkWorkspace(dir);
+    expect(result.files).toHaveLength(2);
+    expect(result.contentByHash.size).toBe(1);
+    expect(result.files[0].hash).toBe(result.files[1].hash);
+  });
+
+  it('normalizes path separators to forward slashes', () => {
+    mkdirSync(join(dir, 'src', 'sub'), { recursive: true });
+    writeFileSync(join(dir, 'src/sub/x.ts'), 'x');
+    const result = walkWorkspace(dir);
+    expect(result.files[0].relativePath).toBe('src/sub/x.ts');
+  });
+
+  it('produces stable projectHash for identical input', () => {
+    writeFileSync(join(dir, 'a.ts'), 'a');
+    writeFileSync(join(dir, 'b.ts'), 'b');
+    const r1 = walkWorkspace(dir);
+    const r2 = walkWorkspace(dir);
+    expect(r1.projectHash).toBe(r2.projectHash);
+  });
+
+  it('respects maxFileBytes', () => {
+    writeFileSync(join(dir, 'big.ts'), 'x'.repeat(2048));
+    writeFileSync(join(dir, 'small.ts'), 'x');
+    const result = walkWorkspace(dir, { maxFileBytes: 1024 });
+    expect(result.files.map((f) => f.relativePath)).toEqual(['small.ts']);
+  });
+
+  // Regression pin: PR #402 round-3 Bugbot review caught that adding `build`
+  // to the shared SKIP_DIRECTORIES set silently broke the CLI compiler's
+  // primitive scan and the per-agent backup walker. The archive encoder
+  // owns its own ARCHIVE_ONLY_SKIP_DIRECTORIES set for that purpose;
+  // `walkWorkspace` (consumed by `buildManifestFromDisk` for `lua push
+  // backup --fresh` AND re-exported as `shouldSkipDirectory` to the CLI
+  // compiler) MUST keep `build/` source visible. Developers with custom
+  // Vite/Next/etc. layouts depend on it.
+  it('does NOT skip `build/` — only the archive encoder excludes it, not the walker', () => {
+    mkdirSync(join(dir, 'build'), { recursive: true });
+    writeFileSync(join(dir, 'build/keep.ts'), 'export const x = 1;');
+    writeFileSync(join(dir, 'src.ts'), 'export const y = 2;');
+    const result = walkWorkspace(dir);
+    const paths = result.files.map((f) => f.relativePath).sort();
+    expect(paths).toEqual(['build/keep.ts', 'src.ts']);
+  });
+});

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

@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "strict": false,
+    "noImplicitAny": false,
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  },
+  "include": ["src/**/*"]
+}

package/node_modules/@lua/shared-source-sync/tsup.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  dts: true,
+  clean: true,
+  splitting: false,
+});