@soederpop/luca 0.1.2 → 0.2.1

package/dist/node/features/networking.d.ts

@@ -0,0 +1,373 @@
+import { z } from 'zod';
+import { Feature } from '../feature.js';
+export declare const LocalNetworkSchema: z.ZodObject<{
+    interface: z.ZodString;
+    address: z.ZodString;
+    netmask: z.ZodString;
+    cidr: z.ZodString;
+    mac: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type LocalNetwork = z.infer<typeof LocalNetworkSchema>;
+export declare const ArpEntrySchema: z.ZodObject<{
+    ip: z.ZodString;
+    mac: z.ZodOptional<z.ZodString>;
+    interface: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ArpEntry = z.infer<typeof ArpEntrySchema>;
+export declare const DiscoverHostSchema: z.ZodObject<{
+    ip: z.ZodString;
+    mac: z.ZodOptional<z.ZodString>;
+    reachable: z.ZodBoolean;
+    method: z.ZodEnum<{
+        arp: "arp";
+        tcp: "tcp";
+    }>;
+}, z.core.$strip>;
+export type DiscoverHost = z.infer<typeof DiscoverHostSchema>;
+export declare const PortScanResultSchema: z.ZodObject<{
+    port: z.ZodNumber;
+    status: z.ZodEnum<{
+        open: "open";
+        closed: "closed";
+        filtered: "filtered";
+    }>;
+    service: z.ZodOptional<z.ZodString>;
+    banner: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PortScanResult = z.infer<typeof PortScanResultSchema>;
+export declare const LocalNetworkScanHostSchema: z.ZodObject<{
+    ip: z.ZodString;
+    mac: z.ZodOptional<z.ZodString>;
+    hostname: z.ZodOptional<z.ZodString>;
+    openPorts: z.ZodArray<z.ZodObject<{
+        port: z.ZodNumber;
+        status: z.ZodEnum<{
+            open: "open";
+            closed: "closed";
+            filtered: "filtered";
+        }>;
+        service: z.ZodOptional<z.ZodString>;
+        banner: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type LocalNetworkScanHost = z.infer<typeof LocalNetworkScanHostSchema>;
+export declare const NetworkSnapshotSchema: z.ZodObject<{
+    cidr: z.ZodString;
+    hosts: z.ZodArray<z.ZodObject<{
+        ip: z.ZodString;
+        mac: z.ZodOptional<z.ZodString>;
+        hostname: z.ZodOptional<z.ZodString>;
+        openPorts: z.ZodArray<z.ZodObject<{
+            port: z.ZodNumber;
+            status: z.ZodEnum<{
+                open: "open";
+                closed: "closed";
+                filtered: "filtered";
+            }>;
+            service: z.ZodOptional<z.ZodString>;
+            banner: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type NetworkSnapshot = z.infer<typeof NetworkSnapshotSchema>;
+export declare const NetworkingEventsSchema: z.ZodObject<{
+    stateChange: z.ZodTuple<[z.ZodAny], null>;
+    enabled: z.ZodTuple<[], null>;
+    'host:discovered': z.ZodTuple<[z.ZodObject<{
+        ip: z.ZodString;
+        mac: z.ZodOptional<z.ZodString>;
+        reachable: z.ZodBoolean;
+        method: z.ZodEnum<{
+            arp: "arp";
+            tcp: "tcp";
+        }>;
+    }, z.core.$strip>], null>;
+    'port:open': z.ZodTuple<[z.ZodObject<{
+        host: z.ZodString;
+        port: z.ZodNumber;
+        service: z.ZodOptional<z.ZodString>;
+        banner: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>], null>;
+    'scan:start': z.ZodTuple<[z.ZodObject<{
+        target: z.ZodString;
+        type: z.ZodString;
+    }, z.core.$strip>], null>;
+    'scan:complete': z.ZodTuple<[z.ZodObject<{
+        target: z.ZodString;
+        type: z.ZodString;
+        duration: z.ZodNumber;
+        hostsFound: z.ZodNumber;
+        portsFound: z.ZodNumber;
+    }, z.core.$strip>], null>;
+}, z.core.$strip>;
+export declare const NetworkingStateSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    lastScan: z.ZodOptional<z.ZodObject<{
+        timestamp: z.ZodNumber;
+        target: z.ZodString;
+        type: z.ZodString;
+        networks: z.ZodArray<z.ZodObject<{
+            cidr: z.ZodString;
+            hosts: z.ZodArray<z.ZodObject<{
+                ip: z.ZodString;
+                mac: z.ZodOptional<z.ZodString>;
+                hostname: z.ZodOptional<z.ZodString>;
+                openPorts: z.ZodArray<z.ZodObject<{
+                    port: z.ZodNumber;
+                    status: z.ZodEnum<{
+                        open: "open";
+                        closed: "closed";
+                        filtered: "filtered";
+                    }>;
+                    service: z.ZodOptional<z.ZodString>;
+                    banner: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$loose>;
+export type NetworkingState = z.infer<typeof NetworkingStateSchema>;
+export declare const NetworkingOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    cached: z.ZodOptional<z.ZodBoolean>;
+    enable: z.ZodOptional<z.ZodBoolean>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+    concurrency: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type NetworkingOptions = z.infer<typeof NetworkingOptionsSchema>;
+type ScanPortsOptions = {
+    ports?: string | number[];
+    timeout?: number;
+    concurrency?: number;
+    banner?: boolean;
+    includeClosed?: boolean;
+};
+type DiscoverHostsOptions = {
+    timeout?: number;
+    concurrency?: number;
+    ports?: number[];
+};
+type ReachableHostOptions = {
+    timeout?: number;
+    ports?: number[];
+};
+type ScanLocalNetworksOptions = {
+    ports?: string | number[];
+    timeout?: number;
+    concurrency?: number;
+    hostConcurrency?: number;
+    banner?: boolean;
+};
+type NmapPort = {
+    port: number;
+    state: string;
+    protocol: string;
+    service?: string;
+};
+type NmapHost = {
+    ip: string;
+    hostname?: string;
+    status?: string;
+    mac?: string;
+    ports: NmapPort[];
+};
+/**
+ * The Networking feature provides utilities for network-related operations.
+ *
+ * This feature includes utilities for port detection and availability checking,
+ * which are commonly needed when setting up servers or network services.
+ *
+ * @example
+ * ```typescript
+ * const networking = container.feature('networking')
+ *
+ * // Find an available port starting from 3000
+ * const port = await networking.findOpenPort(3000)
+ * console.log(`Available port: ${port}`)
+ *
+ * // Check if a specific port is available
+ * const isAvailable = await networking.isPortOpen(8080)
+ * if (isAvailable) {
+ *   console.log('Port 8080 is available')
+ * }
+ * ```
+ *
+ * @extends Feature
+ */
+export declare class Networking extends Feature<NetworkingState, NetworkingOptions> {
+    static shortcut: "features.networking";
+    static stateSchema: z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        lastScan: z.ZodOptional<z.ZodObject<{
+            timestamp: z.ZodNumber;
+            target: z.ZodString;
+            type: z.ZodString;
+            networks: z.ZodArray<z.ZodObject<{
+                cidr: z.ZodString;
+                hosts: z.ZodArray<z.ZodObject<{
+                    ip: z.ZodString;
+                    mac: z.ZodOptional<z.ZodString>;
+                    hostname: z.ZodOptional<z.ZodString>;
+                    openPorts: z.ZodArray<z.ZodObject<{
+                        port: z.ZodNumber;
+                        status: z.ZodEnum<{
+                            open: "open";
+                            closed: "closed";
+                            filtered: "filtered";
+                        }>;
+                        service: z.ZodOptional<z.ZodString>;
+                        banner: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strip>>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$loose>;
+    static optionsSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        _cacheKey: z.ZodOptional<z.ZodString>;
+        cached: z.ZodOptional<z.ZodBoolean>;
+        enable: z.ZodOptional<z.ZodBoolean>;
+        timeout: z.ZodOptional<z.ZodNumber>;
+        concurrency: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    static eventsSchema: z.ZodObject<{
+        stateChange: z.ZodTuple<[z.ZodAny], null>;
+        enabled: z.ZodTuple<[], null>;
+        'host:discovered': z.ZodTuple<[z.ZodObject<{
+            ip: z.ZodString;
+            mac: z.ZodOptional<z.ZodString>;
+            reachable: z.ZodBoolean;
+            method: z.ZodEnum<{
+                arp: "arp";
+                tcp: "tcp";
+            }>;
+        }, z.core.$strip>], null>;
+        'port:open': z.ZodTuple<[z.ZodObject<{
+            host: z.ZodString;
+            port: z.ZodNumber;
+            service: z.ZodOptional<z.ZodString>;
+            banner: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>], null>;
+        'scan:start': z.ZodTuple<[z.ZodObject<{
+            target: z.ZodString;
+            type: z.ZodString;
+        }, z.core.$strip>], null>;
+        'scan:complete': z.ZodTuple<[z.ZodObject<{
+            target: z.ZodString;
+            type: z.ZodString;
+            duration: z.ZodNumber;
+            hostsFound: z.ZodNumber;
+            portsFound: z.ZodNumber;
+        }, z.core.$strip>], null>;
+    }, z.core.$strip>;
+    get initialState(): NetworkingState;
+    private _binCache;
+    /** Resolve a binary path via `which`, caching the result. */
+    private resolveBin;
+    get proc(): ReturnType<typeof this.container.feature<'proc'>>;
+    get os(): ReturnType<typeof this.container.feature<'os'>>;
+    /**
+     * Finds the next available port starting from the specified port number.
+     *
+     * This method will search for the first available port starting from the given
+     * port number. If the specified port is available, it returns that port.
+     * Otherwise, it returns the next available port.
+     *
+     * @param {number} [startAt=0] - The port number to start searching from (0 means system will choose)
+     * @returns {Promise<number>} Promise that resolves to an available port number
+     *
+     * @example
+     * ```typescript
+     * // Find any available port
+     * const anyPort = await networking.findOpenPort()
+     *
+     * // Find an available port starting from 3000
+     * const port = await networking.findOpenPort(3000)
+     * console.log(`Server can use port: ${port}`)
+     * ```
+     */
+    findOpenPort(startAt?: number): Promise<number>;
+    /**
+     * Checks if a specific port is available for use.
+     *
+     * This method attempts to detect if the specified port is available.
+     * It returns true if the port is available, false if it's already in use.
+     *
+     * @param {number} [checkPort=0] - The port number to check for availability
+     * @returns {Promise<boolean>} Promise that resolves to true if the port is available, false otherwise
+     *
+     * @example
+     * ```typescript
+     * // Check if port 8080 is available
+     * const isAvailable = await networking.isPortOpen(8080)
+     * if (isAvailable) {
+     *   console.log('Port 8080 is free to use')
+     * } else {
+     *   console.log('Port 8080 is already in use')
+     * }
+     * ```
+     */
+    isPortOpen(checkPort?: number): Promise<boolean | 0>;
+    /**
+     * Returns local external IPv4 interfaces and their CIDR ranges.
+     */
+    getLocalNetworks(): LocalNetwork[];
+    /**
+     * Expands a CIDR block to host IP addresses.
+     * For /31 and /32, all addresses are returned. For all others, network/broadcast are excluded.
+     */
+    expandCidr(cidr: string): string[];
+    /**
+     * Reads and parses the system ARP cache.
+     */
+    getArpTable(): Promise<ArpEntry[]>;
+    /**
+     * Performs a lightweight TCP reachability probe.
+     */
+    isHostReachable(host: string, options?: ReachableHostOptions): Promise<boolean>;
+    /**
+     * Discovers hosts in a CIDR range by combining ARP cache and TCP probes.
+     */
+    discoverHosts(cidr: string, options?: DiscoverHostsOptions): Promise<DiscoverHost[]>;
+    /**
+     * TCP connect scan for a host. By default only returns open ports.
+     */
+    scanPorts(host: string, options?: ScanPortsOptions): Promise<PortScanResult[]>;
+    /**
+     * Convenience method: discover and port-scan hosts across all local networks.
+     */
+    scanLocalNetworks(options?: ScanLocalNetworksOptions): Promise<LocalNetworkScanHost[]>;
+    /**
+     * Optional nmap wrapper for users that already have nmap installed.
+     */
+    get nmap(): {
+        isAvailable: () => Promise<boolean>;
+        scan: (target: string, args?: string[]) => Promise<{
+            hosts: NmapHost[];
+            raw: string;
+        }>;
+        quickScan: (cidr: string) => Promise<{
+            hosts: NmapHost[];
+            raw: string;
+        }>;
+        fullScan: (target: string) => Promise<{
+            hosts: NmapHost[];
+            raw: string;
+        }>;
+    };
+    private isNmapAvailable;
+    private runNmapScan;
+    private parseNmapGrepable;
+    private parseArpOutput;
+    private normalizeMac;
+    private parsePortsOption;
+    private probeTcpPort;
+    private computeCidr;
+    private ipToInt;
+    private intToIp;
+    private countMaskBits;
+    private mapWithConcurrency;
+}
+export default Networking;
+//# sourceMappingURL=networking.d.ts.map

package/dist/node/features/networking.d.ts.map

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

package/dist/node/features/nlp.d.ts

@@ -0,0 +1,125 @@
+import { z } from 'zod';
+import { Feature } from '../feature.js';
+export declare const NLPStateSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    parseCalls: z.ZodDefault<z.ZodNumber>;
+    analyzeCalls: z.ZodDefault<z.ZodNumber>;
+}, z.core.$loose>;
+export declare const NLPOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    cached: z.ZodOptional<z.ZodBoolean>;
+    enable: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const ParsedCommandSchema: z.ZodObject<{
+    intent: z.ZodNullable<z.ZodString>;
+    target: z.ZodNullable<z.ZodString>;
+    subject: z.ZodNullable<z.ZodString>;
+    modifiers: z.ZodArray<z.ZodString>;
+    raw: z.ZodString;
+}, z.core.$strip>;
+export declare const AnalysisSchema: z.ZodObject<{
+    tokens: z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        pos: z.ZodString;
+    }, z.core.$strip>>;
+    entities: z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        type: z.ZodString;
+    }, z.core.$strip>>;
+    raw: z.ZodString;
+}, z.core.$strip>;
+export type ParsedCommand = z.infer<typeof ParsedCommandSchema>;
+export type Analysis = z.infer<typeof AnalysisSchema>;
+/**
+ * The NLP feature provides natural language processing utilities for parsing
+ * utterances into structured data. Combines two complementary libraries:
+ *
+ * - **compromise**: Verb normalization (toInfinitive), POS pattern matching
+ * - **wink-nlp**: High-accuracy POS tagging (~95%), named entity recognition
+ *
+ * Three methods at increasing levels of detail:
+ * - `parse()` — compromise-powered quick structure + verb normalization
+ * - `analyze()` — wink-powered high-accuracy POS + entity extraction
+ * - `understand()` — combined parse + analyze merged
+ *
+ * @example
+ * ```typescript
+ * const nlp = container.feature('nlp', { enable: true })
+ *
+ * nlp.parse("draw a diagram of the auth flow")
+ * // { intent: "draw", target: "diagram", subject: "auth flow", modifiers: [], raw: "..." }
+ *
+ * nlp.analyze("meet john at 3pm about the deployment")
+ * // { tokens: [{value:"meet",pos:"VERB"}, ...], entities: [{value:"john",type:"PERSON"}, ...] }
+ *
+ * nlp.understand("draw a diagram of the auth flow")
+ * // { intent, target, subject, modifiers, tokens, entities, raw }
+ * ```
+ */
+export declare class NLP extends Feature<z.infer<typeof NLPStateSchema>, z.infer<typeof NLPOptionsSchema>> {
+    static shortcut: "features.nlp";
+    static stateSchema: z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        parseCalls: z.ZodDefault<z.ZodNumber>;
+        analyzeCalls: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$loose>;
+    static optionsSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        _cacheKey: z.ZodOptional<z.ZodString>;
+        cached: z.ZodOptional<z.ZodBoolean>;
+        enable: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+    private _wink?;
+    /** Lazily initializes the wink-nlp instance on first use. */
+    private get wink();
+    /**
+     * Parse an utterance into structured command data using compromise.
+     * Extracts intent (normalized verb), target noun, prepositional subject, and modifiers.
+     *
+     * @param text - The raw utterance to parse
+     * @returns Parsed command structure with intent, target, subject, modifiers
+     *
+     * @example
+     * ```typescript
+     * nlp.parse("open the terminal")
+     * // { intent: "open", target: "terminal", subject: null, modifiers: [], raw: "open the terminal" }
+     *
+     * nlp.parse("draw a diagram of the auth flow")
+     * // { intent: "draw", target: "diagram", subject: "auth flow", modifiers: [], raw: "..." }
+     * ```
+     */
+    parse(text: string): ParsedCommand;
+    /**
+     * Analyze text with high-accuracy POS tagging and named entity recognition using wink-nlp.
+     *
+     * @param text - The text to analyze
+     * @returns Token-level POS tags (Universal POS tagset) and named entities
+     *
+     * @example
+     * ```typescript
+     * nlp.analyze("meet john at 3pm about the deployment")
+     * // { tokens: [{value:"meet",pos:"VERB"}, {value:"john",pos:"PROPN"}, ...],
+     * //   entities: [{value:"john",type:"PERSON"}, {value:"3pm",type:"TIME"}],
+     * //   raw: "meet john at 3pm about the deployment" }
+     * ```
+     */
+    analyze(text: string): Analysis;
+    /**
+     * Full understanding: combines compromise parsing with wink-nlp analysis.
+     * Returns intent, target, subject, modifiers (from parse) plus tokens and entities (from analyze).
+     *
+     * @param text - The text to understand
+     * @returns Combined parse + analyze result
+     *
+     * @example
+     * ```typescript
+     * nlp.understand("draw a diagram of the auth flow")
+     * // { intent: "draw", target: "diagram", subject: "auth flow", modifiers: [],
+     * //   tokens: [{value:"draw",pos:"VERB"}, ...], entities: [...], raw: "..." }
+     * ```
+     */
+    understand(text: string): ParsedCommand & Analysis;
+}
+export default NLP;
+//# sourceMappingURL=nlp.d.ts.map

package/dist/node/features/nlp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nlp.d.ts","sourceRoot":"","sources":["../../../src/node/features/nlp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAMvC,eAAO,MAAM,cAAc;;;;iBAGzB,CAAA;AAEF,eAAO,MAAM,gBAAgB;;;;;iBAAkC,CAAA;AAE/D,eAAO,MAAM,mBAAmB;;;;;;iBAM9B,CAAA;AAEF,eAAO,MAAM,cAAc;;;;;;;;;;iBAUzB,CAAA;AAEF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAC/D,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAA;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,GAAI,SAAQ,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;IAChG,OAAgB,QAAQ,EAAG,cAAc,CAAS;IAClD,OAAgB,WAAW;;;;sBAAiB;IAC5C,OAAgB,aAAa;;;;;sBAAmB;IAGhD,OAAO,CAAC,KAAK,CAAC,CAA4B;IAE1C,6DAA6D;IAC7D,OAAO,KAAK,IAAI,GAKf;IAED;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa;IAgDlC;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ;IA2B/B;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,QAAQ;CAWnD;AAED,eAAe,GAAG,CAAA"}

package/dist/node/features/opener.d.ts

@@ -0,0 +1,93 @@
+import { Feature } from "../feature.js";
+/**
+ * The Opener feature opens files, URLs, desktop applications, and code editors.
+ *
+ * HTTP/HTTPS URLs are opened in Google Chrome. Desktop apps can be launched by name.
+ * VS Code and Cursor can be opened to a specific path. All other paths are opened
+ * with the platform's default handler (e.g. Preview for images, Finder for folders).
+ *
+ * @example
+ * ```typescript
+ * const opener = container.feature('opener')
+ *
+ * // Open a URL in Chrome
+ * await opener.open('https://www.google.com')
+ *
+ * // Open a file with the default application
+ * await opener.open('/path/to/image.png')
+ *
+ * // Open a desktop application
+ * await opener.app('Slack')
+ *
+ * // Open VS Code at a project path
+ * await opener.code('/Users/jon/projects/my-app')
+ *
+ * // Open Cursor at a project path
+ * await opener.cursor('/Users/jon/projects/my-app')
+ * ```
+ *
+ * @extends Feature
+ */
+export declare class Opener extends Feature {
+    static shortcut: "features.opener";
+    static description: string;
+    static stateSchema: import("zod").ZodObject<{
+        enabled: import("zod").ZodDefault<import("zod").ZodBoolean>;
+    }, import("zod/v4/core").$loose>;
+    static optionsSchema: import("zod").ZodObject<{
+        name: import("zod").ZodOptional<import("zod").ZodString>;
+        _cacheKey: import("zod").ZodOptional<import("zod").ZodString>;
+        cached: import("zod").ZodOptional<import("zod").ZodBoolean>;
+        enable: import("zod").ZodOptional<import("zod").ZodBoolean>;
+    }, import("zod/v4/core").$strip>;
+    private _binCache;
+    /** Resolve a binary path via `which`, caching the result. */
+    private resolveBin;
+    /**
+     * Opens a path or URL with the appropriate application.
+     *
+     * HTTP and HTTPS URLs are opened in Google Chrome.
+     * Everything else is opened with the system default handler via `open` (macOS).
+     *
+     * @param {string} target - A URL or file path to open
+     * @returns {Promise<void>}
+     */
+    open(target: string): Promise<void>;
+    private openInChrome;
+    /**
+     * Opens a desktop application by name.
+     *
+     * On macOS, uses `open -a` to launch the app. On Windows, uses `start`.
+     * On Linux, attempts to run the lowercase app name as a command.
+     *
+     * @param {string} name - The application name (e.g. "Slack", "Finder", "Safari")
+     * @returns {Promise<void>}
+     */
+    app(name: string): Promise<void>;
+    /**
+     * Opens VS Code at the specified path.
+     *
+     * Uses the `code` CLI command. Falls back to `open -a "Visual Studio Code"` on macOS.
+     *
+     * @param {string} [path="."] - The file or folder path to open
+     * @returns {Promise<void>}
+     */
+    code(path?: string): Promise<void>;
+    /**
+     * Opens Cursor at the specified path.
+     *
+     * Uses the `cursor` CLI command. Falls back to `open -a "Cursor"` on macOS.
+     *
+     * @param {string} [path="."] - The file or folder path to open
+     * @returns {Promise<void>}
+     */
+    cursor(path?: string): Promise<void>;
+    private openDefault;
+}
+declare module '../../feature' {
+    interface AvailableFeatures {
+        opener: typeof Opener;
+    }
+}
+export default Opener;
+//# sourceMappingURL=opener.d.ts.map

package/dist/node/features/opener.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"opener.d.ts","sourceRoot":"","sources":["../../../src/node/features/opener.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAGxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,MAAO,SAAQ,OAAO;IACjC,OAAgB,QAAQ,EAAG,iBAAiB,CAAS;IACrD,OAAgB,WAAW,SAAsD;IACjF,OAAgB,WAAW;;qCAAqB;IAChD,OAAgB,aAAa;;;;;qCAAuB;IAGpD,OAAO,CAAC,SAAS,CAA6B;IAE9C,6DAA6D;IAC7D,OAAO,CAAC,UAAU;IAUlB;;;;;;;;OAQG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAY3B,YAAY;IAqB1B;;;;;;;;OAQG;IACG,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAatC;;;;;;;OAOG;IACG,IAAI,CAAC,IAAI,GAAE,MAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAc7C;;;;;;;OAOG;IACG,MAAM,CAAC,IAAI,GAAE,MAAY,GAAG,OAAO,CAAC,IAAI,CAAC;YAcjC,WAAW;CAW1B;AAED,OAAO,QAAQ,eAAe,CAAC;IAC7B,UAAU,iBAAiB;QACzB,MAAM,EAAE,OAAO,MAAM,CAAA;KACtB;CACF;AAED,eAAe,MAAM,CAAA"}