@studiometa/forge-cli 0.0.1 → 0.1.0

package/dist/errors.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Error types for forge-cli.
+ *
+ * Provides specific error types for different failure scenarios with
+ * recovery hints for both humans and AI agents.
+ */
+/**
+ * Base error class for all CLI errors.
+ */
+export declare abstract class CliError extends Error {
+    readonly hints?: string[] | undefined;
+    readonly cause?: unknown | undefined;
+    abstract readonly code: string;
+    abstract readonly isRecoverable: boolean;
+    constructor(message: string, hints?: string[] | undefined, cause?: unknown | undefined);
+    toJSON(): Record<string, unknown>;
+    toFormattedMessage(): string;
+}
+export declare class ConfigError extends CliError {
+    readonly code = "CONFIG_ERROR";
+    readonly isRecoverable = true;
+    static missingToken(): ConfigError;
+}
+export declare class ValidationError extends CliError {
+    readonly field?: string | undefined;
+    readonly code = "VALIDATION_ERROR";
+    readonly isRecoverable = true;
+    constructor(message: string, field?: string | undefined, hints?: string[], cause?: unknown);
+    toJSON(): {
+        field: string | undefined;
+    };
+    static required(field: string, hints?: string[]): ValidationError;
+}
+export declare class ApiError extends CliError {
+    readonly statusCode?: number | undefined;
+    readonly code = "API_ERROR";
+    readonly isRecoverable: boolean;
+    constructor(message: string, statusCode?: number | undefined, hints?: string[], cause?: unknown);
+    toJSON(): {
+        statusCode: number | undefined;
+    };
+    static fromForgeError(error: unknown): ApiError;
+}
+export declare function isCliError(error: unknown): error is CliError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,8BAAsB,QAAS,SAAQ,KAAK;aAMxB,KAAK,CAAC,EAAE,MAAM,EAAE;aAChB,KAAK,CAAC,EAAE,OAAO;IANjC,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;gBAGvC,OAAO,EAAE,MAAM,EACC,KAAK,CAAC,EAAE,MAAM,EAAE,YAAA,EAChB,KAAK,CAAC,EAAE,OAAO,YAAA;IAQjC,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAWjC,kBAAkB,IAAI,MAAM;CAO7B;AAID,qBAAa,WAAY,SAAQ,QAAQ;IACvC,QAAQ,CAAC,IAAI,kBAAkB;IAC/B,QAAQ,CAAC,aAAa,QAAQ;IAE9B,MAAM,CAAC,YAAY,IAAI,WAAW;CAOnC;AAID,qBAAa,eAAgB,SAAQ,QAAQ;aAMzB,KAAK,CAAC,EAAE,MAAM;IALhC,QAAQ,CAAC,IAAI,sBAAsB;IACnC,QAAQ,CAAC,aAAa,QAAQ;gBAG5B,OAAO,EAAE,MAAM,EACC,KAAK,CAAC,EAAE,MAAM,YAAA,EAC9B,KAAK,CAAC,EAAE,MAAM,EAAE,EAChB,KAAK,CAAC,EAAE,OAAO;IAKR,MAAM;;;IAIf,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,eAAe;CAGlE;AAID,qBAAa,QAAS,SAAQ,QAAQ;aAMlB,UAAU,CAAC,EAAE,MAAM;IALrC,QAAQ,CAAC,IAAI,eAAe;IAC5B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;gBAG9B,OAAO,EAAE,MAAM,EACC,UAAU,CAAC,EAAE,MAAM,YAAA,EACnC,KAAK,CAAC,EAAE,MAAM,EAAE,EAChB,KAAK,CAAC,EAAE,OAAO;IAMR,MAAM;;;IAIf,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ;CAUhD;AA2BD,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { createContext, createTestContext } from "./context.ts";
+export type { CommandContext, CommandOptions } from "./context.ts";
+export { OutputFormatter } from "./output.ts";
+export type { OutputFormat } from "./types.ts";
+export { CliError, ConfigError, ValidationError, ApiError, isCliError } from "./errors.ts";
+export { handleError, runCommand, ExitCode } from "./error-handler.ts";
+export { getConfig } from "./config.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAChE,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,eAAe,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC3F,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACvE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+import { _ as ConfigError, a as createContext, f as getConfig, g as CliError, h as ApiError, i as runCommand, o as createTestContext, r as handleError, s as OutputFormatter, t as ExitCode, v as ValidationError, y as isCliError } from "./error-handler-BahHMt6t.js";
+export { ApiError, CliError, ConfigError, ExitCode, OutputFormatter, ValidationError, createContext, createTestContext, getConfig, handleError, isCliError, runCommand };

package/dist/output.d.ts

@@ -0,0 +1,47 @@
+import type { OutputFormat } from "./types.ts";
+/**
+ * Output formatter for CLI commands.
+ * Supports human-readable, JSON, and table formats.
+ */
+export declare class OutputFormatter {
+    private format;
+    private noColor;
+    constructor(format?: OutputFormat, noColor?: boolean);
+    /**
+     * Returns true when the current format is JSON.
+     */
+    isJson(): boolean;
+    /**
+     * Output data in the configured format.
+     * Use format='json' for AI agents and structured data.
+     */
+    output(data: unknown): void;
+    /**
+     * Output a list with a human-readable one-liner per item and a table for table format.
+     * Falls back to JSON for json format.
+     *
+     * @param data - Array of items to display
+     * @param columns - Ordered list of field names to include in human/table output
+     * @param emptyMessage - Message shown when data is empty (human format only)
+     * @param lineFormat - Optional custom line formatter for human format
+     */
+    outputList<T extends object>(data: T[], columns: (keyof T & string)[], emptyMessage: string, lineFormat?: (item: T) => string): void;
+    /**
+     * Output a single resource in human-readable format.
+     * For json format, uses JSON.stringify. For table format, uses a two-column key/value table.
+     *
+     * @param data - Object to display
+     * @param fields - Ordered list of fields to display (defaults to all keys)
+     */
+    outputOne<T extends object>(data: T, fields?: (keyof T & string)[]): void;
+    success(message: string): void;
+    error(message: string, details?: unknown): void;
+    warning(message: string): void;
+    info(message: string): void;
+    private outputTable;
+}
+export declare const x: {
+    a: number;
+    b: number;
+};
+//# sourceMappingURL=output.d.ts.map

package/dist/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAI/C;;;GAGG;AACH,qBAAa,eAAe;IAExB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,OAAO;gBADP,MAAM,GAAE,YAAsB,EAC9B,OAAO,GAAE,OAAe;IAGlC;;OAEG;IACH,MAAM,IAAI,OAAO;IAIjB;;;OAGG;IACH,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI;IAe3B;;;;;;;;OAQG;IACH,UAAU,CAAC,CAAC,SAAS,MAAM,EACzB,IAAI,EAAE,CAAC,EAAE,EACT,OAAO,EAAE,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,EAAE,EAC7B,YAAY,EAAE,MAAM,EACpB,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,GAC/B,IAAI;IAsCP;;;;;;OAMG;IACH,SAAS,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,EAAE,GAAG,IAAI;IAyBzE,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAQ9B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI;IAW/C,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAQ9B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAQ3B,OAAO,CAAC,WAAW;CAwBpB;AACD,eAAO,MAAM,CAAC;;;CAAiB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,7 @@
+export type OutputFormat = "json" | "human" | "table";
+export interface CliOptions {
+    format?: OutputFormat;
+    quiet?: boolean;
+    noColor?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAEtD,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB"}

package/dist/utils/args.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Simple argument parser using native Node.js.
+ * Parses process.argv into a structured format with no external deps.
+ */
+export type OptionValue = string | boolean | string[];
+export interface ParsedArgs {
+    command: string[];
+    options: Record<string, OptionValue>;
+    positional: string[];
+}
+export declare function parseArgs(argv?: string[]): ParsedArgs;
+export declare function getOption(options: Record<string, OptionValue>, names: string[], defaultValue?: string): string | undefined;
+export declare function hasFlag(options: Record<string, OptionValue>, names: string[]): boolean;
+//# sourceMappingURL=args.d.ts.map

package/dist/utils/args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/utils/args.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,EAAE,CAAC;AAEtD,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACrC,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,wBAAgB,SAAS,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,UAAU,CAwD5E;AAED,wBAAgB,SAAS,CACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACpC,KAAK,EAAE,MAAM,EAAE,EACf,YAAY,CAAC,EAAE,MAAM,GACpB,MAAM,GAAG,SAAS,CAQpB;AAED,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAEtF"}

package/dist/utils/colors.d.ts

@@ -0,0 +1,17 @@
+/**
+ * ANSI color utilities using native Node.js.
+ * Provides terminal colors without external dependencies.
+ */
+export declare function setColorEnabled(enabled: boolean): void;
+export declare function isColorEnabled(): boolean;
+export declare const colors: {
+    reset: (text: string) => string;
+    bold: (text: string) => string;
+    dim: (text: string) => string;
+    red: (text: string) => string;
+    green: (text: string) => string;
+    yellow: (text: string) => string;
+    cyan: (text: string) => string;
+    gray: (text: string) => string;
+};
+//# sourceMappingURL=colors.d.ts.map

package/dist/utils/colors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"colors.d.ts","sourceRoot":"","sources":["../../src/utils/colors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAiBH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAEtD;AAED,wBAAgB,cAAc,IAAI,OAAO,CAExC;AAOD,eAAO,MAAM,MAAM;kBACH,MAAM;iBACP,MAAM;gBACP,MAAM;gBACN,MAAM;kBACJ,MAAM;mBACL,MAAM;iBACR,MAAM;iBACN,MAAM;CACpB,CAAC"}

package/dist/utils/command-router.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Generic command router factory for CLI commands.
+ *
+ * Eliminates boilerplate switch/case pattern in command routing.
+ *
+ * @example
+ * ```typescript
+ * import { createCommandRouter } from '../../utils/command-router.ts';
+ * import { serversList, serversGet } from './handlers.ts';
+ *
+ * export const handleServersCommand = createCommandRouter({
+ *   resource: 'servers',
+ *   handlers: {
+ *     list: serversList,
+ *     ls: serversList,
+ *     get: [serversGet, 'args'],
+ *   },
+ * });
+ * ```
+ */
+import type { CommandContext } from "../context.ts";
+/**
+ * Handler that only receives context (e.g., list commands)
+ */
+export type ListHandler = (ctx: CommandContext) => Promise<void>;
+/**
+ * Handler that receives args and context (e.g., get/update commands)
+ */
+export type ArgsHandler = (args: string[], ctx: CommandContext) => Promise<void>;
+/**
+ * Handler definition - either a ListHandler or an ArgsHandler marked with 'args'
+ */
+export type Handler = ListHandler | [ArgsHandler, "args"];
+/**
+ * Configuration for the command router
+ */
+export interface CommandRouterConfig {
+    /** Resource name for error messages (e.g., 'servers', 'sites') */
+    resource: string;
+    /** Map of subcommand names to handlers */
+    handlers: Record<string, Handler>;
+}
+/**
+ * Creates a command router function that dispatches to the appropriate handler.
+ */
+export declare function createCommandRouter(config: CommandRouterConfig): (subcommand: string, args: string[], options: Record<string, string | boolean | string[]>) => Promise<void>;
+//# sourceMappingURL=command-router.d.ts.map

package/dist/utils/command-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-router.d.ts","sourceRoot":"","sources":["../../src/utils/command-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAkB,MAAM,eAAe,CAAC;AAMpE;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEjE;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEjF;;GAEG;AACH,MAAM,MAAM,OAAO,GAAG,WAAW,GAAG,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,IAE3D,YAAY,MAAM,EAClB,MAAM,MAAM,EAAE,EACd,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,EAAE,CAAC,KACnD,OAAO,CAAC,IAAI,CAAC,CAqBjB"}

package/dist/utils/resolve.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Smart resolution utilities for --server and --site options.
+ *
+ * Accepts numeric IDs (used as-is) or plain strings (resolved by name/partial match).
+ */
+import type { ExecutorContext } from "@studiometa/forge-core";
+/**
+ * Resolve a --server value to a numeric server ID string.
+ *
+ * - Numeric string → returned as-is (no API call)
+ * - Plain string → fetch all servers, exact match first, then partial match
+ *   - 0 matches → ValidationError listing available servers
+ *   - 2+ matches → ValidationError listing ambiguous matches
+ */
+export declare function resolveServerId(value: string, execCtx: ExecutorContext): Promise<string>;
+/**
+ * Resolve a --site value to a numeric site ID string.
+ *
+ * - Numeric string → returned as-is (no API call)
+ * - Plain string → fetch all sites for the server, exact domain match first, then partial
+ *   - 0 matches → ValidationError listing available sites
+ *   - 2+ matches → ValidationError listing ambiguous matches
+ */
+export declare function resolveSiteId(value: string, serverId: string, execCtx: ExecutorContext): Promise<string>;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/utils/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/utils/resolve.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAI9D;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAoC9F;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,MAAM,CAAC,CAoCjB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@studiometa/forge-cli",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "CLI tool for managing Laravel Forge servers, sites, and deployments",
   "keywords": [
     "ai-agent",
@@ -18,7 +18,47 @@
     "url": "https://github.com/studiometa/forge-tools",
     "directory": "packages/cli"
   },
+  "bin": {
+    "forge-cli": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "dev": "vite build --watch",
+    "build": "vite build && tsc --emitDeclarationOnly",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ci": "vitest run --coverage",
+    "lint": "oxlint src",
+    "format": "oxfmt --write src",
+    "format:check": "oxfmt --check src",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@studiometa/forge-api": "*",
+    "@studiometa/forge-core": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@vitest/coverage-v8": "^4.1.0-beta.4",
+    "typescript": "^5.7.3",
+    "vite": "^8.0.0-beta.14",
+    "vitest": "^4.1.0-beta.4"
+  },
+  "engines": {
+    "node": ">=24.0.0"
   }
 }