@genrupt/cli 0.1.0 → 0.1.3

package/README.md

@@ -2,6 +2,16 @@
 
 Genrupt CLI for local-file workflows and local MCP clients.
 
+## Agent Runtime Install
+
+Use this when setting up Genrupt for an agent:
+
+```bash
+npx -y @genrupt/cli@latest agent install
+```
+
+This checks auth, installs Genrupt skills for the detected agent, and writes a local runtime manifest. It also tries to install or update the global CLI, but global npm install failures do not block the skills/runtime setup; use the printed `npx` commands when global npm install is restricted on the machine.
+
 ## Install
 
 ```bash
@@ -42,6 +52,45 @@ 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
+genrupt doctor
+```
+
+Checks CLI freshness, auth, remote MCP reachability, installed skills, and the local Genrupt runtime manifest.
+
+## Runtime Health
+
+The CLI sends small best-effort runtime health events for failed agent installs, stale CLI detection, doctor failures, and upload failures. Events are sanitized and do not include local paths, filenames, prompts, uploaded content, or tokens.
+
+To disable runtime health telemetry on a machine:
+
+```bash
+GENRUPT_DISABLE_TELEMETRY=1 genrupt doctor
+```
+
+## Install Genrupt Skills
+
+Skills provide optional enhanced workflow guidance for agents. They use Genrupt MCP as the
+source of truth and use this CLI/local MCP bridge when a workflow needs private files from the
+user's machine.
+
+```bash
+npx -y @genrupt/cli@latest agent install
+```
+
+Skills-only fallback:
+
+```bash
+npx -y skills add https://genrupt.com
+```
+
+The Genrupt CLI still includes `genrupt skills install` as a compatibility fallback, but the
+standard skills installer is the preferred distribution path.
+
 ## Upload Product Reference Images
 
 ```bash
@@ -54,10 +103,38 @@ Multiple files are supported:
 genrupt upload image "./front.jpg" "./detail.png" --asin B07QF3GNS2 --json
 ```
 
+Folder paths are supported. The CLI uploads JPEG, PNG, and WebP files directly inside the folder:
+
+```bash
+genrupt upload image "./product-photos" --asin B07QF3GNS2 --json
+```
+
 The command creates Genrupt product reference assets and returns `sourceAssetIds` that can be used by product reference sheet workflows.
 
+It also returns `referenceImageUrls`, so the same uploaded images can be passed directly into video tools that expect image reference URLs.
+
+## Upload Reference Media
+
+Use this for custom video reference images, videos, and audio. The CLI auto-detects supported media by extension and returns typed URL arrays for agent tools.
+
+```bash
+genrupt upload media "./reference-video.mp4" --json
+genrupt upload video "./reference-clips" --json
+genrupt upload audio "./voiceover.m4a" --json
+```
+
+Supported reference media: JPEG, PNG, WebP, MP4, MOV, WebM, MP3, WAV, M4A, and OGG, up to 50 MB per file. Folder paths include supported files directly inside the folder.
+
+Use the JSON output fields with `generate_video`:
+
+- `referenceImageUrls` -> `seedanceReferenceImageUrls`
+- `referenceVideoUrls` -> `seedanceReferenceVideoUrls`
+- `referenceAudioUrls` -> `seedanceReferenceAudioUrls`
+
 Remote MCP calls are audited by Genrupt and rate-limited per connected auth source. Product-reference upload capabilities are executed through Genrupt's capability registry, so hidden workflow tools are not directly exposed to stale MCP clients.
 
+Remote-only MCP clients cannot read local file paths. Use this CLI command or the local MCP bridge when the agent is running on the user's machine; otherwise provide direct public URLs or upload through the Genrupt app.
+
 ## Remote MCP Calls
 
 ```bash

package/dist/agent.js

@@ -0,0 +1,163 @@
+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 { 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 runCommand(command, args, timeoutMs = 120_000) {
+    try {
+        const result = await execFileAsync(binName(command), args, {
+            encoding: "utf8",
+            timeout: timeoutMs,
+            windowsHide: true,
+        });
+        return result.stdout.trim();
+    }
+    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}` : ""}`);
+    }
+}
+async function getGlobalNodeModulesPath() {
+    return runCommand("npm", ["root", "-g"]);
+}
+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;
+    }
+}
+async function installGlobalCli() {
+    await runCommand("npm", ["install", "-g", `${CLI_PACKAGE_NAME}@latest`], 180_000);
+}
+async function ensureGlobalCli(minimumVersion) {
+    const currentVersion = await getGlobalCliPackageVersion();
+    if (currentVersion && isVersionAtLeast(currentVersion, minimumVersion)) {
+        console.log(`Genrupt CLI is installed globally (${currentVersion}).`);
+        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);
+        console.log(`Could not install ${CLI_PACKAGE_NAME}@latest globally.\n${message}\n` +
+            "Continuing with the current npx CLI run.");
+        return false;
+    }
+    const nextVersion = await getGlobalCliPackageVersion();
+    if (!nextVersion || !isVersionAtLeast(nextVersion, minimumVersion)) {
+        console.log(`Global ${CLI_PACKAGE_NAME} did not report a usable version after install.\n` +
+            "Continuing with the current npx CLI run.");
+        return false;
+    }
+    console.log(`Genrupt CLI is installed globally (${nextVersion}).`);
+    return true;
+}
+async function ensureAuth(options) {
+    try {
+        const config = await getValidConfig();
+        console.log(`Genrupt CLI is authenticated (${config.origin}).`);
+        return;
+    }
+    catch {
+        console.log("Genrupt CLI is not authenticated.");
+    }
+    await login({ origin: options.origin, noOpen: options.noOpen });
+}
+export async function installAgentRuntime(options = {}) {
+    const origin = (options.origin ?? DEFAULT_ORIGIN).replace(/\/$/, "");
+    const startedAt = Date.now();
+    let stage = "download_runtime";
+    let runtimeVersion;
+    let requiredCliVersion;
+    let globalCliReady = Boolean(options.skipGlobalInstall);
+    await emitRuntimeTelemetry({
+        eventType: "agent_install_started",
+        command: "agent_install",
+        agent: options.agent,
+        metadata: {
+            skipAuth: Boolean(options.skipAuth),
+            skipGlobalInstall: Boolean(options.skipGlobalInstall),
+        },
+    }, { origin });
+    try {
+        const runtime = await downloadRuntimeManifest(origin);
+        runtimeVersion = runtime.version;
+        requiredCliVersion = runtime.requiresCliVersion;
+        if (!options.skipGlobalInstall) {
+            stage = "global_cli_install";
+            globalCliReady = await ensureGlobalCli(runtime.requiresCliVersion);
+        }
+        if (!options.skipAuth) {
+            stage = "auth";
+            await ensureAuth({ origin, noOpen: options.noOpen });
+        }
+        stage = "skills_install";
+        await installSkills({
+            agent: options.agent,
+            target: options.target,
+            origin,
+        });
+    }
+    catch (error) {
+        await emitRuntimeTelemetry({
+            eventType: "agent_install_failed",
+            command: "agent_install",
+            agent: options.agent,
+            runtimeVersion,
+            requiredCliVersion,
+            errorCode: classifyCliError(error, "AGENT_INSTALL_FAILED"),
+            durationMs: Date.now() - startedAt,
+            metadata: {
+                stage,
+                skipAuth: Boolean(options.skipAuth),
+                skipGlobalInstall: Boolean(options.skipGlobalInstall),
+                globalCliReady,
+            },
+        }, { origin });
+        throw error;
+    }
+    await emitRuntimeTelemetry({
+        eventType: "agent_install_succeeded",
+        command: "agent_install",
+        agent: options.agent,
+        runtimeVersion,
+        requiredCliVersion,
+        durationMs: Date.now() - startedAt,
+        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 repair the global command later: npm install -g ${CLI_PACKAGE_NAME}@latest`);
+    }
+}

package/dist/cli.js

@@ -1,11 +1,42 @@
 #!/usr/bin/env node
 import { readFile } from "node:fs/promises";
 import { CLI_VERSION } from "./constants.js";
+import { installAgentRuntime } from "./agent.js";
 import { login, logout, printAuthStatus } from "./auth.js";
 import { callRemoteMcpTool, assertSuccessfulToolPayload } from "./mcpClient.js";
 import { serveLocalMcp } from "./localMcpServer.js";
 import { setupClaudeCode } from "./setup.js";
-import { uploadProductReferenceImages } from "./upload.js";
+import { installSkills } from "./skills.js";
+import { classifyCliError, emitRuntimeTelemetry } from "./telemetry.js";
+import { maybeWarnAboutCliUpdate } from "./updateCheck.js";
+import { uploadProductReferenceImages, uploadReferenceMedia } from "./upload.js";
+import { runDoctor } from "./doctor.js";
+import { CLI_PACKAGE_NAME, fetchLatestCliVersion, isVersionNewer } from "./version.js";
+const UNKNOWN_COMMAND_PREFIX = "Unknown";
+async function buildUnknownCommandUpdateHint() {
+    try {
+        const latestVersion = await fetchLatestCliVersion();
+        if (!latestVersion || !isVersionNewer(latestVersion, CLI_VERSION)) {
+            return "";
+        }
+        const attemptedArgs = process.argv.slice(2).join(" ").trim();
+        const npxCommand = attemptedArgs
+            ? `npx -y ${CLI_PACKAGE_NAME}@latest ${attemptedArgs}`
+            : `npx -y ${CLI_PACKAGE_NAME}@latest --help`;
+        await emitRuntimeTelemetry({
+            eventType: "stale_cli_detected",
+            command: "unknown_command",
+            latestCliVersion: latestVersion,
+            metadata: {
+                attemptedCommand: process.argv[2] ?? "unknown",
+            },
+        });
+        return `\n\nA newer Genrupt CLI is available: ${latestVersion} (installed: ${CLI_VERSION}).\nUpdate your global install:\n  npm install -g ${CLI_PACKAGE_NAME}@latest\nOr run the latest CLI once:\n  ${npxCommand}`;
+    }
+    catch {
+        return "";
+    }
+}
 function parseFlags(args) {
     const flags = {};
     const positionals = [];
@@ -45,10 +76,17 @@ Usage:
   genrupt auth login [--origin https://genrupt.com] [--no-open]
   genrupt auth status
   genrupt auth logout [--local]
+  genrupt version
+
+  genrupt agent install [--agent claude|codex|cursor] [--target PATH] [--skip-auth] [--skip-global-install]
+  genrupt doctor [--agent claude|codex|cursor] [--target PATH] [--json]
 
   genrupt setup claude-code [--replace] [--scope user|project|local]
 
-  genrupt upload image <path...> [--asin ASIN] [--project-id ID] [--product-profile-id ID] [--domain amazon.com] [--json]
+  genrupt upload media <path-or-folder...> [--project-id ID] [--json]
+  genrupt upload video <path-or-folder...> [--project-id ID] [--json]
+  genrupt upload audio <path-or-folder...> [--project-id ID] [--json]
+  genrupt upload image <path-or-folder...> [--asin ASIN] [--project-id ID] [--product-profile-id ID] [--domain amazon.com] [--json]
 
   genrupt mcp serve
   genrupt mcp call <tool_name> '<json_args>'
@@ -56,12 +94,45 @@ Usage:
   genrupt mcp call <tool_name> --json-file ./args.json
 
 Examples:
+  npx -y @genrupt/cli@latest agent install
   genrupt auth login
+  genrupt doctor
   genrupt setup claude-code
-  genrupt upload image "G:\\My Drive\\product.jpg" --asin B07QF3GNS2
+  genrupt upload media "G:\\My Drive\\product-video.mp4" --json
+  genrupt upload video "G:\\My Drive\\reference-clips" --json
+  genrupt upload image "G:\\My Drive\\product-photos" --asin B07QF3GNS2 --json
   genrupt mcp call search_capabilities --query "product reference upload" --includeUnavailable --limit 10
 `);
 }
+async function handleAgent(args) {
+    const subcommand = args[0];
+    const { flags } = parseFlags(args.slice(1));
+    if (subcommand === "install" || subcommand === "update") {
+        await installAgentRuntime({
+            agent: getStringFlag(flags, "agent"),
+            target: getStringFlag(flags, "target"),
+            origin: getStringFlag(flags, "origin"),
+            skipAuth: hasFlag(flags, "skip-auth"),
+            skipGlobalInstall: hasFlag(flags, "skip-global-install"),
+            noOpen: hasFlag(flags, "no-open"),
+        });
+        return;
+    }
+    throw new Error("Unknown agent command. Run `genrupt --help`.");
+}
+async function handleSkills(args) {
+    const subcommand = args[0];
+    const { flags } = parseFlags(args.slice(1));
+    if (subcommand === "install") {
+        await installSkills({
+            agent: getStringFlag(flags, "agent"),
+            target: getStringFlag(flags, "target"),
+            origin: getStringFlag(flags, "origin"),
+        });
+        return;
+    }
+    throw new Error("Unknown skills command. Run `genrupt --help`.");
+}
 async function handleAuth(args) {
     const subcommand = args[0];
     const { flags } = parseFlags(args.slice(1));
@@ -102,10 +173,55 @@ async function handleSetup(args) {
 }
 async function handleUpload(args) {
     const type = args[0];
-    if (type !== "image") {
-        throw new Error("Only `genrupt upload image` is supported.");
+    const startedAt = Date.now();
+    try {
+        await runUpload(args);
+    }
+    catch (error) {
+        await emitRuntimeTelemetry({
+            eventType: "upload_failed",
+            command: `upload_${type ?? "unknown"}`,
+            errorCode: classifyCliError(error, "UPLOAD_FAILED"),
+            durationMs: Date.now() - startedAt,
+            metadata: {
+                uploadType: type ?? "unknown",
+            },
+        });
+        throw error;
     }
+}
+async function runUpload(args) {
+    const type = args[0];
     const { flags, positionals } = parseFlags(args.slice(1));
+    if (type === "media" || type === "video" || type === "audio") {
+        const result = await uploadReferenceMedia({
+            paths: positionals,
+            mode: type,
+            projectId: getStringFlag(flags, "project-id"),
+        });
+        if (hasFlag(flags, "json")) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log();
+        console.log(`Uploaded ${result.uploads.length} media file${result.uploads.length === 1 ? "" : "s"}.`);
+        if (result.referenceImageUrls.length > 0) {
+            console.log(`referenceImageUrls: ${result.referenceImageUrls.join(", ")}`);
+        }
+        if (result.referenceVideoUrls.length > 0) {
+            console.log(`referenceVideoUrls: ${result.referenceVideoUrls.join(", ")}`);
+        }
+        if (result.referenceAudioUrls.length > 0) {
+            console.log(`referenceAudioUrls: ${result.referenceAudioUrls.join(", ")}`);
+        }
+        for (const upload of result.uploads) {
+            console.log(`- ${upload.fileName} (${upload.mediaKind}): ${upload.url}`);
+        }
+        return;
+    }
+    if (type !== "image") {
+        throw new Error("Unknown upload command. Use `genrupt upload media`, `video`, `audio`, or `image`.");
+    }
     const result = await uploadProductReferenceImages({
         paths: positionals,
         asin: getStringFlag(flags, "asin"),
@@ -120,6 +236,7 @@ async function handleUpload(args) {
     console.log();
     console.log(`Uploaded ${result.uploads.length} image${result.uploads.length === 1 ? "" : "s"}.`);
     console.log(`sourceAssetIds: ${result.sourceAssetIds.join(", ") || "(none returned)"}`);
+    console.log(`referenceImageUrls: ${result.referenceImageUrls.join(", ") || "(none returned)"}`);
     for (const upload of result.uploads) {
         console.log(`- ${upload.fileName}: ${upload.assetId ?? "no asset id"} ${upload.imageUrl}`);
     }
@@ -178,14 +295,14 @@ async function handleMcp(args) {
     }
     throw new Error("Unknown mcp command. Run `genrupt --help`.");
 }
-async function main() {
+async function runCommand() {
     const args = process.argv.slice(2);
     const command = args[0];
     if (!command || command === "--help" || command === "-h") {
         printHelp();
         return;
     }
-    if (command === "--version" || command === "-v") {
+    if (command === "--version" || command === "-v" || command === "version") {
         console.log(CLI_VERSION);
         return;
     }
@@ -193,10 +310,27 @@ async function main() {
         await handleAuth(args.slice(1));
         return;
     }
+    if (command === "agent") {
+        await handleAgent(args.slice(1));
+        return;
+    }
+    if (command === "doctor") {
+        const { flags } = parseFlags(args.slice(1));
+        await runDoctor({
+            agent: getStringFlag(flags, "agent"),
+            target: getStringFlag(flags, "target"),
+            json: hasFlag(flags, "json"),
+        });
+        return;
+    }
     if (command === "setup") {
         await handleSetup(args.slice(1));
         return;
     }
+    if (command === "skills") {
+        await handleSkills(args.slice(1));
+        return;
+    }
     if (command === "upload") {
         await handleUpload(args.slice(1));
         return;
@@ -207,7 +341,24 @@ async function main() {
     }
     throw new Error(`Unknown command: ${command}. Run \`genrupt --help\`.`);
 }
-main().catch((error) => {
-    console.error(error instanceof Error ? error.message : String(error));
+async function main() {
+    await runCommand();
+    const command = process.argv[2];
+    if (command &&
+        command !== "--help" &&
+        command !== "-h" &&
+        command !== "--version" &&
+        command !== "-v" &&
+        command !== "version" &&
+        command !== "doctor") {
+        await maybeWarnAboutCliUpdate();
+    }
+}
+main().catch(async (error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    const updateHint = message.startsWith(UNKNOWN_COMMAND_PREFIX)
+        ? await buildUnknownCommandUpdateHint()
+        : "";
+    console.error(`${message}${updateHint}`);
     process.exit(1);
 });

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.0";
+export const CLI_VERSION = "0.1.3";
 export const ACCESS_TOKEN_REFRESH_SKEW_MS = 60_000;