@manycore/aholo-sdk-mcp 1.0.0

package/README.md

@@ -0,0 +1,160 @@
+# @manycore/aholo-sdk-mcp
+
+Aholo OpenAPI 的本地 MCP Server，供 [Cursor](https://cursor.com)、[Claude Desktop](https://claude.ai/download) 等 Agent Studio 通过 stdio 调用 Aholo 能力。
+
+底层封装公网 npm SDK（`@manycore/aholo-sdk-*`），支持：
+
+- 文件上传（Asset）
+- 3DGS 世界重建 / 生成（World）
+- 图生 3D、文生 3D（Lux3D）
+
+## 前置要求
+
+- **Node.js** ≥ 18
+- **Aholo API Key**
+  - 中国区：[https://labs.aholo3d.cn/api-keys](https://labs.aholo3d.cn/api-keys)
+  - 海外：[https://labs.aholo3d.com/api-keys](https://labs.aholo3d.com/api-keys)
+
+## 快速开始
+
+### 1. 配置 MCP
+
+**Cursor** — 编辑 `~/.cursor/mcp.json`：
+
+```json
+{
+  "mcpServers": {
+    "aholo-sdk-mcp": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@manycore/aholo-sdk-mcp"],
+      "env": {
+        "AHOLO_API_KEY": "your_api_key_here",
+        "AHOLO_REGION": "cn"
+      }
+    }
+  }
+}
+```
+
+**Claude Desktop** — 编辑配置文件（macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`）：
+
+```json
+{
+  "mcpServers": {
+    "aholo-sdk-mcp": {
+      "command": "npx",
+      "args": ["-y", "@manycore/aholo-sdk-mcp"],
+      "env": {
+        "AHOLO_API_KEY": "your_api_key_here",
+        "AHOLO_REGION": "cn"
+      }
+    }
+  }
+}
+```
+
+保存后重启 Agent / Studio，即可在对话中使用 Aholo 相关 tool。
+
+### 2. 验证安装
+
+```bash
+AHOLO_API_KEY=your_key npx -y @manycore/aholo-sdk-mcp
+```
+
+未设置 `AHOLO_API_KEY` 时会提示并退出，属正常行为。
+
+## 环境变量
+
+| 变量 | 必填 | 说明 |
+|------|------|------|
+| `AHOLO_API_KEY` | 是 | Aholo API Key。中国区在 [labs.aholo3d.cn/api-keys](https://labs.aholo3d.cn/api-keys) 申请；海外在 [labs.aholo3d.com/api-keys](https://labs.aholo3d.com/api-keys) 申请 |
+| `AHOLO_REGION` | 否 | `cn`（中国区，默认）或 `com`（海外）；也可在 tool 参数里传 |
+
+## 使用说明
+
+### 文件上传
+
+本地文件通过 `localPath` 传入，由 SDK 直接读磁盘上传至 CDN，**二进制不经过 MCP 协议**。
+
+### World 重建（scene）
+
+| 场景 | 选用 Tool |
+|------|-----------|
+| 单个物体 / 产品 / 手办 | `world_reconstruct_object_from_files` 或 `world_reconstruct_object` |
+| 室内 / 房间环拍 | `world_reconstruct_space_from_files` 或 `world_reconstruct_space` |
+
+- 图片重建须 **≥ 20 张**；纯视频请设 `resourceType=video`
+- `useMask=true` 表示抠图（主体分割）
+- `taskQuality` 默认 `normal`；用户说「快速预览」→ `low`，「高质量/专业」→ `high`
+
+### 长任务
+
+提交类 tool 默认 `wait=false`，立即返回 `worldId` / `taskId`：
+
+1. 查进度：`world_get` / `lux3d_get_task`（推荐，非阻塞）
+2. 等到完成：`world_wait_for` / `lux3d_wait_for_task`（阻塞，可能占用连接数分钟）
+
+## Tools
+
+**推荐（scene 已固定）：**
+
+| Tool | 说明 |
+|------|------|
+| `world_inspect_local_media` | 只读：分析本地图片/视频，可选抽帧预览 |
+| `world_reconstruct_object_from_files` | 本地文件 → 物体（model）重建 |
+| `world_reconstruct_space_from_files` | 本地文件 → 室内（space）重建 |
+| `world_reconstruct_object` | URL → 物体（model）重建 |
+| `world_reconstruct_space` | URL → 室内（space）重建 |
+
+**兼容（须自行指定 scene 并确认）：**
+
+| Tool | 说明 |
+|------|------|
+| `world_reconstruct` | URL 重建 |
+| `world_reconstruct_from_files` | 本地文件重建 |
+
+**通用：**
+
+| Tool | 说明 |
+|------|------|
+| `upload_asset` | 上传本地文件，返回 CDN URL |
+| `world_generate` | 文字生成 3D 世界（Spatial Gen） |
+| `world_get` | 查询 world 详情（只读） |
+| `world_wait_for` | 轮询 world 直至终态 |
+| `world_list` | 分页列出 world（只读） |
+| `lux3d_img_to_3d_from_file` | 本地图片 → Lux3D 3D |
+| `lux3d_img_to_3d` | 图片 URL → Lux3D 3D |
+| `lux3d_text_to_3d` | 文字 → Lux3D 3D |
+| `lux3d_get_task` | 查询 Lux3D 任务（只读） |
+| `lux3d_wait_for_task` | 轮询 Lux3D 任务 |
+
+## 相关文档
+
+- [Aholo API 文档](https://labs.aholo3d.cn/api-docs)
+- [TypeScript SDK 指南](https://labs.aholo3d.cn/api-docs/sdk/typescript)
+- [World 重建 Skill（参考工作流）](https://labs.aholo3d.cn/api-docs/skills/aholo-3dgs-reconstruction)
+
+## 从源码运行（可选）
+
+```bash
+git clone https://github.com/manycoretech/aholo-spatial-sdk.git
+cd aholo-spatial-sdk/typescript/mcp   # 以仓库实际目录为准
+npm install
+npm run build
+AHOLO_API_KEY=your_key npm start
+```
+
+本地调试时，将 Cursor 配置中的 `command` / `args` 改为指向构建产物：
+
+```json
+"aholo-sdk-mcp": {
+  "type": "stdio",
+  "command": "node",
+  "args": ["/absolute/path/to/dist/index.js"],
+  "env": {
+    "AHOLO_API_KEY": "your_api_key_here",
+    "AHOLO_REGION": "cn"
+  }
+}
+```

package/dist/config.d.ts

@@ -0,0 +1,3 @@
+import type { AholoClientConfig, AholoRegion } from '@manycore/aholo-sdk-core';
+export declare function resolveRegion(region?: string): AholoRegion;
+export declare function buildClientConfig(region?: string): AholoClientConfig;

package/dist/config.js

@@ -0,0 +1,11 @@
+export function resolveRegion(region) {
+    const value = region ?? process.env.AHOLO_REGION ?? 'cn';
+    if (value !== 'cn' && value !== 'com') {
+        throw new Error(`Invalid region "${value}". Use "cn" or "com".`);
+    }
+    return value;
+}
+export function buildClientConfig(region) {
+    return { region: resolveRegion(region) };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,aAAa,CAAC,MAAe;IAC3C,MAAM,KAAK,GAAG,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,IAAI,CAAC;IACzD,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,KAAK,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,mBAAmB,KAAK,uBAAuB,CAAC,CAAC;IACnE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,MAAe;IAC/C,OAAO,EAAE,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;AAC3C,CAAC"}

package/dist/constants.d.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+export declare const SERVER_VERSION = "1.0.0";
+export declare const regionSchema: z.ZodOptional<z.ZodEnum<{
+    cn: "cn";
+    com: "com";
+}>>;
+export declare const useMaskSchema: z.ZodOptional<z.ZodBoolean>;
+export declare const waitSchema: z.ZodOptional<z.ZodBoolean>;
+/** 重建质量说明（tool description / instructions 共用） */
+export declare const TASK_QUALITY_HINT: string;
+export declare const taskQualitySchema: z.ZodDefault<z.ZodEnum<{
+    low: "low";
+    normal: "normal";
+    high: "high";
+}>>;
+export declare const sceneSchema: z.ZodEnum<{
+    model: "model";
+    space: "space";
+}>;
+export declare const sceneSourceSchema: z.ZodEnum<{
+    user_explicit: "user_explicit";
+    inspect: "inspect";
+}>;
+export declare const READONLY_ANNOTATIONS: {
+    readonly readOnlyHint: true;
+    readonly destructiveHint: false;
+    readonly idempotentHint: true;
+};
+export declare const DESTRUCTIVE_ANNOTATIONS: {
+    readonly readOnlyHint: false;
+    readonly destructiveHint: true;
+    readonly idempotentHint: false;
+};
+export declare const SERVER_INSTRUCTIONS: string;
+export declare const RECONSTRUCT_OBJECT_DESC: string;
+export declare const RECONSTRUCT_SPACE_DESC: string;
+/** 提交类 tool 共用的长任务提示（index.ts 内联 description 可引用） */
+export declare const LONG_TASK_SUBMIT_HINT = "\u9ED8\u8BA4 wait=false\uFF0C\u7ACB\u5373\u8FD4\u56DE ID\uFF1B\u67E5\u8FDB\u5EA6\u7528 world_get / lux3d_get_task\uFF08\u975E\u963B\u585E\uFF09\u3002";
+/** world_wait_for / lux3d_wait_for_task 的 description */
+export declare const LONG_TASK_BLOCKING_WAIT_DESC = "\u963B\u585E\u5F0F\u8F6E\u8BE2\u76F4\u81F3 SUCCEEDED \u6216\u7EC8\u6001\u5931\u8D25\u3002stdio \u4E0B\u4F1A\u5360\u7528\u8FDE\u63A5\u6570\u5206\u949F\uFF5E\u6570\u5341\u5206\u949F\uFF1B\u5E38\u89C4\u67E5\u8FDB\u5EA6\u8BF7\u7528 world_get / lux3d_get_task\u3002\u4EC5\u5F53\u7528\u6237\u660E\u786E\u8981\u6C42\u300C\u7B49\u5230\u5B8C\u6210\u300D\u65F6\u8C03\u7528\u3002";

package/dist/constants.js

@@ -0,0 +1,94 @@
+import { z } from 'zod';
+export const SERVER_VERSION = '1.0.0';
+export const regionSchema = z
+    .enum(['cn', 'com'])
+    .optional()
+    .describe('API 区域：cn 中国区 / com 海外。默认 AHOLO_REGION 或 cn。');
+export const useMaskSchema = z
+    .boolean()
+    .optional()
+    .describe('是否对上传资源抠图（useMask）。true 开启主体分割；省略或 false 不抠图。');
+export const waitSchema = z
+    .boolean()
+    .optional()
+    .describe('是否在本 tool 内轮询至终态。默认 false（仅返回 worldId/taskId，立即释放连接）。查进度请用 world_get / lux3d_get_task（非阻塞）；仅当用户明确要求「等到完成」时再设 true 或调 world_wait_for / lux3d_wait_for_task（阻塞，stdio 下可能占用数分钟～数十分钟）。');
+/** 重建质量说明（tool description / instructions 共用） */
+export const TASK_QUALITY_HINT = [
+    'taskQuality 默认 normal（标准质量，可省略）。',
+    'low = 极速预览：用户说「快速预览/先看看/试效果/低质量/快点」；',
+    'high = 专业质量：用户说「高质量/专业/商用/精细/最好效果」。',
+].join(' ');
+export const taskQualitySchema = z
+    .enum(['low', 'normal', 'high'])
+    .default('normal')
+    .describe([
+    '重建质量，默认 normal（省略即用标准）。',
+    'low = 极速预览（触发词：快速预览、先看看、试效果、快点）；',
+    'normal = 标准（默认）；',
+    'high = 专业（触发词：高质量、专业、商用、精细、最好效果）。',
+].join(' '));
+export const sceneSchema = z.enum(['model', 'space']).describe([
+    '场景类型（创建后不可改，选错会导致任务作废）：',
+    'model = 单个物体/产品/手办，相机绕物体拍摄；',
+    'space = 室内/房间环拍，重建整个空间。',
+    '用户已明确说「模型/物体/室内/空间」时可填；不确定时不要猜，先追问用户或使用 world_inspect_local_media。',
+].join(' '));
+export const sceneSourceSchema = z.enum(['user_explicit', 'inspect']).describe([
+    'scene 依据：',
+    'user_explicit = 用户原话已明确 model/space（须同时 userConfirmedScene=true）；',
+    'inspect = 已调用 world_inspect_local_media 辅助判断。',
+    '禁止在无依据时 silent 默认 scene。',
+].join(' '));
+export const READONLY_ANNOTATIONS = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+};
+export const DESTRUCTIVE_ANNOTATIONS = {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+};
+export const SERVER_INSTRUCTIONS = [
+    'Aholo OpenAPI local MCP（@manycore/aholo-sdk-*）。需要 AHOLO_API_KEY。',
+    '文件上传走 localPath，二进制不经过 MCP 协议。',
+    '',
+    'World 重建 scene 规则（禁止猜测）：',
+    '- 用户说「模型/物体/产品/手办/模型视频」→ model',
+    '- 用户说「室内/房间/空间/环拍」→ space',
+    '- 仅说「重建/做3D」等模糊说法 → 追问 model 或 space，或可选 world_inspect_local_media',
+    '- 优先使用 world_reconstruct_object_* / world_reconstruct_space_*（scene 已固定）',
+    '',
+    '长任务工作流（stdio 禁止长时间阻塞）：',
+    '- 提交：wait=false（默认），立即返回 worldId / taskId',
+    '- 查进度：优先 world_get / lux3d_get_task（秒回，非阻塞）',
+    '- 等到完成：仅当用户明确要求时，才用 world_wait_for / lux3d_wait_for_task',
+    '图片重建：resources 中图片类须 ≥20 条；纯视频每条 type=video。',
+    'useMask=true 表示抠图/主体分割。',
+    '',
+    '重建质量 taskQuality（默认 normal，不必每次问用户）：',
+    '- 未提及质量 → normal',
+    '- 「快速预览/先看看/试效果/快点」→ low',
+    '- 「高质量/专业/商用/精细」→ high',
+].join('\n');
+export const RECONSTRUCT_OBJECT_DESC = [
+    '从本地文件创建 **物体场景（model）** 3DGS 重建：先上传再提交任务。',
+    '适用：单个物体/产品/手办/模型视频，相机绕物体拍摄。',
+    '不适用：室内房间环拍（请用 world_reconstruct_space_from_files）。',
+    '图片重建须 ≥20 张；纯视频会自动设 type=video。',
+    '提交后不可改 scene；默认 wait=false，查进度用 world_get（非阻塞）。',
+    TASK_QUALITY_HINT,
+].join(' ');
+export const RECONSTRUCT_SPACE_DESC = [
+    '从本地文件创建 **室内空间（space）** 3DGS 重建：先上传再提交任务。',
+    '适用：室内/房间 walkthrough、空间环拍。',
+    '不适用：桌面单品/手办（请用 world_reconstruct_object_from_files）。',
+    '图片重建须 ≥20 张；纯视频会自动设 type=video。',
+    '默认 wait=false，查进度用 world_get（非阻塞）。',
+    TASK_QUALITY_HINT,
+].join(' ');
+/** 提交类 tool 共用的长任务提示（index.ts 内联 description 可引用） */
+export const LONG_TASK_SUBMIT_HINT = '默认 wait=false，立即返回 ID；查进度用 world_get / lux3d_get_task（非阻塞）。';
+/** world_wait_for / lux3d_wait_for_task 的 description */
+export const LONG_TASK_BLOCKING_WAIT_DESC = '阻塞式轮询直至 SUCCEEDED 或终态失败。stdio 下会占用连接数分钟～数十分钟；常规查进度请用 world_get / lux3d_get_task。仅当用户明确要求「等到完成」时调用。';
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,194 @@
+export declare function toolError(toolName: string, error: unknown): {
+    [x: string]: unknown;
+    content: ({
+        type: "text";
+        text: string;
+        annotations?: {
+            audience?: ("user" | "assistant")[] | undefined;
+            priority?: number | undefined;
+            lastModified?: string | undefined;
+        } | undefined;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    } | {
+        type: "image";
+        data: string;
+        mimeType: string;
+        annotations?: {
+            audience?: ("user" | "assistant")[] | undefined;
+            priority?: number | undefined;
+            lastModified?: string | undefined;
+        } | undefined;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    } | {
+        type: "audio";
+        data: string;
+        mimeType: string;
+        annotations?: {
+            audience?: ("user" | "assistant")[] | undefined;
+            priority?: number | undefined;
+            lastModified?: string | undefined;
+        } | undefined;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    } | {
+        uri: string;
+        name: string;
+        type: "resource_link";
+        description?: string | undefined;
+        mimeType?: string | undefined;
+        size?: number | undefined;
+        annotations?: {
+            audience?: ("user" | "assistant")[] | undefined;
+            priority?: number | undefined;
+            lastModified?: string | undefined;
+        } | undefined;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+        icons?: {
+            src: string;
+            mimeType?: string | undefined;
+            sizes?: string[] | undefined;
+            theme?: "light" | "dark" | undefined;
+        }[] | undefined;
+        title?: string | undefined;
+    } | {
+        type: "resource";
+        resource: {
+            uri: string;
+            text: string;
+            mimeType?: string | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | {
+            uri: string;
+            blob: string;
+            mimeType?: string | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        };
+        annotations?: {
+            audience?: ("user" | "assistant")[] | undefined;
+            priority?: number | undefined;
+            lastModified?: string | undefined;
+        } | undefined;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    })[];
+    _meta?: {
+        [x: string]: unknown;
+        progressToken?: string | number | undefined;
+        "io.modelcontextprotocol/related-task"?: {
+            taskId: string;
+        } | undefined;
+    } | undefined;
+    structuredContent?: {
+        [x: string]: unknown;
+    } | undefined;
+    isError?: boolean | undefined;
+};
+export declare function sceneNotConfirmedError(): {
+    [x: string]: unknown;
+    content: ({
+        type: "text";
+        text: string;
+        annotations?: {
+            audience?: ("user" | "assistant")[] | undefined;
+            priority?: number | undefined;
+            lastModified?: string | undefined;
+        } | undefined;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    } | {
+        type: "image";
+        data: string;
+        mimeType: string;
+        annotations?: {
+            audience?: ("user" | "assistant")[] | undefined;
+            priority?: number | undefined;
+            lastModified?: string | undefined;
+        } | undefined;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    } | {
+        type: "audio";
+        data: string;
+        mimeType: string;
+        annotations?: {
+            audience?: ("user" | "assistant")[] | undefined;
+            priority?: number | undefined;
+            lastModified?: string | undefined;
+        } | undefined;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    } | {
+        uri: string;
+        name: string;
+        type: "resource_link";
+        description?: string | undefined;
+        mimeType?: string | undefined;
+        size?: number | undefined;
+        annotations?: {
+            audience?: ("user" | "assistant")[] | undefined;
+            priority?: number | undefined;
+            lastModified?: string | undefined;
+        } | undefined;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+        icons?: {
+            src: string;
+            mimeType?: string | undefined;
+            sizes?: string[] | undefined;
+            theme?: "light" | "dark" | undefined;
+        }[] | undefined;
+        title?: string | undefined;
+    } | {
+        type: "resource";
+        resource: {
+            uri: string;
+            text: string;
+            mimeType?: string | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | {
+            uri: string;
+            blob: string;
+            mimeType?: string | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        };
+        annotations?: {
+            audience?: ("user" | "assistant")[] | undefined;
+            priority?: number | undefined;
+            lastModified?: string | undefined;
+        } | undefined;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    })[];
+    _meta?: {
+        [x: string]: unknown;
+        progressToken?: string | number | undefined;
+        "io.modelcontextprotocol/related-task"?: {
+            taskId: string;
+        } | undefined;
+    } | undefined;
+    structuredContent?: {
+        [x: string]: unknown;
+    } | undefined;
+    isError?: boolean | undefined;
+};

package/dist/errors.js

@@ -0,0 +1,48 @@
+import { AuthenticationError, BusinessError, PollingFailedError, PollingTimeoutError, RateLimitError, } from '@manycore/aholo-sdk-core';
+import { errorResult } from './response.js';
+const BIZ_CODE_HINTS = {
+    '11004': '任务处理失败，请检查素材格式与数量是否符合要求（图片 ≥20 张或视频 type=video）。',
+};
+export function toolError(toolName, error) {
+    if (error instanceof AuthenticationError) {
+        return errorResult(`${toolName}: API Key 无效或未设置`, {
+            code: 'authentication_error',
+            hint: '检查 mcp.json 中 AHOLO_API_KEY；中国区申请 https://labs.aholo3d.cn/api-keys ，海外 https://labs.aholo3d.com/api-keys',
+        });
+    }
+    if (error instanceof RateLimitError) {
+        return errorResult(`${toolName}: 请求频率超限`, {
+            code: 'rate_limit',
+            hint: '稍后重试',
+        });
+    }
+    if (error instanceof BusinessError) {
+        const bizCode = error.bizCode ?? error.cmdCode;
+        return errorResult(`${toolName}: 业务错误`, {
+            code: 'business_error',
+            bizCode,
+            message: error.message,
+            hint: bizCode ? BIZ_CODE_HINTS[bizCode] : undefined,
+        });
+    }
+    if (error instanceof PollingTimeoutError) {
+        return errorResult(`${toolName}: 轮询超时`, {
+            code: 'polling_timeout',
+            timeoutMs: error.timeoutMs,
+            hint: '用 world_get / lux3d_get_task 继续查询',
+        });
+    }
+    if (error instanceof PollingFailedError) {
+        return errorResult(`${toolName}: 任务失败`, {
+            code: 'polling_failed',
+            message: error.message,
+        });
+    }
+    return errorResult(`${toolName} failed`, error);
+}
+export function sceneNotConfirmedError() {
+    return errorResult('scene_not_confirmed', {
+        message: 'scene 未确认。用户已明确 model/space 时请设 sceneSource=user_explicit 且 userConfirmedScene=true；不确定时请追问用户，或先调用 world_inspect_local_media 再设 sceneSource=inspect。',
+    });
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,aAAa,EACb,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,GACf,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,MAAM,cAAc,GAA2B;IAC7C,OAAO,EAAE,kDAAkD;CAC5D,CAAC;AAEF,MAAM,UAAU,SAAS,CAAC,QAAgB,EAAE,KAAc;IACxD,IAAI,KAAK,YAAY,mBAAmB,EAAE,CAAC;QACzC,OAAO,WAAW,CAAC,GAAG,QAAQ,kBAAkB,EAAE;YAChD,IAAI,EAAE,sBAAsB;YAC5B,IAAI,EAAE,0GAA0G;SACjH,CAAC,CAAC;IACL,CAAC;IACD,IAAI,KAAK,YAAY,cAAc,EAAE,CAAC;QACpC,OAAO,WAAW,CAAC,GAAG,QAAQ,UAAU,EAAE;YACxC,IAAI,EAAE,YAAY;YAClB,IAAI,EAAE,MAAM;SACb,CAAC,CAAC;IACL,CAAC;IACD,IAAI,KAAK,YAAY,aAAa,EAAE,CAAC;QACnC,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC;QAC/C,OAAO,WAAW,CAAC,GAAG,QAAQ,QAAQ,EAAE;YACtC,IAAI,EAAE,gBAAgB;YACtB,OAAO;YACP,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS;SACpD,CAAC,CAAC;IACL,CAAC;IACD,IAAI,KAAK,YAAY,mBAAmB,EAAE,CAAC;QACzC,OAAO,WAAW,CAAC,GAAG,QAAQ,QAAQ,EAAE;YACtC,IAAI,EAAE,iBAAiB;YACvB,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,IAAI,EAAE,mCAAmC;SAC1C,CAAC,CAAC;IACL,CAAC;IACD,IAAI,KAAK,YAAY,kBAAkB,EAAE,CAAC;QACxC,OAAO,WAAW,CAAC,GAAG,QAAQ,QAAQ,EAAE;YACtC,IAAI,EAAE,gBAAgB;YACtB,OAAO,EAAE,KAAK,CAAC,OAAO;SACvB,CAAC,CAAC;IACL,CAAC;IACD,OAAO,WAAW,CAAC,GAAG,QAAQ,SAAS,EAAE,KAAK,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,sBAAsB;IACpC,OAAO,WAAW,CAAC,qBAAqB,EAAE;QACxC,OAAO,EACL,sJAAsJ;KACzJ,CAAC,CAAC;AACL,CAAC"}

package/dist/index.d.ts

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