run-repo-script 0.1.0

package/README.md

@@ -0,0 +1,65 @@
+# run-repo
+
+`run-repo` fetches a GitHub repository and runs its installer script with a small, auditable CLI flow.
+
+Package name: `run-repo-script`  
+CLI command: `run-repo`
+
+## Requirements
+
+- Node.js 20+
+- `git` installed and authenticated for the target GitHub repository
+- Runtime for the selected script (`node` or `bash`)
+- `zx` is bundled and used only for explicit zx intent (`--runner zx` or zx shebang)
+
+## Usage
+
+```bash
+run-repo owner/repo
+run-repo owner/repo#v1.2.3
+run-repo https://github.com/owner/repo.git#main
+```
+
+## Install and run
+
+`run-repo-script` is the npm package name.
+`run-repo` is the CLI command installed from that package.
+
+Install globally, then use the command:
+
+```bash
+npm install -g run-repo-script
+run-repo owner/repo
+run-repo owner/repo#v1.2.3
+```
+
+Run directly with npx (no global install). With npx, use the package name:
+
+```bash
+npx run-repo-script owner/repo
+npx run-repo-script owner/repo#v1.2.3
+```
+
+## Example
+
+Run an explicit installer script and forward flags to it:
+
+```bash
+run-repo owner/repo --script scripts/install.sh -- --target local --verbose
+```
+
+Select a runner explicitly:
+
+```bash
+run-repo owner/repo --runner node --dangerously-skip-confirmation
+```
+
+## Safety notes
+
+- The CLI executes code from the fetched repository. Review refs before running.
+- You must confirm execution unless `--dangerously-skip-confirmation` is passed.
+- Clone is non-interactive (`GIT_TERMINAL_PROMPT=0`) to avoid hanging auth prompts.
+- Clone keeps standard GitHub auth token env vars (`GH_TOKEN`, `GITHUB_TOKEN`) so private repository fetches can succeed.
+- Installer execution runs with a strict allowlist environment (for example: `PATH`, `HOME`, temp/locale vars, plus `NO_PROXY` and certificate vars like `SSL_CERT_FILE`, `SSL_CERT_DIR`, and `NODE_EXTRA_CA_CERTS`).
+- Proxy URL vars (`HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`) are forwarded to clone/installer child processes only when they do not contain embedded credentials.
+- `zx` executions are spawned with `ZX_VERBOSE=true` for documented zx verbosity logging.

package/dist/cli.js

@@ -0,0 +1,92 @@
+import { parseArgs } from 'node:util';
+import { rm } from 'node:fs/promises';
+import { pathToFileURL } from 'node:url';
+import { resolveInstaller } from './discovery.js';
+import { executeInstaller } from './execute.js';
+import { fetchRepository } from './fetch.js';
+export function parseRunConfig(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        strict: true,
+        options: {
+            script: {
+                type: 'string'
+            },
+            runner: {
+                type: 'string'
+            },
+            'dangerously-skip-confirmation': {
+                type: 'boolean',
+                default: false
+            },
+            help: {
+                type: 'boolean',
+                default: false
+            }
+        }
+    });
+    const optionTerminatorIndex = argv.indexOf('--');
+    const forwardArgs = optionTerminatorIndex === -1 ? [] : argv.slice(optionTerminatorIndex + 1);
+    const repoTarget = parsed.positionals[0] ?? '';
+    return {
+        repoTarget,
+        script: parsed.values.script,
+        runner: parsed.values.runner,
+        dangerouslySkipConfirmation: parsed.values['dangerously-skip-confirmation'],
+        help: parsed.values.help,
+        forwardArgs
+    };
+}
+function printUsage() {
+    console.log('Usage: run-repo <owner/repo[#ref]|https://github.com/owner/repo[.git][#ref]> [--script <path>] [--runner <node|bash|zx>] [--dangerously-skip-confirmation] [-- <args...>]');
+}
+export async function runCli(argv) {
+    let config;
+    try {
+        config = parseRunConfig(argv);
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        printUsage();
+        return 1;
+    }
+    if (config.help) {
+        printUsage();
+        return 0;
+    }
+    if (!config.repoTarget) {
+        process.stderr.write('Repository target is required.\n');
+        printUsage();
+        return 1;
+    }
+    let workspaceDir;
+    try {
+        const fetchedRepo = await fetchRepository(config.repoTarget);
+        workspaceDir = fetchedRepo.workspaceDir;
+        const script = await resolveInstaller(fetchedRepo.workspaceDir, config.script);
+        return await executeInstaller({
+            repoRoot: fetchedRepo.workspaceDir,
+            script,
+            runnerOverride: config.runner,
+            dangerouslySkipConfirmation: config.dangerouslySkipConfirmation,
+            forwardArgs: config.forwardArgs
+        });
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+    finally {
+        if (workspaceDir) {
+            await rm(workspaceDir, { recursive: true, force: true });
+        }
+    }
+}
+function isDirectExecution() {
+    return (Boolean(process.argv[1]) &&
+        import.meta.url === pathToFileURL(process.argv[1]).href);
+}
+if (isDirectExecution()) {
+    process.exitCode = await runCli(process.argv.slice(2));
+}

package/dist/discovery.js

@@ -0,0 +1,86 @@
+import { realpath, stat } from 'node:fs/promises';
+import path from 'node:path';
+export const DEFAULT_INSTALLER_PATHS = [
+    'install.mjs',
+    'install.js',
+    'install.sh',
+    'scripts/install.mjs',
+    'scripts/install.js',
+    'scripts/install.sh'
+];
+function normalizeRelativeScriptPath(inputPath) {
+    const normalized = path.posix
+        .normalize(inputPath.replaceAll('\\', '/'))
+        .replace(/^\.\//, '');
+    if (path.posix.isAbsolute(normalized) ||
+        normalized === '..' ||
+        normalized.startsWith('../')) {
+        throw new Error('Explicit --script must point to a file inside the fetched repository.');
+    }
+    return normalized;
+}
+async function fileExists(absolutePath) {
+    try {
+        const info = await stat(absolutePath);
+        return info.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function isPathInsideRoot(rootPath, candidatePath) {
+    const relativePath = path.relative(rootPath, candidatePath);
+    return (relativePath === '' ||
+        (!relativePath.startsWith('..') && !path.isAbsolute(relativePath)));
+}
+async function resolveContainedFilePath(repoRootRealPath, absolutePath, rejectOutsideRoot) {
+    let resolvedPath;
+    try {
+        resolvedPath = await realpath(absolutePath);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isPathInsideRoot(repoRootRealPath, resolvedPath)) {
+        if (rejectOutsideRoot) {
+            throw new Error('Explicit --script must resolve to a file inside the fetched repository.');
+        }
+        return undefined;
+    }
+    if (!(await fileExists(resolvedPath))) {
+        return undefined;
+    }
+    return resolvedPath;
+}
+export async function resolveInstaller(repoRoot, explicitScript) {
+    const repoRootRealPath = await realpath(repoRoot);
+    const searchedPaths = [...DEFAULT_INSTALLER_PATHS];
+    if (explicitScript) {
+        const relativePath = normalizeRelativeScriptPath(explicitScript);
+        const absolutePath = path.join(repoRoot, relativePath);
+        const resolvedPath = await resolveContainedFilePath(repoRootRealPath, absolutePath, true);
+        if (!resolvedPath) {
+            throw new Error(`Explicit script not found: ${relativePath}`);
+        }
+        return {
+            absolutePath: resolvedPath,
+            relativePath
+        };
+    }
+    const foundDefaults = [];
+    for (const relativePath of searchedPaths) {
+        const absolutePath = path.join(repoRoot, relativePath);
+        const resolvedPath = await resolveContainedFilePath(repoRootRealPath, absolutePath, false);
+        if (resolvedPath) {
+            foundDefaults.push({ absolutePath: resolvedPath, relativePath });
+        }
+    }
+    if (foundDefaults.length === 1) {
+        return foundDefaults[0];
+    }
+    if (foundDefaults.length === 0) {
+        throw new Error(`No installer script found. Searched: ${searchedPaths.join(', ')}`);
+    }
+    const matched = foundDefaults.map((result) => result.relativePath).join(', ');
+    throw new Error(`Multiple installer scripts found (${matched}). Pass --script to choose exactly one.`);
+}

package/dist/env.js

@@ -0,0 +1,167 @@
+const SENSITIVE_ENV_KEY_PATTERNS = [
+    /^AWS_/i,
+    /^AZURE_/i,
+    /^GCP_/i,
+    /^GOOGLE_/i,
+    /^GITHUB_/i,
+    /^GH_/i,
+    /^NPM_TOKEN$/i,
+    /^NODE_AUTH_TOKEN$/i,
+    /^CI_JOB_TOKEN$/i,
+    /^SSH_AUTH_SOCK$/i,
+    /^SSH_AGENT_PID$/i,
+    /(^|_)(TOKEN|SECRET|PASSWORD|PASSWD|PRIVATE_KEY|API_KEY|AUTH)(_|$)/i
+];
+const INSTALLER_ENV_ALLOWLIST = [
+    'PATH',
+    'HOME',
+    'USER',
+    'LOGNAME',
+    'SHELL',
+    'TERM',
+    'COLORTERM',
+    'NO_COLOR',
+    'FORCE_COLOR',
+    'LANG',
+    'TZ',
+    'HTTP_PROXY',
+    'HTTPS_PROXY',
+    'NO_PROXY',
+    'ALL_PROXY',
+    'SSL_CERT_FILE',
+    'SSL_CERT_DIR',
+    'NODE_EXTRA_CA_CERTS',
+    'TMPDIR',
+    'TMP',
+    'TEMP',
+    'SYSTEMROOT',
+    'WINDIR',
+    'COMSPEC',
+    'PATHEXT',
+    'USERPROFILE',
+    'APPDATA',
+    'LOCALAPPDATA'
+];
+const GIT_CLONE_ENV_ALLOWLIST = [
+    'PATH',
+    'HOME',
+    'USER',
+    'LOGNAME',
+    'SHELL',
+    'LANG',
+    'TZ',
+    'TMPDIR',
+    'TMP',
+    'TEMP',
+    'SYSTEMROOT',
+    'WINDIR',
+    'COMSPEC',
+    'PATHEXT',
+    'USERPROFILE',
+    'APPDATA',
+    'LOCALAPPDATA',
+    'XDG_CONFIG_HOME',
+    'XDG_CACHE_HOME',
+    'XDG_DATA_HOME',
+    'HTTP_PROXY',
+    'HTTPS_PROXY',
+    'NO_PROXY',
+    'ALL_PROXY',
+    'SSL_CERT_FILE',
+    'SSL_CERT_DIR',
+    'GIT_SSL_CAINFO',
+    'GIT_SSL_CAPATH',
+    'GIT_ASKPASS',
+    'SSH_ASKPASS',
+    'SSH_AUTH_SOCK',
+    'SSH_AGENT_PID',
+    'GH_TOKEN',
+    'GITHUB_TOKEN'
+];
+const INSTALLER_ENV_ALLOWLIST_PREFIXES = ['LC_'];
+const INSTALLER_ENV_ALLOWLIST_SET = normalizeKeySet(INSTALLER_ENV_ALLOWLIST);
+const GIT_CLONE_ENV_ALLOWLIST_PREFIXES = ['LC_'];
+const GIT_CLONE_ENV_ALLOWLIST_SET = normalizeKeySet(GIT_CLONE_ENV_ALLOWLIST);
+const INSTALLER_PROXY_URL_ENV_KEYS = normalizeKeySet([
+    'HTTP_PROXY',
+    'HTTPS_PROXY',
+    'ALL_PROXY'
+]);
+function normalizeKeySet(keys) {
+    return new Set(keys.map((key) => key.toUpperCase()));
+}
+function isSensitiveEnvironmentKey(key, allowSensitiveKeys) {
+    if (allowSensitiveKeys.has(key.toUpperCase())) {
+        return false;
+    }
+    return SENSITIVE_ENV_KEY_PATTERNS.some((pattern) => pattern.test(key));
+}
+export function createSafeEnvironment(sourceEnv = process.env, options = {}) {
+    const safeEnv = {};
+    const allowSensitiveKeys = normalizeKeySet(options.allowSensitiveKeys ?? []);
+    for (const [key, value] of Object.entries(sourceEnv)) {
+        if (value === undefined ||
+            isSensitiveEnvironmentKey(key, allowSensitiveKeys)) {
+            continue;
+        }
+        safeEnv[key] = value;
+    }
+    return safeEnv;
+}
+function isInstallerEnvironmentKeyAllowed(key) {
+    const normalizedKey = key.toUpperCase();
+    if (INSTALLER_ENV_ALLOWLIST_SET.has(normalizedKey)) {
+        return true;
+    }
+    return INSTALLER_ENV_ALLOWLIST_PREFIXES.some((prefix) => normalizedKey.startsWith(prefix));
+}
+function isGitCloneEnvironmentKeyAllowed(key) {
+    const normalizedKey = key.toUpperCase();
+    if (GIT_CLONE_ENV_ALLOWLIST_SET.has(normalizedKey)) {
+        return true;
+    }
+    return GIT_CLONE_ENV_ALLOWLIST_PREFIXES.some((prefix) => normalizedKey.startsWith(prefix));
+}
+function hasEmbeddedProxyCredentials(proxyValue) {
+    const trimmedProxyValue = proxyValue.trim();
+    const proxyUrlToParse = trimmedProxyValue.includes('://')
+        ? trimmedProxyValue
+        : `http://${trimmedProxyValue}`;
+    try {
+        const parsedProxyUrl = new URL(proxyUrlToParse);
+        return parsedProxyUrl.username !== '' || parsedProxyUrl.password !== '';
+    }
+    catch {
+        return trimmedProxyValue.includes('@');
+    }
+}
+function shouldDropCredentialBearingProxyEnvironmentKey(key, value) {
+    if (!INSTALLER_PROXY_URL_ENV_KEYS.has(key.toUpperCase())) {
+        return false;
+    }
+    return hasEmbeddedProxyCredentials(value);
+}
+export function createInstallerEnvironment(sourceEnv = process.env) {
+    const safeEnv = {};
+    for (const [key, value] of Object.entries(sourceEnv)) {
+        if (value === undefined ||
+            !isInstallerEnvironmentKeyAllowed(key) ||
+            shouldDropCredentialBearingProxyEnvironmentKey(key, value)) {
+            continue;
+        }
+        safeEnv[key] = value;
+    }
+    return safeEnv;
+}
+export function createGitCloneEnvironment(sourceEnv = process.env) {
+    const safeEnv = {};
+    for (const [key, value] of Object.entries(sourceEnv)) {
+        if (value === undefined ||
+            !isGitCloneEnvironmentKeyAllowed(key) ||
+            shouldDropCredentialBearingProxyEnvironmentKey(key, value)) {
+            continue;
+        }
+        safeEnv[key] = value;
+    }
+    return safeEnv;
+}

package/dist/execute.js

@@ -0,0 +1,205 @@
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { createInstallerEnvironment } from './env.js';
+const require = createRequire(import.meta.url);
+const SUPPORTED_RUNNERS = {
+    node: true,
+    bash: true,
+    zx: true
+};
+const NON_INTERACTIVE_CONFIRMATION_ERROR = 'Confirmation requires an interactive terminal. Re-run with --dangerously-skip-confirmation in non-interactive environments.';
+function toSupportedRunner(candidate) {
+    if (!candidate) {
+        return undefined;
+    }
+    if (candidate in SUPPORTED_RUNNERS) {
+        return candidate;
+    }
+    if (candidate === 'sh') {
+        return 'bash';
+    }
+    return undefined;
+}
+function parseShebangRunner(shebangLine) {
+    const line = shebangLine.trim();
+    if (!line.startsWith('#!')) {
+        return undefined;
+    }
+    const tokens = line.slice(2).trim().split(/\s+/);
+    if (tokens.length === 0) {
+        return undefined;
+    }
+    if (tokens[0].endsWith('/env')) {
+        if (tokens[1] === '-S') {
+            return toSupportedRunner(tokens[2]);
+        }
+        return toSupportedRunner(tokens[1]);
+    }
+    return toSupportedRunner(path.basename(tokens[0]));
+}
+async function readShebang(scriptAbsolutePath) {
+    const content = await readFile(scriptAbsolutePath, 'utf8');
+    const firstLine = content.split(/\r?\n/, 1)[0];
+    return firstLine.startsWith('#!') ? firstLine : undefined;
+}
+function fallbackRunner(scriptRelativePath) {
+    const extension = path.extname(scriptRelativePath);
+    if (extension === '.js' || extension === '.mjs') {
+        return 'node';
+    }
+    if (extension === '.sh') {
+        return 'bash';
+    }
+    return undefined;
+}
+function resolveBundledZxCliPath() {
+    try {
+        const packageJsonPath = require.resolve('zx/package.json');
+        const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+        const binPath = typeof packageJson.bin === 'string'
+            ? packageJson.bin
+            : packageJson.bin?.zx;
+        if (!binPath) {
+            return undefined;
+        }
+        const cliPath = path.join(path.dirname(packageJsonPath), binPath);
+        return existsSync(cliPath) ? cliPath : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function resolveRunnerCommand(runner) {
+    if (runner !== 'zx') {
+        return {
+            command: runner,
+            preArgs: []
+        };
+    }
+    const bundledZxCliPath = resolveBundledZxCliPath();
+    if (!bundledZxCliPath) {
+        throw new Error('Bundled zx runtime is not available in this installation. Reinstall run-repo-script.');
+    }
+    return {
+        command: process.execPath,
+        preArgs: [bundledZxCliPath]
+    };
+}
+function unavailableRunnerMessage(runner) {
+    if (runner === 'zx') {
+        return 'Bundled zx runtime is not available in this installation. Reinstall run-repo-script.';
+    }
+    return `Runner "${runner}" is not available on this host. Install it or use --runner with an available runtime.`;
+}
+export async function resolveRunner(scriptAbsolutePath, scriptRelativePath, runnerOverride) {
+    const override = toSupportedRunner(runnerOverride);
+    if (runnerOverride && !override) {
+        throw new Error(`Unsupported --runner value: ${runnerOverride}. Supported values: node, bash, zx.`);
+    }
+    if (override) {
+        return override;
+    }
+    const shebang = await readShebang(scriptAbsolutePath);
+    const shebangRunner = shebang ? parseShebangRunner(shebang) : undefined;
+    if (shebangRunner) {
+        return shebangRunner;
+    }
+    const fallback = fallbackRunner(scriptRelativePath);
+    if (fallback) {
+        return fallback;
+    }
+    throw new Error(`Unable to determine runner for script: ${scriptRelativePath}. Use --runner <node|bash|zx>.`);
+}
+export async function isRunnerAvailable(runner) {
+    if (runner === 'zx') {
+        return resolveBundledZxCliPath() !== undefined;
+    }
+    return await new Promise((resolve) => {
+        const child = spawn(runner, ['--version'], { stdio: 'ignore' });
+        child.on('error', () => resolve(false));
+        child.on('close', (code) => resolve(code === 0));
+    });
+}
+async function confirmExecution(runner, scriptRelativePath, forwardArgs) {
+    if (!process.stdin.isTTY ||
+        !process.stdout.isTTY ||
+        process.stdin.destroyed ||
+        process.stdin.readableEnded) {
+        throw new Error(NON_INTERACTIVE_CONFIRMATION_ERROR);
+    }
+    const argsText = forwardArgs.length > 0 ? ` ${forwardArgs.join(' ')}` : '';
+    const question = `About to run: ${runner} ${scriptRelativePath}${argsText}\nContinue? [Y/n] `;
+    const readline = createInterface({
+        input: process.stdin,
+        output: process.stdout
+    });
+    try {
+        const answer = await readline.question(question);
+        return isConfirmationAccepted(answer);
+    }
+    finally {
+        readline.close();
+    }
+}
+export function isConfirmationAccepted(answer) {
+    const normalizedAnswer = answer.trim().toLowerCase();
+    return (normalizedAnswer === '' ||
+        normalizedAnswer === 'y' ||
+        normalizedAnswer === 'yes');
+}
+function toRunnerScriptPath(scriptRelativePath) {
+    if (scriptRelativePath.startsWith('./')) {
+        return scriptRelativePath;
+    }
+    return `./${scriptRelativePath}`;
+}
+async function runInstaller(runner, options) {
+    const runnerCommand = resolveRunnerCommand(runner);
+    const args = [
+        ...runnerCommand.preArgs,
+        toRunnerScriptPath(options.script.relativePath),
+        ...options.forwardArgs
+    ];
+    return await new Promise((resolve, reject) => {
+        const child = spawn(runnerCommand.command, args, {
+            cwd: options.repoRoot,
+            stdio: 'inherit',
+            env: createRunnerEnvironment(runner)
+        });
+        child.on('error', (error) => {
+            reject(new Error(`Failed to start installer process: ${error.message}`));
+        });
+        child.on('close', (code, signal) => {
+            if (signal) {
+                reject(new Error(`Installer process terminated by signal: ${signal}`));
+                return;
+            }
+            resolve(code ?? 1);
+        });
+    });
+}
+export function createRunnerEnvironment(runner, sourceEnv = process.env) {
+    const env = createInstallerEnvironment(sourceEnv);
+    if (runner === 'zx') {
+        env.ZX_VERBOSE = 'true';
+    }
+    return env;
+}
+export async function executeInstaller(options) {
+    const runner = await resolveRunner(options.script.absolutePath, options.script.relativePath, options.runnerOverride);
+    const available = await isRunnerAvailable(runner);
+    if (!available) {
+        throw new Error(unavailableRunnerMessage(runner));
+    }
+    if (!options.dangerouslySkipConfirmation) {
+        const confirmed = await confirmExecution(runner, options.script.relativePath, options.forwardArgs);
+        if (!confirmed) {
+            throw new Error('Execution cancelled by user.');
+        }
+    }
+    return await runInstaller(runner, options);
+}

package/dist/fetch.js

@@ -0,0 +1,111 @@
+import { spawn } from 'node:child_process';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createGitCloneEnvironment } from './env.js';
+const SHORTHAND_REGEX = /^(?<owner>[A-Za-z0-9_.-]+)\/(?<repo>[A-Za-z0-9_.-]+)(?:#(?<ref>.+))?$/;
+const HTTPS_PATH_REGEX = /^(?<owner>[A-Za-z0-9_.-]+)\/(?<repo>[A-Za-z0-9_.-]+?)(?:\.git)?$/;
+const SSH_STYLE_REGEX = /^(git@|ssh:\/\/)/i;
+export const SAFE_GIT_ENV = {
+    GIT_TERMINAL_PROMPT: '0',
+    GIT_SSH_COMMAND: 'ssh -o BatchMode=yes',
+    GCM_INTERACTIVE: 'never'
+};
+export function resolveGitHubTarget(input) {
+    const target = input.trim();
+    if (!target) {
+        throw new Error('Repository target is required.');
+    }
+    if (SSH_STYLE_REGEX.test(target)) {
+        throw new Error('Unsupported repository target: SSH syntax is not supported in v1. Use owner/repo or https://github.com/...');
+    }
+    const shorthandMatch = SHORTHAND_REGEX.exec(target);
+    if (shorthandMatch?.groups) {
+        const { owner, repo, ref } = shorthandMatch.groups;
+        return {
+            owner,
+            repo,
+            ref,
+            cloneUrl: `https://github.com/${owner}/${repo}.git`
+        };
+    }
+    let parsed;
+    try {
+        parsed = new URL(target);
+    }
+    catch {
+        throw new Error('Unsupported repository target. Use owner/repo[#ref] or https://github.com/owner/repo[.git][#ref].');
+    }
+    if (parsed.protocol !== 'https:') {
+        throw new Error('Unsupported repository target: only HTTPS GitHub URLs are supported in v1.');
+    }
+    if (parsed.hostname !== 'github.com') {
+        throw new Error('Unsupported repository host. Only github.com is supported in v1.');
+    }
+    const pathname = parsed.pathname.replace(/^\/+|\/+$/g, '');
+    const pathMatch = HTTPS_PATH_REGEX.exec(pathname);
+    if (!pathMatch?.groups) {
+        throw new Error('Unsupported GitHub URL format. Expected https://github.com/owner/repo[.git][#ref].');
+    }
+    const { owner, repo } = pathMatch.groups;
+    const ref = parsed.hash
+        ? decodeURIComponent(parsed.hash.slice(1))
+        : undefined;
+    return {
+        owner,
+        repo,
+        ref,
+        cloneUrl: `https://github.com/${owner}/${repo}.git`
+    };
+}
+export function createGitCloneCommand(resolvedTarget, destinationDir) {
+    const args = ['clone', '--depth', '1'];
+    if (resolvedTarget.ref) {
+        args.push('--branch', resolvedTarget.ref, '--single-branch');
+    }
+    args.push(resolvedTarget.cloneUrl, destinationDir);
+    return {
+        command: 'git',
+        args,
+        env: {
+            ...createGitCloneEnvironment(process.env),
+            ...SAFE_GIT_ENV
+        }
+    };
+}
+export async function cloneIntoDirectory(resolvedTarget, destinationDir) {
+    const command = createGitCloneCommand(resolvedTarget, destinationDir);
+    await new Promise((resolve, reject) => {
+        const child = spawn(command.command, command.args, {
+            env: command.env,
+            stdio: ['ignore', 'pipe', 'pipe']
+        });
+        let stderr = '';
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.on('error', (error) => {
+            reject(new Error(`Failed to launch git clone: ${error.message}`));
+        });
+        child.on('close', (code) => {
+            if (code === 0) {
+                resolve();
+                return;
+            }
+            const stderrLine = stderr.trim();
+            reject(new Error(`git clone failed with exit code ${code ?? 'unknown'}${stderrLine ? `: ${stderrLine}` : ''}`));
+        });
+    });
+}
+export async function fetchRepository(target) {
+    const resolvedTarget = resolveGitHubTarget(target);
+    const workspaceDir = await mkdtemp(join(tmpdir(), 'run-repo-'));
+    try {
+        await cloneIntoDirectory(resolvedTarget, workspaceDir);
+        return { workspaceDir, resolvedTarget };
+    }
+    catch (error) {
+        await rm(workspaceDir, { recursive: true, force: true });
+        throw error;
+    }
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "run-repo-script",
+  "version": "0.1.0",
+  "description": "Fetch a GitHub repository and run its installer script",
+  "type": "module",
+  "packageManager": "pnpm@10.13.1",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "bin": {
+    "run-repo": "dist/cli.js"
+  },
+  "scripts": {
+    "prebuild": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "pnpm build",
+    "prepublishOnly": "pnpm check",
+    "pack:check": "node scripts/validate-pack.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test:unit": "vitest run --dir test/unit",
+    "test:smoke": "vitest run --dir test/smoke",
+    "test": "pnpm test:unit && pnpm test:smoke",
+    "lint": "eslint . --max-warnings=0",
+    "format": "prettier --check .",
+    "format:write": "prettier --write .",
+    "check": "pnpm format && pnpm lint && pnpm typecheck && pnpm build && pnpm pack:check && pnpm test",
+    "prepare": "husky"
+  },
+  "keywords": [
+    "cli",
+    "installer",
+    "github"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.4",
+    "@types/node": "^26.0.1",
+    "@typescript-eslint/eslint-plugin": "^8.62.0",
+    "@typescript-eslint/parser": "^8.62.0",
+    "@vitest/eslint-plugin": "^1.6.20",
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^16.5.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.4.0",
+    "prettier": "^3.8.4",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.9"
+  },
+  "dependencies": {
+    "zx": "^8.8.5"
+  }
+}