@tiinex/app 0.1.1

package/src/adapters/github/github.repoMirror.js

@@ -0,0 +1,255 @@
+import { createRecordFromMarkdown } from '@tiinex/core/artifacts/artifact.record.js';
+import { zipBufferToImportEntries } from '@tiinex/core/adapters/archive/archive.adapter.js';
+import { githubRawUrlForSourcePath, readGithubSourceCacheEntry, writeGithubSourceCacheEntry } from '../../sources/github/github.transport.js';
+import { governanceBoundaryFromRootFiles } from '@tiinex/core/governance/governance.boundary.js';
+
+const MARKDOWN_RE = /(?:\.md|\.markdown|\.trace\.md|\.schema\.md|\.validator\.md|\.workspace\.md)$/i;
+
+export async function materializeGithubRepoFilesFromSourceCache(source = {}, options = {}) {
+  const manifest = readRepoDiscoveryManifest(source, options);
+  if (!manifest?.refs?.length || !manifest.ref) return emptyRepoMirrorResult('cache', 'github.repo.cache.miss', 'No complete cached repo-file manifest was available for this source.');
+  const sourceForRaw = Object.assign({}, source, { ref: manifest.ref });
+  const records = [];
+  const missing = [];
+  for (const ref of manifest.refs || []) {
+    const rawUrl = githubRawUrlForSourcePath(sourceForRaw, ref);
+    const cached = readGithubSourceCacheEntry(rawUrl, 'raw-markdown', options);
+    if (!cached?.body) {
+      missing.push(ref);
+      continue;
+    }
+    records.push(recordFromRepoMarkdown(cached.body, sourceForRaw, ref, rawUrl, 'cache'));
+  }
+  if (!records.length || missing.length) {
+    return emptyRepoMirrorResult('cache', 'github.repo.cache.incomplete', `Cached repo-file material is incomplete (${records.length}/${manifest.refs.length} available).`, { missing });
+  }
+  return {
+    schema: 'tiinex.github.repoFiles.materialization.v1',
+    transportTier: 'cache',
+    ref: manifest.ref,
+    records,
+    warnings: [],
+    errors: [],
+    counts: { records: records.length, loaded: records.length, failed: 0, discovered: manifest.refs.length },
+    diagnostics: { manifestUrl: repoDiscoveryCacheUrl(sourceForRaw), transportEvents: [{ tier: 'cache', code: 'github.repo.cache.hit', severity: 'info', resource: 'repo-files', loaded: records.length }] }
+  };
+}
+
+export async function materializeGithubRepoFilesViaHostedMirror(source = {}, options = {}) {
+  const repoRaw = String(source.repo || source.repository || '').trim().replace(/^https?:\/\/github\.com\//i, '').replace(/\.git$/i, '').replace(/^\/+|\/+$/g, '').split('/').slice(0, 2).join('/');
+  const repo = normalizeRepo(repoRaw);
+  const fetchImpl = options.fetchImpl || (typeof fetch !== 'undefined' ? fetch : null);
+  if (!repo || !fetchImpl) return emptyRepoMirrorResult('mirror', 'github.repo.mirror.unavailable', 'Hosted repository mirror is unavailable without a repository and fetch implementation.');
+  const candidates = hostedRepoMirrorMetadataUrlCandidates(repo, options, repoRaw);
+  const errors = [];
+  for (const metadataUrl of candidates) {
+    try {
+      const meta = await fetchJson(metadataUrl, fetchImpl, 'mirror', options);
+      if (!repoMatches(meta, repo)) throw new Error(`Repository mirror metadata did not match ${repo}.`);
+      const archiveUrl = resolveArchiveUrl(metadataUrl, meta);
+      if (!archiveUrl) throw new Error('Repository mirror metadata did not contain an archive URL.');
+      const archiveBuffer = await fetchArrayBuffer(archiveUrl, fetchImpl, 'mirror', options);
+      const imported = await zipBufferToImportEntries(archiveBuffer, { source: 'github-repository-mirror', excludeRepositoryInternals: true });
+      const ref = String(meta.commit || meta.ref || source.ref || '').trim();
+      const sourceForRaw = Object.assign({}, source, { ref });
+      const roots = rootPaths(source);
+      const governanceRootFiles = governanceRootFilesFromMirrorEntries(imported.entries || [], sourceForRaw, meta);
+      for (const file of governanceRootFiles) {
+        if (file?.url && file?.text) await writeGithubSourceCacheEntry(file.url, file.text, 'text/markdown; charset=utf-8', 'raw-markdown', options);
+      }
+      const governanceBoundary = governanceBoundaryFromRootFiles(sourceForRaw, governanceRootFiles, { rootChecked: true, discoveredFrom: 'repo-mirror-archive' });
+      const records = [];
+      const refs = [];
+      for (const entry of imported.entries || []) {
+        const path = repoMirrorEntryPath(entry.path || '', meta, roots);
+        if (!path || typeof entry.content !== 'string') continue;
+        const rawUrl = githubRawUrlForSourcePath(sourceForRaw, path);
+        records.push(recordFromRepoMarkdown(entry.content, sourceForRaw, path, rawUrl, 'mirror'));
+        refs.push(path);
+        await writeGithubSourceCacheEntry(rawUrl, entry.content, 'text/markdown; charset=utf-8', 'raw-markdown', options);
+      }
+      refs.sort((a, b) => a.localeCompare(b));
+      if (records.length) await writeRepoDiscoveryManifest(sourceForRaw, refs, options);
+      return {
+        schema: 'tiinex.github.repoFiles.materialization.v1',
+        transportTier: 'mirror',
+        ref,
+        records,
+        warnings: imported.warnings || [],
+        errors: imported.errors || [],
+        counts: { records: records.length, loaded: records.length, failed: 0, discovered: refs.length },
+        diagnostics: { metadataUrl, archiveUrl, governanceBoundary, transportEvents: [{ tier: 'mirror', code: 'github.repo.mirror.ok', severity: 'info', url: metadataUrl, resource: 'repo-snapshot', loaded: records.length }] },
+        governanceBoundary
+      };
+    } catch (error) {
+      errors.push({ metadataUrl, message: error?.message || String(error || '') });
+    }
+  }
+  return emptyRepoMirrorResult('mirror', 'github.repo.mirror.unavailable', 'Hosted repository mirror did not materialize repo files.', { errors });
+}
+
+export async function writeGithubRepoDiscoveryCache(source = {}, refs = [], options = {}) {
+  return writeRepoDiscoveryManifest(source, refs, options);
+}
+
+function governanceRootFilesFromMirrorEntries(entries = [], source = {}, meta = {}) {
+  const out = [];
+  for (const entry of entries || []) {
+    const path = repoMirrorRootEntryPath(entry?.path || '', meta);
+    if (!path || typeof entry?.content !== 'string') continue;
+    out.push({ path, kind: path, text: entry.content, url: githubRawUrlForSourcePath(source, path) });
+  }
+  return out;
+}
+
+function repoMirrorRootEntryPath(path = '', meta = {}) {
+  const candidates = [stripArchivePrefix(path, meta), stripFirstArchiveSegment(path)];
+  for (const candidate of candidates) {
+    const clean = String(candidate || '').replace(/^\/+/, '').replace(/\\/g, '/');
+    if (clean && !clean.includes('/')) return clean;
+  }
+  return '';
+}
+
+function recordFromRepoMarkdown(markdown = '', source = {}, path = '', rawUrl = '', tier = '') {
+  const name = String(path || rawUrl).split('/').pop() || 'source.md';
+  return Object.assign(createRecordFromMarkdown(markdown, { path: rawUrl || path, name, sourceMode: 'github-source' }), {
+    sourceTarget: {
+      schema: 'tiinex.source.material.target.v1',
+      surface: 'repoFiles',
+      targetKind: tier === 'mirror' ? 'repo-mirror-markdown' : tier === 'cache' ? 'repo-cache-markdown' : 'repo-markdown',
+      inputTarget: path,
+      targetIndex: 0,
+      rawUrl,
+      sourceArtifactPath: path,
+      materializedCommit: /^[0-9a-f]{40}$/i.test(String(source.ref || '').trim()) ? String(source.ref || '').trim() : '',
+      transportTier: tier,
+      loaded: true
+    }
+  });
+}
+
+function emptyRepoMirrorResult(tier = '', code = '', message = '', extra = {}) {
+  return {
+    schema: 'tiinex.github.repoFiles.materialization.v1',
+    transportTier: tier,
+    records: [],
+    warnings: [{ code, severity: tier === 'cache' ? 'info' : 'warning', surface: 'repoFiles', transportTier: tier, message }],
+    errors: [],
+    counts: { records: 0, loaded: 0, failed: 0, discovered: 0 },
+    diagnostics: Object.assign({ transportEvents: [{ tier, code, severity: tier === 'cache' ? 'info' : 'warning', resource: 'repo-files', message }] }, extra || {})
+  };
+}
+
+function repoDiscoveryCacheUrl(source = {}) {
+  const repo = normalizeRepo(source.repo || source.repository || '');
+  const ref = String(source.ref || '').trim();
+  const roots = rootPaths(source).join(',') || '.topics';
+  return `tiinex://github-repo-discovery/${repo}?ref=${encodeURIComponent(ref)}&roots=${encodeURIComponent(roots)}`;
+}
+
+function readRepoDiscoveryManifest(source = {}, options = {}) {
+  const entry = readGithubSourceCacheEntry(repoDiscoveryCacheUrl(source), 'repo-discovery-json', options);
+  if (!entry?.body) return null;
+  try { return JSON.parse(entry.body); } catch (_) { return null; }
+}
+
+async function writeRepoDiscoveryManifest(source = {}, refs = [], options = {}) {
+  const manifest = { schema: 'tiinex.github.repoFiles.cache.v1', repo: normalizeRepo(source.repo || source.repository || ''), ref: String(source.ref || '').trim(), rootPath: source.rootPath || '', refs: Array.from(new Set((refs || []).filter(Boolean))).sort() };
+  if (!manifest.repo || !manifest.ref || !manifest.refs.length) return false;
+  return writeGithubSourceCacheEntry(repoDiscoveryCacheUrl(source), JSON.stringify(manifest), 'application/json', 'repo-discovery-json', options);
+}
+
+function hostedRepoMirrorMetadataUrlCandidates(repo = '', options = {}, rawRepo = '') {
+  const repoPaths = Array.from(new Set([rawRepo, repo].map((item) => String(item || '').replace(/^\/+|\/+$/g, '')).filter(Boolean)));
+
+  const bases = [];
+  const addBase = (value) => {
+    const clean = String(value || '').trim();
+    if (!clean) return;
+    try { bases.push(new URL(clean, typeof location !== 'undefined' ? location.href : 'https://example.invalid/').toString()); } catch (_) {}
+  };
+  (options.hostedRepoMirrorBaseUrls || options.repositoryMirrorBaseUrls || []).forEach(addBase);
+  if (typeof window !== 'undefined') addBase(window.TIINEX_VIEWER_OPTIONS?.publicBaseUrl || window.TIINEX_VIEWER_OPTIONS?.viewerBaseUrl || window.TIINEX_VIEWER_OPTIONS?.shareBaseUrl || '');
+  if (typeof location !== 'undefined' && location.origin) addBase(`${location.origin}/`);
+  const sourcePages = githubPagesDefaultBaseUrlForRepository(rawRepo || repo);
+  if (sourcePages) addBase(sourcePages);
+  const urls = [];
+  for (const base of bases) {
+    for (const repoPath of repoPaths) {
+      urls.push(new URL(`.mirrors/github.com/${repoPath}.json`, base).toString());
+      urls.push(new URL(`mirrors/github.com/${repoPath}.json`, base).toString());
+    }
+  }
+  return [...new Set(urls)];
+}
+
+function githubPagesDefaultBaseUrlForRepository(repo = '') {
+  const [owner, repository] = String(repo || '').split('/').filter(Boolean);
+  if (!owner || !repository) return '';
+  return `https://${owner.toLowerCase()}.github.io/${encodeURIComponent(repository)}/`;
+}
+
+async function fetchJson(url, fetchImpl, tier, options = {}) {
+  const cached = readGithubSourceCacheEntry(url, 'api-json', options);
+  if (cached?.body && options.cacheMode !== 'refresh') return JSON.parse(cached.body || '{}');
+  const res = await fetchImpl(url, { cache: 'no-cache', headers: { Accept: 'application/json,*/*' } });
+  if (!res?.ok) throw Object.assign(new Error(`Repository mirror metadata ${res?.status || 0} ${res?.statusText || ''}`.trim()), { status: res?.status || 0, url });
+  const text = typeof res.clone === 'function' ? await res.clone().text() : JSON.stringify(await res.json());
+  await writeGithubSourceCacheEntry(url, text, 'application/json', 'api-json', options);
+  return JSON.parse(text || '{}');
+}
+
+async function fetchArrayBuffer(url, fetchImpl, tier, options = {}) {
+  const res = await fetchImpl(url, { cache: 'no-cache', headers: { Accept: 'application/zip,application/octet-stream,*/*' } });
+  if (!res?.ok) throw Object.assign(new Error(`Repository mirror archive ${res?.status || 0} ${res?.statusText || ''}`.trim()), { status: res?.status || 0, url });
+  return await res.arrayBuffer();
+}
+
+function resolveArchiveUrl(metadataUrl = '', meta = {}) {
+  const archive = String(meta.archive || meta.archiveUrl || meta.zip || '').trim();
+  if (!archive) return '';
+  try { return new URL(archive, metadataUrl).toString(); } catch (_) { return ''; }
+}
+
+function repoMatches(meta = {}, repo = '') {
+  const expected = normalizeRepo(repo);
+  const actual = normalizeRepo(meta.repository || meta.repo || '');
+  return Boolean(expected && actual && expected === actual && (!meta.type || meta.type === 'tiinex.repository.snapshot'));
+}
+
+function stripArchivePrefix(path = '', meta = {}) {
+  let clean = String(path || '').replace(/^\/+/, '').replace(/\\/g, '/');
+  const prefixes = [meta.prefix, meta.root, meta.archiveRoot, meta.directory].map((item) => String(item || '').replace(/^\/+|\/+$/g, '')).filter(Boolean);
+  for (const prefix of prefixes) if (clean.startsWith(prefix + '/')) clean = clean.slice(prefix.length + 1);
+  return clean;
+}
+
+
+function repoMirrorEntryPath(path = '', meta = {}, roots = []) {
+  const candidates = [stripArchivePrefix(path, meta), stripFirstArchiveSegment(path)];
+  for (const candidate of candidates) {
+    const clean = String(candidate || '').replace(/^\/+/, '').replace(/\\/g, '/');
+    if (clean && MARKDOWN_RE.test(clean) && underRoots(clean, roots)) return clean;
+  }
+  return '';
+}
+
+function stripFirstArchiveSegment(path = '') {
+  const clean = String(path || '').replace(/^\/+/, '').replace(/\\/g, '/');
+  const parts = clean.split('/').filter(Boolean);
+  return parts.length > 1 ? parts.slice(1).join('/') : clean;
+}
+
+function rootPaths(source = {}) {
+  return String(source.rootPath || '.topics').split(/\r?\n|,/).map((item) => item.trim().replace(/^\.\//, '').replace(/^\/+/, '').replace(/\/+$/, '')).filter(Boolean);
+}
+
+function underRoots(path = '', roots = []) {
+  if (!roots.length) return true;
+  return roots.some((root) => path === root || path.startsWith(root + '/'));
+}
+
+function normalizeRepo(value = '') {
+  return String(value || '').trim().replace(/^https?:\/\/github\.com\//i, '').replace(/\.git$/i, '').replace(/^\/+|\/+$/g, '').split('/').slice(0, 2).join('/').toLowerCase();
+}

package/src/adapters/github/github.repoProxy.js

@@ -0,0 +1,276 @@
+import { createRecordFromMarkdown } from '@tiinex/core/artifacts/artifact.record.js';
+import { githubRawUrlForSourcePath, writeGithubSourceCacheEntry } from '../../sources/github/github.transport.js';
+import { writeGithubRepoDiscoveryCache } from './github.repoMirror.js';
+
+const MARKDOWN_RE = /(?:\.md|\.markdown|\.trace\.md|\.schema\.md|\.validator\.md|\.workspace\.md)$/i;
+
+export async function materializeGithubRepoFilesViaGitProxy(source = {}, options = {}) {
+  const repo = normalizeRepo(source.repo || source.repository || '');
+  const runtime = options.gitNativeRuntime || (typeof window !== 'undefined' ? window.TiinexGitNativeRuntime : null) || (typeof globalThis !== 'undefined' ? globalThis.TiinexGitNativeRuntime : null);
+  const proxyUrl = repoProxyUrlFor(repo, options);
+  if (!repo) return emptyRepoProxyResult('github.repo.proxy.unavailable', 'Repo-file proxy transport requires a repository identity.');
+  if (!runtime?.acquireSnapshot || !runtime?.ensureRuntime || !runtime?.readGitText) return emptyRepoProxyResult('github.repo.proxy.unavailable', 'Repo-file proxy transport requires the browser Git runtime bridge.');
+  if (!proxyUrl) return emptyRepoProxyResult('github.repo.proxy.unavailable', 'Repo-file proxy transport requires an explicit git-proxy URL in workspace configuration.');
+  const roots = rootPaths(source);
+  const timeoutMs = repoProxyTimeoutMs(options);
+  const proxyController = typeof AbortController !== 'undefined' ? new AbortController() : null;
+  const disconnectAbort = linkAbortSignal(options.abortSignal || options.signal || null, proxyController);
+  try {
+    reportProgress(options, { phase: 'repo-proxy', percent: 18, label: `Connecting to repo-file proxy for ${repo}` });
+    const runtimeOptions = {
+      repo,
+      ref: source.ref || '',
+      rootPaths: roots,
+      corsProxy: proxyUrl,
+      loadFromUnpkg: options.loadGitNativeVendor !== false,
+      allowDefaultVendorUrls: options.allowDefaultGitNativeVendorUrls !== false,
+      reuseExistingClone: true,
+      reloadRuntime: true,
+      refreshExistingClone: options.cacheMode === 'refresh' || options.transportOrderExact === true,
+      cloneDepth: Math.max(1, Number(options.gitNativeCloneDepth || options.cloneDepth || 1)),
+      transportSignal: proxyController?.signal || options.abortSignal || options.signal || null,
+      requestTimeoutMs: timeoutMs,
+      maxNetworkDurationMs: timeoutMs,
+      responseStartTimeoutMs: repoProxyResponseStartTimeoutMs(options),
+      idleTimeoutMs: repoProxyIdleTimeoutMs(options),
+      lowSpeedGraceMs: repoProxyLowSpeedGraceMs(options),
+      minBytesPerSecond: repoProxyMinBytesPerSecond(options),
+      onTransportEvent: (event = {}) => {
+        if (event?.event === 'progress') reportProgress(options, {
+          phase: 'repo-proxy-network',
+          percent: 30,
+          label: proxyNetworkProgressLabel(event, repo)
+        });
+      },
+      onProgress: (event = {}) => reportProgress(options, {
+        phase: 'repo-proxy',
+        percent: proxyProgressPercent(event),
+        label: proxyProgressLabel(event, repo)
+      })
+    };
+    const snapshot = await withTimeout(runtime.acquireSnapshot(runtimeOptions), timeoutMs, 'Repo-file proxy transport timed out.', proxyController);
+    if (!snapshot?.ok) throw new Error(snapshot?.error || 'Git proxy did not produce a repository snapshot.');
+    const commit = String(snapshot.commit || '').trim() || String(snapshot.ref || source.ref || '').trim();
+    const runtimeHandle = await runtime.ensureRuntime(Object.assign({}, runtimeOptions, { ref: snapshot.ref || source.ref || '' }));
+    const sourceForRaw = Object.assign({}, source, { ref: commit || source.ref || '' });
+    const candidates = repoProxyCandidatePaths(snapshot, roots).slice(0, Math.max(1, Number(options.maxFiles || 500)));
+    const records = [];
+    const errors = [];
+    let loaded = 0;
+    for (const path of candidates) {
+      try {
+        const markdown = await runtime.readGitText(runtimeHandle, path, commit || snapshot.ref || 'HEAD');
+        if (!String(markdown || '').trim()) continue;
+        const rawUrl = githubRawUrlForSourcePath(sourceForRaw, path);
+        records.push(recordFromRepoProxyMarkdown(markdown, sourceForRaw, path, rawUrl));
+        if (rawUrl) await writeGithubSourceCacheEntry(rawUrl, markdown, 'text/markdown; charset=utf-8', 'raw-markdown', options);
+        loaded += 1;
+        if (loaded === 1 || loaded === candidates.length || loaded % 25 === 0) reportProgress(options, {
+          phase: 'repo-proxy-read',
+          loaded,
+          total: candidates.length,
+          percent: Math.min(92, 44 + Math.round((loaded / Math.max(candidates.length, 1)) * 44)),
+          label: `Loaded Git proxy Markdown ${loaded}/${candidates.length}`
+        });
+      } catch (error) {
+        errors.push({ code: 'github.repo.proxy.file-failed', severity: 'warning', surface: 'repoFiles', transportTier: 'proxy', ref: path, message: error?.message || String(error || '') });
+      }
+    }
+    if (records.length) await writeGithubRepoDiscoveryCache(sourceForRaw, records.map((record) => record.sourceTarget?.sourceArtifactPath || '').filter(Boolean), options);
+    return {
+      schema: 'tiinex.github.repoFiles.materialization.v1',
+      transportTier: 'proxy',
+      ref: commit || snapshot.ref || '',
+      records,
+      warnings: [],
+      errors,
+      counts: { records: records.length, loaded: records.length, failed: errors.length, discovered: candidates.length },
+      diagnostics: {
+        proxyUrl,
+        commit,
+        runtime: 'tiinex.browser-git-native-runtime',
+        networkOperation: snapshot.networkOperation || '',
+        networkOperationSucceeded: Boolean(snapshot.networkOperationSucceeded),
+        transportEvents: [{ tier: 'proxy', code: records.length ? 'github.repo.proxy.ok' : 'github.repo.proxy.empty', severity: records.length ? 'info' : 'warning', resource: 'repo-files', loaded: records.length, discovered: candidates.length, proxyUrl }]
+      }
+    };
+  } catch (error) {
+    const failure = repoProxyFailure(error);
+    return emptyRepoProxyResult(failure.code, failure.message, failure.extra);
+  } finally {
+    disconnectAbort?.();
+    abortController(proxyController, 'Repo-file proxy transport finished.');
+  }
+}
+
+function recordFromRepoProxyMarkdown(markdown = '', source = {}, path = '', rawUrl = '') {
+  const name = String(path || rawUrl).split('/').pop() || 'source.md';
+  return Object.assign(createRecordFromMarkdown(markdown, { path: rawUrl || path, name, sourceMode: 'github-source' }), {
+    sourceTarget: {
+      schema: 'tiinex.source.material.target.v1',
+      surface: 'repoFiles',
+      targetKind: 'repo-proxy-markdown',
+      inputTarget: path,
+      targetIndex: 0,
+      rawUrl,
+      sourceArtifactPath: path,
+      materializedCommit: /^[0-9a-f]{40}$/i.test(String(source.ref || '').trim()) ? String(source.ref || '').trim() : '',
+      transportTier: 'proxy',
+      loaded: true
+    }
+  });
+}
+
+function repoProxyCandidatePaths(snapshot = {}, roots = []) {
+  const files = Array.isArray(snapshot.candidates) && snapshot.candidates.length ? snapshot.candidates : snapshot.files || [];
+  return Array.from(new Set(files.map((item) => normalizePath(item)).filter((path) => path && MARKDOWN_RE.test(path) && underRoots(path, roots)))).sort((a, b) => a.localeCompare(b));
+}
+
+function repoProxyUrlFor(repo = '', options = {}) {
+  const configured = Array.isArray(options.workspaceConfig?.repositoryTransports) ? options.workspaceConfig.repositoryTransports : [];
+  for (const item of configured) {
+    const kind = String(item.kind || '').toLowerCase();
+    if (!kind.includes('proxy')) continue;
+    const activation = String(item.activation || item.mode || item.use || '').trim().toLowerCase();
+    const manual = ['manual', 'explicit', 'opt-in', 'optin', 'user'].includes(activation);
+    const disabled = ['off', 'disabled', 'never'].includes(activation);
+    if (disabled) continue;
+    const exactProxy = options.transportOrderExact === true && (String(options.transportRefreshTier || '').toLowerCase() === 'proxy' || (Array.isArray(options.preferredTransports) && String(options.preferredTransports[0] || '').toLowerCase() === 'proxy'));
+    if (manual && !exactProxy && options.allowManualProxy !== true) continue;
+    const proxy = String(item.proxy || item.proxyUrl || item.corsProxy || '').trim();
+    if (!proxy) continue;
+    if (repoTransportMatches(repo, item.match || item.repository || item.repo || '')) return proxy;
+  }
+  return String(options.gitProxyUrl || options.corsProxy || '').trim();
+}
+
+function repoTransportMatches(repo = '', match = '') {
+  const cleanRepo = normalizeRepo(repo);
+  const cleanMatch = String(match || '').trim().toLowerCase();
+  if (!cleanMatch || cleanMatch === cleanRepo) return true;
+  if (cleanMatch === 'github.com/*' || cleanMatch === 'github.com/**') return true;
+  if (cleanMatch.startsWith('github.com/') && cleanMatch.endsWith('*')) return cleanRepo.startsWith(cleanMatch.slice('github.com/'.length, -1));
+  return cleanMatch.endsWith('*') && cleanRepo.startsWith(cleanMatch.slice(0, -1).replace(/^github\.com\//, ''));
+}
+
+function emptyRepoProxyResult(code = '', message = '', extra = {}) {
+  return {
+    schema: 'tiinex.github.repoFiles.materialization.v1',
+    transportTier: 'proxy',
+    records: [],
+    warnings: [{ code, severity: 'warning', surface: 'repoFiles', transportTier: 'proxy', message }],
+    errors: [],
+    counts: { records: 0, loaded: 0, failed: 0, discovered: 0 },
+    diagnostics: { transportEvents: [Object.assign({ tier: 'proxy', code, severity: 'warning', resource: 'repo-files', message }, extra || {})] }
+  };
+}
+
+function rootPaths(source = {}) {
+  return String(source.rootPath || '.topics').split(/\r?\n|,/).map((item) => normalizePath(item)).filter(Boolean);
+}
+
+function underRoots(path = '', roots = []) {
+  if (!roots.length) return true;
+  return roots.some((root) => path === root || path.startsWith(root + '/'));
+}
+
+function normalizePath(value = '') {
+  return String(value || '').replace(/^\/+/, '').replace(/^\.\//, '').replace(/\\/g, '/').replace(/\/{2,}/g, '/').replace(/\/+$/g, '');
+}
+
+function normalizeRepo(value = '') {
+  return String(value || '').trim().replace(/^https?:\/\/github\.com\//i, '').replace(/\.git$/i, '').replace(/^\/+|\/+$/g, '').split('/').slice(0, 2).join('/').toLowerCase();
+}
+
+function reportProgress(options = {}, progress = {}) {
+  if (typeof options.onProgress === 'function') options.onProgress(progress);
+}
+
+function repoProxyTimeoutMs(options = {}) {
+  const configured = Number(options.repoProxyTimeoutMs || options.gitProxyTimeoutMs || 12000);
+  return Math.max(2000, Math.min(60000, Number.isFinite(configured) ? configured : 12000));
+}
+
+function repoProxyResponseStartTimeoutMs(options = {}) {
+  const configured = Number(options.repoProxyResponseStartTimeoutMs || options.gitProxyResponseStartTimeoutMs || 5000);
+  return Math.max(1000, Math.min(repoProxyTimeoutMs(options), Number.isFinite(configured) ? configured : 5000));
+}
+
+function repoProxyIdleTimeoutMs(options = {}) {
+  const configured = Number(options.repoProxyIdleTimeoutMs || options.gitProxyIdleTimeoutMs || 4000);
+  return Math.max(1000, Math.min(repoProxyTimeoutMs(options), Number.isFinite(configured) ? configured : 4000));
+}
+
+function repoProxyLowSpeedGraceMs(options = {}) {
+  const configured = Number(options.repoProxyLowSpeedGraceMs || options.gitProxyLowSpeedGraceMs || 5000);
+  return Math.max(1000, Math.min(repoProxyTimeoutMs(options), Number.isFinite(configured) ? configured : 5000));
+}
+
+function repoProxyMinBytesPerSecond(options = {}) {
+  const configured = Number(options.repoProxyMinBytesPerSecond || options.gitProxyMinBytesPerSecond || 8192);
+  return Math.max(0, Math.min(1024 * 1024, Number.isFinite(configured) ? configured : 8192));
+}
+
+function proxyNetworkProgressLabel(event = {}, repo = '') {
+  const bps = Number(event.bytesPerSecond || 0);
+  const loaded = Number(event.loaded || 0);
+  const kbps = Math.max(0, Math.round(bps / 1024));
+  const kb = Math.max(0, Math.round(loaded / 1024));
+  return `${repo} repo proxy · receiving ${kb} KB at ${kbps} KB/s`;
+}
+
+function linkAbortSignal(signal, controller) {
+  if (!signal || !controller?.abort) return () => {};
+  const abort = () => abortController(controller, signal.reason || 'Repo-file proxy transport superseded.');
+  if (signal.aborted) abort();
+  else signal.addEventListener?.('abort', abort, { once: true });
+  return () => signal.removeEventListener?.('abort', abort);
+}
+
+function abortController(controller, reason = 'Repo-file proxy transport aborted.') {
+  if (!controller || controller.signal?.aborted) return;
+  try { controller.abort(reason instanceof Error ? reason : new DOMException(String(reason), 'AbortError')); }
+  catch (_) { try { controller.abort(); } catch (_) {} }
+}
+
+function repoProxyFailure(error = {}) {
+  const name = String(error?.name || '').toLowerCase();
+  const kind = String(error?.transportFailureKind || '').toLowerCase();
+  const message = error?.message || String(error || 'Repo-file proxy transport failed.');
+  const extra = { failureKind: kind || name || 'proxy-failed' };
+  if (name === 'aborterror' || kind === 'aborted') return { code: 'github.repo.proxy.aborted', message: 'Repo-file proxy transport was aborted before it could commit material.', extra };
+  if (kind === 'low-throughput') return { code: 'github.repo.proxy.low-throughput', message: `${message} Try direct or configure a faster Git proxy endpoint.`, extra: Object.assign(extra, { bytesPerSecond: Number(error.bytesPerSecond || 0), loaded: Number(error.loaded || 0) }) };
+  if (kind === 'idle-timeout' || kind === 'response-start-timeout' || kind === 'max-network-duration' || name === 'timeouterror') return { code: 'github.repo.proxy.timeout', message: `${message} Try direct or configure a faster Git proxy endpoint.`, extra };
+  return { code: 'github.repo.proxy.failed', message: `Repo-file proxy transport failed: ${message}`, extra };
+}
+
+async function withTimeout(promise, timeoutMs = 12000, message = 'Operation timed out.', controller = null) {
+  let timer = null;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((_, reject) => {
+        timer = setTimeout(() => {
+          const error = new Error(message);
+          error.name = 'TimeoutError';
+          abortController(controller, error);
+          reject(error);
+        }, timeoutMs);
+      })
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+function proxyProgressPercent(event = {}) {
+  const phase = String(event.phase || '').toLowerCase();
+  if (phase.includes('clone') || phase.includes('fetch')) return 32;
+  if (phase.includes('list')) return 40;
+  return 26;
+}
+
+function proxyProgressLabel(event = {}, repo = '') {
+  const phase = String(event.phase || 'git proxy').replace(/[._-]+/g, ' ');
+  return `${repo} repo proxy · ${phase}`;
+}

package/src/adapters/github/github.repoSurface.js

@@ -0,0 +1,60 @@
+import { normalizeGithubTransportTier } from '../../sources/github/github.transport.js';
+import { materializeGithubRepoFilesFromSourceCache, materializeGithubRepoFilesViaHostedMirror } from './github.repoMirror.js';
+import { materializeGithubRepoFilesViaGitProxy } from './github.repoProxy.js';
+
+const REPO_TRANSPORT_FALLBACKS = Object.freeze({
+  default: Object.freeze(['cache', 'mirror', 'proxy', 'direct']),
+  cache: Object.freeze(['cache', 'mirror', 'proxy', 'direct']),
+  mirror: Object.freeze(['mirror']),
+  proxy: Object.freeze(['proxy']),
+  direct: Object.freeze(['direct'])
+});
+
+export function requestedRepoTransportTier(options = {}) {
+  const fromOrder = options.transportOrderExact === true && Array.isArray(options.preferredTransports) ? options.preferredTransports[0] : '';
+  return normalizeGithubTransportTier(options.transportRefreshTier || options.transportPolicy?.requestedTier || fromOrder || '');
+}
+
+export function repoTransportFallbackTiers(options = {}, source = {}) {
+  const normalized = requestedRepoTransportTier(options);
+  const defaultTiers = repoProxyAutoEnabled(source, options) ? REPO_TRANSPORT_FALLBACKS.default : REPO_TRANSPORT_FALLBACKS.default.filter((tier) => tier !== 'proxy');
+  const tiers = Array.from(normalized ? (REPO_TRANSPORT_FALLBACKS[normalized] || [normalized]) : defaultTiers);
+  if (options.allowCache === false && normalized !== 'cache') return tiers.filter((tier) => tier !== 'cache');
+  return tiers;
+}
+
+export async function preMaterializeGithubRepoFiles(source = {}, options = {}) {
+  const tiers = repoTransportFallbackTiers(options, source);
+  const diagnostics = { transportEvents: [] };
+  for (const tier of tiers) {
+    let result = null;
+    if (tier === 'cache') result = await materializeGithubRepoFilesFromSourceCache(source, options);
+    else if (tier === 'mirror') result = await materializeGithubRepoFilesViaHostedMirror(source, Object.assign({}, options, { cacheMode: 'refresh' }));
+    else if (tier === 'proxy') result = await materializeGithubRepoFilesViaGitProxy(source, options);
+    else break;
+    diagnostics.transportEvents.push(...(result?.diagnostics?.transportEvents || []));
+    if (result?.records?.length) return withDiagnostics(result, tiers, diagnostics);
+    if (options.transportOrderExact === true && requestedRepoTransportTier(options)) return withDiagnostics(result || {}, tiers, diagnostics);
+  }
+  return { records: [], warnings: [], errors: [], counts: { records: 0 }, attemptedTiers: tiers, diagnostics };
+}
+
+function repoProxyAutoEnabled(source = {}, options = {}) {
+  if (options.allowManualProxy === true || requestedRepoTransportTier(options) === 'proxy') return true;
+  const repo = String(source.repo || source.repository || '').trim().replace(/^https?:\/\/github\.com\//i, '').replace(/\.git$/i, '').replace(/^\/+|\/+$/g, '').split('/').slice(0, 2).join('/').toLowerCase();
+  const configured = Array.isArray(options.workspaceConfig?.repositoryTransports) ? options.workspaceConfig.repositoryTransports : [];
+  return configured.some((item) => {
+    const kind = String(item.kind || '').toLowerCase();
+    if (!kind.includes('proxy')) return false;
+    const activation = String(item.activation || item.mode || item.use || '').trim().toLowerCase();
+    if (['manual', 'explicit', 'opt-in', 'optin', 'user', 'off', 'disabled', 'never'].includes(activation)) return false;
+    const proxy = String(item.proxy || item.proxyUrl || item.corsProxy || '').trim();
+    if (!proxy) return false;
+    const match = String(item.match || item.repository || item.repo || '').trim().toLowerCase();
+    return !match || match === repo || match === 'github.com/*' || match === 'github.com/**' || (match.endsWith('*') && repo.startsWith(match.slice(0, -1).replace(/^github\.com\//, '')));
+  });
+}
+
+function withDiagnostics(result = {}, tiers = [], diagnostics = {}) {
+  return Object.assign({}, result, { attemptedTiers: tiers, diagnostics: Object.assign({}, result.diagnostics || {}, { transportEvents: diagnostics.transportEvents }) });
+}

package/src/adapters/github/github.transportDiagnostics.js

@@ -0,0 +1,68 @@
+import { normalizeGithubTransportTier } from '../../sources/github/github.transport.js';
+
+export function summarizeTransportTiers(events = []) {
+  const counts = { cache: 0, mirror: 0, proxy: 0, direct: 0, skipped: 0, failed: 0 };
+  for (const event of Array.isArray(events) ? events : []) {
+    const tier = String(event.tier || '').toLowerCase();
+    if (counts[tier] != null && /\.ok$|\.hit$/u.test(String(event.code || ''))) counts[tier] += 1;
+    if (/configured-unavailable|unavailable/u.test(String(event.code || ''))) counts.skipped += 1;
+    if (/failed|exception|exhausted/u.test(String(event.code || ''))) counts.failed += 1;
+  }
+  return counts;
+}
+
+export function summarizeTransportOutcome(events = [], plan = {}, options = {}) {
+  const attempted = new Set();
+  const winning = new Set();
+  const skipped = [];
+  const failed = [];
+  let activeTier = '';
+  let activeStatus = 'idle';
+  for (const event of Array.isArray(events) ? events : []) {
+    const tier = String(event.tier || '').toLowerCase();
+    const code = String(event.code || '');
+    if (!tier || !['cache', 'mirror', 'proxy', 'direct'].includes(tier)) continue;
+    if (/\.try$|\.miss$|\.hit$|\.ok$|configured-unavailable|unavailable|failed|exception/u.test(code)) {
+      attempted.add(tier);
+      activeTier = tier;
+      activeStatus = 'attempted';
+    }
+    if (/\.ok$|\.hit$/u.test(code)) {
+      winning.add(tier);
+      activeTier = tier;
+      activeStatus = 'ok';
+    }
+    if (/configured-unavailable|unavailable/u.test(code)) {
+      skipped.push({ tier, code, resource: event.resource || '', message: event.message || '' });
+      activeTier = tier;
+      activeStatus = 'unavailable';
+    }
+    if (/failed|exception|exhausted/u.test(code)) {
+      failed.push({ tier, code, resource: event.resource || '', status: event.status || 0, message: event.message || '' });
+      activeTier = tier;
+      activeStatus = 'failed';
+    }
+  }
+  const requestedTier = Array.isArray(options.preferredTransports) && options.preferredTransports.length === 1
+    ? normalizeGithubTransportTier(options.preferredTransports[0] || '')
+    : '';
+  const winningList = Array.from(winning);
+  const attemptedList = Array.from(attempted);
+  const sequenceTier = winningList[winningList.length - 1]
+    || (activeStatus === 'failed' || activeStatus === 'unavailable' ? activeTier : '')
+    || requestedTier
+    || '';
+  return {
+    schema: 'tiinex.github.transport.outcome.v1',
+    configuredPlan: Array.isArray(plan.tiers) ? plan.tiers.slice() : [],
+    configured: plan.configured ? Object.assign({}, plan.configured) : {},
+    requestedTier,
+    sequenceTier,
+    activeTier,
+    activeStatus,
+    attemptedTiers: attemptedList,
+    winningTiers: winningList,
+    skipped,
+    failed
+  };
+}