git0 0.2.99 → 0.3.1

package/src/utils.ts

@@ -1,22 +1,29 @@
 import chalk from 'chalk';
 import { execSync } from 'child_process';
 
+/** Set once the logo has been printed, so repeat calls are no-ops. */
+let logoPrinted = false;
+
 /**
- * Prints the git0 ASCII-art logo in cyan to stdout.
+ * Prints the git0 ASCII-art logo in cyan to stdout — **at most once per
+ * process**.
  *
- * Called at the start of every major CLI action so the user always sees the
- * branding regardless of which code path is entered.
+ * Several entry points want to guarantee the branding is on screen: `main()`
+ * prints it before parsing arguments, and each download path prints it before
+ * it starts work, because a download can be reached without going through
+ * `main()`. Left unguarded that renders the logo twice for the most common
+ * invocation of all, `git0 owner/repo`, which reads as a bug. The guard lets
+ * every call site keep saying "show the branding here" while the user sees it
+ * exactly once.
  *
  * @example
  * printLogo();
- * //                 ___
- * //     __ _(_)‾|_ / _ \
- * //    / _  | | __| | | |
- * //   | (_| | | |_| |_| |
- * //    \__, |_|\__|\___/
- * //    |___/
+ * printLogo(); // no-op — the banner is already on screen
  */
 export function printLogo(): void {
+  if (logoPrinted) return;
+  logoPrinted = true;
+
   console.log(chalk.cyan(`                ___
     __ _(_)‾|_ / _ \\
    / _  | | __| | | |
@@ -25,6 +32,19 @@ export function printLogo(): void {
    |___/`));
 }
 
+/**
+ * Forgets that the logo was printed, so the next {@link printLogo} call
+ * renders it again.
+ *
+ * Only useful to tests, which drive several CLI flows through one process and
+ * would otherwise see the banner once for the whole suite.
+ *
+ * @internal
+ */
+export function resetLogo(): void {
+  logoPrinted = false;
+}
+
 /**
  * Runs a shell command synchronously, inheriting the parent's stdio so output
  * streams directly to the terminal.

package/test/args.test.ts

@@ -0,0 +1,44 @@
+import { describe, test, expect, vi } from 'vitest';
+import { parseArgs } from '../src/args.ts';
+
+describe('parseArgs', () => {
+  test('treats bare arguments as positional', () => {
+    const { positional, flags } = parseArgs(['facebook/react', 'my-folder']);
+    expect(positional).toEqual(['facebook/react', 'my-folder']);
+    expect(flags.history).toBe(false);
+  });
+
+  test('keeps URLs intact, including deep ones', () => {
+    const url = 'https://github.com/debate/debate-ai.com/blob/master/.continue/agents/x.yaml';
+    expect(parseArgs([url]).positional).toEqual([url]);
+  });
+
+  test('reads --path and --branch values', () => {
+    const { flags } = parseArgs(['facebook/react', '--path=packages/react-dom', '--branch=v18']);
+    expect(flags.path).toBe('packages/react-dom');
+    expect(flags.branch).toBe('v18');
+  });
+
+  test('accepts --ref as an alias for --branch', () => {
+    expect(parseArgs(['a/b', '--ref=main']).flags.branch).toBe('main');
+  });
+
+  test('reads the history flags', () => {
+    expect(parseArgs(['a/b', '--history']).flags.history).toBe(true);
+    expect(parseArgs(['a/b', '--git']).flags.history).toBe(true);
+    expect(parseArgs(['a/b', '--history-only']).flags.historyOnly).toBe(true);
+    expect(parseArgs(['a/b', '--mirror']).flags.mirror).toBe(true);
+  });
+
+  test('keeps a path containing an equals sign in one piece', () => {
+    expect(parseArgs(['a/b', '--path=dir/a=b']).flags.path).toBe('dir/a=b');
+  });
+
+  test('warns about an unknown flag instead of treating it as a query', () => {
+    const warn = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const { positional } = parseArgs(['a/b', '--nope']);
+    expect(positional).toEqual(['a/b']);
+    expect(warn).toHaveBeenCalled();
+    warn.mockRestore();
+  });
+});

package/test/benchmark-report.test.ts

@@ -0,0 +1,102 @@
+import { describe, test, expect } from 'vitest';
+import {
+  formatDuration,
+  formatBytes,
+  speedups,
+  formatTable,
+  type Measurement,
+} from '../benchmark/report.ts';
+
+/** A measured run, with the fields a test does not care about filled in. */
+function run(partial: Partial<Measurement> & { strategy: string }): Measurement {
+  return { repo: 'owner/repo', timeToFiles: 0, timeToHistory: null, ...partial };
+}
+
+describe('formatDuration', () => {
+  test('keeps sub-second times in milliseconds', () => {
+    expect(formatDuration(842)).toBe('842ms');
+    expect(formatDuration(999.4)).toBe('999ms');
+  });
+
+  test('switches to seconds at a second', () => {
+    expect(formatDuration(1000)).toBe('1.00s');
+    expect(formatDuration(12400)).toBe('12.40s');
+  });
+
+  test('renders "never happened" rather than zero', () => {
+    expect(formatDuration(null)).toBe('—');
+  });
+});
+
+describe('formatBytes', () => {
+  test('scales through binary units', () => {
+    expect(formatBytes(512)).toBe('512 B');
+    expect(formatBytes(1536)).toBe('1.5 KiB');
+    expect(formatBytes(5 * 1024 * 1024)).toBe('5.0 MiB');
+  });
+
+  test('renders an unmeasured size as a dash', () => {
+    expect(formatBytes(undefined)).toBe('—');
+  });
+});
+
+describe('speedups', () => {
+  test('measures time-to-files against the clone baseline', () => {
+    const gains = speedups([
+      run({ strategy: 'git clone', timeToFiles: 8000, timeToHistory: 8000 }),
+      run({ strategy: 'git0', timeToFiles: 2000 }),
+      run({ strategy: 'git0 --history', timeToFiles: 2000, timeToHistory: 9000 }),
+    ]);
+
+    expect(gains.get('git0')).toBe(4);
+    expect(gains.get('git0 --history')).toBe(4);
+    expect(gains.has('git clone')).toBe(false);
+  });
+
+  test('reports nothing when the baseline itself failed', () => {
+    const gains = speedups([
+      run({ strategy: 'git clone', error: 'network down' }),
+      run({ strategy: 'git0', timeToFiles: 2000 }),
+    ]);
+
+    expect(gains.size).toBe(0);
+  });
+
+  test('skips runs that failed', () => {
+    const gains = speedups([
+      run({ strategy: 'git clone', timeToFiles: 8000, timeToHistory: 8000 }),
+      run({ strategy: 'git0', error: 'rate limited' }),
+    ]);
+
+    expect(gains.has('git0')).toBe(false);
+  });
+});
+
+describe('formatTable', () => {
+  const rows = [
+    run({ strategy: 'git clone', timeToFiles: 8000, timeToHistory: 8000, bytesOnDisk: 40 * 1024 * 1024 }),
+    run({ strategy: 'git0', timeToFiles: 2000, bytesOnDisk: 4 * 1024 * 1024 }),
+  ];
+
+  test('emits a markdown table with one row per measurement', () => {
+    const lines = formatTable(rows).split('\n');
+    expect(lines).toHaveLength(4);
+    expect(lines[0]).toContain('time to files');
+    expect(lines[1]).toMatch(/^\| --- \|/);
+  });
+
+  test('shows the speedup against the baseline', () => {
+    expect(formatTable(rows)).toContain('4.00×');
+  });
+
+  test('marks a strategy that produces no history', () => {
+    const git0Row = formatTable(rows).split('\n')[3];
+    expect(git0Row).toContain('—');
+  });
+
+  test('says so when a run failed rather than printing zeros', () => {
+    const table = formatTable([run({ strategy: 'git0', error: 'rate limited' })]);
+    expect(table).toContain('failed: rate limited');
+    expect(table).not.toContain('0ms');
+  });
+});

package/test/download-repo.test.ts

@@ -0,0 +1,178 @@
+import { describe, test, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import * as tar from 'tar';
+import { downloadRepo } from '../src/download.ts';
+
+/**
+ * Builds a tarball shaped exactly like the ones GitHub's `/tarball` endpoint
+ * serves: every entry under one top-level `owner-repo-sha/` directory.
+ */
+function githubTarball(root: string, files: Record<string, string>): string {
+  const staging = fs.mkdtempSync(path.join(os.tmpdir(), 'git0-tarball-'));
+  const wrapper = path.join(staging, root);
+
+  for (const [relative, contents] of Object.entries(files)) {
+    const full = path.join(wrapper, relative);
+    fs.mkdirSync(path.dirname(full), { recursive: true });
+    fs.writeFileSync(full, contents);
+  }
+
+  const archive = path.join(staging, 'repo.tar.gz');
+  tar.c({ gzip: true, sync: true, C: staging, file: archive }, [root]);
+  return archive;
+}
+
+/**
+ * A `callGithub` stand-in that hands the tarball to `onStream` the way `grab`
+ * does — including awaiting it, which is what lets extraction finish before
+ * `downloadRepo` moves on.
+ */
+function fakeGithub(archive: string, options: { fail?: boolean } = {}) {
+  const requested: string[] = [];
+
+  const callGithub = async (url: string, params?: any) => {
+    requested.push(url);
+    if (options.fail) return { error: 'HTTP error: 404 Not Found' };
+
+    const stream = fs.createReadStream(archive);
+    const { Readable } = await import('stream');
+    await params.onStream(Readable.toWeb(stream) as ReadableStream);
+    return {};
+  };
+
+  return { callGithub, requested };
+}
+
+const FILES = {
+  'package.json': '{"name":"demo"}',
+  'readme.md': '# demo\n',
+  'packages/ui/package.json': '{"name":"ui"}',
+  'packages/ui/src/index.ts': 'export const ui = 1;\n',
+  'packages/core/index.ts': 'export const core = 1;\n',
+  '.continue/agents/new-config.yaml': 'name: agent\n',
+};
+
+describe('downloadRepo', () => {
+  let cwd: string;
+  let tmp: string;
+  let archive: string;
+
+  beforeEach(() => {
+    cwd = process.cwd();
+    tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'git0-download-'));
+    process.chdir(tmp);
+    archive = githubTarball('owner-demo-abc1234', FILES);
+  });
+
+  afterEach(() => {
+    process.chdir(cwd);
+    fs.rmSync(tmp, { recursive: true, force: true });
+  });
+
+  test('extracts the whole repository into a folder named after it', async () => {
+    const { callGithub } = fakeGithub(archive);
+    const dir = await downloadRepo(callGithub, 'https://github.com/owner/demo');
+
+    expect(path.basename(dir)).toBe('demo');
+    expect(fs.readdirSync(dir).sort()).toEqual(['.continue', 'package.json', 'packages', 'readme.md']);
+  });
+
+  test('downloads only the sub-path when one is given', async () => {
+    const { callGithub } = fakeGithub(archive);
+    const dir = await downloadRepo(callGithub, 'https://github.com/owner/demo', null, {
+      subPath: 'packages/ui',
+      subPathType: 'tree',
+    });
+
+    expect(fs.readdirSync(dir).sort()).toEqual(['package.json', 'src']);
+    expect(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')).toBe('{"name":"ui"}');
+  });
+
+  test('never writes the parts of the repo it was not asked for', async () => {
+    const { callGithub } = fakeGithub(archive);
+    const dir = await downloadRepo(callGithub, 'https://github.com/owner/demo', null, {
+      subPath: 'packages/ui',
+      subPathType: 'tree',
+    });
+
+    expect(fs.existsSync(path.join(dir, 'readme.md'))).toBe(false);
+    expect(fs.existsSync(path.join(dir, 'core'))).toBe(false);
+    expect(fs.existsSync(path.join(dir, 'packages'))).toBe(false);
+  });
+
+  test('names the folder after the sub-path, not the repository', async () => {
+    const { callGithub } = fakeGithub(archive);
+    const dir = await downloadRepo(callGithub, 'https://github.com/owner/demo', null, {
+      subPath: '.continue/agents',
+      subPathType: 'tree',
+    });
+
+    expect(path.basename(dir)).toBe('agents');
+    expect(fs.readdirSync(dir)).toEqual(['new-config.yaml']);
+  });
+
+  test('downloads a single file and names the folder after its parent', async () => {
+    const { callGithub } = fakeGithub(archive);
+    const dir = await downloadRepo(callGithub, 'https://github.com/owner/demo', null, {
+      subPath: '.continue/agents/new-config.yaml',
+      subPathType: 'blob',
+    });
+
+    expect(path.basename(dir)).toBe('agents');
+    expect(fs.readdirSync(dir)).toEqual(['new-config.yaml']);
+    expect(fs.readFileSync(path.join(dir, 'new-config.yaml'), 'utf8')).toBe('name: agent\n');
+  });
+
+  test('an explicit folder name still wins over the sub-path', async () => {
+    const { callGithub } = fakeGithub(archive);
+    const dir = await downloadRepo(callGithub, 'https://github.com/owner/demo', 'my-ui', {
+      subPath: 'packages/ui',
+      subPathType: 'tree',
+    });
+
+    expect(path.basename(dir)).toBe('my-ui');
+  });
+
+  test('requests the named ref and does not guess at a branch', async () => {
+    const { callGithub, requested } = fakeGithub(archive);
+    await downloadRepo(callGithub, 'https://github.com/owner/demo', null, { ref: 'develop' });
+
+    expect(requested).toEqual(['/repos/owner/demo/tarball/develop']);
+  });
+
+  test('falls back from master to main when no ref was named', async () => {
+    const { callGithub, requested } = fakeGithub(archive, { fail: true });
+    await expect(downloadRepo(callGithub, 'https://github.com/owner/demo')).rejects.toThrow();
+
+    expect(requested).toEqual([
+      '/repos/owner/demo/tarball/master',
+      '/repos/owner/demo/tarball/main',
+    ]);
+  });
+
+  test('reports a failed download instead of leaving an empty folder', async () => {
+    const { callGithub } = fakeGithub(archive, { fail: true });
+
+    await expect(downloadRepo(callGithub, 'https://github.com/owner/demo'))
+      .rejects.toThrow(/Could not download owner\/demo/);
+    expect(fs.existsSync(path.join(tmp, 'demo'))).toBe(false);
+  });
+
+  test('says which path was missing rather than producing an empty folder', async () => {
+    const { callGithub } = fakeGithub(archive);
+
+    await expect(
+      downloadRepo(callGithub, 'https://github.com/owner/demo', null, { subPath: 'packages/nope' })
+    ).rejects.toThrow(/not found in this repository/);
+  });
+
+  test('refuses a sub-path that would escape the target folder', async () => {
+    const { callGithub } = fakeGithub(archive);
+
+    await expect(
+      downloadRepo(callGithub, 'https://github.com/owner/demo', null, { subPath: '../../etc' })
+    ).rejects.toThrow(/\.\./);
+  });
+});

package/test/history.test.ts

@@ -0,0 +1,157 @@
+import { describe, test, expect, beforeAll, afterAll, beforeEach, afterEach } from 'vitest';
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { attachGitHistory, attachGitHistoryLazily, cloneHistoryOnly, gitAvailable } from '../src/history.ts';
+
+/** A real repository on disk to clone from, so the conversion is exercised for real. */
+let origin: string;
+let sandbox: string;
+
+function git(args: string[], cwd: string): string {
+  return execFileSync('git', args, { cwd, encoding: 'utf8' }).trim();
+}
+
+beforeAll(() => {
+  sandbox = fs.mkdtempSync(path.join(os.tmpdir(), 'git0-history-test-'));
+  origin = path.join(sandbox, 'origin');
+  fs.mkdirSync(origin);
+
+  git(['init', '--quiet', '--initial-branch=main'], origin);
+  git(['config', 'user.email', 'test@example.com'], origin);
+  git(['config', 'user.name', 'git0 test'], origin);
+
+  fs.writeFileSync(path.join(origin, 'readme.md'), '# one\n');
+  git(['add', '.'], origin);
+  git(['commit', '--quiet', '-m', 'first'], origin);
+
+  fs.writeFileSync(path.join(origin, 'readme.md'), '# two\n');
+  git(['commit', '--quiet', '-am', 'second'], origin);
+});
+
+afterAll(() => {
+  fs.rmSync(sandbox, { recursive: true, force: true });
+});
+
+describe('gitAvailable', () => {
+  test('finds the git binary in this environment', async () => {
+    await expect(gitAvailable()).resolves.toBe(true);
+  });
+});
+
+describe('attachGitHistory', () => {
+  let extractPath: string;
+
+  beforeEach(() => {
+    // Stands in for a tarball extraction: the files, but no .git.
+    extractPath = fs.mkdtempSync(path.join(sandbox, 'extract-'));
+    fs.writeFileSync(path.join(extractPath, 'readme.md'), '# two\n');
+  });
+
+  afterEach(() => {
+    fs.rmSync(extractPath, { recursive: true, force: true });
+  });
+
+  test('turns an extracted folder into a working repository', async () => {
+    await attachGitHistory(extractPath, `file://${origin}`);
+
+    expect(fs.existsSync(path.join(extractPath, '.git'))).toBe(true);
+    expect(git(['rev-parse', '--is-bare-repository'], extractPath)).toBe('false');
+  });
+
+  test('brings the full history, not one commit', async () => {
+    await attachGitHistory(extractPath, `file://${origin}`);
+
+    expect(git(['rev-list', '--count', 'HEAD'], extractPath)).toBe('2');
+  });
+
+  test('leaves the working tree clean against the extracted files', async () => {
+    await attachGitHistory(extractPath, `file://${origin}`);
+
+    expect(git(['status', '--porcelain'], extractPath)).toBe('');
+  });
+
+  test('keeps the extracted files rather than re-checking them out', async () => {
+    fs.writeFileSync(path.join(extractPath, 'untracked.txt'), 'mine');
+
+    await attachGitHistory(extractPath, `file://${origin}`);
+
+    expect(fs.readFileSync(path.join(extractPath, 'untracked.txt'), 'utf8')).toBe('mine');
+  });
+
+  test('sets up origin so the repo can fetch and push', async () => {
+    await attachGitHistory(extractPath, `file://${origin}`);
+
+    expect(git(['config', '--get', 'remote.origin.fetch'], extractPath))
+      .toBe('+refs/heads/*:refs/remotes/origin/*');
+  });
+
+  test('refuses to overwrite an existing .git', async () => {
+    fs.mkdirSync(path.join(extractPath, '.git'));
+
+    await expect(attachGitHistory(extractPath, `file://${origin}`))
+      .rejects.toThrow(/already exists/);
+  });
+
+  test('refuses a remote that is not a URL', async () => {
+    await expect(attachGitHistory(extractPath, 'ext::sh -c whoami'))
+      .rejects.toThrow(/Refusing to clone/);
+    await expect(attachGitHistory(extractPath, '--upload-pack=touch'))
+      .rejects.toThrow(/Refusing to clone/);
+  });
+
+  test('leaves no .git behind when the clone fails', async () => {
+    await expect(attachGitHistory(extractPath, `file://${path.join(sandbox, 'nope')}`))
+      .rejects.toThrow();
+
+    expect(fs.existsSync(path.join(extractPath, '.git'))).toBe(false);
+  });
+});
+
+describe('attachGitHistoryLazily', () => {
+  test('resolves rather than rejecting when the history cannot be fetched', async () => {
+    const extractPath = fs.mkdtempSync(path.join(sandbox, 'lazy-'));
+
+    // A download that fails must not take the project down with it.
+    await expect(attachGitHistoryLazily(extractPath, 'not-a-url')).resolves.toBeUndefined();
+    expect(fs.existsSync(path.join(extractPath, '.git'))).toBe(false);
+
+    fs.rmSync(extractPath, { recursive: true, force: true });
+  });
+});
+
+describe('cloneHistoryOnly', () => {
+  test('produces a history-only repository with no working files', async () => {
+    const target = path.join(sandbox, 'mirror.git');
+    await cloneHistoryOnly(`file://${origin}`, target);
+
+    expect(fs.existsSync(path.join(target, 'objects'))).toBe(true);
+    expect(fs.existsSync(path.join(target, 'readme.md'))).toBe(false);
+    expect(git(['--git-dir', target, 'rev-list', '--count', '--all'], sandbox)).toBe('2');
+
+    fs.rmSync(target, { recursive: true, force: true });
+  });
+
+  test('restores a normal working copy when cloned from', async () => {
+    const target = path.join(sandbox, 'restore.git');
+    await cloneHistoryOnly(`file://${origin}`, target);
+
+    const restored = path.join(sandbox, 'restored');
+    execFileSync('git', ['clone', '--quiet', target, restored]);
+
+    expect(fs.readFileSync(path.join(restored, 'readme.md'), 'utf8')).toBe('# two\n');
+
+    fs.rmSync(target, { recursive: true, force: true });
+    fs.rmSync(restored, { recursive: true, force: true });
+  });
+
+  test('refuses to write over an existing directory', async () => {
+    const target = path.join(sandbox, 'occupied.git');
+    fs.mkdirSync(target);
+
+    await expect(cloneHistoryOnly(`file://${origin}`, target)).rejects.toThrow(/already exists/);
+
+    fs.rmSync(target, { recursive: true, force: true });
+  });
+});

package/test/parse-target.test.ts

@@ -0,0 +1,73 @@
+import { describe, test, expect } from 'vitest';
+import { parseTarget } from '../src/github-api.ts';
+
+describe('parseTarget', () => {
+  test('parses a plain repository URL', () => {
+    const target = parseTarget('https://github.com/facebook/react');
+    expect(target).toMatchObject({
+      owner: 'facebook',
+      name: 'react',
+      href: 'https://github.com/facebook/react',
+      subPath: '',
+      subPathType: '',
+    });
+  });
+
+  test('parses owner/repo shorthand', () => {
+    expect(parseTarget('vitejs/vite')).toMatchObject({
+      owner: 'vitejs',
+      name: 'vite',
+      subPath: '',
+    });
+  });
+
+  test('reads branch and folder out of a /tree/ URL', () => {
+    expect(parseTarget('https://github.com/facebook/react/tree/main/packages/react-dom'))
+      .toMatchObject({
+        owner: 'facebook',
+        name: 'react',
+        ref: 'main',
+        subPath: 'packages/react-dom',
+        subPathType: 'tree',
+      });
+  });
+
+  test('reads branch and file out of a /blob/ URL', () => {
+    expect(
+      parseTarget(
+        'https://github.com/debate/debate-ai.com/blob/master/.continue/agents/new-config.yaml'
+      )
+    ).toMatchObject({
+      owner: 'debate',
+      name: 'debate-ai.com',
+      ref: 'master',
+      subPath: '.continue/agents/new-config.yaml',
+      subPathType: 'blob',
+    });
+  });
+
+  test('takes a path off the owner/repo shorthand too', () => {
+    expect(parseTarget('facebook/react/packages/react-dom')).toMatchObject({
+      owner: 'facebook',
+      name: 'react',
+      subPath: 'packages/react-dom',
+      subPathType: '',
+    });
+  });
+
+  test('canonicalizes href to the repository root, not the deep link', () => {
+    const target = parseTarget('https://github.com/facebook/react/tree/main/packages/react-dom');
+    expect(target && target.href).toBe('https://github.com/facebook/react');
+  });
+
+  test('unwraps the fork chain GitHub puts in the owner', () => {
+    expect(parseTarget('https://github.com/upstream/fork/repo')).toMatchObject({
+      owner: 'fork',
+    });
+  });
+
+  test('returns false for a search query', () => {
+    expect(parseTarget('react starter template')).toBe(false);
+    expect(parseTarget('react')).toBe(false);
+  });
+});