takos-control 1.0.0

package/src/application/services/git-smart/core/refs.ts

@@ -0,0 +1,364 @@
+/**
+ * Git ref management (branches & tags) — D1 with Drizzle + fallback.
+ *
+ * Adapted from git-store/refs.ts with SHA-1 (40-char) validation.
+ */
+
+import type { D1Database } from '../../../../shared/types/bindings.ts';
+import type { SelectOf } from '../../../../shared/types/drizzle-helpers';
+import type { GitBranch, GitTag, RefUpdateResult } from '../git-objects';
+import { SHA1_PATTERN } from '../git-objects';
+import { getDb, branches, tags } from '../../../../infra/db';
+import { eq, and, desc, asc } from 'drizzle-orm';
+import { generateId, now, toIsoString } from '../../../../shared/utils';
+import { isInvalidArrayBufferError } from '../../../../shared/utils/db-guards';
+
+const MAX_REPO_ID_LENGTH = 128;
+const REPO_ID_PATTERN = /^[a-z0-9_-]+$/i;
+const MAX_REF_NAME_LENGTH = 255;
+const ASCII_PRINTABLE_PATTERN = /^[\x21-\x7E]+$/;
+const INVALID_REF_CHARS_PATTERN = /[~^:?*[\\]/;
+// Accept both SHA-1 (40) and legacy SHA-256 (64) for backward compat during migration
+const COMMIT_SHA_PATTERN = /^[a-f0-9]{40}([a-f0-9]{24})?$/i;
+
+const BRANCH_COLUMNS = `id, repo_id, name, commit_sha, is_default, is_protected, created_at, updated_at`;
+const TAG_COLUMNS = `id, repo_id, name, commit_sha, message, tagger_name, tagger_email, created_at`;
+
+type D1BranchRow = {
+  id: string; repo_id: string; name: string; commit_sha: string;
+  is_default: number; is_protected: number; created_at: string; updated_at: string;
+};
+
+type D1TagRow = {
+  id: string; repo_id: string; name: string; commit_sha: string;
+  message: string | null; tagger_name: string | null; tagger_email: string | null; created_at: string;
+};
+
+async function withDrizzleFallback<T>(
+  drizzleOp: () => Promise<T>,
+  fallbackOp: () => Promise<T>,
+): Promise<T> {
+  try {
+    return await drizzleOp();
+  } catch (error) {
+    // Fall back to D1 raw queries for Drizzle adapter issues:
+    // - Invalid array buffer length (large payload)
+    // - D1 transient errors (SQLITE_BUSY, timeout)
+    if (
+      isInvalidArrayBufferError(error) ||
+      (error instanceof Error && (
+        error.message.includes('SQLITE_BUSY') ||
+        error.message.includes('D1_ERROR') ||
+        error.message.includes('database is locked')
+      ))
+    ) {
+      return fallbackOp();
+    }
+    throw error;
+  }
+}
+
+function toBranch(row: D1BranchRow): GitBranch {
+  return {
+    id: row.id, repo_id: row.repo_id, name: row.name, commit_sha: row.commit_sha,
+    is_default: !!row.is_default, is_protected: !!row.is_protected,
+    created_at: row.created_at, updated_at: row.updated_at,
+  };
+}
+
+function branchFromDrizzle(b: SelectOf<typeof branches>): GitBranch {
+  return {
+    id: b.id, repo_id: b.repoId, name: b.name, commit_sha: b.commitSha,
+    is_default: b.isDefault, is_protected: b.isProtected,
+    created_at: toIsoString(b.createdAt), updated_at: toIsoString(b.updatedAt),
+  };
+}
+
+function toTag(row: D1TagRow): GitTag {
+  return {
+    id: row.id, repo_id: row.repo_id, name: row.name, commit_sha: row.commit_sha,
+    message: row.message, tagger_name: row.tagger_name, tagger_email: row.tagger_email,
+    created_at: row.created_at,
+  };
+}
+
+function tagFromDrizzle(t: SelectOf<typeof tags>): GitTag {
+  return {
+    id: t.id, repo_id: t.repoId, name: t.name, commit_sha: t.commitSha,
+    message: t.message, tagger_name: t.taggerName, tagger_email: t.taggerEmail,
+    created_at: toIsoString(t.createdAt),
+  };
+}
+
+function isValidRepoId(repoId: unknown): repoId is string {
+  if (typeof repoId !== 'string') return false;
+  const v = repoId.trim();
+  return !!v && v.length <= MAX_REPO_ID_LENGTH && REPO_ID_PATTERN.test(v);
+}
+
+export function isValidRefName(name: unknown): name is string {
+  if (typeof name !== 'string') return false;
+  const v = name.trim();
+  if (!v || v.length > MAX_REF_NAME_LENGTH) return false;
+  if (!ASCII_PRINTABLE_PATTERN.test(v)) return false;
+  if (INVALID_REF_CHARS_PATTERN.test(v)) return false;
+  if (v.includes('..') || v.includes('@{')) return false;
+  if (v.endsWith('.') || v.endsWith('.lock')) return false;
+  if (v.startsWith('/') || v.endsWith('/') || v.includes('//')) return false;
+  return true;
+}
+
+function isValidCommitSha(sha: unknown): sha is string {
+  return typeof sha === 'string' && COMMIT_SHA_PATTERN.test(sha);
+}
+
+export async function getBranch(dbBinding: D1Database, repoId: string, name: string): Promise<GitBranch | null> {
+  if (!isValidRepoId(repoId) || !isValidRefName(name)) return null;
+  const db = getDb(dbBinding);
+  return withDrizzleFallback(
+    async () => {
+      const row = await db.select().from(branches)
+        .where(and(eq(branches.repoId, repoId), eq(branches.name, name)))
+        .get();
+      return row ? branchFromDrizzle(row) : null;
+    },
+    async () => {
+      const row = await dbBinding.prepare(`SELECT ${BRANCH_COLUMNS} FROM branches WHERE repo_id = ? AND name = ? LIMIT 1`)
+        .bind(repoId, name).first<D1BranchRow>();
+      return row ? toBranch(row) : null;
+    },
+  );
+}
+
+export async function getDefaultBranch(dbBinding: D1Database, repoId: string): Promise<GitBranch | null> {
+  if (!isValidRepoId(repoId)) return null;
+  const db = getDb(dbBinding);
+  return withDrizzleFallback(
+    async () => {
+      const row = await db.select().from(branches)
+        .where(and(eq(branches.repoId, repoId), eq(branches.isDefault, true)))
+        .get();
+      return row ? branchFromDrizzle(row) : null;
+    },
+    async () => {
+      const row = await dbBinding.prepare(`SELECT ${BRANCH_COLUMNS} FROM branches WHERE repo_id = ? AND is_default = 1 LIMIT 1`)
+        .bind(repoId).first<D1BranchRow>();
+      return row ? toBranch(row) : null;
+    },
+  );
+}
+
+export async function listBranches(dbBinding: D1Database, repoId: string): Promise<GitBranch[]> {
+  if (!isValidRepoId(repoId)) return [];
+  const db = getDb(dbBinding);
+  return withDrizzleFallback(
+    async () => {
+      const rows = await db.select().from(branches)
+        .where(eq(branches.repoId, repoId))
+        .orderBy(desc(branches.isDefault), asc(branches.name))
+        .all();
+      return rows.map(branchFromDrizzle);
+    },
+    async () => {
+      const result = await dbBinding.prepare(`SELECT ${BRANCH_COLUMNS} FROM branches WHERE repo_id = ? ORDER BY is_default DESC, name ASC`)
+        .bind(repoId).all<D1BranchRow>();
+      return result.results.map(toBranch);
+    },
+  );
+}
+
+export async function createBranch(
+  dbBinding: D1Database, repoId: string, name: string, commitSha: string, isDefault = false,
+): Promise<RefUpdateResult> {
+  if (!isValidRepoId(repoId) || !isValidRefName(name)) return { success: false, error: 'Invalid branch name' };
+  if (!isValidCommitSha(commitSha)) return { success: false, error: 'Invalid commit SHA' };
+
+  const db = getDb(dbBinding);
+  const id = generateId();
+  const timestamp = now();
+
+  try {
+    await db.insert(branches).values({
+      id, repoId, name, commitSha, isDefault, isProtected: false, createdAt: timestamp, updatedAt: timestamp,
+    });
+    return { success: true };
+  } catch {
+    const existing = await getBranch(dbBinding, repoId, name);
+    if (existing) return { success: false, current: existing.commit_sha, error: 'Branch already exists' };
+    throw new Error('Failed to create branch');
+  }
+}
+
+export async function updateBranch(
+  dbBinding: D1Database, repoId: string, name: string, oldSha: string | null, newSha: string,
+): Promise<RefUpdateResult> {
+  if (!isValidRepoId(repoId) || !isValidRefName(name)) return { success: false, error: 'Invalid branch name' };
+  if ((oldSha !== null && !isValidCommitSha(oldSha)) || !isValidCommitSha(newSha)) return { success: false, error: 'Invalid commit SHA' };
+
+  if (oldSha === null) return createBranch(dbBinding, repoId, name, newSha);
+
+  const db = getDb(dbBinding);
+  const timestamp = now();
+  const result = await db.update(branches)
+    .set({ commitSha: newSha, updatedAt: timestamp })
+    .where(and(eq(branches.repoId, repoId), eq(branches.name, name), eq(branches.commitSha, oldSha)))
+    .returning()
+    .all();
+
+  if (result.length === 0) {
+    const current = await getBranch(dbBinding, repoId, name);
+    if (!current) return { success: false, error: 'Branch not found' };
+    return { success: false, current: current.commit_sha, error: 'Ref conflict: branch was modified by another process' };
+  }
+
+  return { success: true };
+}
+
+export async function deleteBranch(dbBinding: D1Database, repoId: string, name: string): Promise<RefUpdateResult> {
+  if (!isValidRepoId(repoId) || !isValidRefName(name)) return { success: false, error: 'Invalid branch name' };
+
+  const branch = await getBranch(dbBinding, repoId, name);
+  if (!branch) return { success: false, error: 'Branch not found' };
+  if (branch.is_default) return { success: false, error: 'Cannot delete default branch' };
+  if (branch.is_protected) return { success: false, error: 'Cannot delete protected branch' };
+
+  const db = getDb(dbBinding);
+  await db.delete(branches).where(and(eq(branches.repoId, repoId), eq(branches.name, name)));
+  return { success: true };
+}
+
+export async function setDefaultBranch(dbBinding: D1Database, repoId: string, name: string): Promise<RefUpdateResult> {
+  if (!isValidRepoId(repoId) || !isValidRefName(name)) return { success: false, error: 'Invalid branch name' };
+
+  const branch = await getBranch(dbBinding, repoId, name);
+  if (!branch) return { success: false, error: 'Branch not found' };
+
+  const db = getDb(dbBinding);
+  await db.update(branches).set({ isDefault: false }).where(eq(branches.repoId, repoId));
+  await db.update(branches).set({ isDefault: true }).where(and(eq(branches.repoId, repoId), eq(branches.name, name)));
+  return { success: true };
+}
+
+export async function getTag(dbBinding: D1Database, repoId: string, name: string): Promise<GitTag | null> {
+  if (!isValidRepoId(repoId) || !isValidRefName(name)) return null;
+  const db = getDb(dbBinding);
+  return withDrizzleFallback(
+    async () => {
+      const row = await db.select().from(tags)
+        .where(and(eq(tags.repoId, repoId), eq(tags.name, name)))
+        .get();
+      return row ? tagFromDrizzle(row) : null;
+    },
+    async () => {
+      const row = await dbBinding.prepare(`SELECT ${TAG_COLUMNS} FROM tags WHERE repo_id = ? AND name = ? LIMIT 1`)
+        .bind(repoId, name).first<D1TagRow>();
+      return row ? toTag(row) : null;
+    },
+  );
+}
+
+export async function listTags(dbBinding: D1Database, repoId: string): Promise<GitTag[]> {
+  if (!isValidRepoId(repoId)) return [];
+  const db = getDb(dbBinding);
+  return withDrizzleFallback(
+    async () => {
+      const rows = await db.select().from(tags)
+        .where(eq(tags.repoId, repoId))
+        .orderBy(desc(tags.createdAt))
+        .all();
+      return rows.map(tagFromDrizzle);
+    },
+    async () => {
+      const result = await dbBinding.prepare(`SELECT ${TAG_COLUMNS} FROM tags WHERE repo_id = ? ORDER BY created_at DESC`)
+        .bind(repoId).all<D1TagRow>();
+      return result.results.map(toTag);
+    },
+  );
+}
+
+export async function createTag(
+  dbBinding: D1Database, repoId: string, name: string, commitSha: string,
+  message?: string, taggerName?: string, taggerEmail?: string,
+): Promise<RefUpdateResult> {
+  if (!isValidRepoId(repoId) || !isValidRefName(name)) return { success: false, error: 'Invalid tag name' };
+  if (!isValidCommitSha(commitSha)) return { success: false, error: 'Invalid commit SHA' };
+
+  const existing = await getTag(dbBinding, repoId, name);
+  if (existing) return { success: false, current: existing.commit_sha, error: 'Tag already exists' };
+
+  const db = getDb(dbBinding);
+  const id = generateId();
+  const timestamp = now();
+
+  try {
+    await db.insert(tags).values({
+      id, repoId, name, commitSha,
+      message: message || null, taggerName: taggerName || null, taggerEmail: taggerEmail || null,
+      createdAt: timestamp,
+    });
+    return { success: true };
+  } catch {
+    const existingNow = await getTag(dbBinding, repoId, name);
+    if (existingNow) return { success: false, current: existingNow.commit_sha, error: 'Tag already exists' };
+    throw new Error('Failed to create tag');
+  }
+}
+
+export async function deleteTag(dbBinding: D1Database, repoId: string, name: string): Promise<RefUpdateResult> {
+  if (!isValidRepoId(repoId) || !isValidRefName(name)) return { success: false, error: 'Invalid tag name' };
+
+  const tag = await getTag(dbBinding, repoId, name);
+  if (!tag) return { success: false, error: 'Tag not found' };
+
+  const db = getDb(dbBinding);
+  await db.delete(tags).where(and(eq(tags.repoId, repoId), eq(tags.name, name)));
+  return { success: true };
+}
+
+export async function resolveRef(dbBinding: D1Database, repoId: string, ref: string): Promise<string | null> {
+  if (!isValidRepoId(repoId) || !isValidRefName(ref)) return null;
+
+  let branch = await getBranch(dbBinding, repoId, ref);
+  if (branch) return branch.commit_sha;
+
+  const tag = await getTag(dbBinding, repoId, ref);
+  if (tag) return tag.commit_sha;
+
+  if (ref.startsWith('refs/heads/')) {
+    branch = await getBranch(dbBinding, repoId, ref.slice('refs/heads/'.length));
+    return branch?.commit_sha || null;
+  }
+  if (ref.startsWith('refs/remotes/')) {
+    branch = await getBranch(dbBinding, repoId, ref.slice('refs/'.length));
+    return branch?.commit_sha || null;
+  }
+  if (ref.startsWith('refs/tags/')) {
+    const t = await getTag(dbBinding, repoId, ref.slice('refs/tags/'.length));
+    return t?.commit_sha || null;
+  }
+
+  if (isValidCommitSha(ref)) return ref;
+  return null;
+}
+
+export async function listAllRefs(
+  dbBinding: D1Database, repoId: string,
+): Promise<Array<{ name: string; target: string; type: 'branch' | 'tag' | 'remote' }>> {
+  const [branchList, tagList] = await Promise.all([listBranches(dbBinding, repoId), listTags(dbBinding, repoId)]);
+
+  return [
+    ...branchList.map(b => {
+      const isRemote = b.name.startsWith('remotes/');
+      return {
+        name: isRemote ? `refs/${b.name}` : `refs/heads/${b.name}`,
+        target: b.commit_sha,
+        type: (isRemote ? 'remote' : 'branch') as 'branch' | 'tag' | 'remote',
+      };
+    }),
+    ...tagList.map(t => ({
+      name: `refs/tags/${t.name}`,
+      target: t.commit_sha,
+      type: 'tag' as const,
+    })),
+  ];
+}

package/src/application/services/git-smart/core/sha1.ts

@@ -0,0 +1,40 @@
+/**
+ * SHA-1 hashing using Web Crypto API (crypto.subtle).
+ * Used for standard git object ID computation.
+ */
+
+import {
+  bytesToHex,
+  hexToBytes,
+} from '../../../../shared/utils/encoding-utils';
+
+function toBufferSource(bytes: Uint8Array): ArrayBuffer {
+  return bytes.slice().buffer as ArrayBuffer;
+}
+
+export async function sha1(data: Uint8Array): Promise<string> {
+  const hashBuffer = await crypto.subtle.digest('SHA-1', toBufferSource(data));
+  return hexFromBuffer(hashBuffer);
+}
+
+export function sha1Bytes(data: Uint8Array): Promise<ArrayBuffer> {
+  return crypto.subtle.digest('SHA-1', toBufferSource(data));
+}
+
+export function hexFromBuffer(buffer: ArrayBuffer): string {
+  return bytesToHex(new Uint8Array(buffer));
+}
+
+export { hexToBytes };
+
+export function concatBytes(...arrays: Uint8Array[]): Uint8Array {
+  let totalLength = 0;
+  for (const arr of arrays) totalLength += arr.length;
+  const result = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const arr of arrays) {
+    result.set(arr, offset);
+    offset += arr.length;
+  }
+  return result;
+}

package/src/application/services/git-smart/core/tree-ops.ts

@@ -0,0 +1,228 @@
+/**
+ * Tree operations — navigate, flatten, build, and apply changes.
+ *
+ * Adapted from git-store/tree.ts for native git tree format.
+ */
+
+import type { R2Bucket } from '../../../../shared/types/bindings.ts';
+import type { TreeEntry } from '../git-objects';
+import { FILE_MODES } from '../git-objects';
+import { putTree, putBlob, getTreeEntries, getBlob } from './object-store';
+
+const DEFAULT_MAX_FLATTEN_DEPTH = 50;
+const DEFAULT_MAX_FLATTEN_ENTRIES = 100000;
+const MAX_GIT_PATH_LENGTH = 4096;
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHAR_PATTERN = /[\x00-\x1F\x7F]/;
+
+function isValidGitPathSegment(segment: string): boolean {
+  return !(!segment || segment === '.' || segment === '..' || segment.includes('\0') || CONTROL_CHAR_PATTERN.test(segment));
+}
+
+export function isValidGitPath(path: string): boolean {
+  if (typeof path !== 'string') return false;
+  if (path.length === 0 || path.length > MAX_GIT_PATH_LENGTH) return false;
+  if (path.includes('\0') || CONTROL_CHAR_PATTERN.test(path)) return false;
+  if (path.startsWith('/') || path.endsWith('/') || path.includes('\\') || path.includes('//')) return false;
+  const segments = path.split('/');
+  return segments.length > 0 && segments.every(isValidGitPathSegment);
+}
+
+export function assertValidGitPath(path: string): string {
+  const normalized = path.trim();
+  if (!isValidGitPath(normalized)) throw new Error(`Invalid git path: ${path}`);
+  return normalized;
+}
+
+export async function createTree(bucket: R2Bucket, entries: TreeEntry[]): Promise<string> {
+  return putTree(bucket, entries);
+}
+
+export async function getTree(
+  bucket: R2Bucket, sha: string,
+): Promise<{ sha: string; entries: TreeEntry[] } | null> {
+  const entries = await getTreeEntries(bucket, sha);
+  if (!entries) return null;
+  return { sha, entries };
+}
+
+export async function getEntryAtPath(
+  bucket: R2Bucket, rootTreeSha: string, path: string,
+): Promise<(TreeEntry & { type: 'blob' | 'tree' }) | null> {
+  const normalizedPath = path.replace(/^\/+|\/+$/g, '');
+  if (!normalizedPath) {
+    return { mode: FILE_MODES.DIRECTORY, name: '', sha: rootTreeSha, type: 'tree' } as TreeEntry & { type: 'blob' | 'tree' };
+  }
+
+  const parts = normalizedPath.split('/');
+  let currentTreeSha = rootTreeSha;
+
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i];
+    const isLast = i === parts.length - 1;
+
+    const entries = await getTreeEntries(bucket, currentTreeSha);
+    if (!entries) return null;
+
+    const entry = entries.find(e => e.name === part);
+    if (!entry) return null;
+
+    const isDir = entry.mode === '040000' || entry.mode === '40000';
+    const entryType: 'blob' | 'tree' = isDir ? 'tree' : 'blob';
+
+    if (isLast) return { ...entry, type: entryType };
+    if (!isDir) return null;
+
+    currentTreeSha = entry.sha;
+  }
+
+  return null;
+}
+
+export async function listDirectory(
+  bucket: R2Bucket, rootTreeSha: string, path = '',
+): Promise<TreeEntry[] | null> {
+  const entry = await getEntryAtPath(bucket, rootTreeSha, path);
+  if (!entry || entry.type !== 'tree') return null;
+  return getTreeEntries(bucket, entry.sha);
+}
+
+export async function getBlobAtPath(
+  bucket: R2Bucket, rootTreeSha: string, path: string,
+): Promise<Uint8Array | null> {
+  const entry = await getEntryAtPath(bucket, rootTreeSha, path);
+  if (!entry || entry.type !== 'blob' || entry.mode === FILE_MODES.SYMLINK) return null;
+  return getBlob(bucket, entry.sha);
+}
+
+export async function buildTreeFromPaths(
+  bucket: R2Bucket,
+  files: Array<{ path: string; sha: string; mode?: string }>,
+): Promise<string> {
+  interface TreeNode {
+    entries: Map<string, TreeEntry | TreeNode>;
+  }
+
+  const root: TreeNode = { entries: new Map() };
+
+  for (const file of files) {
+    const validPath = assertValidGitPath(file.path);
+    const parts = validPath.split('/');
+    let current = root;
+
+    for (let i = 0; i < parts.length - 1; i++) {
+      const part = parts[i];
+      if (!current.entries.has(part)) {
+        current.entries.set(part, { entries: new Map() });
+      }
+      const next = current.entries.get(part);
+      if (!next || !('entries' in next)) throw new Error(`Path conflict at ${parts.slice(0, i + 1).join('/')}`);
+      current = next;
+    }
+
+    const fileName = parts[parts.length - 1];
+    current.entries.set(fileName, {
+      mode: file.mode || FILE_MODES.REGULAR_FILE,
+      name: fileName,
+      sha: file.sha,
+    });
+  }
+
+  async function createTreeFromNode(node: TreeNode): Promise<string> {
+    const entries: TreeEntry[] = [];
+
+    for (const [name, child] of node.entries) {
+      if ('entries' in child && child.entries instanceof Map) {
+        const subtreeSha = await createTreeFromNode(child as TreeNode);
+        entries.push({ mode: FILE_MODES.DIRECTORY, name, sha: subtreeSha });
+      } else {
+        entries.push(child as TreeEntry);
+      }
+    }
+
+    return createTree(bucket, entries);
+  }
+
+  return createTreeFromNode(root);
+}
+
+export async function applyTreeChanges(
+  bucket: R2Bucket,
+  baseTreeSha: string,
+  changes: Array<{
+    path: string;
+    operation: 'add' | 'modify' | 'delete';
+    sha?: string;
+    mode?: string;
+  }>,
+): Promise<string> {
+  const files = await flattenTree(bucket, baseTreeSha);
+  const fileMap = new Map(files.map(f => [f.path, f]));
+
+  for (const change of changes) {
+    if (change.operation === 'delete') {
+      fileMap.delete(change.path);
+    } else {
+      if (!change.sha) throw new Error(`SHA required for ${change.operation} operation`);
+      fileMap.set(change.path, { path: change.path, sha: change.sha, mode: change.mode || FILE_MODES.REGULAR_FILE });
+    }
+  }
+
+  return buildTreeFromPaths(bucket, Array.from(fileMap.values()));
+}
+
+export async function flattenTree(
+  bucket: R2Bucket,
+  treeSha: string,
+  basePath = '',
+  options?: { maxDepth?: number; maxEntries?: number; skipSymlinks?: boolean },
+): Promise<Array<{ path: string; sha: string; mode: string }>> {
+  const maxDepth = options?.maxDepth ?? DEFAULT_MAX_FLATTEN_DEPTH;
+  const maxEntries = options?.maxEntries ?? DEFAULT_MAX_FLATTEN_ENTRIES;
+  const skipSymlinks = options?.skipSymlinks ?? false;
+
+  const files: Array<{ path: string; sha: string; mode: string }> = [];
+  const counters = { entries: 0 };
+  const visited = new Set<string>();
+
+  async function walk(currentTreeSha: string, currentBasePath: string, depth: number): Promise<void> {
+    if (depth > maxDepth) throw new Error(`Tree flatten depth limit exceeded (max ${maxDepth})`);
+    if (visited.has(currentTreeSha)) return; // Prevent circular reference loops
+    visited.add(currentTreeSha);
+
+    const entries = await getTreeEntries(bucket, currentTreeSha);
+    if (!entries) return;
+
+    for (const entry of entries) {
+      counters.entries++;
+      if (counters.entries > maxEntries) throw new Error(`Tree flatten entry limit exceeded (max ${maxEntries})`);
+
+      const fullPath = currentBasePath ? `${currentBasePath}/${entry.name}` : entry.name;
+      const isDir = entry.mode === '040000' || entry.mode === '40000';
+
+      if (isDir) {
+        await walk(entry.sha, fullPath, depth + 1);
+      } else {
+        if (entry.mode === FILE_MODES.SYMLINK) {
+          if (skipSymlinks) continue;
+          throw new Error(`Symlink blob entries are not supported: ${fullPath}`);
+        }
+        files.push({ path: fullPath, sha: entry.sha, mode: entry.mode });
+      }
+    }
+  }
+
+  await walk(treeSha, basePath, 0);
+  return files;
+}
+
+export async function createEmptyTree(bucket: R2Bucket): Promise<string> {
+  return createTree(bucket, []);
+}
+
+export async function createSingleFileTree(
+  bucket: R2Bucket, fileName: string, content: Uint8Array,
+): Promise<string> {
+  const blobSha = await putBlob(bucket, content);
+  return createTree(bucket, [{ mode: FILE_MODES.REGULAR_FILE, name: fileName, sha: blobSha }]);
+}