@aisa-one/cli 0.2.2 → 0.2.3

package/dist/skills-registry.js

@@ -0,0 +1,219 @@
+import { readCache, writeCache, touchCache } from "./cache.js";
+import { pool } from "./utils/pool.js";
+/**
+ * GitHub-backed skill registry.
+ *
+ * The repo nests skills two levels deep (`<category>/<name>/SKILL.md`), so the
+ * canonical slug is the repo-relative directory. Everything here is driven off
+ * a single recursive tree fetch: api.github.com allows only 60 unauthenticated
+ * requests per hour per IP, and the previous per-command fetching burned
+ * several of those on every invocation.
+ */
+export const SKILLS_REPO = "AIsa-team/agent-skills";
+const GH_API = `https://api.github.com/repos/${SKILLS_REPO}`;
+export const GH_RAW = `https://raw.githubusercontent.com/${SKILLS_REPO}/main`;
+const TREE_CACHE_KEY = "skills/tree.json";
+const META_CACHE_KEY = "skills/meta.json";
+const TREE_TTL_MS = 60 * 60 * 1000;
+const META_TTL_MS = 30 * 24 * 60 * 60 * 1000; // keyed by blob sha, so effectively permanent
+const FETCH_CONCURRENCY = 8;
+function ghHeaders(etag) {
+    const headers = {
+        Accept: "application/vnd.github+json",
+        "User-Agent": "aisa-cli",
+    };
+    // Raises the rate limit from 60/hr to 5000/hr when the user has one set.
+    const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+    if (token)
+        headers.Authorization = `Bearer ${token}`;
+    if (etag)
+        headers["If-None-Match"] = etag;
+    return headers;
+}
+function buildIndex(tree) {
+    // A skill is any directory containing a SKILL.md, at whatever depth. Deriving
+    // slugs from the SKILL.md locations rather than guessing at directory levels
+    // is what keeps this working if the repo layout changes again.
+    const slugs = tree
+        .filter((e) => e.type === "blob" && e.path.endsWith("/SKILL.md"))
+        .map((e) => e.path.slice(0, -"/SKILL.md".length))
+        .sort();
+    const blobs = {};
+    for (const slug of slugs)
+        blobs[slug] = [];
+    for (const entry of tree) {
+        if (entry.type !== "blob")
+            continue;
+        // Longest matching slug wins, so a nested skill doesn't steal its parent's files.
+        const owner = slugs
+            .filter((s) => entry.path.startsWith(`${s}/`))
+            .sort((a, b) => b.length - a.length)[0];
+        if (owner)
+            blobs[owner].push({ path: entry.path, sha: entry.sha });
+    }
+    return { slugs, blobs };
+}
+let indexPromise;
+/**
+ * Fetch (or reuse) the skill index. Memoized per process on top of a 1h disk
+ * cache with ETag revalidation, so repeated commands cost at most one
+ * conditional request.
+ */
+export function getSkillIndex(options = {}) {
+    if (options.refresh)
+        indexPromise = undefined;
+    if (!indexPromise) {
+        indexPromise = loadSkillIndex(options.refresh).catch((err) => {
+            indexPromise = undefined; // don't cache failures for the process lifetime
+            throw err;
+        });
+    }
+    return indexPromise;
+}
+async function loadSkillIndex(refresh) {
+    const cached = readCache(TREE_CACHE_KEY);
+    if (cached?.fresh && !refresh)
+        return cached.data;
+    let res;
+    try {
+        res = await fetch(`${GH_API}/git/trees/main?recursive=1`, {
+            headers: ghHeaders(refresh ? undefined : cached?.etag),
+        });
+    }
+    catch (err) {
+        if (cached)
+            return cached.data; // offline: stale beats nothing
+        throw err;
+    }
+    if (res.status === 304 && cached) {
+        touchCache(TREE_CACHE_KEY, TREE_TTL_MS);
+        return cached.data;
+    }
+    if (!res.ok) {
+        if (cached)
+            return cached.data;
+        const detail = res.status === 403 ? " (rate limited — set GITHUB_TOKEN to raise the limit)" : "";
+        throw new Error(`GitHub API error: ${res.status}${detail}`);
+    }
+    const data = (await res.json());
+    const index = buildIndex(data.tree || []);
+    writeCache(TREE_CACHE_KEY, index, TREE_TTL_MS, res.headers.get("etag") || undefined);
+    return index;
+}
+/** Last path segment — what the skill is called once installed. */
+export function leafName(slug) {
+    return slug.split("/").pop() || slug;
+}
+/**
+ * Accept either a canonical `<category>/<name>` slug or a bare name. A bare
+ * name that matches several skills is an error rather than a guess: installing
+ * the wrong skill silently is worse than asking.
+ */
+export function resolveSlug(input, index) {
+    const clean = input.replace(/^\/+|\/+$/g, "");
+    if (index.slugs.includes(clean))
+        return clean;
+    const matches = index.slugs.filter((s) => leafName(s) === clean);
+    if (matches.length === 1)
+        return matches[0];
+    if (matches.length > 1) {
+        throw new Error(`Ambiguous skill "${input}". Matches: ${matches.join(", ")}`);
+    }
+    throw new Error(`No skill "${input}" in ${SKILLS_REPO}`);
+}
+/** Parse YAML frontmatter from SKILL.md content. */
+export function parseSkillFrontmatter(slug, content) {
+    const info = { slug, name: leafName(slug), description: "", emoji: "" };
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match)
+        return info;
+    const frontmatter = match[1];
+    const nameMatch = frontmatter.match(/^name:\s*(.+)$/m);
+    if (nameMatch)
+        info.name = nameMatch[1].trim().replace(/^["']|["']$/g, "");
+    const descMatch = frontmatter.match(/^description:\s*(.+)$/m);
+    if (descMatch)
+        info.description = descMatch[1].trim().replace(/^["']|["']$/g, "");
+    const metaMatch = frontmatter.match(/^metadata:\s*(.+)$/m);
+    if (metaMatch) {
+        try {
+            const meta = JSON.parse(metaMatch[1]);
+            // agent-skills repo uses metadata.aisa; legacy skills used metadata.openclaw.
+            info.emoji = meta?.aisa?.emoji || meta?.openclaw?.emoji || "";
+        }
+        catch {
+            // ignore malformed metadata
+        }
+    }
+    return info;
+}
+function skillMdBlob(slug, index) {
+    return index.blobs[slug]?.find((b) => b.path === `${slug}/SKILL.md`);
+}
+export async function fetchSkillMarkdown(slug) {
+    const res = await fetch(`${GH_RAW}/${slug}/SKILL.md`);
+    if (!res.ok)
+        throw new Error(`Cannot read ${slug}/SKILL.md: ${res.status}`);
+    return res.text();
+}
+/**
+ * Metadata for every skill. Cached by blob sha, so a warm cache needs zero
+ * content requests and only re-fetches the skills that actually changed.
+ */
+export async function listSkills(index) {
+    const cached = readCache(META_CACHE_KEY)?.data || {};
+    const bySha = { ...cached };
+    const missing = index.slugs.filter((slug) => {
+        const blob = skillMdBlob(slug, index);
+        return blob ? !bySha[blob.sha] : false;
+    });
+    if (missing.length > 0) {
+        const fetched = await pool(missing.map((slug) => async () => ({
+            slug,
+            content: await fetchSkillMarkdown(slug),
+        })), FETCH_CONCURRENCY);
+        for (const item of fetched) {
+            if (!item)
+                continue;
+            const blob = skillMdBlob(item.slug, index);
+            if (blob)
+                bySha[blob.sha] = parseSkillFrontmatter(item.slug, item.content);
+        }
+        writeCache(META_CACHE_KEY, bySha, META_TTL_MS);
+    }
+    return index.slugs
+        .map((slug) => {
+        const blob = skillMdBlob(slug, index);
+        const meta = blob ? bySha[blob.sha] : undefined;
+        // Cached entries carry the slug they were first seen under; the current
+        // one is authoritative if a skill moved between categories.
+        return meta ? { ...meta, slug } : { slug, name: leafName(slug), description: "", emoji: "" };
+    })
+        .filter(Boolean);
+}
+/**
+ * Download every file in a skill directory. Content is kept as bytes: skills
+ * may ship images or fonts, and decoding those as UTF-8 corrupts them.
+ *
+ * A partial download is an error, not a smaller skill. Installing replaces the
+ * target directory, so silently dropping failed files would delete a working
+ * skill and leave a broken one — possibly without its SKILL.md.
+ */
+export async function fetchSkillFiles(slug, index) {
+    const blobs = index.blobs[slug] || [];
+    const prefix = `${slug}/`;
+    const results = await pool(blobs.map((blob) => async () => {
+        const res = await fetch(`${GH_RAW}/${blob.path}`);
+        if (!res.ok)
+            throw new Error(`${blob.path}: ${res.status}`);
+        return {
+            path: blob.path.slice(prefix.length),
+            content: Buffer.from(await res.arrayBuffer()),
+        };
+    }), FETCH_CONCURRENCY);
+    const missing = blobs.filter((_, i) => results[i] === undefined).map((b) => b.path);
+    if (missing.length > 0) {
+        throw new Error(`Could not download ${missing.length} of ${blobs.length} files for ${slug}: ${missing.join(", ")}`);
+    }
+    return results;
+}

package/dist/types.d.ts

@@ -79,8 +79,32 @@ export interface VideoTask {
     resultUrl?: string;
     createdAt: string;
 }
+/**
+ * Billing facts the gateway reports in response headers.
+ *
+ * Metered providers (DataForSEO, Jina) bill per consumed credit, so the
+ * catalog's flat `per_request` price does not describe what a call actually
+ * cost — these headers are the only accurate source. Plain integration
+ * responses carry just a price key, and the LLM gateway sends nothing at all,
+ * so every field is optional.
+ */
+export interface CostInfo {
+    /** Dollars charged, e.g. "0.012000". Metered responses only. */
+    priceUsd?: string;
+    pricingStrategy?: string;
+    pricingVersion?: string;
+    creditModel?: string;
+    estimatedCredits?: string;
+    accountedCredits?: string;
+    requestMultiplier?: string;
+    /** Opaque pricing identifier; present on integration responses. */
+    priceKey?: string;
+    requestId?: string;
+}
 export interface ApiResponse<T = unknown> {
     success: boolean;
     data?: T;
     error?: string;
+    /** Present when the response carried any billing header. */
+    cost?: CostInfo;
 }

package/dist/utils/file.d.ts

@@ -1,8 +1,12 @@
 export declare function expandHome(p: string): string;
 export declare function ensureDir(dirPath: string): void;
+/**
+ * Content is written as raw bytes: skills may ship images or fonts alongside
+ * SKILL.md, and round-tripping those through a UTF-8 string corrupts them.
+ */
 export declare function writeSkillFiles(targetDir: string, files: Array<{
     path: string;
-    content: string;
+    content: string | Uint8Array;
 }>): void;
 export declare function removeDir(dirPath: string): void;
 export declare function detectAgents(agentDirs: Record<string, string>): string[];

package/dist/utils/file.js

@@ -12,12 +12,16 @@ export function ensureDir(dirPath) {
         mkdirSync(dirPath, { recursive: true });
     }
 }
+/**
+ * Content is written as raw bytes: skills may ship images or fonts alongside
+ * SKILL.md, and round-tripping those through a UTF-8 string corrupts them.
+ */
 export function writeSkillFiles(targetDir, files) {
     for (const file of files) {
         const safePath = sanitizePath(file.path);
         const fullPath = join(targetDir, safePath);
         ensureDir(join(fullPath, ".."));
-        writeFileSync(fullPath, file.content, "utf-8");
+        writeFileSync(fullPath, file.content);
     }
 }
 export function removeDir(dirPath) {

package/dist/utils/pool.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Run tasks with a bounded number in flight.
+ *
+ * Cold-starting the catalog means ~29 requests and the skills index ~42, both
+ * against third parties that rate-limit. Results keep the input order; a task
+ * that rejects yields `undefined` rather than failing the whole batch.
+ */
+export declare function pool<T>(tasks: Array<() => Promise<T>>, concurrency: number, onProgress?: (done: number, total: number) => void): Promise<Array<T | undefined>>;

package/dist/utils/pool.js

@@ -0,0 +1,27 @@
+/**
+ * Run tasks with a bounded number in flight.
+ *
+ * Cold-starting the catalog means ~29 requests and the skills index ~42, both
+ * against third parties that rate-limit. Results keep the input order; a task
+ * that rejects yields `undefined` rather than failing the whole batch.
+ */
+export async function pool(tasks, concurrency, onProgress) {
+    const results = new Array(tasks.length);
+    let next = 0;
+    let done = 0;
+    const workers = Array.from({ length: Math.min(concurrency, tasks.length) }, async () => {
+        while (next < tasks.length) {
+            const index = next++;
+            try {
+                results[index] = await tasks[index]();
+            }
+            catch {
+                results[index] = undefined;
+            }
+            done++;
+            onProgress?.(done, tasks.length);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}

package/package.json

@@ -1,15 +1,21 @@
 {
   "name": "@aisa-one/cli",
-  "version": "0.2.2",
-  "description": "CLI for the AISA unified AI infrastructure platform - access 70+ LLMs, web search, finance, Twitter, and video generation APIs",
+  "version": "0.2.3",
+  "description": "CLI for the AISA unified AI infrastructure platform - one API key for 80+ LLMs and 900+ endpoints across finance, search, social, and video APIs",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "bin": {
     "aisa": "dist/index.js"
   },
   "scripts": {
-    "build": "tsc",
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc",
     "dev": "tsc -w",
     "start": "node dist/index.js",
     "test": "vitest run",

package/tests/account.test.ts

@@ -1,89 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { balanceAction, formatMicrosUSD } from "../src/commands/account.js";
-
-const balance = {
-  currency: "USD",
-  account_balance_micros_usd: 2_500_000,
-  available_balance_micros_usd: 1_000_000,
-  api_key: {
-    unlimited: false,
-    remaining_micros_usd: 1_000_000,
-    used_micros_usd: 300_000,
-  },
-  as_of: "2026-08-03T12:00:00Z",
-};
-
-describe("balanceAction", () => {
-  beforeEach(() => {
-    process.env.AISA_API_KEY = "test-balance-key";
-  });
-
-  afterEach(() => {
-    delete process.env.AISA_API_KEY;
-    vi.unstubAllGlobals();
-    vi.restoreAllMocks();
-  });
-
-  it("formats microdollars without floating-point drift", () => {
-    expect(formatMicrosUSD(2_500_000)).toBe("$2.50");
-    expect(formatMicrosUSD(2_505_001)).toBe("$2.51");
-    expect(formatMicrosUSD(1_999_999)).toBe("$2.00");
-    expect(formatMicrosUSD(-1_500_000)).toBe("-$1.50");
-  });
-
-  it("requests the balance endpoint with the API key and renders the summary", async () => {
-    const fetchMock = vi.fn(async () => new Response(JSON.stringify(balance), { status: 200 }));
-    vi.stubGlobal("fetch", fetchMock);
-    const log = vi.spyOn(console, "log").mockImplementation(() => {});
-
-    await balanceAction();
-
-    expect(fetchMock).toHaveBeenCalledTimes(1);
-    const [url, init] = fetchMock.mock.calls[0];
-    expect(url).toBe("https://api.aisa.one/v1/credits/balance");
-    expect((init?.headers as Record<string, string>).Authorization).toBe("Bearer test-balance-key");
-    expect(log.mock.calls.map(([line]) => line).join("\n")).toContain("Balance:");
-    expect(log.mock.calls.map(([line]) => line).join("\n")).toContain("$2.50 USD");
-    expect(log.mock.calls.map(([line]) => line).join("\n")).toContain("$1.00 USD");
-    expect(log.mock.calls.map(([line]) => line).join("\n")).not.toContain("test-balance-key");
-  });
-
-  it("renders unlimited keys", async () => {
-    const fetchMock = vi.fn(async () => new Response(JSON.stringify({
-      ...balance,
-      api_key: { ...balance.api_key, unlimited: true },
-    }), { status: 200 }));
-    vi.stubGlobal("fetch", fetchMock);
-    const log = vi.spyOn(console, "log").mockImplementation(() => {});
-
-    await balanceAction();
-
-    expect(log.mock.calls.map(([line]) => line).join("\n")).toContain("API key limit:       Unlimited");
-  });
-
-  it("supports raw JSON output", async () => {
-    const fetchMock = vi.fn(async () => new Response(JSON.stringify(balance), { status: 200 }));
-    vi.stubGlobal("fetch", fetchMock);
-    const log = vi.spyOn(console, "log").mockImplementation(() => {});
-
-    await balanceAction({ json: true });
-
-    expect(JSON.parse(log.mock.calls[0][0] as string)).toEqual(balance);
-  });
-
-  it.each([401, 403, 404, 500])("raises API errors for HTTP %s", async (status) => {
-    const fetchMock = vi.fn(async () => new Response(JSON.stringify({ error: "balance unavailable" }), { status }));
-    vi.stubGlobal("fetch", fetchMock);
-
-    await expect(balanceAction()).rejects.toThrow(`${status}: balance unavailable`);
-  });
-
-  it("raises network errors", async () => {
-    const fetchMock = vi.fn(async () => {
-      throw new Error("connection refused");
-    });
-    vi.stubGlobal("fetch", fetchMock);
-
-    await expect(balanceAction()).rejects.toThrow("connection refused");
-  });
-});

package/tests/streaming.test.ts

@@ -1,73 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { handleSSEStream } from "../src/utils/streaming.js";
-
-function sseResponse(chunks: string[]): Response {
-  const encoder = new TextEncoder();
-  const stream = new ReadableStream<Uint8Array>({
-    start(controller) {
-      for (const chunk of chunks) {
-        controller.enqueue(encoder.encode(chunk));
-      }
-      controller.close();
-    },
-  });
-  return new Response(stream);
-}
-
-describe("handleSSEStream", () => {
-  it("emits tokens from a native fetch Response body", async () => {
-    const res = sseResponse([
-      'data: {"choices":[{"delta":{"content":"Hello"}}]}\n\n',
-      'data: {"choices":[{"delta":{"content":" world"}}]}\n\n',
-      "data: [DONE]\n\n",
-    ]);
-
-    const tokens: string[] = [];
-    let done = false;
-    await handleSSEStream(
-      res,
-      (t) => tokens.push(t),
-      () => {
-        done = true;
-      }
-    );
-
-    expect(tokens.join("")).toBe("Hello world");
-    expect(done).toBe(true);
-  });
-
-  it("handles multi-byte characters split across chunks", async () => {
-    const encoder = new TextEncoder();
-    const line = encoder.encode(
-      'data: {"choices":[{"delta":{"content":"你好"}}]}\n\ndata: [DONE]\n\n'
-    );
-    // split in the middle of a multi-byte character
-    const stream = new ReadableStream<Uint8Array>({
-      start(controller) {
-        controller.enqueue(line.slice(0, 40));
-        controller.enqueue(line.slice(40));
-        controller.close();
-      },
-    });
-    const res = new Response(stream);
-
-    const tokens: string[] = [];
-    await handleSSEStream(res, (t) => tokens.push(t));
-
-    expect(tokens.join("")).toBe("你好");
-  });
-
-  it("reports usage to onDone", async () => {
-    const res = sseResponse([
-      'data: {"choices":[{"delta":{"content":"hi"}}],"usage":{"prompt_tokens":3,"completion_tokens":1}}\n\n',
-      "data: [DONE]\n\n",
-    ]);
-
-    let usage: { prompt_tokens: number; completion_tokens: number } | undefined;
-    await handleSSEStream(res, () => {}, (u) => {
-      usage = u;
-    });
-
-    expect(usage).toEqual({ prompt_tokens: 3, completion_tokens: 1 });
-  });
-});