portercode 0.1.3 → 0.1.10

package/dist/src/gateway/protocol.d.ts

@@ -0,0 +1,159 @@
+import { z } from "zod";
+/**
+ * Porter Wire Protocol (PWP)
+ * Protocolo de comunicacion bidireccional via WebSocket
+ * Usa MessagePack para serializacion binaria eficiente
+ */
+export declare const MessageType: z.ZodEnum<["request", "response", "event", "stream"]>;
+export type MessageType = z.infer<typeof MessageType>;
+export declare const Channel: z.ZodEnum<["session", "llm", "tool", "permission", "system"]>;
+export type Channel = z.infer<typeof Channel>;
+export declare const PorterMessage: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    type: z.ZodEnum<["request", "response", "event", "stream"]>;
+    id: z.ZodString;
+    timestamp: z.ZodNumber;
+    channel: z.ZodEnum<["session", "llm", "tool", "permission", "system"]>;
+    action: z.ZodString;
+    payload: z.ZodUnknown;
+}, "strip", z.ZodTypeAny, {
+    version: 1;
+    type: "event" | "request" | "response" | "stream";
+    id: string;
+    timestamp: number;
+    channel: "llm" | "session" | "tool" | "permission" | "system";
+    action: string;
+    payload?: unknown;
+}, {
+    version: 1;
+    type: "event" | "request" | "response" | "stream";
+    id: string;
+    timestamp: number;
+    channel: "llm" | "session" | "tool" | "permission" | "system";
+    action: string;
+    payload?: unknown;
+}>;
+export type PorterMessage = z.infer<typeof PorterMessage>;
+export declare function createRequest<T>(channel: Channel, action: string, payload: T): PorterMessage;
+export declare function createResponse<T>(requestId: string, channel: Channel, action: string, payload: T): PorterMessage;
+export declare function createEvent<T>(channel: Channel, action: string, payload: T): PorterMessage;
+export declare function createStream<T>(streamId: string, channel: Channel, action: string, payload: T): PorterMessage;
+export declare function createError(requestId: string, channel: Channel, error: string, details?: unknown): PorterMessage;
+export declare const SessionPayloads: {
+    create: z.ZodObject<{
+        title: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        title?: string | undefined;
+    }, {
+        title?: string | undefined;
+    }>;
+    list: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+    get: z.ZodObject<{
+        sessionId: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        sessionId: string;
+    }, {
+        sessionId: string;
+    }>;
+    messages: z.ZodObject<{
+        sessionId: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        sessionId: string;
+    }, {
+        sessionId: string;
+    }>;
+};
+export declare const LLMPayloads: {
+    prompt: z.ZodObject<{
+        sessionId: z.ZodString;
+        content: z.ZodString;
+        attachments: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        sessionId: string;
+        content: string;
+        attachments?: string[] | undefined;
+    }, {
+        sessionId: string;
+        content: string;
+        attachments?: string[] | undefined;
+    }>;
+    cancel: z.ZodObject<{
+        sessionId: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        sessionId: string;
+    }, {
+        sessionId: string;
+    }>;
+};
+export declare const ToolPayloads: {
+    list: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+    execute: z.ZodObject<{
+        toolId: z.ZodString;
+        args: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, "strip", z.ZodTypeAny, {
+        toolId: string;
+        args: Record<string, unknown>;
+    }, {
+        toolId: string;
+        args: Record<string, unknown>;
+    }>;
+};
+export declare const PermissionPayloads: {
+    respond: z.ZodObject<{
+        id: z.ZodString;
+        granted: z.ZodBoolean;
+        pattern: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        granted: boolean;
+        pattern?: string | undefined;
+    }, {
+        id: string;
+        granted: boolean;
+        pattern?: string | undefined;
+    }>;
+};
+export declare const SystemPayloads: {
+    auth: z.ZodObject<{
+        token: z.ZodString;
+        clientId: z.ZodString;
+        capabilities: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        token: string;
+        clientId: string;
+        capabilities?: string[] | undefined;
+    }, {
+        token: string;
+        clientId: string;
+        capabilities?: string[] | undefined;
+    }>;
+    health: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+};
+export interface ConnectedClient {
+    id: string;
+    socket: WebSocket;
+    authenticated: boolean;
+    capabilities: string[];
+    subscriptions: Set<string>;
+    connectedAt: number;
+}
+export declare const GatewayInfo: z.ZodObject<{
+    pid: z.ZodNumber;
+    port: z.ZodNumber;
+    token: z.ZodString;
+    projectDir: z.ZodString;
+    startedAt: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    token: string;
+    pid: number;
+    port: number;
+    projectDir: string;
+    startedAt: number;
+}, {
+    token: string;
+    pid: number;
+    port: number;
+    projectDir: string;
+    startedAt: number;
+}>;
+export type GatewayInfo = z.infer<typeof GatewayInfo>;

package/dist/src/gateway/router.d.ts

@@ -0,0 +1,7 @@
+import type { PorterMessage, ConnectedClient } from "./protocol";
+export declare namespace Router {
+    /**
+     * Enruta un mensaje al handler apropiado
+     */
+    function handle(msg: PorterMessage, client: ConnectedClient): Promise<PorterMessage | void>;
+}

package/dist/src/gateway/server.d.ts

@@ -0,0 +1,24 @@
+import { type PorterMessage, type ConnectedClient, type GatewayInfo } from "./protocol";
+export declare namespace Gateway {
+    /**
+     * Inicia el Gateway Server
+     * Encuentra un puerto dinamico y guarda la info en gateway.json
+     */
+    function start(): Promise<GatewayInfo>;
+    /**
+     * Detiene el Gateway Server
+     */
+    function stop(): void;
+    /**
+     * Envia un mensaje a todos los clientes autenticados
+     */
+    function broadcast(msg: PorterMessage): void;
+    /**
+     * Envia un mensaje a un cliente especifico
+     */
+    function send(clientId: string, msg: PorterMessage): void;
+    /**
+     * Obtiene la lista de clientes conectados
+     */
+    function getClients(): ConnectedClient[];
+}

package/dist/src/global/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Helper function to resolve home directory paths (~/...)
+ * Works cross-platform (Windows, macOS, Linux)
+ */
+export declare function resolveHomePath(filepath: string): string;
+/**
+ * Get platform-specific config directory for a command
+ * - Windows: %APPDATA%\<commandName>
+ * - macOS: ~/Library/Application Support/<commandName>
+ * - Linux: ~/.config/<commandName>
+ */
+export declare function getConfigDir(commandName: string): string;
+export declare namespace Global {
+    const Path: {
+        readonly home: string;
+        readonly data: string;
+        readonly bin: string;
+        readonly log: string;
+        readonly cache: string;
+        readonly config: string;
+        readonly state: string;
+    };
+}

package/dist/src/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/src/permission/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./types";
+export { Permission, type PermissionMode } from "./permission";

package/dist/src/permission/permission.d.ts

@@ -0,0 +1,172 @@
+import z from "zod";
+import type { PermissionRequest, PermissionResponse, ToolPermissions } from "./types";
+export type PermissionMode = "auto" | "ask" | "plan";
+export declare namespace Permission {
+    /**
+     * Load allowed patterns from config file
+     */
+    function loadPatterns(): Promise<void>;
+    /**
+     * Set the current permission mode
+     * Clears session-scoped remembered permissions but keeps permanent ones
+     */
+    function setMode(mode: PermissionMode): void;
+    /**
+     * Get the current permission mode
+     */
+    function getMode(): PermissionMode;
+    /**
+     * Permission events
+     */
+    const Event: {
+        Request: {
+            type: "permission.request";
+            properties: z.ZodObject<{
+                request: z.ZodType<{
+                    id: string;
+                    tool: string;
+                    action: string;
+                    description: string;
+                    risk: "low" | "medium" | "high";
+                    details?: Record<string, any> | undefined;
+                }, z.ZodTypeDef, {
+                    id: string;
+                    tool: string;
+                    action: string;
+                    description: string;
+                    risk: "low" | "medium" | "high";
+                    details?: Record<string, any> | undefined;
+                }>;
+            }, "strip", z.ZodTypeAny, {
+                request: {
+                    id: string;
+                    tool: string;
+                    action: string;
+                    description: string;
+                    risk: "low" | "medium" | "high";
+                    details?: Record<string, any> | undefined;
+                };
+            }, {
+                request: {
+                    id: string;
+                    tool: string;
+                    action: string;
+                    description: string;
+                    risk: "low" | "medium" | "high";
+                    details?: Record<string, any> | undefined;
+                };
+            }>;
+        };
+        Response: {
+            type: "permission.response";
+            properties: z.ZodObject<{
+                response: z.ZodType<{
+                    id: string;
+                    granted: boolean;
+                    remember: boolean;
+                }, z.ZodTypeDef, {
+                    id: string;
+                    granted: boolean;
+                    remember: boolean;
+                }>;
+            }, "strip", z.ZodTypeAny, {
+                response: {
+                    id: string;
+                    granted: boolean;
+                    remember: boolean;
+                };
+            }, {
+                response: {
+                    id: string;
+                    granted: boolean;
+                    remember: boolean;
+                };
+            }>;
+        };
+    };
+    /**
+     * Get effective permissions based on current mode and config
+     */
+    function getPermissions(): Promise<ToolPermissions>;
+    /**
+     * Check if a file path is within the project directory
+     */
+    function isInProject(filepath: string): boolean;
+    /**
+     * Check permission for file edit
+     */
+    function checkEdit(filepath: string): Promise<boolean>;
+    /**
+     * Check permission for file write
+     */
+    function checkWrite(filepath: string): Promise<boolean>;
+    /**
+     * Check permission for bash command
+     *
+     * Bash commands are ALWAYS validated against stored patterns,
+     * regardless of permission mode. This ensures security even in auto mode.
+     */
+    function checkBash(command: string): Promise<boolean>;
+    /**
+     * Check permission for web fetch
+     */
+    function checkWebFetch(url: string): Promise<boolean>;
+    /**
+     * Respond to a permission request (called by UI)
+     */
+    function respond(response: PermissionResponse): void;
+    /**
+     * Grant a pending permission request
+     */
+    function grant(id: string, remember?: boolean): void;
+    /**
+     * Deny a pending permission request
+     */
+    function deny(id: string, remember?: boolean): void;
+    /**
+     * Clear remembered permissions
+     */
+    function clearRemembered(): void;
+    /**
+     * Clear all permissions (remembered and permanent)
+     * Also resets the patterns loaded flag for testing
+     */
+    function clearAll(): void;
+    /**
+     * Get all pending permission requests
+     */
+    function getPending(): PermissionRequest[];
+    /**
+     * Get all permanent permissions (allowed patterns)
+     */
+    function getPermanentPermissions(): string[];
+    /**
+     * Grant a permission permanently for a pattern
+     * Saves the pattern to the project config file
+     */
+    function grantPermanent(id: string, pattern: string): void;
+    /**
+     * Deny a permission permanently for a pattern
+     * Saves the pattern to the project config file
+     */
+    function denyPermanent(id: string, pattern: string): void;
+    /**
+     * Match a permission key against a pattern
+     * Supports wildcards: * matches one segment, ** matches any depth
+     */
+    function matchPermissionPattern(key: string, pattern: string): boolean;
+    /**
+     * Generate a permission key for a tool and target
+     */
+    function generatePermissionKey(tool: string, target: string): string;
+    /**
+     * Infer a pattern from a tool and target
+     * Returns a reasonable pattern that could be used for "allow always"
+     */
+    function inferPattern(tool: string, target: string): string;
+    /**
+     * Suggest possible patterns for a tool and target
+     * Returns patterns from most specific to least specific
+     */
+    function suggestPatterns(tool: string, target: string): string[];
+}

package/dist/src/permission/types.d.ts

@@ -0,0 +1,109 @@
+import z from "zod";
+/**
+ * Permission System Types
+ *
+ * Defines permission levels and rules for tool execution.
+ */
+/**
+ * Permission level for an action
+ */
+export declare const PermissionLevel: z.ZodEnum<["allow", "ask", "deny"]>;
+export type PermissionLevel = z.infer<typeof PermissionLevel>;
+/**
+ * Permission rule with optional pattern matching
+ */
+export declare const PermissionRule: z.ZodObject<{
+    pattern: z.ZodString;
+    level: z.ZodEnum<["allow", "ask", "deny"]>;
+}, "strip", z.ZodTypeAny, {
+    pattern: string;
+    level: "ask" | "allow" | "deny";
+}, {
+    pattern: string;
+    level: "ask" | "allow" | "deny";
+}>;
+export type PermissionRule = z.infer<typeof PermissionRule>;
+/**
+ * Tool-specific permissions
+ */
+export declare const ToolPermissions: z.ZodObject<{
+    edit: z.ZodDefault<z.ZodEnum<["allow", "ask", "deny"]>>;
+    write: z.ZodDefault<z.ZodEnum<["allow", "ask", "deny"]>>;
+    bash: z.ZodDefault<z.ZodUnion<[z.ZodEnum<["allow", "ask", "deny"]>, z.ZodRecord<z.ZodString, z.ZodEnum<["allow", "ask", "deny"]>>]>>;
+    webfetch: z.ZodDefault<z.ZodEnum<["allow", "ask", "deny"]>>;
+    externalDirectory: z.ZodDefault<z.ZodEnum<["allow", "ask", "deny"]>>;
+}, "strip", z.ZodTypeAny, {
+    write: "ask" | "allow" | "deny";
+    bash: "ask" | "allow" | "deny" | Record<string, "ask" | "allow" | "deny">;
+    edit: "ask" | "allow" | "deny";
+    webfetch: "ask" | "allow" | "deny";
+    externalDirectory: "ask" | "allow" | "deny";
+}, {
+    write?: "ask" | "allow" | "deny" | undefined;
+    bash?: "ask" | "allow" | "deny" | Record<string, "ask" | "allow" | "deny"> | undefined;
+    edit?: "ask" | "allow" | "deny" | undefined;
+    webfetch?: "ask" | "allow" | "deny" | undefined;
+    externalDirectory?: "ask" | "allow" | "deny" | undefined;
+}>;
+export type ToolPermissions = z.infer<typeof ToolPermissions>;
+/**
+ * Stored allowed patterns for bash commands
+ * Persisted to project-level config file
+ */
+export declare const AllowedPatterns: z.ZodObject<{
+    bash: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    edit: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    write: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    write: string[];
+    bash: string[];
+    edit: string[];
+}, {
+    write?: string[] | undefined;
+    bash?: string[] | undefined;
+    edit?: string[] | undefined;
+}>;
+export type AllowedPatterns = z.infer<typeof AllowedPatterns>;
+/**
+ * Permission request for user confirmation
+ */
+export declare const PermissionRequest: z.ZodObject<{
+    id: z.ZodString;
+    tool: z.ZodString;
+    action: z.ZodString;
+    description: z.ZodString;
+    risk: z.ZodDefault<z.ZodEnum<["low", "medium", "high"]>>;
+    details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    tool: string;
+    action: string;
+    description: string;
+    risk: "low" | "medium" | "high";
+    details?: Record<string, any> | undefined;
+}, {
+    id: string;
+    tool: string;
+    action: string;
+    description: string;
+    risk?: "low" | "medium" | "high" | undefined;
+    details?: Record<string, any> | undefined;
+}>;
+export type PermissionRequest = z.infer<typeof PermissionRequest>;
+/**
+ * Permission response from user
+ */
+export declare const PermissionResponse: z.ZodObject<{
+    id: z.ZodString;
+    granted: z.ZodBoolean;
+    remember: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    granted: boolean;
+    remember: boolean;
+}, {
+    id: string;
+    granted: boolean;
+    remember?: boolean | undefined;
+}>;
+export type PermissionResponse = z.infer<typeof PermissionResponse>;

package/dist/src/project/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./project";
+export * from "./instance";
+export * from "./state";

package/dist/src/project/instance.d.ts

@@ -0,0 +1,33 @@
+import { Project } from "./project";
+export declare const Instance: {
+    /**
+     * Provide an instance context for a given directory
+     * Supports two signatures:
+     * 1. { directory, init?, fn } - auto-detects project
+     * 2. { project, directory, worktree }, fn - explicit context (for testing)
+     */
+    provide<R>(input: {
+        directory: string;
+        init?: () => Promise<any>;
+        fn: () => R;
+    } | {
+        project: Project.Info;
+        directory: string;
+        worktree: string;
+    }, fn?: () => R): Promise<R>;
+    readonly directory: string;
+    readonly worktree: string;
+    readonly project: {
+        id: string;
+        worktree: string;
+        time: {
+            created: number;
+            updated: number;
+        };
+        vcs?: "git" | undefined;
+        name?: string | undefined;
+    };
+    state<S>(init: () => S, dispose?: (state: Awaited<S>) => Promise<void>): () => S;
+    dispose(): Promise<void>;
+    disposeAll(): Promise<void>;
+};

package/dist/src/project/project.d.ts

@@ -0,0 +1,82 @@
+import z from "zod";
+export declare namespace Project {
+    const Info: z.ZodObject<{
+        id: z.ZodString;
+        worktree: z.ZodString;
+        vcs: z.ZodOptional<z.ZodLiteral<"git">>;
+        name: z.ZodOptional<z.ZodString>;
+        time: z.ZodObject<{
+            created: z.ZodNumber;
+            updated: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            created: number;
+            updated: number;
+        }, {
+            created: number;
+            updated: number;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        worktree: string;
+        time: {
+            created: number;
+            updated: number;
+        };
+        vcs?: "git" | undefined;
+        name?: string | undefined;
+    }, {
+        id: string;
+        worktree: string;
+        time: {
+            created: number;
+            updated: number;
+        };
+        vcs?: "git" | undefined;
+        name?: string | undefined;
+    }>;
+    type Info = z.infer<typeof Info>;
+    const Event: {
+        Updated: {
+            type: "project.updated";
+            properties: z.ZodObject<{
+                id: z.ZodString;
+                worktree: z.ZodString;
+                vcs: z.ZodOptional<z.ZodLiteral<"git">>;
+                name: z.ZodOptional<z.ZodString>;
+                time: z.ZodObject<{
+                    created: z.ZodNumber;
+                    updated: z.ZodNumber;
+                }, "strip", z.ZodTypeAny, {
+                    created: number;
+                    updated: number;
+                }, {
+                    created: number;
+                    updated: number;
+                }>;
+            }, "strip", z.ZodTypeAny, {
+                id: string;
+                worktree: string;
+                time: {
+                    created: number;
+                    updated: number;
+                };
+                vcs?: "git" | undefined;
+                name?: string | undefined;
+            }, {
+                id: string;
+                worktree: string;
+                time: {
+                    created: number;
+                    updated: number;
+                };
+                vcs?: "git" | undefined;
+                name?: string | undefined;
+            }>;
+        };
+    };
+    function fromDirectory(directory: string): Promise<Info>;
+    /**
+     * Alias for fromDirectory for compatibility
+     */
+    const detect: typeof fromDirectory;
+}

package/dist/src/project/state.d.ts

@@ -0,0 +1,4 @@
+export declare namespace State {
+    function create<S>(root: () => string, init: () => S, dispose?: (state: Awaited<S>) => Promise<void>): () => S;
+    function dispose(key: string): Promise<void>;
+}

package/dist/src/prompt/index.d.ts

@@ -0,0 +1,5 @@
+export { SystemPrompt, type OperationMode } from "./system";
+export { default as PROMPT_TITLE } from "./title.txt";
+export { default as PROMPT_SUMMARY } from "./summary.txt";
+export { default as PROMPT_CONTEXT_OPTIMIZATION } from "./context-optimization.txt";
+export { default as PROMPT_EXPLORE } from "./explore.txt";

package/dist/src/prompt/system.d.ts

@@ -0,0 +1,29 @@
+/**
+ * System Prompt Management
+ *
+ * Assembles system prompts from templates, environment info, and custom rules.
+ * Different prompts are used based on the model provider for optimal behavior.
+ */
+export type OperationMode = "ask" | "auto" | "plan";
+export declare namespace SystemPrompt {
+    /**
+     * Get planning mode prompt
+     */
+    function forPlanMode(): string[];
+    /**
+     * Get provider-specific prompt template
+     */
+    function forModel(modelId: string): string[];
+    /**
+     * Get environment context information
+     */
+    function environment(): Promise<string[]>;
+    /**
+     * Load custom rules from PORTER.md files
+     */
+    function customRules(): Promise<string[]>;
+    /**
+     * Assemble complete system prompt for a model
+     */
+    function assemble(modelId: string, mode?: OperationMode): Promise<string[]>;
+}