Merge pull request #1628 from serhiizghama/feat/auto-detect-github-shorthand

feat(cli): auto-detect GitHub shorthand (owner/repo) in positional arguments

Author: yamadashy

src/cli/cliRun.ts

@@ -1,8 +1,10 @@
+import * as fs from 'node:fs/promises';
+import path from 'node:path';
 import process from 'node:process';
 import { Option, program } from 'commander';
 import pc from 'picocolors';
 import { getVersion } from '../core/file/packageJsonParse.js';
-import { isExplicitRemoteUrl } from '../core/git/gitRemoteUrl.js';
+import { isExplicitRemoteUrl, isValidShorthand } from '../core/git/gitRemoteUrl.js';
 import { handleError, RepomixError } from '../shared/errorHandle.js';
 import { logger, repomixLogLevels } from '../shared/logger.js';
 import { parseHumanSizeToBytes } from '../shared/sizeParse.js';
@@ -296,6 +298,35 @@ export const runCli = async (directories: string[], cwd: string, options: CliOpt
     return await runRemoteAction(directories[0], options);
   }
 
+  // Auto-detect GitHub shorthand (owner/repo) in positional arguments.
+  // Shorthand is ambiguous with relative local paths, so it is only treated as remote when:
+  //   1. the argument does not exist as a local path, and
+  //   2. the repository is confirmed reachable on GitHub (HEAD-only `git ls-remote` probe).
+  // A mistyped local path (e.g. `src/uitls`) fails the probe and falls through to the
+  // regular local-path handling instead of triggering an unintended clone attempt.
+  // Skipped in stdin mode, where positional directory arguments are rejected.
+  if (directories.length === 1 && !options.stdin && isValidShorthand(directories[0])) {
+    const localPathExists = await fs.access(path.resolve(cwd, directories[0])).then(
+      () => true,
+      // EACCES/EPERM mean the path exists but is inaccessible — keep local-path precedence
+      // and only fall through to the remote probe when the path is truly missing.
+      (error: NodeJS.ErrnoException) => !['ENOENT', 'ENOTDIR'].includes(error.code ?? ''),
+    );
+    if (!localPathExists) {
+      const { checkRemoteRepoExists } = await import('../core/git/gitRemoteHandle.js');
+      if (await checkRemoteRepoExists(`https://github.com/${directories[0]}.git`)) {
+        logger.log(
+          pc.dim(
+            `Detected GitHub repository shorthand: ${directories[0]} (prefix with ./ to treat it as a local path)\n`,
+          ),
+        );
+        const { runRemoteAction } = await import('./actions/remoteAction.js');
+        return await runRemoteAction(directories[0], options);
+      }
+      logger.trace(`Argument matches owner/repo shorthand but is not a reachable GitHub repository: ${directories[0]}`);
+    }
+  }
+
   const { runDefaultAction } = await import('./actions/defaultAction.js');
   return await runDefaultAction(directories, cwd, options);
 };

src/core/git/gitCommand.ts

@@ -11,6 +11,12 @@ const GIT_REMOTE_TIMEOUT = 30000;
 const gitRemoteEnv = { ...process.env, GIT_TERMINAL_PROMPT: '0' };
 const gitRemoteOpts = { timeout: GIT_REMOTE_TIMEOUT, env: gitRemoteEnv };
 
+// Opts for the automatic existence probe. It can be triggered by a mistyped local path,
+// so it must fail fast on slow/offline networks and must never block on credential
+// prompts (GCM_INTERACTIVE suppresses Git Credential Manager GUI popups on Windows).
+const GIT_PROBE_TIMEOUT = 5000;
+const gitProbeOpts = { timeout: GIT_PROBE_TIMEOUT, env: { ...gitRemoteEnv, GCM_INTERACTIVE: 'never' } };
+
 export const execGitLogFilenames = async (
   directory: string,
   maxCommits = 100,
@@ -105,6 +111,27 @@ export const execLsRemote = async (
   }
 };
 
+/**
+ * Lightweight remote existence probe: only asks for HEAD instead of all refs,
+ * so the response stays tiny even for repositories with thousands of branches/tags.
+ */
+export const execLsRemoteHead = async (
+  url: string,
+  deps = {
+    execFileAsync,
+  },
+): Promise<string> => {
+  validateGitUrl(url);
+
+  try {
+    const result = await deps.execFileAsync('git', ['ls-remote', '--', url, 'HEAD'], gitProbeOpts);
+    return result.stdout || '';
+  } catch (error) {
+    logger.trace('Failed to execute git ls-remote HEAD:', (error as Error).message);
+    throw error;
+  }
+};
+
 export const execGitShallowClone = async (
   url: string,
   directory: string,

src/core/git/gitRemoteHandle.ts

@@ -1,6 +1,29 @@
 import { RepomixError } from '../../shared/errorHandle.js';
 import { logger } from '../../shared/logger.js';
-import { execLsRemote, validateGitUrl } from './gitCommand.js';
+import { execLsRemote, execLsRemoteHead, validateGitUrl } from './gitCommand.js';
+
+/**
+ * Checks if a remote repository exists and is reachable without cloning it.
+ * Uses a HEAD-only `git ls-remote` so the probe is cheap even for large repositories.
+ * Returns false for unreachable, non-existent, or auth-gated repositories
+ * (interactive credential prompts are disabled for remote git commands).
+ */
+export const checkRemoteRepoExists = async (
+  url: string,
+  deps = {
+    execLsRemoteHead,
+  },
+): Promise<boolean> => {
+  validateGitUrl(url);
+
+  try {
+    await deps.execLsRemoteHead(url);
+    return true;
+  } catch (error) {
+    logger.trace(`Remote repository not reachable: ${url}:`, (error as Error).message);
+    return false;
+  }
+};
 
 export const getRemoteRefs = async (
   url: string,

src/core/git/gitRemoteParse.ts

@@ -1,6 +1,7 @@
 import gitUrlParse, { type GitUrl } from 'git-url-parse';
 import { RepomixError } from '../../shared/errorHandle.js';
 import { logger } from '../../shared/logger.js';
+import { isValidShorthand } from './gitRemoteUrl.js';
 
 interface IGitUrl extends GitUrl {
   commit: string | undefined;
@@ -12,12 +13,8 @@ export interface GitHubRepoInfo {
   ref?: string; // branch, tag, or commit SHA
 }
 
-// Check the short form of the GitHub URL. e.g. yamadashy/repomix
-const VALID_NAME_PATTERN = '[a-zA-Z0-9](?:[a-zA-Z0-9._-]*[a-zA-Z0-9])?';
-const validShorthandRegex = new RegExp(`^${VALID_NAME_PATTERN}/${VALID_NAME_PATTERN}$`);
-export const isValidShorthand = (remoteValue: string): boolean => {
-  return validShorthandRegex.test(remoteValue);
-};
+// Re-export from lightweight module to preserve public API
+export { isValidShorthand } from './gitRemoteUrl.js';
 
 /**
  * Check if a URL is an Azure DevOps repository URL by validating the hostname.

src/core/git/gitRemoteUrl.ts

@@ -14,3 +14,17 @@ export const remoteUrlPrefixes = ['https://', 'git@', 'ssh://', 'git://'] as con
 export const isExplicitRemoteUrl = (value: string): boolean => {
   return remoteUrlPrefixes.some((prefix) => value.startsWith(prefix));
 };
+
+// Check the short form of the GitHub URL. e.g. yamadashy/repomix
+const VALID_NAME_PATTERN = '[a-zA-Z0-9](?:[a-zA-Z0-9._-]*[a-zA-Z0-9])?';
+const validShorthandRegex = new RegExp(`^${VALID_NAME_PATTERN}/${VALID_NAME_PATTERN}$`);
+
+/**
+ * Checks if a string matches the GitHub shorthand format (owner/repo).
+ * Note: a relative local path like `src/utils` also matches this pattern,
+ * so callers must disambiguate against the local filesystem before treating
+ * a shorthand match as a remote repository.
+ */
+export const isValidShorthand = (remoteValue: string): boolean => {
+  return validShorthandRegex.test(remoteValue);
+};

tests/cli/cliRun.test.ts

@@ -1,3 +1,4 @@
+import * as fs from 'node:fs/promises';
 import { program } from 'commander';
 import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
 import * as defaultAction from '../../src/cli/actions/defaultAction.js';
@@ -6,6 +7,7 @@ import * as remoteAction from '../../src/cli/actions/remoteAction.js';
 import * as versionAction from '../../src/cli/actions/versionAction.js';
 import { run, runCli } from '../../src/cli/cliRun.js';
 import type { CliOptions } from '../../src/cli/types.js';
+import * as gitRemoteHandle from '../../src/core/git/gitRemoteHandle.js';
 import type { PackResult } from '../../src/core/packager.js';
 import { logger, type RepomixLogLevel, repomixLogLevels } from '../../src/shared/logger.js';
 import { createMockConfig } from '../testing/testUtils.js';
@@ -40,11 +42,25 @@ vi.mock('../../src/shared/logger', () => ({
 vi.mock('../../src/cli/actions/defaultAction');
 vi.mock('../../src/cli/actions/initAction');
 vi.mock('../../src/cli/actions/remoteAction');
+vi.mock('../../src/core/git/gitRemoteHandle');
 vi.mock('../../src/cli/actions/versionAction');
 
+// Partial mock: `access` is spyable for shorthand-detection tests, everything else stays real.
+vi.mock('node:fs/promises', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:fs/promises')>();
+  return {
+    ...actual,
+    access: vi.fn(actual.access),
+  };
+});
+
+const actualFs = await vi.importActual<typeof import('node:fs/promises')>('node:fs/promises');
+
 describe('cliRun', () => {
   beforeEach(() => {
     vi.resetAllMocks();
+    // resetAllMocks clears the default implementation — restore real fs.access behavior.
+    vi.mocked(fs.access).mockImplementation(actualFs.access);
 
     vi.mocked(defaultAction.runDefaultAction).mockResolvedValue({
       config: createMockConfig({
@@ -241,13 +257,66 @@ describe('cliRun', () => {
       expect(defaultAction.runDefaultAction).not.toHaveBeenCalled();
     });
 
-    test('should not auto-detect shorthand format as remote URL', async () => {
+    test('should auto-detect shorthand when no local path exists and the repository is reachable', async () => {
+      vi.mocked(gitRemoteHandle.checkRemoteRepoExists).mockResolvedValue(true);
+
+      await runCli(['user/repo'], process.cwd(), {});
+
+      expect(gitRemoteHandle.checkRemoteRepoExists).toHaveBeenCalledWith('https://github.com/user/repo.git');
+      expect(remoteAction.runRemoteAction).toHaveBeenCalledWith('user/repo', expect.any(Object));
+      expect(defaultAction.runDefaultAction).not.toHaveBeenCalled();
+    });
+
+    test('should fall back to local handling when shorthand is not a reachable repository', async () => {
+      vi.mocked(gitRemoteHandle.checkRemoteRepoExists).mockResolvedValue(false);
+
+      await runCli(['user/repo'], process.cwd(), {});
+
+      expect(gitRemoteHandle.checkRemoteRepoExists).toHaveBeenCalledWith('https://github.com/user/repo.git');
+      expect(defaultAction.runDefaultAction).toHaveBeenCalledWith(['user/repo'], process.cwd(), expect.any(Object));
+      expect(remoteAction.runRemoteAction).not.toHaveBeenCalled();
+    });
+
+    test('should prefer existing local path over shorthand auto-detection', async () => {
+      // Simulate an existing local path that also matches the owner/repo pattern.
+      // Mocking fs.access keeps the test independent of the repository's own directory layout.
+      vi.mocked(fs.access).mockResolvedValue(undefined);
+
       await runCli(['user/repo'], process.cwd(), {});
 
+      expect(gitRemoteHandle.checkRemoteRepoExists).not.toHaveBeenCalled();
       expect(defaultAction.runDefaultAction).toHaveBeenCalledWith(['user/repo'], process.cwd(), expect.any(Object));
       expect(remoteAction.runRemoteAction).not.toHaveBeenCalled();
     });
 
+    test('should treat permission-denied local path as existing and skip the remote probe', async () => {
+      const accessError = Object.assign(new Error('permission denied'), { code: 'EACCES' });
+      vi.mocked(fs.access).mockRejectedValue(accessError);
+
+      await runCli(['user/repo'], process.cwd(), {});
+
+      expect(gitRemoteHandle.checkRemoteRepoExists).not.toHaveBeenCalled();
+      expect(remoteAction.runRemoteAction).not.toHaveBeenCalled();
+      expect(defaultAction.runDefaultAction).toHaveBeenCalledWith(['user/repo'], process.cwd(), expect.any(Object));
+    });
+
+    test('should not treat Windows-style absolute path as shorthand', async () => {
+      // `C:` contains a colon, which the owner/repo pattern rejects — no probe even when missing locally.
+      await runCli(['C:/project'], process.cwd(), {});
+
+      expect(gitRemoteHandle.checkRemoteRepoExists).not.toHaveBeenCalled();
+      expect(remoteAction.runRemoteAction).not.toHaveBeenCalled();
+      expect(defaultAction.runDefaultAction).toHaveBeenCalledWith(['C:/project'], process.cwd(), expect.any(Object));
+    });
+
+    test('should not probe shorthand in stdin mode', async () => {
+      await runCli(['user/repo'], process.cwd(), { stdin: true });
+
+      expect(gitRemoteHandle.checkRemoteRepoExists).not.toHaveBeenCalled();
+      expect(remoteAction.runRemoteAction).not.toHaveBeenCalled();
+      expect(defaultAction.runDefaultAction).toHaveBeenCalledWith(['user/repo'], process.cwd(), expect.any(Object));
+    });
+
     test('should prioritize explicit --remote flag over auto-detected URL', async () => {
       await runCli(['https://github.com/other/repo'], process.cwd(), {
         remote: 'yamadashy/repomix',

tests/core/git/gitCommand.test.ts

@@ -7,6 +7,7 @@ import {
   execGitShallowClone,
   execGitVersion,
   execLsRemote,
+  execLsRemoteHead,
 } from '../../../src/core/git/gitCommand.js';
 import { logger } from '../../../src/shared/logger.js';
 
@@ -17,6 +18,12 @@ const expectGitRemoteOpts = expect.objectContaining({
   env: expect.objectContaining({ GIT_TERMINAL_PROMPT: '0' }),
 });
 
+// The automatic existence probe uses a short timeout and suppresses credential prompts.
+const expectGitProbeOpts = expect.objectContaining({
+  timeout: 5000,
+  env: expect.objectContaining({ GIT_TERMINAL_PROMPT: '0', GCM_INTERACTIVE: 'never' }),
+});
+
 describe('gitCommand', () => {
   beforeEach(() => {
     vi.resetAllMocks();
@@ -434,4 +441,42 @@ c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8\trefs/tags/v1.0.0
       expect(logger.trace).toHaveBeenCalledWith('Failed to execute git ls-remote:', 'git command failed');
     });
   });
+
+  describe('execLsRemoteHead', () => {
+    test('should query only HEAD instead of all refs', async () => {
+      const mockOutput = 'a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6\tHEAD';
+      const mockFileExecAsync = vi.fn().mockResolvedValue({ stdout: mockOutput });
+
+      const result = await execLsRemoteHead('https://github.com/user/repo.git', {
+        execFileAsync: mockFileExecAsync,
+      });
+
+      expect(result).toBe(mockOutput);
+      expect(mockFileExecAsync).toHaveBeenCalledWith(
+        'git',
+        ['ls-remote', '--', 'https://github.com/user/repo.git', 'HEAD'],
+        expectGitProbeOpts,
+      );
+    });
+
+    test('should throw error when git ls-remote HEAD fails', async () => {
+      const mockFileExecAsync = vi.fn().mockRejectedValue(new Error('repository not found'));
+
+      await expect(
+        execLsRemoteHead('https://github.com/user/nonexistent.git', { execFileAsync: mockFileExecAsync }),
+      ).rejects.toThrow('repository not found');
+      expect(logger.trace).toHaveBeenCalledWith('Failed to execute git ls-remote HEAD:', 'repository not found');
+    });
+
+    test('should validate URL before executing', async () => {
+      const mockFileExecAsync = vi.fn();
+
+      await expect(
+        execLsRemoteHead('https://github.com/user/repo.git --upload-pack=evil-command', {
+          execFileAsync: mockFileExecAsync,
+        }),
+      ).rejects.toThrow('Invalid repository URL. URL contains potentially dangerous parameters');
+      expect(mockFileExecAsync).not.toHaveBeenCalled();
+    });
+  });
 });

tests/core/git/gitRemoteHandle.test.ts

@@ -1,5 +1,5 @@
 import { beforeEach, describe, expect, test, vi } from 'vitest';
-import { getRemoteRefs } from '../../../src/core/git/gitRemoteHandle.js';
+import { checkRemoteRepoExists, getRemoteRefs } from '../../../src/core/git/gitRemoteHandle.js';
 import { logger } from '../../../src/shared/logger.js';
 
 vi.mock('../../../src/shared/logger');
@@ -9,6 +9,44 @@ describe('gitRemoteHandle', () => {
     vi.resetAllMocks();
   });
 
+  describe('checkRemoteRepoExists', () => {
+    test('should return true when the repository is reachable', async () => {
+      const mockExecLsRemoteHead = vi.fn().mockResolvedValue('a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6\tHEAD');
+
+      const result = await checkRemoteRepoExists('https://github.com/user/repo.git', {
+        execLsRemoteHead: mockExecLsRemoteHead,
+      });
+
+      expect(result).toBe(true);
+      expect(mockExecLsRemoteHead).toHaveBeenCalledWith('https://github.com/user/repo.git');
+    });
+
+    test('should return false when the repository is not reachable', async () => {
+      const mockExecLsRemoteHead = vi.fn().mockRejectedValue(new Error('Repository not found'));
+
+      const result = await checkRemoteRepoExists('https://github.com/user/nonexistent.git', {
+        execLsRemoteHead: mockExecLsRemoteHead,
+      });
+
+      expect(result).toBe(false);
+      expect(logger.trace).toHaveBeenCalledWith(
+        'Remote repository not reachable: https://github.com/user/nonexistent.git:',
+        'Repository not found',
+      );
+    });
+
+    test('should reject dangerous URLs before probing', async () => {
+      const mockExecLsRemoteHead = vi.fn();
+
+      await expect(
+        checkRemoteRepoExists('https://github.com/user/repo.git --upload-pack=evil-command', {
+          execLsRemoteHead: mockExecLsRemoteHead,
+        }),
+      ).rejects.toThrow('Invalid repository URL. URL contains potentially dangerous parameters');
+      expect(mockExecLsRemoteHead).not.toHaveBeenCalled();
+    });
+  });
+
   describe('getRemoteRefs', () => {
     test('should return refs when URL is valid', async () => {
       const mockOutput = `