@shrkcrft/ai 0.1.0-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SharkCraft contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,15 @@
+# @shrkcrft/ai
+
+SharkCraft AI provider abstraction: Claude HTTP + Claude CLI adapters.
+
+Part of [SharkCraft](https://github.com/shrkcrft/sharkcraft) — a deterministic, local-first toolkit that gives AI coding agents durable project context. See the main repo for documentation, examples, and the `shrk` CLI.
+
+## Install
+
+```bash
+bun add @shrkcrft/ai
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/ai-provider.d.ts

@@ -0,0 +1,18 @@
+import type { Result, AppError } from '@shrkcrft/core';
+import type { IAiProviderConfig, IAiRequest, IAiResponse } from './ai-request.js';
+export interface IAiProvider {
+    readonly id: string;
+    readonly name: string;
+    configure(config: IAiProviderConfig): void;
+    isReady(): boolean;
+    send(request: IAiRequest): Promise<Result<IAiResponse, AppError>>;
+}
+export declare abstract class AbstractAiProvider implements IAiProvider {
+    abstract readonly id: string;
+    abstract readonly name: string;
+    protected config: IAiProviderConfig;
+    configure(config: IAiProviderConfig): void;
+    isReady(): boolean;
+    abstract send(request: IAiRequest): Promise<Result<IAiResponse, AppError>>;
+}
+//# sourceMappingURL=ai-provider.d.ts.map

package/dist/ai-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-provider.d.ts","sourceRoot":"","sources":["../src/ai-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAElF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC3C,OAAO,IAAI,OAAO,CAAC;IACnB,IAAI,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC;CACnE;AAED,8BAAsB,kBAAmB,YAAW,WAAW;IAC7D,QAAQ,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAC/B,SAAS,CAAC,MAAM,EAAE,iBAAiB,CAAM;IAEzC,SAAS,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI;IAI1C,OAAO,IAAI,OAAO;IAIlB,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;CAC3E"}

package/dist/ai-provider.js

@@ -0,0 +1,9 @@
+export class AbstractAiProvider {
+    config = {};
+    configure(config) {
+        this.config = { ...this.config, ...config };
+    }
+    isReady() {
+        return true;
+    }
+}

package/dist/ai-request.d.ts

@@ -0,0 +1,33 @@
+export declare enum AiMessageRole {
+    System = "system",
+    User = "user",
+    Assistant = "assistant"
+}
+export interface IAiMessage {
+    role: AiMessageRole;
+    content: string;
+}
+export interface IAiRequest {
+    messages: readonly IAiMessage[];
+    model?: string;
+    maxTokens?: number;
+    temperature?: number;
+    context?: string;
+}
+export interface IAiResponse {
+    content: string;
+    model: string;
+    finishReason?: string;
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+    };
+    raw?: unknown;
+}
+export interface IAiProviderConfig {
+    apiKey?: string;
+    baseUrl?: string;
+    model?: string;
+    timeoutMs?: number;
+}
+//# sourceMappingURL=ai-request.d.ts.map

package/dist/ai-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-request.d.ts","sourceRoot":"","sources":["../src/ai-request.ts"],"names":[],"mappings":"AAAA,oBAAY,aAAa;IACvB,MAAM,WAAW;IACjB,IAAI,SAAS;IACb,SAAS,cAAc;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,SAAS,UAAU,EAAE,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACxD,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}

package/dist/ai-request.js

@@ -0,0 +1,6 @@
+export var AiMessageRole;
+(function (AiMessageRole) {
+    AiMessageRole["System"] = "system";
+    AiMessageRole["User"] = "user";
+    AiMessageRole["Assistant"] = "assistant";
+})(AiMessageRole || (AiMessageRole = {}));

package/dist/claude/claude-cli-adapter.d.ts

@@ -0,0 +1,17 @@
+import { type AppError, type Result } from '@shrkcrft/core';
+import { AbstractAiProvider } from '../ai-provider.js';
+import type { IAiRequest, IAiResponse } from '../ai-request.js';
+/**
+ * Optional adapter that shells out to a local `claude` CLI binary.
+ * It assumes the binary supports `--print --output-format=text`. If it does not,
+ * isReady() returns false and send() returns an actionable error.
+ */
+export declare class ClaudeCliAdapter extends AbstractAiProvider {
+    readonly id = "claude-cli";
+    readonly name = "Claude (local CLI)";
+    private readonly cliPath;
+    constructor(cliPath?: string);
+    isReady(): boolean;
+    send(request: IAiRequest): Promise<Result<IAiResponse, AppError>>;
+}
+//# sourceMappingURL=claude-cli-adapter.d.ts.map

package/dist/claude/claude-cli-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-cli-adapter.d.ts","sourceRoot":"","sources":["../../src/claude/claude-cli-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsC,KAAK,QAAQ,EAAE,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAEhG,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEhE;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,kBAAkB;IACtD,QAAQ,CAAC,EAAE,gBAAgB;IAC3B,QAAQ,CAAC,IAAI,wBAAwB;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,OAAO,SAAW;IAK9B,OAAO,IAAI,OAAO;IAKZ,IAAI,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;CAgDxE"}

package/dist/claude/claude-cli-adapter.js

@@ -0,0 +1,52 @@
+import { AppErrorImpl, ERROR_CODES, err, ok } from '@shrkcrft/core';
+import { spawn } from 'node:child_process';
+import { AbstractAiProvider } from "../ai-provider.js";
+/**
+ * Optional adapter that shells out to a local `claude` CLI binary.
+ * It assumes the binary supports `--print --output-format=text`. If it does not,
+ * isReady() returns false and send() returns an actionable error.
+ */
+export class ClaudeCliAdapter extends AbstractAiProvider {
+    id = 'claude-cli';
+    name = 'Claude (local CLI)';
+    cliPath;
+    constructor(cliPath = 'claude') {
+        super();
+        this.cliPath = cliPath;
+    }
+    isReady() {
+        // Best-effort. The actual check happens during send().
+        return true;
+    }
+    async send(request) {
+        const prompt = request.messages.map((m) => `[${m.role}] ${m.content}`).join('\n\n');
+        return await new Promise((resolve) => {
+            try {
+                const proc = spawn(this.cliPath, ['--print', '--output-format=text'], {
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                });
+                let stdout = '';
+                let stderr = '';
+                proc.stdout.on('data', (b) => (stdout += b.toString('utf8')));
+                proc.stderr.on('data', (b) => (stderr += b.toString('utf8')));
+                proc.on('error', (e) => {
+                    resolve(err(new AppErrorImpl(ERROR_CODES.IO_ERROR, `Failed to spawn claude CLI at "${this.cliPath}": ${e.message}`, { suggestion: 'Install Claude Code or pass a different cliPath', cause: e })));
+                });
+                proc.on('close', (code) => {
+                    if (code === 0) {
+                        resolve(ok({ content: stdout.trim(), model: 'claude-cli' }));
+                    }
+                    else {
+                        resolve(err(new AppErrorImpl(ERROR_CODES.IO_ERROR, `claude CLI exited with ${code}: ${stderr.slice(0, 500)}`)));
+                    }
+                });
+                proc.stdin.end(prompt);
+            }
+            catch (e) {
+                resolve(err(new AppErrorImpl(ERROR_CODES.IO_ERROR, `Failed to invoke claude CLI: ${e.message}`, {
+                    cause: e,
+                })));
+            }
+        });
+    }
+}

package/dist/claude/claude-provider.d.ts

@@ -0,0 +1,15 @@
+import { type AppError, type Result } from '@shrkcrft/core';
+import { AbstractAiProvider } from '../ai-provider.js';
+import type { IAiRequest, IAiResponse } from '../ai-request.js';
+/**
+ * Reference HTTP adapter for Anthropic's Claude Messages API.
+ * Kept dependency-free: uses fetch() directly. If ANTHROPIC_API_KEY is missing,
+ * isReady() returns false and send() reports an actionable error.
+ */
+export declare class ClaudeProvider extends AbstractAiProvider {
+    readonly id = "claude";
+    readonly name = "Anthropic Claude (HTTP)";
+    isReady(): boolean;
+    send(request: IAiRequest): Promise<Result<IAiResponse, AppError>>;
+}
+//# sourceMappingURL=claude-provider.d.ts.map

package/dist/claude/claude-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-provider.d.ts","sourceRoot":"","sources":["../../src/claude/claude-provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsC,KAAK,QAAQ,EAAE,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAChG,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEhE;;;;GAIG;AACH,qBAAa,cAAe,SAAQ,kBAAkB;IACpD,QAAQ,CAAC,EAAE,YAAY;IACvB,QAAQ,CAAC,IAAI,6BAA6B;IAE1C,OAAO,IAAI,OAAO;IAIZ,IAAI,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;CAmExE"}

package/dist/claude/claude-provider.js

@@ -0,0 +1,65 @@
+import { AppErrorImpl, ERROR_CODES, err, ok } from '@shrkcrft/core';
+import { AbstractAiProvider } from "../ai-provider.js";
+/**
+ * Reference HTTP adapter for Anthropic's Claude Messages API.
+ * Kept dependency-free: uses fetch() directly. If ANTHROPIC_API_KEY is missing,
+ * isReady() returns false and send() reports an actionable error.
+ */
+export class ClaudeProvider extends AbstractAiProvider {
+    id = 'claude';
+    name = 'Anthropic Claude (HTTP)';
+    isReady() {
+        return Boolean(this.config.apiKey ?? process.env.ANTHROPIC_API_KEY);
+    }
+    async send(request) {
+        const apiKey = this.config.apiKey ?? process.env.ANTHROPIC_API_KEY;
+        if (!apiKey) {
+            return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, 'ANTHROPIC_API_KEY is not set — cannot reach Claude', { suggestion: 'export ANTHROPIC_API_KEY=...' }));
+        }
+        const baseUrl = this.config.baseUrl ?? 'https://api.anthropic.com';
+        const model = request.model ?? this.config.model ?? 'claude-sonnet-4-6';
+        const maxTokens = request.maxTokens ?? 1024;
+        const messages = request.messages
+            .filter((m) => m.role !== 'system')
+            .map((m) => ({ role: m.role, content: m.content }));
+        const system = request.messages
+            .filter((m) => m.role === 'system')
+            .map((m) => m.content)
+            .join('\n\n') || undefined;
+        try {
+            const res = await fetch(`${baseUrl}/v1/messages`, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    'x-api-key': apiKey,
+                    'anthropic-version': '2023-06-01',
+                },
+                body: JSON.stringify({ model, max_tokens: maxTokens, messages, system }),
+            });
+            if (!res.ok) {
+                const text = await res.text();
+                return err(new AppErrorImpl(ERROR_CODES.IO_ERROR, `Claude API ${res.status}: ${text.slice(0, 500)}`));
+            }
+            const json = (await res.json());
+            const text = (json.content ?? [])
+                .filter((b) => b.type === 'text' && typeof b.text === 'string')
+                .map((b) => b.text)
+                .join('');
+            return ok({
+                content: text,
+                model: json.model ?? model,
+                finishReason: json.stop_reason,
+                usage: {
+                    inputTokens: json.usage?.input_tokens,
+                    outputTokens: json.usage?.output_tokens,
+                },
+                raw: json,
+            });
+        }
+        catch (e) {
+            return err(new AppErrorImpl(ERROR_CODES.IO_ERROR, `Failed to call Claude: ${e.message}`, {
+                cause: e,
+            }));
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './ai-provider.js';
+export * from './ai-request.js';
+export * from './prompt/prompt-builder.js';
+export * from './claude/claude-provider.js';
+export * from './claude/claude-cli-adapter.js';
+//# 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":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,gCAAgC,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from "./ai-provider.js";
+export * from "./ai-request.js";
+export * from "./prompt/prompt-builder.js";
+export * from "./claude/claude-provider.js";
+export * from "./claude/claude-cli-adapter.js";

package/dist/prompt/prompt-builder.d.ts

@@ -0,0 +1,9 @@
+import { type IAiMessage } from '../ai-request.js';
+export interface BuildPromptInput {
+    systemPreamble?: string;
+    context?: string;
+    task: string;
+    userMessage?: string;
+}
+export declare function buildPromptMessages(input: BuildPromptInput): IAiMessage[];
+//# sourceMappingURL=prompt-builder.d.ts.map

package/dist/prompt/prompt-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-builder.d.ts","sourceRoot":"","sources":["../../src/prompt/prompt-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAElE,MAAM,WAAW,gBAAgB;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,gBAAgB,GAAG,UAAU,EAAE,CAkBzE"}

package/dist/prompt/prompt-builder.js

@@ -0,0 +1,19 @@
+import { AiMessageRole } from "../ai-request.js";
+export function buildPromptMessages(input) {
+    const messages = [];
+    const systemParts = [];
+    if (input.systemPreamble)
+        systemParts.push(input.systemPreamble.trim());
+    if (input.context) {
+        systemParts.push('## Repository context\n\nUse this context as authoritative ground truth.\n\n' +
+            input.context.trim());
+    }
+    if (systemParts.length) {
+        messages.push({ role: AiMessageRole.System, content: systemParts.join('\n\n') });
+    }
+    const userContent = input.userMessage
+        ? `${input.task}\n\n${input.userMessage}`
+        : input.task;
+    messages.push({ role: AiMessageRole.User, content: userContent });
+    return messages;
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@shrkcrft/ai",
+  "version": "0.1.0-alpha.2",
+  "description": "SharkCraft AI provider abstraction: Claude HTTP + Claude CLI adapters.",
+  "license": "MIT",
+  "author": "SharkCraft contributors",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shrkcrft/sharkcraft.git",
+    "directory": "packages/ai"
+  },
+  "homepage": "https://github.com/shrkcrft/sharkcraft",
+  "bugs": {
+    "url": "https://github.com/shrkcrft/sharkcraft/issues"
+  },
+  "keywords": [
+    "sharkcraft",
+    "ai",
+    "claude",
+    "anthropic"
+  ],
+  "engines": {
+    "bun": ">=1.1.0",
+    "node": ">=18"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@shrkcrft/core": "^0.1.0-alpha.2",
+    "@shrkcrft/context": "^0.1.0-alpha.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}