git0 0.2.13 → 0.2.14

package/src/github-api.ts

@@ -0,0 +1,237 @@
+import { grab } from 'grab-api.js';
+import chalk from 'chalk';
+import gitUrlParse from 'git-url-parse';
+import type { PlatformInfo, CategorizedRelease, SearchResult } from './types.js';
+import { getCurrentPlatform } from './platform.js';
+import { categorizeReleasesByPlatform, filterReleasesByPlatform } from './releases.js';
+import { downloadRepo, downloadPackage } from './download.js';
+
+/**
+ * GitHub API client for searching repositories, downloading source tarballs,
+ * and fetching release assets.
+ *
+ * Internally uses a `grab` instance pre-configured with the GitHub base URL,
+ * optional bearer token, and a 403 rate-limit handler.
+ *
+ * @example
+ * const github = new GithubAPI({ token: process.env.GITHUB_TOKEN });
+ * const repos  = await github.searchRepositories('nodejs template');
+ * const dir    = await github.downloadRepo('facebook/react');
+ */
+class GithubAPI {
+  /** Default number of repository search results returned per query. */
+  static DEFAULT_RESULTS_PER_PAGE = 10;
+
+  private callGithub: ReturnType<typeof grab.instance>;
+
+  /**
+   * Creates a new GithubAPI instance and initialises the underlying HTTP client.
+   *
+   * When no `token` is supplied the constructor falls back to the
+   * `GITHUB_TOKEN` environment variable. Unauthenticated requests are
+   * limited to 60/hour by GitHub; a token raises this to 5 000/hour.
+   *
+   * @param options.token   - GitHub personal access token.
+   * @param options.debug   - Pass `true` to enable `grab` request logging.
+   * @param options.baseURL - Override the GitHub REST API base URL
+   *   (useful for GitHub Enterprise).
+   */
+  constructor(options: { token?: string; debug?: boolean; baseURL?: string } = {}) {
+    const token = options.token || process.env.GITHUB_TOKEN;
+    const debug = options.debug ?? false;
+    const baseURL = options.baseURL || 'https://api.github.com';
+
+    this.callGithub = grab.instance({
+      debug,
+      baseURL,
+      timeout: 500,
+      headers: token ? { Authorization: `token ${token}` } : {},
+      onError: (error: string) => {
+        if (error.includes('403')) {
+          console.log(chalk.red(
+            'Rate limit exceeded. Set the GITHUB_TOKEN env var.\n' +
+            'Create a token at https://github.com/settings/personal-access-tokens/new'
+          ));
+          process.exit(1);
+        }
+      },
+    });
+  }
+
+  /**
+   * Downloads a GitHub repository as a tarball and extracts it locally.
+   *
+   * Delegates to {@link downloadRepo} in `download.ts`.
+   * Falls back from the `master` branch to `main` when the first attempt fails.
+   *
+   * @param repo      - Full GitHub URL or `owner/repo` shorthand.
+   * @param targetDir - Optional extraction folder name; defaults to the repo name.
+   * @returns Absolute path of the extracted project directory.
+   *
+   * @example
+   * const dir = await github.downloadRepo('https://github.com/vitejs/vite');
+   * // → '/current/working/dir/vite'
+   */
+  async downloadRepo(repo: string, targetDir: string | null = null): Promise<string> {
+    return downloadRepo(this.callGithub, repo, targetDir);
+  }
+
+  /**
+   * Searches GitHub repositories by name and enriches each result with
+   * release availability information.
+   *
+   * Results are sorted by stars descending by default. When `getReleaseInfo`
+   * is true (the default), the function fires one extra API request per result
+   * to fetch release data — all requests run concurrently via `Promise.all`.
+   *
+   * @param query               - Search string matched against repository names.
+   * @param options.perPage     - Maximum results (default {@link DEFAULT_RESULTS_PER_PAGE}).
+   * @param options.sort        - GitHub sort field: `'stars'` | `'forks'` | `'updated'`.
+   * @param options.order       - Sort direction: `'asc'` | `'desc'`.
+   * @param options.getReleaseInfo - When `false`, skips the per-repo release fetch.
+   * @returns Array of {@link SearchResult} objects ordered by `sort`/`order`.
+   * @throws Re-throws any network or API error after logging it.
+   *
+   * @example
+   * const repos = await github.searchRepositories('react starter');
+   * repos.forEach(r => console.log(r.full_name, r.hasCompatibleReleases));
+   */
+  async searchRepositories(
+    query: string,
+    options: { perPage?: number; sort?: string; order?: string; getReleaseInfo?: boolean } = {}
+  ): Promise<SearchResult[]> {
+    const {
+      perPage = GithubAPI.DEFAULT_RESULTS_PER_PAGE,
+      sort = 'stars',
+      order = 'desc',
+      getReleaseInfo = true,
+    } = options;
+
+    try {
+      const response = await this.callGithub('/search/repositories', {
+        q: `${query} in:name`,
+        sort,
+        order,
+        per_page: perPage,
+      });
+
+      if (response.error || !response.items) {
+        console.log('No response');
+        return [];
+      }
+
+      if (!getReleaseInfo) return response.items;
+
+      return Promise.all(
+        response.items.map(async (repo: SearchResult) => {
+          const releases = await this.callGithub(
+            `/repos/${repo.owner.login}/${repo.name}/releases`
+          );
+          const platform = getCurrentPlatform();
+
+          return {
+            ...repo,
+            hasReleases: releases?.length > 0,
+            hasCompatibleReleases: filterReleasesByPlatform(releases, platform).length > 0,
+            releases: filterReleasesByPlatform(releases, platform),
+            allReleases: categorizeReleasesByPlatform(releases),
+          };
+        })
+      );
+    } catch (error: any) {
+      console.error(chalk.red('Search failed:'), error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * Downloads a single release asset binary to disk.
+   *
+   * Delegates to {@link downloadPackage} in `download.ts`.
+   *
+   * @param packageURL   - Direct HTTPS download URL for the asset.
+   * @param downloadPath - Absolute local path to write the file to.
+   * @returns The `downloadPath` on success.
+   * @throws When the download request fails.
+   */
+  async downloadPackage(packageURL: string, downloadPath: string): Promise<string> {
+    return downloadPackage(this.callGithub, packageURL, downloadPath);
+  }
+
+  /**
+   * Parses a GitHub URL or `owner/repo` shorthand into a structured URL object.
+   *
+   * Accepts:
+   * - Full HTTPS URLs: `https://github.com/owner/repo`
+   * - SSH URLs: `git@github.com:owner/repo`
+   * - Git protocol: `git://github.com/owner/repo`
+   * - Shorthand: `owner/repo`
+   *
+   * @param query - The string to parse.
+   * @returns A `git-url-parse` result object, or `false` when the input does
+   *   not look like a GitHub reference.
+   *
+   * @example
+   * github.parseURL('facebook/react');
+   * // → { owner: 'facebook', name: 'react', href: 'https://github.com/facebook/react', … }
+   *
+   * github.parseURL('just a search query'); // → false
+   */
+  parseURL(query: string): ReturnType<typeof gitUrlParse> | false {
+    if (
+      query.includes('github.com') ||
+      query.startsWith('git@github.com:') ||
+      query.startsWith('https://') ||
+      query.startsWith('git://')
+    ) {
+      return gitUrlParse(query);
+    }
+    if (/^[\w-]+\/[\w.-]+$/.test(query)) {
+      return gitUrlParse(`https://github.com/${query}`);
+    }
+    return false;
+  }
+
+  /**
+   * Returns normalized OS and CPU architecture for the current machine.
+   *
+   * Delegates to {@link getCurrentPlatform} from `platform.ts`.
+   *
+   * @returns {@link PlatformInfo} with canonical OS/arch strings.
+   */
+  getCurrentPlatform(): PlatformInfo {
+    return getCurrentPlatform();
+  }
+
+  /**
+   * Fetches all releases for a repo and categorizes their assets by platform.
+   *
+   * @param owner - GitHub username or organisation name.
+   * @param repo  - Repository name.
+   * @returns Array of {@link CategorizedRelease} objects, one per release that
+   *   has at least one downloadable asset.
+   *
+   * @example
+   * const releases = await github.getReleases('microsoft', 'vscode');
+   */
+  async getReleases(owner: string, repo: string): Promise<CategorizedRelease[]> {
+    const releases = await this.callGithub(`/repos/${owner}/${repo}/releases`);
+    return categorizeReleasesByPlatform(releases);
+  }
+
+  /**
+   * Fetches releases that have at least one asset compatible with the current
+   * operating system.
+   *
+   * @param owner - GitHub username or organisation name.
+   * @param repo  - Repository name.
+   * @returns Subset of {@link CategorizedRelease} objects compatible with the
+   *   current platform (including `universal` assets).
+   */
+  async getCompatibleReleases(owner: string, repo: string): Promise<CategorizedRelease[]> {
+    const releases = await this.callGithub(`/repos/${owner}/${repo}/releases`);
+    return filterReleasesByPlatform(releases, getCurrentPlatform());
+  }
+}
+
+export default GithubAPI;

package/src/ide.ts

@@ -0,0 +1,141 @@
+import chalk from 'chalk';
+import { execSync, spawn } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import type { IdeInfo } from './types.js';
+
+/**
+ * Ordered list of editors to probe. The first one found on `PATH` wins.
+ * Add new entries at the top to give them higher priority.
+ *
+ * @internal
+ */
+const SUPPORTED_IDES: IdeInfo[] = [
+  { name: 'Antigravity', cmd: 'antigravity' },
+  { name: 'Cursor',      cmd: 'cursor'      },
+  { name: 'Windsurf',    cmd: 'windsurf'    },
+  { name: 'VSCode',      cmd: 'code'        },
+  { name: 'Code Server', cmd: 'code-server' },
+  { name: 'Neovim',      cmd: 'nvim'        },
+  { name: 'Webstorm',    cmd: 'webstorm'    },
+];
+
+/**
+ * Probes `PATH` for the first IDE in {@link SUPPORTED_IDES} that is installed.
+ *
+ * Uses `where` on Windows and `command -v` on Unix. The check is intentionally
+ * silent (`stdio: 'ignore'`) so no output leaks into the CLI.
+ *
+ * @returns The first installed {@link IdeInfo}, or `null` when none are found.
+ *
+ * @example
+ * const ide = getInstalledIde();
+ * if (ide) console.log(`Found: ${ide.name}`);
+ */
+export function getInstalledIde(): IdeInfo | null {
+  const probe = process.platform === 'win32'
+    ? (cmd: string) => `where ${cmd}`
+    : (cmd: string) => `command -v ${cmd}`;
+
+  for (const ide of SUPPORTED_IDES) {
+    try {
+      execSync(probe(ide.cmd), { stdio: 'ignore' });
+      return ide;
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+/**
+ * Builds the argument list for spawning an editor process.
+ *
+ * `code-server` requires a `--open` flag to actually open the browser;
+ * all other editors accept a bare path.
+ *
+ * @param ide  - The IDE to build args for.
+ * @param target - Path to open (directory or file).
+ * @returns Argument array suitable for `spawn(ide.cmd, args)`.
+ *
+ * @internal
+ */
+function buildIdeArgs(ide: IdeInfo, target: string): string[] {
+  return ide.cmd === 'code-server' ? [target, '--open'] : [target];
+}
+
+/**
+ * Locates the entry-point document to open after the IDE loads the project
+ * folder. Checks for README files first (case-insensitive), then falls back
+ * to `package.json`.
+ *
+ * @param dir - Directory to search inside (defaults to `process.cwd()`).
+ * @returns Relative path of the first match, or `null` if nothing is found.
+ *
+ * @internal
+ */
+function findEntryDocument(dir = '.'): string | null {
+  const candidates = [
+    `${dir}/readme.md`,
+    `${dir}/Readme.md`,
+    `${dir}/README.md`,
+    `${dir}/package.json`,
+  ];
+  return candidates.find(p => fs.existsSync(p)) ?? null;
+}
+
+/**
+ * Spawns an IDE process in a detached, fire-and-forget manner.
+ *
+ * The process is detached and unreffed so it outlives the parent CLI process.
+ * Shell mode is enabled on Windows to handle PATH resolution correctly.
+ *
+ * @param ide  - IDE to launch.
+ * @param args - Arguments to pass (e.g. path to open).
+ *
+ * @internal
+ */
+function spawnDetached(ide: IdeInfo, args: string[]): void {
+  spawn(ide.cmd, args, {
+    detached: true,
+    stdio: 'ignore',
+    shell: process.platform === 'win32',
+  }).unref();
+}
+
+/**
+ * Opens a project directory in the first available IDE and, after a short
+ * delay, also opens the project's entry document (README or `package.json`).
+ *
+ * The 3-second delay gives the IDE time to finish loading the workspace before
+ * it receives the file-open command — opening too early can cause some editors
+ * to ignore the second argument.
+ *
+ * Does nothing and prints a warning when no supported IDE is installed.
+ *
+ * @param targetDir - Absolute path to the project directory to open.
+ *
+ * @example
+ * openInIDE('/home/user/projects/my-app');
+ * // Logs: 🚀 Opening my-app in Cursor
+ */
+export function openInIDE(targetDir: string): void {
+  const ide = getInstalledIde();
+  if (!ide) {
+    console.log(chalk.yellow('⚠️  No supported IDE found'));
+    return;
+  }
+
+  try {
+    spawnDetached(ide, buildIdeArgs(ide, targetDir));
+
+    setTimeout(() => {
+      const doc = findEntryDocument(targetDir);
+      if (doc) spawnDetached(ide, buildIdeArgs(ide, doc));
+    }, 3000);
+
+    console.log(chalk.green(`🚀 Opening ${path.basename(targetDir)} in ${ide.name}`));
+  } catch {
+    // Swallow — IDE launch errors are non-fatal for the download workflow.
+  }
+}

package/src/install.ts

@@ -0,0 +1,147 @@
+import { execSync } from 'child_process';
+import fs from 'fs';
+import { exec } from './utils.js';
+
+/**
+ * A detector checks whether a specific project type is present in the current
+ * working directory by looking for a characteristic file.
+ *
+ * @internal
+ */
+type Detector = () => boolean;
+
+/**
+ * An installer runs the appropriate package manager or build tool for a
+ * detected project type.
+ *
+ * @internal
+ */
+type Installer = () => void;
+
+/**
+ * Returns true when the `bun` binary is available on `PATH`.
+ *
+ * Uses `where` on Windows and `command -v` on Unix. Throws when not found
+ * (callers catch this to fall back to npm).
+ *
+ * @internal
+ */
+function bunAvailable(): boolean {
+  try {
+    execSync(
+      process.platform === 'win32' ? 'where bun' : 'command -v bun',
+      { stdio: 'ignore' }
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Installs Node.js dependencies and starts the dev/start script.
+ *
+ * Prefers `bun` when available; falls back to `npm`. Runs `dev` first and
+ * `start` as a fallback in the same shell invocation — both are expected to
+ * fail gracefully when the script doesn't exist.
+ *
+ * @internal
+ */
+function installNode(): void {
+  if (bunAvailable()) {
+    exec('bun install');
+    exec('bun run dev; bun run start');
+  } else {
+    exec('npm install');
+    exec('npm run dev; npm run start');
+  }
+}
+
+/**
+ * Starts a Docker project using Compose if `docker-compose.yml` is present,
+ * otherwise builds a plain Docker image from `Dockerfile`.
+ *
+ * @internal
+ */
+function installDocker(): void {
+  if (fs.existsSync('docker-compose.yml')) {
+    exec('sudo docker-compose up -d');
+  } else if (fs.existsSync('Dockerfile')) {
+    exec('sudo docker build -t project .');
+  }
+}
+
+/**
+ * Creates a Python virtualenv, activates it, and installs dependencies.
+ *
+ * Installs from `requirements.txt` and/or `setup.py` depending on which
+ * files exist. The `source .venv/bin/activate` call is a no-op on Windows
+ * (where the command is not available) but is harmless to include.
+ *
+ * @internal
+ */
+function installPython(): void {
+  exec('python -m venv .venv');
+  exec('source .venv/bin/activate');
+  if (fs.existsSync('requirements.txt')) exec('pip install -r requirements.txt');
+  if (fs.existsSync('setup.py'))         exec('pip install -e .');
+}
+
+/**
+ * Project-type detectors keyed by ecosystem name.
+ * Each function returns `true` when it recognises the current directory.
+ *
+ * @internal
+ */
+const DETECTORS: Record<string, Detector> = {
+  nodejs: () => fs.existsSync('package.json'),
+  docker: () => fs.existsSync('Dockerfile') || fs.existsSync('docker-compose.yml'),
+  python: () => fs.existsSync('requirements.txt') || fs.existsSync('setup.py'),
+  rust:   () => fs.existsSync('Cargo.toml'),
+  go:     () => fs.existsSync('go.mod'),
+};
+
+/**
+ * Per-ecosystem install handlers, keyed to match {@link DETECTORS}.
+ *
+ * @internal
+ */
+const INSTALLERS: Record<string, Installer> = {
+  nodejs: installNode,
+  docker: installDocker,
+  python: installPython,
+  rust:   () => exec('cargo build'),
+  go:     () => exec('go mod tidy'),
+};
+
+/**
+ * Detects the project type(s) in `targetDir` and runs the appropriate
+ * dependency installer(s).
+ *
+ * A directory can match multiple project types simultaneously (e.g. a Node.js
+ * project that also has a Dockerfile). All matched installers are run in order.
+ *
+ * Supported ecosystems:
+ * | Ecosystem | Detection file         | Install command           |
+ * |-----------|------------------------|---------------------------|
+ * | Node.js   | `package.json`         | `bun install` / `npm i`   |
+ * | Docker    | `Dockerfile` / Compose | `docker-compose up -d`    |
+ * | Python    | `requirements.txt`     | `pip install -r …`        |
+ * | Rust      | `Cargo.toml`           | `cargo build`             |
+ * | Go        | `go.mod`               | `go mod tidy`             |
+ *
+ * @param targetDir - Absolute path to the project root to install into.
+ *   The function changes the process working directory to this path before
+ *   running any commands.
+ *
+ * @example
+ * await installDependencies('/home/user/projects/my-node-app');
+ * // Detects package.json → runs bun install && bun run dev
+ */
+export async function installDependencies(targetDir: string): Promise<void> {
+  process.chdir(targetDir);
+
+  for (const [name, detect] of Object.entries(DETECTORS)) {
+    if (detect()) INSTALLERS[name]?.();
+  }
+}