@ggui-ai/cli 0.1.0-rc.1

package/dist/dev-command.d.ts

@@ -0,0 +1,169 @@
+/**
+ * `ggui dev` argument parsing + runtime resolution + browser auto-open.
+ *
+ * Extracted from `cli.ts` so the pure logic (flag parsing, agent
+ * entry → command mapping, hub URL resolution, auto-open decision)
+ * is unit-testable without importing the bin's top-level `main()`
+ * side effect. The bin itself stays tiny.
+ *
+ * Browser auto-open lives here (the CLI layer) intentionally —
+ * `@ggui-ai/dev-stack` keeps owning the server/runtime stack; only
+ * the `ggui` binary decides "a human is driving this, open a tab."
+ * Other hosts (the future `guuey dev` shim, a hub spawned from a
+ * tunnel, a test harness) pick their own launch policy.
+ */
+import { type ChildProcess, type SpawnOptions } from 'node:child_process';
+import { buildAgentRuntime, resolveAgentCommand, type AgentCommandResolution } from './agent-resolution.js';
+import type { TunnelContext, TunnelProvider, TunnelSession, TunnelSessionReady, TunnelSessionUnavailable } from './tunnel-provider.js';
+export interface ParsedDevFlags {
+    port?: number;
+    host?: string;
+    noServe: boolean;
+    noOpen: boolean;
+    /**
+     * Opt into managed-mode. When true, the CLI orchestration calls
+     * the configured `TunnelProvider` after the local dev stack is
+     * listening. The local loop always runs unchanged — `--tunnel`
+     * only adds the managed layer above it.
+     */
+    tunnel: boolean;
+    agent?: string;
+    error?: string;
+}
+/**
+ * Parse the raw `ggui dev` argv tail. Returns a discriminated
+ * shape — `error` field is non-undefined when the input was
+ * malformed; callers render it and bail with exit code 1.
+ */
+export declare function parseDevFlags(args: readonly string[]): ParsedDevFlags;
+export { resolveAgentCommand, buildAgentRuntime };
+export type { AgentCommandResolution };
+/**
+ * Build the URL the local hub is reachable at. Normalises
+ * wildcard bind addresses (`0.0.0.0` / `::`) to `127.0.0.1` so
+ * the link is actually clickable — the dev's browser can't dial
+ * `0.0.0.0`. Loopback host binds pass through unchanged.
+ */
+export declare function resolveHubUrl(host: string, port: number): string;
+/** Inputs that drive the auto-open decision. Pure data so tests
+ * exercise every branch without touching real env / stdio. */
+export interface AutoOpenContext {
+    /** `true` when the command is serving a real HTTP port. The
+     * `--no-serve` path never opens anything. */
+    readonly serving: boolean;
+    /** `true` when the user passed `--no-open` — the explicit
+     * escape hatch. Highest-precedence skip reason. */
+    readonly noOpen: boolean;
+    /** Whether the CLI's stdout is attached to an interactive TTY.
+     * Pipelines and detached contexts set this to `false`. */
+    readonly isTty: boolean;
+    /** Process env — read here so tests can substitute. */
+    readonly env: Readonly<Record<string, string | undefined>>;
+}
+/**
+ * Auto-open policy — `shouldAutoOpen` returns a discriminated
+ * decision. The `reason` field is both a test hook and a human
+ * diagnostic the CLI prints when it decides NOT to open. Never
+ * returns an error; the only shape is `{ open: boolean; reason }`.
+ *
+ * Rules (first-match wins):
+ *
+ *   1. `noOpen=true`     → explicit `--no-open`.
+ *   2. `serving=false`   → no server to open.
+ *   3. `CI=<truthy>`     → CI runner; headless by convention.
+ *   4. `BROWSER=none`    → explicit opt-out (create-react-app / expo
+ *                          pattern).
+ *   5. `isTty=false`     → piped / daemonised; probably scripted.
+ *   6. otherwise         → open.
+ */
+export declare function shouldAutoOpen(ctx: AutoOpenContext): {
+    open: boolean;
+    reason: string;
+};
+/**
+ * Browser launcher — best-effort, cross-platform, dep-free.
+ *
+ *   - Honours `$BROWSER` when set (and not `'none'`), so users who
+ *     explicitly pick a browser get their choice.
+ *   - Otherwise delegates to the platform's standard opener:
+ *       darwin  → `open <url>`
+ *       win32   → `cmd /c start "" <url>`   (empty title avoids the
+ *                                            first quoted arg being
+ *                                            consumed as the window
+ *                                            title — a Windows gotcha)
+ *       other   → `xdg-open <url>`
+ *   - Child is spawned detached with stdio ignored so our parent
+ *     process is free to exit / stay alive independently; `unref()`
+ *     ensures the event loop doesn't wait on it.
+ *   - Async spawn errors (ENOENT when `xdg-open` isn't installed on
+ *     a minimal Linux image) are caught on the `error` event — we
+ *     don't surface them because by the time they fire the caller
+ *     has already printed the URL and returned; they're purely
+ *     cosmetic.
+ *
+ * Return value semantics:
+ *   `ok: true`   — spawn was dispatched without a synchronous throw.
+ *                  (Actual browser launch may still fail async.)
+ *   `ok: false`  — synchronous spawn throw (invalid command, etc.).
+ *                  Caller should treat this as "no browser opened"
+ *                  and hint at the URL.
+ */
+export interface LaunchBrowserOptions {
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly platform?: NodeJS.Platform;
+    /** Seam for tests — receives `(cmd, args)` and MUST return a
+     * `ChildProcess`-shaped object with `.on()` + `.unref()`. */
+    readonly spawner?: Spawner;
+}
+type Spawner = (command: string, args: readonly string[], options: SpawnOptions) => ChildProcess;
+export type LaunchBrowserResult = {
+    ok: true;
+    command: string;
+    args: readonly string[];
+} | {
+    ok: false;
+    error: string;
+};
+export declare function launchBrowser(url: string, options?: LaunchBrowserOptions): LaunchBrowserResult;
+/**
+ * Orchestrate a `TunnelProvider.open(ctx)` call.
+ *
+ * Why this exists as a narrow helper:
+ *
+ *   - Keeps `cli.ts` free of provider-result branching — the bin
+ *     just prints the result line and wires `close()` to shutdown.
+ *   - Collapses any thrown error into an `unavailable` session so
+ *     `cli.ts` has a single shape to render. Per contract, a
+ *     well-behaved provider never throws for missing
+ *     configuration; but we defend against a buggy provider to
+ *     preserve the "local dev must never break" invariant.
+ *   - Ignores the `ctx` shape knowledge: callers pass a prepared
+ *     `TunnelContext`, and this function stays pure (no env,
+ *     stdio, or network access).
+ */
+export declare function openTunnel(provider: TunnelProvider, ctx: TunnelContext): Promise<TunnelSession>;
+/**
+ * Describe a `TunnelSession` as lines ready for the CLI banner.
+ * Pure function — no stdio access. Tests pin the exact copy so
+ * banner drift is caught in review.
+ *
+ * Shape:
+ *
+ *   ready       → `[' tunnel  →  https://…']`
+ *   unavailable → `[' tunnel skipped: <reason>', '         hint: <hint>']`
+ *                 (hint line is omitted when `hint` is undefined)
+ */
+export declare function describeTunnelSession(session: TunnelSession): string[];
+/**
+ * Narrow alias surfaces so `cli.ts` can import a single type name
+ * when handling a ready session. Kept here (next to `openTunnel`)
+ * so the CLI doesn't have to reach into the seam module.
+ */
+export type { TunnelProvider, TunnelSession, TunnelSessionReady, TunnelSessionUnavailable, TunnelContext };
+/** Pure command resolver — split out so tests can pin platform
+ * branches without actually spawning. */
+export declare function resolveLaunchCommand(url: string, platform: NodeJS.Platform, env: Readonly<Record<string, string | undefined>>): {
+    command: string;
+    args: readonly string[];
+};
+//# sourceMappingURL=dev-command.d.ts.map

package/dist/dev-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-command.d.ts","sourceRoot":"","sources":["../src/dev-command.ts"],"names":[],"mappings":"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"}

package/dist/dev-command.js

@@ -0,0 +1,222 @@
+/**
+ * `ggui dev` argument parsing + runtime resolution + browser auto-open.
+ *
+ * Extracted from `cli.ts` so the pure logic (flag parsing, agent
+ * entry → command mapping, hub URL resolution, auto-open decision)
+ * is unit-testable without importing the bin's top-level `main()`
+ * side effect. The bin itself stays tiny.
+ *
+ * Browser auto-open lives here (the CLI layer) intentionally —
+ * `@ggui-ai/dev-stack` keeps owning the server/runtime stack; only
+ * the `ggui` binary decides "a human is driving this, open a tab."
+ * Other hosts (the future `guuey dev` shim, a hub spawned from a
+ * tunnel, a test harness) pick their own launch policy.
+ */
+import { spawn as nodeSpawn, } from 'node:child_process';
+import { buildAgentRuntime, resolveAgentCommand, } from './agent-resolution.js';
+/**
+ * Parse the raw `ggui dev` argv tail. Returns a discriminated
+ * shape — `error` field is non-undefined when the input was
+ * malformed; callers render it and bail with exit code 1.
+ */
+export function parseDevFlags(args) {
+    const out = { noServe: false, noOpen: false, tunnel: false };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--no-serve') {
+            out.noServe = true;
+            continue;
+        }
+        if (arg === '--no-open') {
+            out.noOpen = true;
+            continue;
+        }
+        if (arg === '--tunnel') {
+            out.tunnel = true;
+            continue;
+        }
+        if (arg === '--port') {
+            const v = args[++i];
+            if (v === undefined)
+                return { ...out, error: '--port requires a value' };
+            const n = Number(v);
+            if (!Number.isInteger(n) || n < 0 || n > 65535) {
+                return { ...out, error: `--port must be an integer in [0, 65535], got "${v}"` };
+            }
+            out.port = n;
+            continue;
+        }
+        if (arg === '--host') {
+            const v = args[++i];
+            if (v === undefined)
+                return { ...out, error: '--host requires a value' };
+            out.host = v;
+            continue;
+        }
+        if (arg === '--agent') {
+            const v = args[++i];
+            if (v === undefined || v.length === 0) {
+                return { ...out, error: '--agent requires an entry file path' };
+            }
+            out.agent = v;
+            continue;
+        }
+        return { ...out, error: `unknown flag "${arg ?? ''}"` };
+    }
+    return out;
+}
+// Agent-entry resolution + adapter construction live in
+// `./agent-resolution.ts`. They are re-exported here so call sites
+// that reach for these from `dev-command.js` keep working — and
+// because `--agent` is conceptually a dev-command concern, even
+// though the same helpers also back `ggui serve`.
+export { resolveAgentCommand, buildAgentRuntime };
+/**
+ * Build the URL the local hub is reachable at. Normalises
+ * wildcard bind addresses (`0.0.0.0` / `::`) to `127.0.0.1` so
+ * the link is actually clickable — the dev's browser can't dial
+ * `0.0.0.0`. Loopback host binds pass through unchanged.
+ */
+export function resolveHubUrl(host, port) {
+    const safeHost = host === '0.0.0.0' || host === '::' || host === '' ? '127.0.0.1' : host;
+    return `http://${safeHost}:${port}/hub`;
+}
+/**
+ * Auto-open policy — `shouldAutoOpen` returns a discriminated
+ * decision. The `reason` field is both a test hook and a human
+ * diagnostic the CLI prints when it decides NOT to open. Never
+ * returns an error; the only shape is `{ open: boolean; reason }`.
+ *
+ * Rules (first-match wins):
+ *
+ *   1. `noOpen=true`     → explicit `--no-open`.
+ *   2. `serving=false`   → no server to open.
+ *   3. `CI=<truthy>`     → CI runner; headless by convention.
+ *   4. `BROWSER=none`    → explicit opt-out (create-react-app / expo
+ *                          pattern).
+ *   5. `isTty=false`     → piped / daemonised; probably scripted.
+ *   6. otherwise         → open.
+ */
+export function shouldAutoOpen(ctx) {
+    if (ctx.noOpen)
+        return { open: false, reason: '--no-open set' };
+    if (!ctx.serving)
+        return { open: false, reason: '--no-serve set' };
+    const ci = ctx.env.CI;
+    if (ci && ci !== '' && ci !== '0' && ci.toLowerCase() !== 'false') {
+        return { open: false, reason: `CI env detected (CI=${ci})` };
+    }
+    if (ctx.env.BROWSER === 'none') {
+        return { open: false, reason: 'BROWSER=none' };
+    }
+    if (!ctx.isTty) {
+        return { open: false, reason: 'stdout is not a TTY' };
+    }
+    return { open: true, reason: 'interactive dev session' };
+}
+export function launchBrowser(url, options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const spawn = options.spawner ?? nodeSpawn;
+    const resolved = resolveLaunchCommand(url, platform, env);
+    try {
+        const child = spawn(resolved.command, resolved.args, {
+            stdio: 'ignore',
+            detached: true,
+            windowsHide: true,
+        });
+        // Async ENOENT / permission errors arrive here; swallow so they
+        // don't crash the CLI's unhandled-rejection path. The URL is
+        // already on screen.
+        child.on('error', () => {
+            /* best-effort; user still has the URL */
+        });
+        child.unref();
+        return { ok: true, command: resolved.command, args: resolved.args };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/**
+ * Orchestrate a `TunnelProvider.open(ctx)` call.
+ *
+ * Why this exists as a narrow helper:
+ *
+ *   - Keeps `cli.ts` free of provider-result branching — the bin
+ *     just prints the result line and wires `close()` to shutdown.
+ *   - Collapses any thrown error into an `unavailable` session so
+ *     `cli.ts` has a single shape to render. Per contract, a
+ *     well-behaved provider never throws for missing
+ *     configuration; but we defend against a buggy provider to
+ *     preserve the "local dev must never break" invariant.
+ *   - Ignores the `ctx` shape knowledge: callers pass a prepared
+ *     `TunnelContext`, and this function stays pure (no env,
+ *     stdio, or network access).
+ */
+export async function openTunnel(provider, ctx) {
+    try {
+        const session = await provider.open(ctx);
+        // Defensive check — the seam's contract says `open` returns a
+        // discriminated session, but a misbehaving provider could
+        // return `undefined` / a malformed object. Collapse to
+        // `unavailable` rather than letting `cli.ts` crash trying to
+        // read `.status` on a non-object.
+        if (session &&
+            typeof session === 'object' &&
+            'status' in session &&
+            (session.status === 'ready' || session.status === 'unavailable')) {
+            return session;
+        }
+        return {
+            status: 'unavailable',
+            reason: `tunnel provider "${provider.name}" returned an invalid session shape`,
+        };
+    }
+    catch (err) {
+        return {
+            status: 'unavailable',
+            reason: `tunnel provider "${provider.name}" threw: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+/**
+ * Describe a `TunnelSession` as lines ready for the CLI banner.
+ * Pure function — no stdio access. Tests pin the exact copy so
+ * banner drift is caught in review.
+ *
+ * Shape:
+ *
+ *   ready       → `[' tunnel  →  https://…']`
+ *   unavailable → `[' tunnel skipped: <reason>', '         hint: <hint>']`
+ *                 (hint line is omitted when `hint` is undefined)
+ */
+export function describeTunnelSession(session) {
+    if (session.status === 'ready') {
+        return [`  tunnel  →  ${session.remoteUrl}`];
+    }
+    const lines = [`  tunnel skipped: ${session.reason}`];
+    if (session.hint) {
+        lines.push(`          hint: ${session.hint}`);
+    }
+    return lines;
+}
+/** Pure command resolver — split out so tests can pin platform
+ * branches without actually spawning. */
+export function resolveLaunchCommand(url, platform, env) {
+    const custom = env.BROWSER;
+    if (custom && custom !== 'none') {
+        return { command: custom, args: [url] };
+    }
+    if (platform === 'darwin')
+        return { command: 'open', args: [url] };
+    if (platform === 'win32') {
+        // Empty string after 'start' is the window title — without it
+        // Windows treats the URL as the title and drops the real arg.
+        return { command: 'cmd', args: ['/c', 'start', '', url] };
+    }
+    return { command: 'xdg-open', args: [url] };
+}

package/dist/gadget-command.d.ts

@@ -0,0 +1,3 @@
+export declare const GADGET_HELP = "ggui gadget \u2014 author + manage marketplace gadgets\n\nUsage:\n  ggui gadget <subcommand> [options]\n\nSubcommands:\n  create       Scaffold a new gadget repo.\n  publish      Build, sign, and push the gadget in CWD to a marketplace registry.\n  install      Fetch, verify, and register a gadget in ggui.json.\n  search       Search the marketplace registry for gadgets.\n\nRun `ggui gadget <subcommand> --help` for subcommand-specific options.\n";
+export declare function runGadgetCommand(args: readonly string[]): Promise<number>;
+//# sourceMappingURL=gadget-command.d.ts.map

package/dist/gadget-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gadget-command.d.ts","sourceRoot":"","sources":["../src/gadget-command.ts"],"names":[],"mappings":"AAwCA,eAAO,MAAM,WAAW,scAYvB,CAAC;AAEF,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,OAAO,CAAC,MAAM,CAAC,CAoBjB"}

package/dist/gadget-command.js

@@ -0,0 +1,181 @@
+/**
+ * `ggui gadget <create|publish|install|search>` — top-level router for
+ * the marketplace author + consumer surface.
+ *
+ * A thin sibling of `blueprint-command.ts`. Both commands dispatch into
+ * the shared `internal/artifact-*` modules with their own `kind`
+ * discriminator; per-kind state (scaffolders, help text) lives in
+ * sibling files.
+ *
+ * - `create`  — scaffold a new gadget repo (hook + bundle stub).
+ * - `publish` — build, sign, and push to a registry.
+ *               Manifest-kind mismatch surfaces a redirect.
+ * - `install` — fetch, verify, append to ggui.json.
+ * - `search`  — query the registry, hard-locked to `kind=gadget`.
+ */
+import { GADGET_CREATE_HELP, parseGadgetCreateFlags, runGadgetCreate, } from './gadget-create.js';
+import { buildPublishHelp, parseArtifactPublishFlags, runArtifactPublish, } from './internal/artifact-publish.js';
+import { buildInstallHelp, parseArtifactInstallFlags, runArtifactInstall, } from './internal/artifact-install.js';
+import { buildSearchHelp, parseArtifactSearchFlags, runArtifactSearch, } from './internal/artifact-search.js';
+const KIND = 'gadget';
+export const GADGET_HELP = `ggui gadget — author + manage marketplace gadgets
+
+Usage:
+  ggui gadget <subcommand> [options]
+
+Subcommands:
+  create       Scaffold a new gadget repo.
+  publish      Build, sign, and push the gadget in CWD to a marketplace registry.
+  install      Fetch, verify, and register a gadget in ggui.json.
+  search       Search the marketplace registry for gadgets.
+
+Run \`ggui gadget <subcommand> --help\` for subcommand-specific options.
+`;
+export async function runGadgetCommand(args) {
+    const [sub, ...rest] = args;
+    if (!sub || sub === '--help' || sub === '-h') {
+        process.stdout.write(GADGET_HELP);
+        return sub ? 0 : 2;
+    }
+    switch (sub) {
+        case 'create':
+            return runCreate(rest);
+        case 'publish':
+            return runPublish(rest);
+        case 'install':
+            return runInstall(rest);
+        case 'search':
+            return runSearch(rest);
+        default:
+            process.stderr.write(`ggui gadget: unknown subcommand "${sub}"\n\n`);
+            process.stderr.write(GADGET_HELP);
+            return 2;
+    }
+}
+/* -------------------------------------------------------------------------- */
+/* create                                                                     */
+/* -------------------------------------------------------------------------- */
+async function runCreate(args) {
+    const parsed = parseGadgetCreateFlags(args);
+    if (parsed.error === '__help__') {
+        process.stdout.write(GADGET_CREATE_HELP);
+        return 0;
+    }
+    if (parsed.error) {
+        process.stderr.write(`ggui gadget create: ${parsed.error}\n\n`);
+        process.stderr.write(GADGET_CREATE_HELP);
+        return 2;
+    }
+    if (!parsed.flags) {
+        process.stderr.write(`ggui gadget create: failed to parse flags\n`);
+        return 2;
+    }
+    const result = await runGadgetCreate(parsed.flags, { cwd: process.cwd() });
+    return renderCreateResult(result);
+}
+function renderCreateResult(result) {
+    if (!result.ok) {
+        process.stderr.write(`ggui gadget create: ${result.message}\n`);
+        return 1;
+    }
+    process.stdout.write(`\n`);
+    process.stdout.write(`Scaffolded gadget at ${result.targetDir}\n\n`);
+    process.stdout.write(`Files written:\n`);
+    for (const f of result.files) {
+        process.stdout.write(`  - ${f}\n`);
+    }
+    process.stdout.write(`\n`);
+    process.stdout.write(`Hook export: ${result.hook}\n`);
+    process.stdout.write(`Identifier:  ${result.manifest.scope}/${result.manifest.name}@${result.manifest.version}\n`);
+    process.stdout.write(`\nNext steps:\n`);
+    process.stdout.write(`  cd ${result.targetDir}\n`);
+    process.stdout.write(`  pnpm install\n`);
+    process.stdout.write(`  # implement the hook in src/index.ts, then:\n`);
+    process.stdout.write(`  ggui gadget publish\n\n`);
+    return 0;
+}
+/* -------------------------------------------------------------------------- */
+/* publish                                                                    */
+/* -------------------------------------------------------------------------- */
+async function runPublish(args) {
+    const flags = parseArtifactPublishFlags(args);
+    if (flags.help) {
+        process.stdout.write(buildPublishHelp(KIND));
+        return 0;
+    }
+    if (flags.error) {
+        process.stderr.write(`ggui gadget publish: ${flags.error}\n`);
+        return 2;
+    }
+    const result = await runArtifactPublish({
+        kind: KIND,
+        ...(flags.registry !== undefined ? { registry: flags.registry } : {}),
+        dryRun: flags.dryRun,
+        ...(flags.key !== undefined ? { key: flags.key } : {}),
+        ...(flags.auth !== undefined ? { auth: flags.auth } : {}),
+    });
+    return result.exitCode;
+}
+/* -------------------------------------------------------------------------- */
+/* install                                                                    */
+/* -------------------------------------------------------------------------- */
+async function runInstall(args) {
+    const parsed = parseArtifactInstallFlags(KIND, args);
+    if ('error' in parsed) {
+        if (parsed.error === '__help__') {
+            process.stdout.write(buildInstallHelp(KIND));
+            return 0;
+        }
+        process.stderr.write(`ggui gadget install: ${parsed.error}\n\n`);
+        process.stderr.write(buildInstallHelp(KIND));
+        return 2;
+    }
+    return runArtifactInstall(parsed, {
+        cwd: process.cwd(),
+        env: process.env,
+        fetch: globalThis.fetch.bind(globalThis),
+    });
+}
+/* -------------------------------------------------------------------------- */
+/* search                                                                     */
+/* -------------------------------------------------------------------------- */
+async function runSearch(args) {
+    const parsed = parseArtifactSearchFlags(KIND, args);
+    if (parsed.error === '__help__') {
+        process.stdout.write(buildSearchHelp(KIND));
+        return 0;
+    }
+    if (parsed.error) {
+        process.stderr.write(`ggui gadget search: ${parsed.error}\n\n`);
+        process.stderr.write(buildSearchHelp(KIND));
+        return 2;
+    }
+    if (!parsed.flags) {
+        process.stderr.write(`ggui gadget search: failed to parse flags\n`);
+        return 2;
+    }
+    const result = await runArtifactSearch(parsed.flags, {
+        cwd: process.cwd(),
+        env: { GGUI_REGISTRY: process.env['GGUI_REGISTRY'] },
+        fetch: globalThis.fetch.bind(globalThis),
+    });
+    return renderSearchResult(result, parsed.flags.json === true);
+}
+function renderSearchResult(result, json) {
+    if (!result.ok) {
+        process.stderr.write(`ggui gadget search: ${result.message}\n`);
+        return 1;
+    }
+    if (json) {
+        process.stdout.write(`${result.json}\n`);
+        return 0;
+    }
+    if (result.response.results.length === 0) {
+        process.stderr.write('No gadgets found matching the supplied criteria.\n');
+        return 0;
+    }
+    for (const line of result.lines) {
+        process.stdout.write(`${line}\n`);
+    }
+    return 0;
+}