@genrupt/cli 0.1.2 → 0.1.4

package/README.md

@@ -6,14 +6,37 @@ Genrupt CLI for local-file workflows and local MCP clients.
 
 Use this when setting up Genrupt for an agent:
 
+Windows user-local launcher:
+
+```powershell
+powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "irm https://genrupt.com/downloads/genrupt-cli/install.ps1 | iex"
+genrupt agent install
+```
+
+Universal one-time run:
+
 ```bash
 npx -y @genrupt/cli@latest agent install
 ```
 
-This installs or updates the global CLI, checks auth, installs Genrupt skills for the detected agent, and writes a local runtime manifest.
+This checks auth, installs Genrupt skills for the detected agent, and writes a local runtime manifest. The user-local launcher avoids `npm install -g`; the `npx` runtime install still tries to install or update the global CLI, but global npm install failures do not block the skills/runtime setup.
 
 ## Install
 
+User-local launcher without npm global writes:
+
+```powershell
+powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "irm https://genrupt.com/downloads/genrupt-cli/install.ps1 | iex"
+```
+
+macOS/Linux:
+
+```bash
+curl -fsSL https://genrupt.com/downloads/genrupt-cli/install.sh | sh
+```
+
+Optional global npm install:
+
 ```bash
 npm install -g @genrupt/cli
 ```
@@ -52,6 +75,8 @@ genrupt mcp serve
 
 Claude Code can then call Genrupt from chat while the local process can read user-approved local file paths.
 
+If the global `genrupt` command is unavailable, setup registers the bridge through `npx -y @genrupt/cli@latest` so Claude Code can still start it.
+
 ## Doctor
 
 ```bash

package/dist/agent.js

@@ -1,74 +1,72 @@
-import { execFile } from "node:child_process";
-import { readFile } from "node:fs/promises";
-import path from "node:path";
-import { promisify } from "node:util";
 import { getValidConfig, login } from "./auth.js";
 import { DEFAULT_ORIGIN } from "./constants.js";
+import { buildGlobalCliDiagnosticsLines, buildNoGlobalInstallRemediation, clearGlobalCliInstallFailure, collectGlobalCliDiagnostics, getGlobalCliPackageVersion, runCommandDetailed, summarizeCommandFailure, writeGlobalCliInstallFailure, } from "./globalCli.js";
 import { downloadRuntimeManifest, installSkills } from "./skills.js";
 import { classifyCliError, emitRuntimeTelemetry } from "./telemetry.js";
 import { CLI_PACKAGE_NAME, isVersionAtLeast } from "./version.js";
-const execFileAsync = promisify(execFile);
-function binName(command) {
-    return process.platform === "win32" ? `${command}.cmd` : command;
+async function installGlobalCli() {
+    return runCommandDetailed("npm", ["install", "-g", `${CLI_PACKAGE_NAME}@latest`], 180_000);
 }
-async function runCommand(command, args, timeoutMs = 120_000) {
-    try {
-        const result = await execFileAsync(binName(command), args, {
-            encoding: "utf8",
-            timeout: timeoutMs,
-            windowsHide: true,
-        });
-        return result.stdout.trim();
+function printGlobalCliInstallDiagnostics(params) {
+    console.log(`Could not install ${CLI_PACKAGE_NAME}@latest globally.`);
+    console.log(summarizeCommandFailure(params.failure));
+    if (params.failure.stdout) {
+        console.log();
+        console.log("npm stdout:");
+        console.log(params.failure.stdout);
     }
-    catch (error) {
-        const detail = error && typeof error === "object" && "stderr" in error && typeof error.stderr === "string"
-            ? error.stderr.trim()
-            : "";
-        throw new Error(`${command} ${args.join(" ")} failed${detail ? `: ${detail}` : ""}`);
+    if (params.failure.stderr) {
+        console.log();
+        console.log("npm stderr:");
+        console.log(params.failure.stderr);
     }
-}
-async function getGlobalNodeModulesPath() {
-    return runCommand("npm", ["root", "-g"]);
-}
-async function getGlobalCliPackageVersion() {
-    try {
-        const globalRoot = await getGlobalNodeModulesPath();
-        const packageJsonPath = path.join(globalRoot, "@genrupt", "cli", "package.json");
-        const packageJson = JSON.parse(await readFile(packageJsonPath, "utf8"));
-        return typeof packageJson.version === "string" ? packageJson.version : undefined;
+    console.log();
+    console.log("Global npm diagnostics:");
+    for (const line of buildGlobalCliDiagnosticsLines(params.diagnostics)) {
+        console.log(`  ${line}`);
     }
-    catch {
-        return undefined;
+    console.log();
+    for (const line of buildNoGlobalInstallRemediation()) {
+        console.log(line);
     }
-}
-async function installGlobalCli() {
-    await runCommand("npm", ["install", "-g", `${CLI_PACKAGE_NAME}@latest`], 180_000);
+    console.log();
+    console.log("Continuing with the current npx CLI run.");
 }
 async function ensureGlobalCli(minimumVersion) {
     const currentVersion = await getGlobalCliPackageVersion();
     if (currentVersion && isVersionAtLeast(currentVersion, minimumVersion)) {
         console.log(`Genrupt CLI is installed globally (${currentVersion}).`);
-        return;
+        return true;
     }
     const reason = currentVersion
         ? `Global Genrupt CLI ${currentVersion} is below required ${minimumVersion}.`
         : "Genrupt CLI is not installed globally.";
     console.log(reason);
     console.log(`Installing ${CLI_PACKAGE_NAME}@latest globally...`);
-    try {
-        await installGlobalCli();
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        throw new Error(`Could not install ${CLI_PACKAGE_NAME}@latest globally.\n${message}\n` +
-            `Run manually: npm install -g ${CLI_PACKAGE_NAME}@latest`);
+    const installResult = await installGlobalCli();
+    if (!installResult.ok) {
+        const diagnostics = await collectGlobalCliDiagnostics();
+        await writeGlobalCliInstallFailure(installResult, diagnostics).catch(() => { });
+        printGlobalCliInstallDiagnostics({ failure: installResult, diagnostics });
+        return false;
     }
     const nextVersion = await getGlobalCliPackageVersion();
     if (!nextVersion || !isVersionAtLeast(nextVersion, minimumVersion)) {
-        throw new Error(`Global ${CLI_PACKAGE_NAME} did not report a usable version after install.\n` +
-            `Run manually: npm install -g ${CLI_PACKAGE_NAME}@latest`);
+        const diagnostics = await collectGlobalCliDiagnostics();
+        await writeGlobalCliInstallFailure(installResult, diagnostics).catch(() => { });
+        console.log(`Global ${CLI_PACKAGE_NAME} did not report a usable version after install.`);
+        console.log();
+        console.log("Global npm diagnostics:");
+        for (const line of buildGlobalCliDiagnosticsLines(diagnostics)) {
+            console.log(`  ${line}`);
+        }
+        console.log();
+        console.log("Continuing with the current npx CLI run.");
+        return false;
     }
+    await clearGlobalCliInstallFailure().catch(() => { });
     console.log(`Genrupt CLI is installed globally (${nextVersion}).`);
+    return true;
 }
 async function ensureAuth(options) {
     try {
@@ -87,6 +85,7 @@ export async function installAgentRuntime(options = {}) {
     let stage = "download_runtime";
     let runtimeVersion;
     let requiredCliVersion;
+    let globalCliReady = Boolean(options.skipGlobalInstall);
     await emitRuntimeTelemetry({
         eventType: "agent_install_started",
         command: "agent_install",
@@ -102,7 +101,7 @@ export async function installAgentRuntime(options = {}) {
         requiredCliVersion = runtime.requiresCliVersion;
         if (!options.skipGlobalInstall) {
             stage = "global_cli_install";
-            await ensureGlobalCli(runtime.requiresCliVersion);
+            globalCliReady = await ensureGlobalCli(runtime.requiresCliVersion);
         }
         if (!options.skipAuth) {
             stage = "auth";
@@ -128,6 +127,7 @@ export async function installAgentRuntime(options = {}) {
                 stage,
                 skipAuth: Boolean(options.skipAuth),
                 skipGlobalInstall: Boolean(options.skipGlobalInstall),
+                globalCliReady,
             },
         }, { origin });
         throw error;
@@ -142,8 +142,20 @@ export async function installAgentRuntime(options = {}) {
         metadata: {
             skipAuth: Boolean(options.skipAuth),
             skipGlobalInstall: Boolean(options.skipGlobalInstall),
+            globalCliReady,
         },
     }, { origin });
     console.log();
     console.log("Genrupt agent runtime is ready.");
+    if (!globalCliReady) {
+        console.log();
+        console.log("Global CLI install was not completed. Use npx commands on this machine:");
+        console.log(`  npx -y ${CLI_PACKAGE_NAME}@latest doctor`);
+        console.log(`  npx -y ${CLI_PACKAGE_NAME}@latest setup claude-code`);
+        console.log();
+        console.log("To install a user-local launcher without npm global writes:");
+        console.log(`  powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "irm https://genrupt.com/downloads/genrupt-cli/install.ps1 | iex"`);
+        console.log();
+        console.log(`To repair the global npm command later: npm install -g ${CLI_PACKAGE_NAME}@latest`);
+    }
 }

package/dist/constants.js

@@ -3,5 +3,5 @@ export const DEFAULT_MCP_SERVER_URL = `${DEFAULT_ORIGIN}/api/agent/mcp`;
 export const OAUTH_DEVICE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
 export const OAUTH_SCOPE = "mcp";
 export const CLI_CLIENT_NAME = "Genrupt CLI";
-export const CLI_VERSION = "0.1.2";
+export const CLI_VERSION = "0.1.4";
 export const ACCESS_TOKEN_REFRESH_SKEW_MS = 60_000;

package/dist/doctor.js

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import path from "node:path";
 import { getValidConfig } from "./auth.js";
 import { CLI_VERSION } from "./constants.js";
+import { buildNoGlobalInstallRemediation, collectGlobalCliDiagnostics, readGlobalCliInstallFailure, } from "./globalCli.js";
 import { listRemoteMcpTools } from "./mcpClient.js";
 import { GENRUPT_SKILL_NAMES, computeInstalledSkillDigests, defaultTargetForAgent, detectAgent, getInstalledRuntimeManifestPath, readInstalledRuntimeManifest, } from "./skills.js";
 import { emitRuntimeTelemetry } from "./telemetry.js";
@@ -40,6 +41,56 @@ function buildSkillsCheck(params) {
         detail: `Installed for ${params.agent} at ${params.targetRoot}`,
     };
 }
+function buildPackageManagerCheck(diagnostics) {
+    if (diagnostics.npmVersion && diagnostics.npxVersion) {
+        return {
+            label: "Node/npm",
+            status: "ok",
+            detail: `Node ${diagnostics.nodeVersion}, npm ${diagnostics.npmVersion}, npx ${diagnostics.npxVersion}`,
+        };
+    }
+    return {
+        label: "Node/npm",
+        status: "warn",
+        detail: `Node ${diagnostics.nodeVersion}; npm ${diagnostics.npmVersion ?? "unavailable"}; npx ${diagnostics.npxVersion ?? "unavailable"}`,
+        remediation: "Install Node.js 20 or newer with npm/npx enabled.",
+    };
+}
+function buildGlobalCliCheck(diagnostics) {
+    if (diagnostics.globalCliVersion) {
+        if (isVersionNewer(CLI_VERSION, diagnostics.globalCliVersion)) {
+            return {
+                label: "Global CLI",
+                status: "warn",
+                detail: `Global ${CLI_PACKAGE_NAME} ${diagnostics.globalCliVersion} is older than this CLI (${CLI_VERSION}); npm prefix ${diagnostics.npmPrefix ?? "unknown"}`,
+                remediation: buildNoGlobalInstallRemediation().join(" "),
+            };
+        }
+        return {
+            label: "Global CLI",
+            status: "ok",
+            detail: `Global ${CLI_PACKAGE_NAME} ${diagnostics.globalCliVersion}; npm prefix ${diagnostics.npmPrefix ?? "unknown"}`,
+        };
+    }
+    return {
+        label: "Global CLI",
+        status: "warn",
+        detail: `Global ${CLI_PACKAGE_NAME} is not installed; npm prefix ${diagnostics.npmPrefix ?? "unknown"}; npm global root ${diagnostics.npmGlobalRoot ?? "unknown"}`,
+        remediation: buildNoGlobalInstallRemediation().join(" "),
+    };
+}
+function buildLastGlobalInstallFailureCheck(failure) {
+    if (!failure)
+        return null;
+    const status = failure.status === null ? "unknown" : String(failure.status);
+    const output = failure.stderr || failure.stdout || failure.errorMessage || "no output captured";
+    return {
+        label: "Last global install failure",
+        status: "warn",
+        detail: `${failure.command} ${failure.args.join(" ")} failed at ${failure.recordedAt} with exit ${status}: ${output}`,
+        remediation: buildNoGlobalInstallRemediation().join(" "),
+    };
+}
 async function buildRuntimeManifestCheck(targetRoot) {
     const manifest = await readInstalledRuntimeManifest(targetRoot);
     if (!manifest) {
@@ -106,6 +157,13 @@ export async function runDoctor(options = {}) {
         status: "ok",
         detail: `${CLI_PACKAGE_NAME} ${CLI_VERSION}`,
     });
+    const globalCliDiagnostics = await collectGlobalCliDiagnostics();
+    checks.push(buildPackageManagerCheck(globalCliDiagnostics));
+    checks.push(buildGlobalCliCheck(globalCliDiagnostics));
+    const lastInstallFailureCheck = buildLastGlobalInstallFailureCheck(await readGlobalCliInstallFailure());
+    if (lastInstallFailureCheck) {
+        checks.push(lastInstallFailureCheck);
+    }
     try {
         const latestVersion = await fetchLatestCliVersion();
         latestCliVersion = latestVersion;
@@ -115,7 +173,7 @@ export async function runDoctor(options = {}) {
                 label: "CLI update",
                 status: "warn",
                 detail: `Latest published CLI is ${latestVersion}; current is ${CLI_VERSION}`,
-                remediation: `Run: npm install -g ${CLI_PACKAGE_NAME}@latest`,
+                remediation: `Run: npx -y ${CLI_PACKAGE_NAME}@latest agent install`,
             });
         }
         else {

package/dist/globalCli.js

@@ -0,0 +1,189 @@
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { getConfigDir } from "./config.js";
+import { CLI_PACKAGE_NAME } from "./version.js";
+const execFileAsync = promisify(execFile);
+const MAX_CAPTURED_OUTPUT_LENGTH = 4000;
+function resolveCommand(command, args) {
+    if (process.platform !== "win32" || (command !== "npm" && command !== "npx")) {
+        return { command, args };
+    }
+    const cliFileName = command === "npm" ? "npm-cli.js" : "npx-cli.js";
+    const candidates = [
+        path.join(path.dirname(process.execPath), "node_modules", "npm", "bin", cliFileName),
+        process.env.ProgramFiles
+            ? path.join(process.env.ProgramFiles, "nodejs", "node_modules", "npm", "bin", cliFileName)
+            : null,
+        process.env["ProgramFiles(x86)"]
+            ? path.join(process.env["ProgramFiles(x86)"], "nodejs", "node_modules", "npm", "bin", cliFileName)
+            : null,
+    ].filter((candidate) => Boolean(candidate));
+    const cliPath = candidates.find((candidate) => existsSync(candidate));
+    if (cliPath) {
+        return {
+            command: process.execPath,
+            args: [cliPath, ...args],
+        };
+    }
+    return {
+        command: `${command}.cmd`,
+        args,
+        shell: true,
+    };
+}
+function trimCapturedOutput(value) {
+    if (!value)
+        return undefined;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return undefined;
+    return trimmed.slice(0, MAX_CAPTURED_OUTPUT_LENGTH);
+}
+function normalizeStatus(error) {
+    if (error && typeof error === "object") {
+        if ("code" in error && typeof error.code === "number")
+            return error.code;
+        if ("status" in error && typeof error.status === "number")
+            return error.status;
+    }
+    return null;
+}
+function readErrorString(error, key) {
+    if (!error || typeof error !== "object")
+        return "";
+    const value = error[key];
+    return typeof value === "string" ? value : "";
+}
+export async function runCommandDetailed(command, args, timeoutMs = 30_000) {
+    const resolved = resolveCommand(command, args);
+    try {
+        const result = await execFileAsync(resolved.command, resolved.args, {
+            encoding: "utf8",
+            timeout: timeoutMs,
+            windowsHide: true,
+            ...(resolved.shell ? { shell: resolved.shell } : {}),
+        });
+        return {
+            command,
+            args,
+            ok: true,
+            status: 0,
+            stdout: result.stdout.trim(),
+            stderr: result.stderr.trim(),
+        };
+    }
+    catch (error) {
+        return {
+            command,
+            args,
+            ok: false,
+            status: normalizeStatus(error),
+            stdout: readErrorString(error, "stdout").trim(),
+            stderr: readErrorString(error, "stderr").trim(),
+            errorMessage: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+async function getCommandOutput(command, args, timeoutMs = 30_000) {
+    const result = await runCommandDetailed(command, args, timeoutMs);
+    if (result.ok && result.stdout) {
+        return { value: result.stdout };
+    }
+    return {
+        value: undefined,
+        error: summarizeCommandFailure(result),
+    };
+}
+export function summarizeCommandFailure(result) {
+    const status = result.status === null ? "unknown" : String(result.status);
+    const detail = result.stderr || result.stdout || result.errorMessage || "no output";
+    return `${result.command} ${result.args.join(" ")} failed (exit ${status}): ${detail}`;
+}
+export async function getGlobalNodeModulesPath() {
+    const result = await getCommandOutput("npm", ["root", "-g"]);
+    if (!result.value) {
+        throw new Error(result.error ?? "npm root -g failed");
+    }
+    return result.value;
+}
+export async function getGlobalCliPackageVersion() {
+    try {
+        const globalRoot = await getGlobalNodeModulesPath();
+        const packageJsonPath = path.join(globalRoot, "@genrupt", "cli", "package.json");
+        const packageJson = JSON.parse(await readFile(packageJsonPath, "utf8"));
+        return typeof packageJson.version === "string" ? packageJson.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function collectGlobalCliDiagnostics() {
+    const [npmVersion, npxVersion, npmPrefix, npmGlobalRoot] = await Promise.all([
+        getCommandOutput("npm", ["--version"]),
+        getCommandOutput("npx", ["--version"]),
+        getCommandOutput("npm", ["config", "get", "prefix"]),
+        getCommandOutput("npm", ["root", "-g"]),
+    ]);
+    return {
+        nodeVersion: process.version,
+        npmVersion: npmVersion.value,
+        npmVersionError: npmVersion.error,
+        npxVersion: npxVersion.value,
+        npxVersionError: npxVersion.error,
+        npmPrefix: npmPrefix.value,
+        npmPrefixError: npmPrefix.error,
+        npmGlobalRoot: npmGlobalRoot.value,
+        npmGlobalRootError: npmGlobalRoot.error,
+        globalCliVersion: await getGlobalCliPackageVersion(),
+    };
+}
+function getInstallFailurePath() {
+    return path.join(getConfigDir(), "global-cli-install-failure.json");
+}
+export async function writeGlobalCliInstallFailure(result, diagnostics) {
+    await mkdir(getConfigDir(), { recursive: true });
+    const record = {
+        recordedAt: new Date().toISOString(),
+        command: result.command,
+        args: result.args,
+        status: result.status,
+        stdout: trimCapturedOutput(result.stdout),
+        stderr: trimCapturedOutput(result.stderr),
+        errorMessage: trimCapturedOutput(result.errorMessage),
+        diagnostics,
+    };
+    await writeFile(getInstallFailurePath(), `${JSON.stringify(record, null, 2)}\n`, "utf8");
+}
+export async function readGlobalCliInstallFailure() {
+    try {
+        return JSON.parse(await readFile(getInstallFailurePath(), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export async function clearGlobalCliInstallFailure() {
+    await rm(getInstallFailurePath(), { force: true });
+}
+export function buildGlobalCliDiagnosticsLines(diagnostics) {
+    return [
+        `Node: ${diagnostics.nodeVersion}`,
+        `npm: ${diagnostics.npmVersion ?? `unavailable (${diagnostics.npmVersionError ?? "unknown"})`}`,
+        `npx: ${diagnostics.npxVersion ?? `unavailable (${diagnostics.npxVersionError ?? "unknown"})`}`,
+        `npm prefix: ${diagnostics.npmPrefix ?? `unavailable (${diagnostics.npmPrefixError ?? "unknown"})`}`,
+        `npm global root: ${diagnostics.npmGlobalRoot ?? `unavailable (${diagnostics.npmGlobalRootError ?? "unknown"})`}`,
+        `global ${CLI_PACKAGE_NAME}: ${diagnostics.globalCliVersion ?? "not installed"}`,
+    ];
+}
+export function buildNoGlobalInstallRemediation() {
+    return [
+        "Install the user-local launcher without npm global writes:",
+        `  powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "irm https://genrupt.com/downloads/genrupt-cli/install.ps1 | iex"`,
+        "Or keep using npx:",
+        `  npx -y ${CLI_PACKAGE_NAME}@latest doctor`,
+        "If you want the global npm command, check that npm's global prefix is writable or run the install from an elevated terminal.",
+    ];
+}

package/dist/setup.js

@@ -1,14 +1,33 @@
 import { spawnSync } from "node:child_process";
 import { assertLoggedIn } from "./auth.js";
+import { CLI_VERSION } from "./constants.js";
+import { getGlobalCliPackageVersion } from "./globalCli.js";
+import { CLI_PACKAGE_NAME, isVersionAtLeast } from "./version.js";
 function runClaude(args) {
     return spawnSync("claude", args, {
         stdio: "inherit",
         shell: process.platform === "win32",
     });
 }
+async function resolveBridgeCommand() {
+    const globalVersion = await getGlobalCliPackageVersion();
+    if (globalVersion && isVersionAtLeast(globalVersion, CLI_VERSION)) {
+        return {
+            command: ["genrupt", "mcp", "serve"],
+            usingGlobalCli: true,
+            globalVersion,
+        };
+    }
+    return {
+        command: ["npx", "-y", `${CLI_PACKAGE_NAME}@latest`, "mcp", "serve"],
+        usingGlobalCli: false,
+        globalVersion,
+    };
+}
 export async function setupClaudeCode(options = {}) {
     await assertLoggedIn();
     const scope = options.scope ?? "user";
+    const bridgeCommand = await resolveBridgeCommand();
     if (options.replace) {
         runClaude(["mcp", "remove", "genrupt"]);
     }
@@ -21,9 +40,7 @@ export async function setupClaudeCode(options = {}) {
         scope,
         "genrupt",
         "--",
-        "genrupt",
-        "mcp",
-        "serve",
+        ...bridgeCommand.command,
     ];
     const result = runClaude(args);
     if (result.error || result.status !== 0) {
@@ -40,5 +57,10 @@ export async function setupClaudeCode(options = {}) {
     }
     console.log();
     console.log("Genrupt local MCP bridge is installed for Claude Code.");
+    if (!bridgeCommand.usingGlobalCli) {
+        console.log(bridgeCommand.globalVersion
+            ? `Global Genrupt CLI ${bridgeCommand.globalVersion} is below ${CLI_VERSION}, so Claude Code will launch the bridge with npx.`
+            : "No usable global Genrupt CLI was found, so Claude Code will launch the bridge with npx.");
+    }
     console.log("Start a new Claude Code chat, then ask Genrupt to upload local product files or run a workflow.");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genrupt/cli",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Genrupt CLI for OAuth login, local file uploads, and local MCP bridge setup.",
   "license": "MIT",
   "repository": {