@maintainer-pro/ai-cli 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,239 @@
+import { z } from 'zod';
+
+type AiCliProviderId = "claude" | "cursor" | "antigravity" | (string & {});
+interface ToolCall {
+    tool: string;
+    args: Record<string, unknown>;
+}
+interface AiResponse {
+    text: string;
+    toolCalls: ToolCall[];
+    provider: string;
+}
+interface ChatAttachment {
+    /** Original filename, e.g. screenshot.png */
+    name: string;
+    mimeType: string;
+    /** Raw base64 (no data: URL prefix). */
+    data: string;
+}
+interface ChatMessage {
+    role: "user" | "assistant";
+    content: string;
+}
+/** Sender roles for the shared client / developer / AI chat panel. */
+type ChatSenderType = "client" | "developer" | "ai";
+interface ChatUser {
+    name: string;
+    type: ChatSenderType;
+    /** When true, this user is selected by default in the composer (client/developer only). */
+    default?: boolean;
+    /** Login email when users come from Maintainer Pro. */
+    email?: string;
+    /** Org role from Maintainer Pro (owner, admin, staff, member, …). */
+    role?: string;
+}
+/** Live UI / app snapshot sent with each chat request (host-defined). */
+interface ClientContext {
+    route: string;
+    pageTitle: string;
+    visiblePanels?: string[];
+    focusedElement?: string | null;
+    relevantFiles?: string[];
+    /** Arbitrary host app state (tasks, stats, form values, etc.). */
+    data?: Record<string, unknown>;
+}
+interface CallAiOptions {
+    systemPrompt: string;
+    workspaceDir?: string;
+    providerPreference?: "auto" | "claude" | "cursor" | "antigravity";
+    /** Absolute paths to screenshot/image files the agent should inspect. */
+    attachmentPaths?: string[];
+    /**
+     * Compact excerpts from other `.maintainer-pro/chat` conversations.
+     * Injected into the prompt for the model to use when relevant.
+     */
+    priorConversationsContext?: string;
+    /** Extra / override providers (e.g. future HTTP model backends). */
+    providers?: AiProvider[];
+}
+interface AiProvider {
+    id: string;
+    label: string;
+    /** Return true if this provider can run in the current environment. */
+    isAvailable(): Promise<boolean>;
+    call(messages: ChatMessage[], context: ClientContext | undefined, options: CallAiOptions): Promise<AiResponse>;
+}
+
+declare function callAi(messages: ChatMessage[], context: ClientContext | undefined, options: CallAiOptions): Promise<AiResponse>;
+
+type ProviderPreference = "auto" | "claude" | "cursor" | "antigravity";
+type BuiltinProviderId = "claude" | "cursor" | "antigravity";
+declare function commandExists(command: string): Promise<boolean>;
+declare function getProviderPreference(override?: ProviderPreference): ProviderPreference;
+declare function resolveCliBinary(provider: BuiltinProviderId): Promise<string | null>;
+declare function createBuiltinProviders(): AiProvider[];
+declare function resolveProvider(options?: {
+    preference?: ProviderPreference;
+    providers?: AiProvider[];
+}): Promise<AiProvider>;
+declare function providerLabel(providerId: string): string;
+
+/** Extract ```json ... ``` tool blocks and strip them from assistant text. */
+declare function parseAiResponse(raw: string, provider: AiCliProviderId): AiResponse;
+
+declare function buildConversationPrompt(messages: ChatMessage[]): string;
+declare function formatClientContext(context?: ClientContext): string;
+/** Full prompt for providers without a native --system-prompt flag (Cursor). */
+declare function buildCursorPrompt(systemPrompt: string, messages: ChatMessage[], context?: ClientContext, attachmentPaths?: string[], priorConversationsContext?: string): string;
+/** Conversation + context for Claude (system prompt passed separately). */
+declare function buildClaudeUserPrompt(messages: ChatMessage[], context?: ClientContext, attachmentPaths?: string[], priorConversationsContext?: string): string;
+
+declare function createDefaultSystemPrompt(input: {
+    productDescription: string;
+    relevantFilesHint?: string;
+    runtimeToolsHint?: string;
+}): string;
+
+declare function createClaudeProvider(): AiProvider;
+
+declare function createCursorProvider(): AiProvider;
+
+declare function createAntigravityProvider(): AiProvider;
+
+type ToolSchemaMap = Record<string, z.ZodTypeAny>;
+declare function createToolValidator(schemas: ToolSchemaMap): (toolCall: ToolCall) => {
+    valid: true;
+    name: string;
+    args: Record<string, unknown>;
+} | {
+    valid: false;
+    error: string;
+};
+
+/** Minimal persistence contract (file store, SQL, or Maintainer Pro). */
+interface ChatStoreLike {
+    ensureConversation(id: string): Promise<void>;
+    saveMessage(input: {
+        conversationId: string;
+        role: "user" | "assistant" | "system";
+        content: string;
+        provider?: string;
+        attachmentPaths?: string[];
+        senderType?: "client" | "developer" | "ai";
+        senderName?: string;
+    }): Promise<unknown>;
+    listMessages?(conversationId: string): Promise<Array<{
+        id: string;
+        role: string;
+        content: string;
+        provider?: string | null;
+        createdAt?: string | Date;
+        attachmentPaths?: string[];
+        senderType?: "client" | "developer" | "ai" | null;
+        senderName?: string | null;
+    }>>;
+    /** All conversations under the store (for prior-chat context). */
+    listConversations?(): Promise<Array<{
+        id: string;
+        updatedAt: string;
+        messages: Array<{
+            role: string;
+            content: string;
+            createdAt?: string | Date;
+        }>;
+    }>>;
+    saveToolEvents?(conversationId: string, events: Array<{
+        tool: string;
+        args: Record<string, unknown>;
+    }>): Promise<void>;
+    /**
+     * Optional remote/local upload hook. When present, chat images are persisted
+     * through the store instead of `.maintainer-pro/uploads`.
+     * `localPaths` are absolute paths for CLI inspection; `refs` are stored on messages.
+     */
+    uploadAttachments?(conversationId: string, attachments: ChatAttachment[] | undefined): Promise<{
+        refs: string[];
+        localPaths: string[];
+    }>;
+}
+interface ChatHandlerOptions {
+    systemPrompt: string;
+    workspaceDir?: string;
+    providerPreference?: CallAiOptions["providerPreference"];
+    providers?: AiProvider[];
+    tools?: ToolSchemaMap;
+    db?: ChatStoreLike;
+    conversationId?: string | ((request: Request) => string | undefined);
+    onToolCalls?: (toolCalls: ToolCall[], context?: ClientContext) => void | Promise<void>;
+}
+interface ChatHandlers {
+    GET: (request: Request) => Promise<Response>;
+    POST: (request: Request) => Promise<Response>;
+}
+declare function createChatHandler(options: ChatHandlerOptions): ChatHandlers;
+declare function toNextRoute(handlers: ChatHandlers): {
+    GET: (request: Request) => Promise<Response>;
+    POST: (request: Request) => Promise<Response>;
+};
+
+/** Persist chat image attachments under the workspace and return absolute paths. */
+declare function saveChatAttachments(attachments: ChatAttachment[] | undefined, workspaceDir: string): Promise<string[]>;
+
+interface LocalStoredMessage {
+    id: string;
+    conversationId: string;
+    role: "user" | "assistant" | "system";
+    content: string;
+    provider: string | null;
+    createdAt: string;
+    attachmentPaths?: string[];
+    senderType?: "client" | "developer" | "ai" | null;
+    senderName?: string | null;
+}
+/**
+ * Persist conversations as JSON files under a local directory.
+ * Layout: `{baseDir}/{conversationId}.json`
+ */
+declare function createLocalDirectoryStore(baseDir: string): ChatStoreLike & {
+    listMessages: (conversationId: string) => Promise<LocalStoredMessage[]>;
+    listConversations: NonNullable<ChatStoreLike["listConversations"]>;
+};
+
+interface MaintainerProStoreOptions {
+    baseUrl: string;
+    apiKey: string;
+    /** Directory for temporary local copies of images for CLI providers. */
+    tempDir?: string;
+    fetchImpl?: typeof fetch;
+}
+type UploadResult = {
+    /** Refs persisted on messages (maintainer-pro://uuid). */
+    refs: string[];
+    /** Absolute local temp paths for CLI image inspection. */
+    localPaths: string[];
+    attachmentIds: string[];
+};
+/**
+ * Persist chat data via Maintainer Pro HTTP API (no local .maintainer-pro writes).
+ */
+declare function createMaintainerProStore(options: MaintainerProStoreOptions): ChatStoreLike & {
+    uploadAttachments: (conversationId: string, attachments: ChatAttachment[] | undefined) => Promise<UploadResult>;
+};
+/** Build a Maintainer Pro store from env when configured. */
+declare function createMaintainerProStoreFromEnv(): ReturnType<typeof createMaintainerProStore> | null;
+
+interface PriorConversationOptions {
+    excludeConversationId?: string;
+    currentRequest: string;
+    maxConversations?: number;
+    maxMessagesPerConversation?: number;
+}
+/**
+ * Load other conversations from the store and format a compact prompt block.
+ * Prefers chats that share keywords with the current request; falls back to
+ * most recently updated. Empty string when nothing useful is available.
+ */
+declare function buildPriorConversationsContext(db: ChatStoreLike, options: PriorConversationOptions): Promise<string>;
+
+export { type AiCliProviderId, type AiProvider, type AiResponse, type CallAiOptions, type ChatAttachment, type ChatHandlerOptions, type ChatHandlers, type ChatMessage, type ChatSenderType, type ChatStoreLike, type ChatUser, type ClientContext, type LocalStoredMessage, type MaintainerProStoreOptions, type PriorConversationOptions, type ProviderPreference, type ToolCall, type ToolSchemaMap, buildClaudeUserPrompt, buildConversationPrompt, buildCursorPrompt, buildPriorConversationsContext, callAi, commandExists, createAntigravityProvider, createBuiltinProviders, createChatHandler, createClaudeProvider, createCursorProvider, createDefaultSystemPrompt, createLocalDirectoryStore, createMaintainerProStore, createMaintainerProStoreFromEnv, createToolValidator, formatClientContext, getProviderPreference, parseAiResponse, providerLabel, resolveCliBinary, resolveProvider, saveChatAttachments, toNextRoute };

package/dist/index.d.ts

@@ -0,0 +1,239 @@
+import { z } from 'zod';
+
+type AiCliProviderId = "claude" | "cursor" | "antigravity" | (string & {});
+interface ToolCall {
+    tool: string;
+    args: Record<string, unknown>;
+}
+interface AiResponse {
+    text: string;
+    toolCalls: ToolCall[];
+    provider: string;
+}
+interface ChatAttachment {
+    /** Original filename, e.g. screenshot.png */
+    name: string;
+    mimeType: string;
+    /** Raw base64 (no data: URL prefix). */
+    data: string;
+}
+interface ChatMessage {
+    role: "user" | "assistant";
+    content: string;
+}
+/** Sender roles for the shared client / developer / AI chat panel. */
+type ChatSenderType = "client" | "developer" | "ai";
+interface ChatUser {
+    name: string;
+    type: ChatSenderType;
+    /** When true, this user is selected by default in the composer (client/developer only). */
+    default?: boolean;
+    /** Login email when users come from Maintainer Pro. */
+    email?: string;
+    /** Org role from Maintainer Pro (owner, admin, staff, member, …). */
+    role?: string;
+}
+/** Live UI / app snapshot sent with each chat request (host-defined). */
+interface ClientContext {
+    route: string;
+    pageTitle: string;
+    visiblePanels?: string[];
+    focusedElement?: string | null;
+    relevantFiles?: string[];
+    /** Arbitrary host app state (tasks, stats, form values, etc.). */
+    data?: Record<string, unknown>;
+}
+interface CallAiOptions {
+    systemPrompt: string;
+    workspaceDir?: string;
+    providerPreference?: "auto" | "claude" | "cursor" | "antigravity";
+    /** Absolute paths to screenshot/image files the agent should inspect. */
+    attachmentPaths?: string[];
+    /**
+     * Compact excerpts from other `.maintainer-pro/chat` conversations.
+     * Injected into the prompt for the model to use when relevant.
+     */
+    priorConversationsContext?: string;
+    /** Extra / override providers (e.g. future HTTP model backends). */
+    providers?: AiProvider[];
+}
+interface AiProvider {
+    id: string;
+    label: string;
+    /** Return true if this provider can run in the current environment. */
+    isAvailable(): Promise<boolean>;
+    call(messages: ChatMessage[], context: ClientContext | undefined, options: CallAiOptions): Promise<AiResponse>;
+}
+
+declare function callAi(messages: ChatMessage[], context: ClientContext | undefined, options: CallAiOptions): Promise<AiResponse>;
+
+type ProviderPreference = "auto" | "claude" | "cursor" | "antigravity";
+type BuiltinProviderId = "claude" | "cursor" | "antigravity";
+declare function commandExists(command: string): Promise<boolean>;
+declare function getProviderPreference(override?: ProviderPreference): ProviderPreference;
+declare function resolveCliBinary(provider: BuiltinProviderId): Promise<string | null>;
+declare function createBuiltinProviders(): AiProvider[];
+declare function resolveProvider(options?: {
+    preference?: ProviderPreference;
+    providers?: AiProvider[];
+}): Promise<AiProvider>;
+declare function providerLabel(providerId: string): string;
+
+/** Extract ```json ... ``` tool blocks and strip them from assistant text. */
+declare function parseAiResponse(raw: string, provider: AiCliProviderId): AiResponse;
+
+declare function buildConversationPrompt(messages: ChatMessage[]): string;
+declare function formatClientContext(context?: ClientContext): string;
+/** Full prompt for providers without a native --system-prompt flag (Cursor). */
+declare function buildCursorPrompt(systemPrompt: string, messages: ChatMessage[], context?: ClientContext, attachmentPaths?: string[], priorConversationsContext?: string): string;
+/** Conversation + context for Claude (system prompt passed separately). */
+declare function buildClaudeUserPrompt(messages: ChatMessage[], context?: ClientContext, attachmentPaths?: string[], priorConversationsContext?: string): string;
+
+declare function createDefaultSystemPrompt(input: {
+    productDescription: string;
+    relevantFilesHint?: string;
+    runtimeToolsHint?: string;
+}): string;
+
+declare function createClaudeProvider(): AiProvider;
+
+declare function createCursorProvider(): AiProvider;
+
+declare function createAntigravityProvider(): AiProvider;
+
+type ToolSchemaMap = Record<string, z.ZodTypeAny>;
+declare function createToolValidator(schemas: ToolSchemaMap): (toolCall: ToolCall) => {
+    valid: true;
+    name: string;
+    args: Record<string, unknown>;
+} | {
+    valid: false;
+    error: string;
+};
+
+/** Minimal persistence contract (file store, SQL, or Maintainer Pro). */
+interface ChatStoreLike {
+    ensureConversation(id: string): Promise<void>;
+    saveMessage(input: {
+        conversationId: string;
+        role: "user" | "assistant" | "system";
+        content: string;
+        provider?: string;
+        attachmentPaths?: string[];
+        senderType?: "client" | "developer" | "ai";
+        senderName?: string;
+    }): Promise<unknown>;
+    listMessages?(conversationId: string): Promise<Array<{
+        id: string;
+        role: string;
+        content: string;
+        provider?: string | null;
+        createdAt?: string | Date;
+        attachmentPaths?: string[];
+        senderType?: "client" | "developer" | "ai" | null;
+        senderName?: string | null;
+    }>>;
+    /** All conversations under the store (for prior-chat context). */
+    listConversations?(): Promise<Array<{
+        id: string;
+        updatedAt: string;
+        messages: Array<{
+            role: string;
+            content: string;
+            createdAt?: string | Date;
+        }>;
+    }>>;
+    saveToolEvents?(conversationId: string, events: Array<{
+        tool: string;
+        args: Record<string, unknown>;
+    }>): Promise<void>;
+    /**
+     * Optional remote/local upload hook. When present, chat images are persisted
+     * through the store instead of `.maintainer-pro/uploads`.
+     * `localPaths` are absolute paths for CLI inspection; `refs` are stored on messages.
+     */
+    uploadAttachments?(conversationId: string, attachments: ChatAttachment[] | undefined): Promise<{
+        refs: string[];
+        localPaths: string[];
+    }>;
+}
+interface ChatHandlerOptions {
+    systemPrompt: string;
+    workspaceDir?: string;
+    providerPreference?: CallAiOptions["providerPreference"];
+    providers?: AiProvider[];
+    tools?: ToolSchemaMap;
+    db?: ChatStoreLike;
+    conversationId?: string | ((request: Request) => string | undefined);
+    onToolCalls?: (toolCalls: ToolCall[], context?: ClientContext) => void | Promise<void>;
+}
+interface ChatHandlers {
+    GET: (request: Request) => Promise<Response>;
+    POST: (request: Request) => Promise<Response>;
+}
+declare function createChatHandler(options: ChatHandlerOptions): ChatHandlers;
+declare function toNextRoute(handlers: ChatHandlers): {
+    GET: (request: Request) => Promise<Response>;
+    POST: (request: Request) => Promise<Response>;
+};
+
+/** Persist chat image attachments under the workspace and return absolute paths. */
+declare function saveChatAttachments(attachments: ChatAttachment[] | undefined, workspaceDir: string): Promise<string[]>;
+
+interface LocalStoredMessage {
+    id: string;
+    conversationId: string;
+    role: "user" | "assistant" | "system";
+    content: string;
+    provider: string | null;
+    createdAt: string;
+    attachmentPaths?: string[];
+    senderType?: "client" | "developer" | "ai" | null;
+    senderName?: string | null;
+}
+/**
+ * Persist conversations as JSON files under a local directory.
+ * Layout: `{baseDir}/{conversationId}.json`
+ */
+declare function createLocalDirectoryStore(baseDir: string): ChatStoreLike & {
+    listMessages: (conversationId: string) => Promise<LocalStoredMessage[]>;
+    listConversations: NonNullable<ChatStoreLike["listConversations"]>;
+};
+
+interface MaintainerProStoreOptions {
+    baseUrl: string;
+    apiKey: string;
+    /** Directory for temporary local copies of images for CLI providers. */
+    tempDir?: string;
+    fetchImpl?: typeof fetch;
+}
+type UploadResult = {
+    /** Refs persisted on messages (maintainer-pro://uuid). */
+    refs: string[];
+    /** Absolute local temp paths for CLI image inspection. */
+    localPaths: string[];
+    attachmentIds: string[];
+};
+/**
+ * Persist chat data via Maintainer Pro HTTP API (no local .maintainer-pro writes).
+ */
+declare function createMaintainerProStore(options: MaintainerProStoreOptions): ChatStoreLike & {
+    uploadAttachments: (conversationId: string, attachments: ChatAttachment[] | undefined) => Promise<UploadResult>;
+};
+/** Build a Maintainer Pro store from env when configured. */
+declare function createMaintainerProStoreFromEnv(): ReturnType<typeof createMaintainerProStore> | null;
+
+interface PriorConversationOptions {
+    excludeConversationId?: string;
+    currentRequest: string;
+    maxConversations?: number;
+    maxMessagesPerConversation?: number;
+}
+/**
+ * Load other conversations from the store and format a compact prompt block.
+ * Prefers chats that share keywords with the current request; falls back to
+ * most recently updated. Empty string when nothing useful is available.
+ */
+declare function buildPriorConversationsContext(db: ChatStoreLike, options: PriorConversationOptions): Promise<string>;
+
+export { type AiCliProviderId, type AiProvider, type AiResponse, type CallAiOptions, type ChatAttachment, type ChatHandlerOptions, type ChatHandlers, type ChatMessage, type ChatSenderType, type ChatStoreLike, type ChatUser, type ClientContext, type LocalStoredMessage, type MaintainerProStoreOptions, type PriorConversationOptions, type ProviderPreference, type ToolCall, type ToolSchemaMap, buildClaudeUserPrompt, buildConversationPrompt, buildCursorPrompt, buildPriorConversationsContext, callAi, commandExists, createAntigravityProvider, createBuiltinProviders, createChatHandler, createClaudeProvider, createCursorProvider, createDefaultSystemPrompt, createLocalDirectoryStore, createMaintainerProStore, createMaintainerProStoreFromEnv, createToolValidator, formatClientContext, getProviderPreference, parseAiResponse, providerLabel, resolveCliBinary, resolveProvider, saveChatAttachments, toNextRoute };