@camerontaylor/paseo-cli 0.8.0-fork.1

package/dist/output/types.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Output format types for the Paseo CLI.
+ *
+ * This module defines the structured data types used by the output abstraction layer.
+ * Commands return CommandResult<T> which contains both data and rendering metadata.
+ */
+/** Supported output formats */
+export type OutputFormat = "table" | "json" | "yaml";
+/** Options controlling output rendering */
+export interface OutputOptions {
+    /** Output format (table, json, yaml) */
+    format: OutputFormat;
+    /** Minimal output - IDs only */
+    quiet: boolean;
+    /** Omit table headers */
+    noHeaders: boolean;
+    /** Disable color output */
+    noColor: boolean;
+}
+/** Column definition for table output */
+export interface ColumnDef<T> {
+    /** Header text for the column */
+    header: string;
+    /** Field key or accessor function */
+    field: keyof T | ((item: T) => unknown);
+    /** Optional width hint (characters) */
+    width?: number;
+    /** Optional alignment */
+    align?: "left" | "right" | "center";
+    /** Optional color function - returns chalk color name */
+    color?: (value: unknown, item: T) => string | undefined;
+}
+/** Schema describing how to render command output */
+export interface OutputSchema<T> {
+    /** Field to use for quiet mode (--quiet outputs just this) */
+    idField: keyof T | ((item: T) => string);
+    /** Column definitions for table output */
+    columns: ColumnDef<T>[];
+    /** Optional: custom renderer for human/table output */
+    renderHuman?: (result: AnyCommandResult<T>, options: OutputOptions) => string;
+    /** Optional: transform data before JSON/YAML output */
+    serialize?: (data: T) => unknown;
+}
+/** Result type for commands returning a single item */
+export interface SingleResult<T> {
+    type: "single";
+    /** The structured data to render */
+    data: T;
+    /** Schema describing how to render this data (for item type T) */
+    schema: OutputSchema<T>;
+}
+/** Result type for commands returning a list */
+export interface ListResult<T> {
+    type: "list";
+    /** The structured data to render */
+    data: T[];
+    /** Schema describing how to render this data (for item type T) */
+    schema: OutputSchema<T>;
+}
+/** Union type for all command results */
+export type AnyCommandResult<T> = T extends unknown ? SingleResult<T> | ListResult<T> : never;
+/** Base interface for command results (deprecated, use SingleResult or ListResult) */
+export type CommandResult<T> = SingleResult<T> | ListResult<T>;
+/** Structured error for command failures */
+export interface CommandError {
+    /** Machine-readable error code */
+    code: string;
+    /** Human-readable message */
+    message: string;
+    /** Additional context */
+    details?: unknown;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/output/types.js

@@ -0,0 +1,8 @@
+/**
+ * Output format types for the Paseo CLI.
+ *
+ * This module defines the structured data types used by the output abstraction layer.
+ * Commands return CommandResult<T> which contains both data and rendering metadata.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/output/with-output.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Command wrapper for automatic output rendering.
+ *
+ * Wraps command handlers to automatically render results and handle errors.
+ */
+import type { Command } from "commander";
+import type { AnyCommandResult, OutputOptions } from "./types.js";
+/** Options that include output settings from global options */
+export interface CommandOptions extends Partial<OutputOptions> {
+    /** Daemon host target from --host option */
+    host?: string;
+    /** JSON output flag from --json option */
+    json?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Wrap a command handler to automatically render output.
+ *
+ * The wrapped handler should return a CommandResult. The wrapper will:
+ * 1. Call the handler
+ * 2. Render the result using the appropriate format
+ * 3. Write to stdout
+ * 4. Handle errors by rendering to stderr and exiting with code 1
+ *
+ * @example
+ * ```typescript
+ * program
+ *   .command('list')
+ *   .action(withOutput(async (options) => {
+ *     const data = await fetchData()
+ *     return { type: 'list', data, schema }
+ *   }))
+ * ```
+ */
+export declare function withOutput<T, Args extends unknown[]>(handler: (...args: [...Args, CommandOptions, Command]) => Promise<AnyCommandResult<T>>): (...args: [...Args, CommandOptions, Command]) => Promise<void>;
+/**
+ * Helper to create output options from partial input.
+ * Useful for testing or manual rendering.
+ */
+export declare function createOutputOptions(partial?: Partial<OutputOptions>): OutputOptions;
+//# sourceMappingURL=with-output.d.ts.map

package/dist/output/with-output.js

@@ -0,0 +1,85 @@
+/**
+ * Command wrapper for automatic output rendering.
+ *
+ * Wraps command handlers to automatically render results and handle errors.
+ */
+import { render, renderError, toCommandError, defaultOutputOptions } from "./render.js";
+import { withGlobalOptions } from "../utils/command-options.js";
+function normalizeFormat(raw) {
+    const value = typeof raw === "string" ? raw.trim().toLowerCase() : "";
+    // Common user expectation: "cli" means "table/human"
+    if (value === "cli")
+        return "table";
+    if (value === "table" || value === "json" || value === "yaml")
+        return value;
+    const error = {
+        code: "INVALID_FORMAT",
+        message: `Unsupported output format: ${String(raw)}`,
+        details: "Supported formats: table, json, yaml",
+    };
+    throw error;
+}
+/** Extract output options from command options */
+function extractOutputOptions(options) {
+    const hasStructuredOutputSchema = typeof options.outputSchema === "string" && options.outputSchema.trim().length > 0;
+    if (hasStructuredOutputSchema) {
+        return {
+            format: "json",
+            quiet: false,
+            noHeaders: options.headers === false,
+            noColor: options.color === false,
+        };
+    }
+    return {
+        format: options.json ? "json" : normalizeFormat(options.format ?? defaultOutputOptions.format),
+        quiet: options.quiet ?? defaultOutputOptions.quiet,
+        noHeaders: options.headers === false, // Commander uses --no-headers -> headers: false
+        noColor: options.color === false, // Commander uses --no-color -> color: false
+    };
+}
+/**
+ * Wrap a command handler to automatically render output.
+ *
+ * The wrapped handler should return a CommandResult. The wrapper will:
+ * 1. Call the handler
+ * 2. Render the result using the appropriate format
+ * 3. Write to stdout
+ * 4. Handle errors by rendering to stderr and exiting with code 1
+ *
+ * @example
+ * ```typescript
+ * program
+ *   .command('list')
+ *   .action(withOutput(async (options) => {
+ *     const data = await fetchData()
+ *     return { type: 'list', data, schema }
+ *   }))
+ * ```
+ */
+export function withOutput(handler) {
+    return withGlobalOptions(async (...args) => {
+        const options = args[args.length - 2];
+        const outputOptions = extractOutputOptions(options);
+        try {
+            const result = await handler(...args);
+            const output = render(result, outputOptions);
+            if (output) {
+                process.stdout.write(output + "\n");
+            }
+        }
+        catch (error) {
+            const commandError = toCommandError(error);
+            const errorOutput = renderError(commandError, outputOptions);
+            process.stderr.write(errorOutput + "\n");
+            process.exit(1);
+        }
+    });
+}
+/**
+ * Helper to create output options from partial input.
+ * Useful for testing or manual rendering.
+ */
+export function createOutputOptions(partial = {}) {
+    return { ...defaultOutputOptions, ...partial };
+}
+//# sourceMappingURL=with-output.js.map

package/dist/output/yaml.d.ts

@@ -0,0 +1,11 @@
+/**
+ * YAML renderer for CLI output.
+ *
+ * Renders structured data as YAML for machine consumption and human readability.
+ */
+import type { AnyCommandResult, OutputOptions } from "./types.js";
+/** Render command result as YAML */
+export declare function renderYaml<T>(result: AnyCommandResult<T>, _options: OutputOptions): string;
+/** Render a single item as YAML document (for streaming) */
+export declare function renderYamlDoc<T>(item: T, serialize?: (data: T) => unknown): string;
+//# sourceMappingURL=yaml.d.ts.map

package/dist/output/yaml.js

@@ -0,0 +1,38 @@
+/**
+ * YAML renderer for CLI output.
+ *
+ * Renders structured data as YAML for machine consumption and human readability.
+ */
+import YAML from "yaml";
+/** Render command result as YAML */
+export function renderYaml(result, _options) {
+    const { schema } = result;
+    // Apply custom serializer if provided
+    if (schema.serialize) {
+        if (result.type === "list") {
+            // If all items serialize to the same object, return just one
+            // This handles the case where a list of key-value rows should serialize
+            // to a single structured object
+            const serialized = result.data.map((item) => schema.serialize(item));
+            if (serialized.length > 0) {
+                const first = JSON.stringify(serialized[0]);
+                const allSame = serialized.every((s) => JSON.stringify(s) === first);
+                if (allSame) {
+                    return YAML.stringify(serialized[0]);
+                }
+            }
+            return YAML.stringify(serialized);
+        }
+        else {
+            const serialized = schema.serialize(result.data);
+            return YAML.stringify(serialized);
+        }
+    }
+    return YAML.stringify(result.data);
+}
+/** Render a single item as YAML document (for streaming) */
+export function renderYamlDoc(item, serialize) {
+    const output = serialize ? serialize(item) : item;
+    return YAML.stringify(output);
+}
+//# sourceMappingURL=yaml.js.map

package/dist/run.d.ts

@@ -0,0 +1,14 @@
+export interface RunCliOptions {
+    cwd?: string;
+    nodeArgv?: [string, string];
+}
+export declare function createCliParseArgv(input: {
+    argv: string[];
+    cwd: string;
+    nodeArgv?: [string, string];
+}): string[] | {
+    kind: "open-project";
+    resolvedPath: string;
+};
+export declare function runCli(argv: string[], options?: RunCliOptions): Promise<number>;
+//# sourceMappingURL=run.d.ts.map

package/dist/run.js

@@ -0,0 +1,40 @@
+import { createCli } from "./cli.js";
+import { classifyInvocation } from "./classify.js";
+import { openDesktopWithProject } from "./commands/open.js";
+export function createCliParseArgv(input) {
+    const program = createCli();
+    const knownCommands = new Set(program.commands.map((command) => command.name()));
+    const invocation = classifyInvocation({
+        argv: input.argv,
+        knownCommands,
+        cwd: input.cwd,
+    });
+    if (invocation.kind === "open-project") {
+        return invocation;
+    }
+    const nodeArgv = input.nodeArgv ?? ["paseo", "paseo"];
+    const isOnboardRootFlag = invocation.argv[0] === "--relay" || invocation.argv[0] === "--no-relay";
+    let cliArgv = invocation.argv;
+    if (invocation.argv.length === 0) {
+        cliArgv = ["onboard"];
+    }
+    else if (isOnboardRootFlag) {
+        cliArgv = ["onboard", ...invocation.argv];
+    }
+    return [...nodeArgv, ...cliArgv];
+}
+export async function runCli(argv, options = {}) {
+    const parseArgv = createCliParseArgv({
+        argv,
+        cwd: options.cwd ?? process.cwd(),
+        nodeArgv: options.nodeArgv,
+    });
+    if (!Array.isArray(parseArgv)) {
+        await openDesktopWithProject(parseArgv.resolvedPath);
+        return typeof process.exitCode === "number" ? process.exitCode : 0;
+    }
+    const program = createCli();
+    await program.parseAsync(parseArgv, { from: "node" });
+    return typeof process.exitCode === "number" ? process.exitCode : 0;
+}
+//# sourceMappingURL=run.js.map

package/dist/ssh/ssh-tunnel.d.ts

@@ -0,0 +1,9 @@
+import { type SshTransportTarget } from "@camerontaylor/paseo-protocol/ssh-transport";
+export interface SshTunnel {
+    endpoint: string;
+    close(): void;
+    failureDetail(): string | null;
+}
+export declare function resolveSshFailureDetail(failure: string | null, stderr: string): string | null;
+export declare function createSshTunnel(target: SshTransportTarget): Promise<SshTunnel>;
+//# sourceMappingURL=ssh-tunnel.d.ts.map

package/dist/ssh/ssh-tunnel.js

@@ -0,0 +1,79 @@
+import { spawn } from "node:child_process";
+import { createServer } from "node:net";
+import { buildSshTunnelArgs } from "@camerontaylor/paseo-protocol/ssh-transport";
+const SSH_STDERR_LIMIT = 8192;
+function formatSshFailure(stderr, code, signal) {
+    const detail = stderr.trim();
+    if (detail)
+        return detail;
+    if (signal)
+        return `ssh exited with signal ${signal}`;
+    return `ssh exited with code ${code ?? "unknown"}`;
+}
+export function resolveSshFailureDetail(failure, stderr) {
+    return failure ?? (stderr.trim() || null);
+}
+export function createSshTunnel(target) {
+    let server = null;
+    let socket = null;
+    let child = null;
+    let stderr = "";
+    let failure = null;
+    function close() {
+        server?.close();
+        server = null;
+        socket?.destroy();
+        socket = null;
+        if (child && !child.killed)
+            child.kill();
+        child = null;
+    }
+    return new Promise((resolve, reject) => {
+        server = createServer((acceptedSocket) => {
+            socket = acceptedSocket;
+            server?.close();
+            server = null;
+            child = spawn("ssh", buildSshTunnelArgs(target), {
+                stdio: ["pipe", "pipe", "pipe"],
+                windowsHide: true,
+            });
+            child.stderr.on("data", (chunk) => {
+                stderr = `${stderr}${chunk.toString()}`.slice(-SSH_STDERR_LIMIT);
+            });
+            child.on("error", (error) => {
+                failure = error.message;
+                acceptedSocket.destroy(error);
+            });
+            child.on("exit", (code, signal) => {
+                if (code !== 0 || signal)
+                    failure = formatSshFailure(stderr, code, signal);
+                acceptedSocket.destroy(failure ? new Error(failure) : undefined);
+            });
+            acceptedSocket.on("error", () => undefined);
+            acceptedSocket.on("close", () => {
+                if (child && !child.killed)
+                    child.kill();
+            });
+            acceptedSocket.pipe(child.stdin);
+            child.stdout.pipe(acceptedSocket);
+        });
+        server.once("error", (error) => {
+            close();
+            reject(error);
+        });
+        server.listen(0, "127.0.0.1", () => {
+            const address = server?.address();
+            if (!address || typeof address === "string") {
+                close();
+                reject(new Error("Failed to allocate the SSH tunnel port"));
+                return;
+            }
+            resolve({
+                endpoint: `127.0.0.1:${address.port}`,
+                close,
+                failureDetail: () => resolveSshFailureDetail(failure, stderr),
+            });
+        });
+    });
+}
+//# sourceMappingURL=ssh-tunnel.js.map

package/dist/utils/client-id.d.ts

@@ -0,0 +1,2 @@
+export declare function getOrCreateCliClientId(): Promise<string>;
+//# sourceMappingURL=client-id.d.ts.map

package/dist/utils/client-id.js

@@ -0,0 +1,37 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+const CLIENT_SESSION_KEY_FILE = join(process.env.PASEO_HOME ?? join(homedir(), ".paseo"), "cli-client-id");
+let cachedClientId = null;
+function normalizeClientId(value) {
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function generateClientId() {
+    return `cid_${randomUUID().replace(/-/g, "")}`;
+}
+export async function getOrCreateCliClientId() {
+    if (cachedClientId) {
+        return cachedClientId;
+    }
+    try {
+        const existing = normalizeClientId(await readFile(CLIENT_SESSION_KEY_FILE, "utf8"));
+        if (existing) {
+            cachedClientId = existing;
+            return existing;
+        }
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code !== "ENOENT") {
+            throw error;
+        }
+    }
+    const nextValue = generateClientId();
+    await mkdir(dirname(CLIENT_SESSION_KEY_FILE), { recursive: true });
+    await writeFile(CLIENT_SESSION_KEY_FILE, nextValue, { mode: 0o600 });
+    cachedClientId = nextValue;
+    return nextValue;
+}
+//# sourceMappingURL=client-id.js.map

package/dist/utils/client.d.ts

@@ -0,0 +1,54 @@
+import { DaemonClient } from "@camerontaylor/paseo-client/internal/daemon-client";
+export interface ConnectOptions {
+    host?: string;
+    timeout?: number;
+}
+export interface DaemonConnectionCommandError {
+    code: "DAEMON_NOT_RUNNING";
+    message: string;
+    details: string;
+}
+type DaemonTarget = {
+    type: "tcp";
+    url: string;
+} | {
+    type: "ipc";
+    url: string;
+    socketPath: string;
+};
+/**
+ * Get the daemon host from environment or options
+ */
+export declare function getDaemonHost(options?: ConnectOptions): string;
+export declare function buildDaemonConnectionCommandError(options: {
+    host?: string;
+    error: unknown;
+}): DaemonConnectionCommandError;
+export declare function normalizeDaemonHost(raw: string): string | null;
+export declare function resolveDefaultDaemonHost(env?: NodeJS.ProcessEnv): string;
+export declare function resolveDefaultDaemonHosts(env?: NodeJS.ProcessEnv): string[];
+export declare function getExplicitDaemonHost(host: string | undefined, env?: NodeJS.ProcessEnv): string | undefined;
+export declare function resolveDaemonTarget(host: string): DaemonTarget;
+export declare function resolveDaemonPassword(host: string): string | undefined;
+export declare function connectToDaemon(options?: ConnectOptions): Promise<DaemonClient>;
+/**
+ * Try to connect to the daemon, returns null if connection fails
+ */
+export declare function tryConnectToDaemon(options?: ConnectOptions): Promise<DaemonClient | null>;
+/** Minimal agent type for ID resolution */
+interface AgentLike {
+    id: string;
+    title?: string | null;
+}
+/**
+ * Resolve an agent ID from a partial ID or name.
+ * Supports:
+ * - Full ID match
+ * - Prefix match (first N characters)
+ * - Title/name match (case-insensitive)
+ *
+ * Returns the full agent ID if found, null otherwise.
+ */
+export declare function resolveAgentId(idOrName: string, agents: AgentLike[]): string | null;
+export {};
+//# sourceMappingURL=client.d.ts.map