@offworld/sdk 0.2.2 → 0.3.0

package/README.md

@@ -10,26 +10,40 @@ Powers the CLI and web app with git clone management, AI reference generation, a
 bun add @offworld/sdk
 ```
 
+### Optional dependencies
+
+- Sync: `bun add convex`
+- AI: `bun add @opencode-ai/sdk`
+
+### Entry points
+
+- `@offworld/sdk` (core local functionality)
+- `@offworld/sdk/sync` (Convex sync)
+- `@offworld/sdk/ai` (AI generation)
+- `@offworld/sdk/internal` (CLI-only helpers)
+- `@offworld/sdk/convex/api` and `@offworld/sdk/convex/server` (Convex types)
+
 ## Modules
 
-| Module                 | Description                               |
-| ---------------------- | ----------------------------------------- |
-| `config.ts`            | Config load/save, path utilities          |
-| `paths.ts`             | XDG-compliant path resolution             |
-| `clone.ts`             | Git clone/update/remove                   |
-| `index-manager.ts`     | Global + project map management           |
-| `generate.ts`          | AI reference generation                   |
-| `sync.ts`              | Convex client for push/pull               |
-| `auth.ts`              | WorkOS token management                   |
-| `agents.ts`            | Agent registry                            |
-| `agents-md.ts`         | AGENTS.md reference table generation      |
-| `repo-source.ts`       | Parse repo input (URL, owner/repo, local) |
-| `manifest.ts`          | Dependency parsing (package.json, etc.)   |
-| `dep-mappings.ts`      | npm package to GitHub repo resolution     |
-| `reference-matcher.ts` | Match deps to installed references        |
-| `repo-manager.ts`      | Bulk repo operations (update, prune, gc)  |
-| `models.ts`            | AI provider/model registry                |
-| `installation.ts`      | Upgrade/uninstall utilities               |
+| Module                 | Description                                        |
+| ---------------------- | -------------------------------------------------- |
+| `config.ts`            | Config load/save, path utilities                   |
+| `paths.ts`             | XDG-compliant path resolution                      |
+| `clone.ts`             | Git clone/update/remove                            |
+| `index-manager.ts`     | Global + project map management                    |
+| `reference.ts`         | Reference install + SKILL.md                       |
+| `generate.ts`          | AI reference generation (`@offworld/sdk/ai`)       |
+| `sync.ts`              | Convex client for push/pull (`@offworld/sdk/sync`) |
+| `auth.ts`              | WorkOS token management                            |
+| `agents.ts`            | Agent registry                                     |
+| `agents-md.ts`         | AGENTS.md reference table generation (internal)    |
+| `repo-source.ts`       | Parse repo input (URL, owner/repo, local)          |
+| `manifest.ts`          | Dependency parsing (package.json, etc.)            |
+| `dep-mappings.ts`      | npm package to GitHub repo resolution              |
+| `reference-matcher.ts` | Match deps to installed references                 |
+| `repo-manager.ts`      | Bulk repo operations (update, prune, gc)           |
+| `models.ts`            | AI provider/model registry                         |
+| `installation.ts`      | Upgrade/uninstall utilities                        |
 
 ## Usage
 
@@ -56,7 +70,8 @@ await removeRepo("owner/repo", { referenceOnly: true });
 ### Reference Generation
 
 ```typescript
-import { generateReferenceWithAI, installReference } from "@offworld/sdk";
+import { generateReferenceWithAI } from "@offworld/sdk/ai";
+import { installReference } from "@offworld/sdk";
 
 const result = await generateReferenceWithAI(repoPath, { model: "claude-sonnet-4-20250514" });
 await installReference("owner/repo", result.referenceContent, result.commitSha);
@@ -75,7 +90,7 @@ await writeProjectMap(cwd, projectMap);
 ### Sync (Push/Pull)
 
 ```typescript
-import { pullReference, pushReference, checkRemote } from "@offworld/sdk";
+import { pullReference, pushReference, checkRemote } from "@offworld/sdk/sync";
 
 const ref = await pullReference("owner/repo");
 await pushReference("owner/repo", referenceData);

package/dist/ai/index.d.mts

@@ -0,0 +1,134 @@
+//#region src/ai/opencode.d.ts
+declare const DEFAULT_AI_PROVIDER = "opencode";
+declare const DEFAULT_AI_MODEL = "claude-opus-4-5";
+interface StreamPromptOptions {
+  prompt: string;
+  cwd: string;
+  systemPrompt?: string;
+  provider?: string;
+  model?: string;
+  /** Timeout in milliseconds. Set to 0 or undefined for no timeout. */
+  timeoutMs?: number;
+  onDebug?: (message: string) => void;
+  onStream?: (text: string) => void;
+}
+interface StreamPromptResult {
+  text: string;
+  sessionId: string;
+  durationMs: number;
+}
+declare function streamPrompt(options: StreamPromptOptions): Promise<StreamPromptResult>;
+//#endregion
+//#region src/ai/errors.d.ts
+/**
+ * Base class for OpenCode reference errors
+ */
+declare class OpenCodeReferenceError extends Error {
+  readonly details?: unknown | undefined;
+  readonly _tag: string;
+  constructor(message: string, details?: unknown | undefined);
+}
+/**
+ * Error when the @opencode-ai/sdk package is not installed or invalid
+ */
+declare class OpenCodeSDKError extends OpenCodeReferenceError {
+  readonly _tag: "OpenCodeSDKError";
+  constructor(message?: string);
+}
+/**
+ * Error when the requested provider is not found
+ */
+declare class InvalidProviderError extends OpenCodeReferenceError {
+  readonly providerID: string;
+  readonly availableProviders: string[];
+  readonly _tag: "InvalidProviderError";
+  readonly hint: string;
+  constructor(providerID: string, availableProviders: string[]);
+}
+/**
+ * Error when the provider exists but is not connected/authenticated
+ */
+declare class ProviderNotConnectedError extends OpenCodeReferenceError {
+  readonly providerID: string;
+  readonly connectedProviders: string[];
+  readonly _tag: "ProviderNotConnectedError";
+  readonly hint: string;
+  constructor(providerID: string, connectedProviders: string[]);
+}
+/**
+ * Error when the requested model is not found for a provider
+ */
+declare class InvalidModelError extends OpenCodeReferenceError {
+  readonly modelID: string;
+  readonly providerID: string;
+  readonly availableModels: string[];
+  readonly _tag: "InvalidModelError";
+  readonly hint: string;
+  constructor(modelID: string, providerID: string, availableModels: string[]);
+}
+/**
+ * Error when the OpenCode server fails to start
+ */
+declare class ServerStartError extends OpenCodeReferenceError {
+  readonly port?: number | undefined;
+  readonly _tag: "ServerStartError";
+  readonly hint: string;
+  constructor(message: string, port?: number | undefined, details?: unknown);
+}
+/**
+ * Error when a session operation fails
+ */
+declare class SessionError extends OpenCodeReferenceError {
+  readonly sessionId?: string | undefined;
+  readonly sessionState?: string | undefined;
+  readonly _tag: "SessionError";
+  readonly hint: string;
+  constructor(message: string, sessionId?: string | undefined, sessionState?: string | undefined, details?: unknown);
+}
+/**
+ * Error when a request times out
+ */
+declare class TimeoutError extends OpenCodeReferenceError {
+  readonly timeoutMs: number;
+  readonly operation: string;
+  readonly _tag: "TimeoutError";
+  readonly hint: string;
+  constructor(timeoutMs: number, operation?: string);
+}
+//#endregion
+//#region src/generate.d.ts
+/**
+ * This module provides a streamlined approach to generating reference files
+ * by delegating all codebase exploration to the AI agent via OpenCode.
+ */
+interface GenerateReferenceOptions {
+  /** AI provider ID (e.g., "anthropic", "openai"). Defaults to config value. */
+  provider?: string;
+  /** AI model ID. Defaults to config value. */
+  model?: string;
+  /** Debug callback for detailed logging */
+  onDebug?: (message: string) => void;
+  /** Stream callback for real-time AI output */
+  onStream?: (text: string) => void;
+}
+interface GenerateReferenceResult {
+  /** The generated reference markdown content */
+  referenceContent: string;
+  /** The commit SHA at the time of generation */
+  commitSha: string;
+}
+/**
+ * Generate a reference markdown file for a repository using AI.
+ *
+ * Opens an OpenCode session and instructs the AI agent to explore the codebase
+ * using Read, Grep, and Glob tools, then produce a comprehensive reference.
+ *
+ * @param repoPath - Path to the repository to analyze
+ * @param repoName - Qualified name of the repo (e.g., "tanstack/query" or "my-local-repo")
+ * @param options - Generation options (provider, model, callbacks)
+ * @returns The generated reference content and commit SHA
+ */
+declare function generateReferenceWithAI(repoPath: string, repoName: string, options?: GenerateReferenceOptions): Promise<GenerateReferenceResult>;
+//#endregion
+export { DEFAULT_AI_MODEL, DEFAULT_AI_PROVIDER, type GenerateReferenceOptions, type GenerateReferenceResult, InvalidModelError, InvalidProviderError, OpenCodeReferenceError, OpenCodeSDKError, ProviderNotConnectedError, ServerStartError, SessionError, type StreamPromptOptions, type StreamPromptResult, TimeoutError, generateReferenceWithAI, streamPrompt };
+//# sourceMappingURL=index.d.mts.map

package/dist/ai/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/ai/opencode.ts","../../src/ai/errors.ts","../../src/generate.ts"],"mappings":";cAYa,mBAAA;AAAA,cACA,gBAAA;AAAA,UAEI,mBAAA;EAChB,MAAA;EACA,GAAA;EACA,YAAA;EACA,QAAA;EAEA,KAAA;;EAEA,SAAA;EACA,OAAA,IAAW,OAAA;EACX,QAAA,IAAY,IAAA;AAAA;AAAA,UAGI,kBAAA;EAChB,IAAA;EACA,SAAA;EACA,UAAA;AAAA;AAAA,iBA+KqB,YAAA,CAAa,OAAA,EAAS,mBAAA,GAAsB,OAAA,CAAQ,kBAAA;;;;AAlM1E;;cCTa,sBAAA,SAA+B,KAAA;EAAA,SAI1B,OAAA;EAAA,SAHR,IAAA;cAER,OAAA,UACgB,OAAA;AAAA;;;;cAUL,gBAAA,SAAyB,sBAAA;EAAA,SAC5B,IAAA;cACG,OAAA;AAAA;;;;cAWA,oBAAA,SAA6B,sBAAA;EAAA,SAKxB,UAAA;EAAA,SACA,kBAAA;EAAA,SALR,IAAA;EAAA,SACA,IAAA;cAGQ,UAAA,UACA,kBAAA;AAAA;;;ADRlB;cCuBa,yBAAA,SAAkC,sBAAA;EAAA,SAK7B,UAAA;EAAA,SACA,kBAAA;EAAA,SALR,IAAA;EAAA,SACA,IAAA;cAGQ,UAAA,UACA,kBAAA;AAAA;;ADqJlB;;cCtIa,iBAAA,SAA0B,sBAAA;EAAA,SAKrB,OAAA;EAAA,SACA,UAAA;EAAA,SACA,eAAA;EAAA,SANR,IAAA;EAAA,SACA,IAAA;cAGQ,OAAA,UACA,UAAA,UACA,eAAA;AAAA;;;;cAeL,gBAAA,SAAyB,sBAAA;EAAA,SAMpB,IAAA;EAAA,SALR,IAAA;EAAA,SACA,IAAA;cAGR,OAAA,UACgB,IAAA,uBAChB,OAAA;AAAA;;;;cAcW,YAAA,SAAqB,sBAAA;EAAA,SAMhB,SAAA;EAAA,SACA,YAAA;EAAA,SANR,IAAA;EAAA,SACA,IAAA;cAGR,OAAA,UACgB,SAAA,uBACA,YAAA,uBAChB,OAAA;AAAA;AA1GF;;;AAAA,cAwHa,YAAA,SAAqB,sBAAA;EAAA,SAKhB,SAAA;EAAA,SACA,SAAA;EAAA,SALR,IAAA;EAAA,SACA,IAAA;cAGQ,SAAA,UACA,SAAA;AAAA;;;;ADnIlB;;;UEHiB,wBAAA;EFGe;EED/B,QAAA;EFE4B;EEA5B,KAAA;EFA4B;EEE5B,OAAA,IAAW,OAAA;EFAK;EEEhB,QAAA,IAAY,IAAA;AAAA;AAAA,UAGI,uBAAA;EFJhB;EEMA,gBAAA;EFJA;EEMA,SAAA;AAAA;;;;;;;;AFID;;;;iBE6TsB,uBAAA,CACrB,QAAA,UACA,QAAA,UACA,OAAA,GAAS,wBAAA,GACP,OAAA,CAAQ,uBAAA"}