sella-cli 0.8.0 → 0.9.0

package/README.md

@@ -71,7 +71,7 @@ npx sella-cli sandbox "web search"
   <img src="https://sellag.vercel.app/readme/cli-sandbox.svg" alt="sella sandbox returns live marketplace results: Exa, Tavily and more, with no account" width="740" />
 </p>
 
-What's in there: a catalogue of 1,100+ machine-payable API providers, plus first-party datasets, workflows, and Sella Native products such as Cradle. Free previews let your agent check quality before it pays.
+What's in there: a catalogue of 1,500+ machine-payable API providers with 8,000+ verified callable endpoints, plus first-party datasets, workflows, and Sella Native products such as Cradle. Free previews let your agent check quality before it pays.
 
 ## What you get
 

package/dist/index.js

@@ -7,6 +7,7 @@ import { runDoctor, runStatus, loadStoredKey } from './doctor.js';
 import { runMcpBridge } from './mcp-bridge.js';
 import { scaffoldCard, pushDataset, CARD_FILENAME } from './publish.js';
 import { sandboxSearch, listBusinesses } from './api.js';
+import { skillStatus, syncSkillBundle } from './skill.js';
 import { getFundingInfo, annotateFunding } from './fund.js';
 import { capabilityLabel } from './chains.js';
 import { defaultIo, Printer } from './output.js';
@@ -63,6 +64,7 @@ Commands:
   doctor     Verify the install: endpoint, credentials, auth, wallets, pay-quote
   status     Show your key + AgentWallet balances
   businesses Show your agent's named runs: spend, tool calls, outcome
+  skill      Show the cached agent instruction bundle; 'skill update' refreshes it
   fund       Show deposit addresses + funding links to add USDC to your agent wallet
   mcp        Run as a local stdio MCP server that proxies Sella with your stored key
   publish    Publish a dataset from a CSV: 'publish init <file.csv>' then 'publish push'
@@ -290,6 +292,17 @@ async function cmdInit(ctx, flags, printer) {
             sp.fail('Verify could not run (network?) — try `sella doctor` later.');
             verifySummary = { ok: false, error: err instanceof Error ? err.message : String(err) };
         }
+        // Cache the agent instruction bundle alongside the credentials, so the agent reads its
+        // instructions from disk instead of re-fetching them every session. Best effort on purpose:
+        // onboarding must not fail because a documentation download did, and `sella skill update`
+        // fixes it later.
+        try {
+            const bundle = await syncSkillBundle({ env: ctx.env, origin });
+            ui.detail(`Skill bundle ${bundle.version} cached at ${bundle.dir}`);
+        }
+        catch {
+            ui.detail('Skill bundle not cached (network?). Run `sella skill update` later.');
+        }
     }
     if (paired.code === 0) {
         const awStatus = String(paired.summary?.agentWallet || 'none');
@@ -484,6 +497,47 @@ export async function runCli(argv, io = defaultIo(), env = defaultEnv()) {
                 }
                 return 0;
             }
+            case 'skill': {
+                const origin = ctx.mcpUrl.replace(/\/api\/mcp\/?$/, '');
+                const sub = flags.positional[1];
+                if (sub === 'update') {
+                    const result = await syncSkillBundle({ env: ctx.env, origin, force: flags.positional.includes('--force') });
+                    printer.jsonOut(result);
+                    if (!flags.json) {
+                        if (result.upToDate) {
+                            printer.info(`Already on ${result.version}. Nothing to download.`);
+                        }
+                        else {
+                            const moved = result.previousVersion ? `${result.previousVersion} -> ${result.version}` : result.version;
+                            printer.info(`Skill bundle ${moved}`);
+                            printer.info(`  ${result.written.length} downloaded, ${result.reused.length} unchanged`);
+                            printer.info(`  ${result.dir}`);
+                        }
+                    }
+                    return 0;
+                }
+                const status = await skillStatus(ctx.env, origin);
+                printer.jsonOut(status);
+                if (!flags.json) {
+                    if (!status.localVersion) {
+                        printer.info(`No local bundle. Live version is ${status.remoteVersion}.`);
+                        printer.info('Run `sella skill update` to cache it.');
+                    }
+                    else if (status.upToDate) {
+                        printer.info(`Skill bundle ${status.localVersion} (current).`);
+                        if (status.dir)
+                            printer.info(`  ${status.dir}`);
+                    }
+                    else {
+                        printer.info(`Skill bundle ${status.localVersion} is out of date. Live version is ${status.remoteVersion}.`);
+                        if (status.breaking) {
+                            printer.info('  This is a breaking change: a tool may have been removed or changed.');
+                        }
+                        printer.info('  Run `sella skill update`.');
+                    }
+                }
+                return status.localVersion && !status.upToDate ? 1 : 0;
+            }
             case 'businesses': {
                 const stored = loadStoredKey(ctx.env);
                 if (!stored) {

package/dist/skill.js

@@ -0,0 +1,169 @@
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/**
+ * Local skill-bundle cache.
+ *
+ * An agent that re-fetches 25 KB of instructions every session burns context and gets whatever is
+ * live, which can change mid-task. A pinned local copy is cheaper and reproducible: two runs of the
+ * same prompt read the same instructions, so when something goes wrong you know which version
+ * produced it.
+ *
+ * The danger is the obvious one. A cache that never expires is a confidently wrong copy of a world
+ * that moved, which is exactly how the old hand-written skill.json ended up advertising four
+ * deprecated tools. So the bundle is stored under its version, the server stamps stale callers on
+ * calls they were already making, and `sella skill update` is one command.
+ */
+/** Placeholder the server substitutes per request host. See lib/agent-docs.ts. */
+const ORIGIN_PLACEHOLDER = '{{SELLA_ORIGIN}}';
+export class SkillSyncError extends Error {
+}
+function skillRoot(env) {
+    return path.join(env.home, '.sella', 'skill');
+}
+function pointerPath(env) {
+    return path.join(skillRoot(env), 'current');
+}
+/**
+ * A plain text pointer rather than a symlink. Symlink creation needs elevation or developer mode on
+ * Windows, and this has to work for every operator, not just the ones on a unix box.
+ */
+export function readCurrentVersion(env) {
+    try {
+        const v = fs.readFileSync(pointerPath(env), 'utf8').trim();
+        return v || null;
+    }
+    catch {
+        return null;
+    }
+}
+export function readLocalBundle(env) {
+    const version = readCurrentVersion(env);
+    if (!version)
+        return null;
+    const dir = path.join(skillRoot(env), version);
+    let meta = {};
+    try {
+        meta = JSON.parse(fs.readFileSync(path.join(dir, 'bundle.json'), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    let files = [];
+    try {
+        files = fs.readdirSync(dir).filter((f) => f !== 'bundle.json');
+    }
+    catch {
+        return null;
+    }
+    return { version, dir, files, fetchedAt: meta.fetchedAt || '' };
+}
+/**
+ * Reverses the server's origin substitution so a downloaded document hashes to the value the
+ * manifest published.
+ *
+ * The manifest hashes the RAW template, before substitution, so that a bundle cached on one Sella
+ * domain is not invalidated by re-checking from another. What arrives over HTTP is the rendered
+ * form. Putting the placeholder back is exact rather than approximate because the server guarantees
+ * no template contains a literal absolute origin (asserted by findLiteralOrigins in the app), so
+ * every occurrence of the origin in a served document came from the placeholder.
+ */
+export function canonicalize(body, origin) {
+    const trimmed = origin.replace(/\/+$/, '');
+    return trimmed ? body.split(trimmed).join(ORIGIN_PLACEHOLDER) : body;
+}
+export function hashCanonical(body, origin) {
+    return `sha256:${crypto.createHash('sha256').update(canonicalize(body, origin), 'utf8').digest('hex')}`;
+}
+export async function fetchManifest(origin, fetchImpl = fetch) {
+    const base = origin.replace(/\/+$/, '');
+    const res = await fetchImpl(`${base}/skill.json`);
+    if (!res.ok)
+        throw new SkillSyncError(`Could not read ${base}/skill.json (HTTP ${res.status}).`);
+    const manifest = (await res.json());
+    if (!manifest?.version || !manifest?.files) {
+        throw new SkillSyncError(`${base}/skill.json is not a skill manifest.`);
+    }
+    return manifest;
+}
+/**
+ * Brings the local bundle to the version the server is serving.
+ *
+ * Unchanged files are copied forward from the previous bundle rather than re-downloaded, which is
+ * why the manifest carries a per-file hash at all. A version bump for a one-line prose fix then
+ * costs one small request instead of the whole bundle.
+ */
+export async function syncSkillBundle(opts) {
+    const { env, origin } = opts;
+    const fetchImpl = opts.fetchImpl || fetch;
+    const manifest = await fetchManifest(origin, fetchImpl);
+    const previousVersion = readCurrentVersion(env);
+    const dir = path.join(skillRoot(env), manifest.version);
+    const alreadyCurrent = previousVersion === manifest.version && fs.existsSync(dir);
+    if (alreadyCurrent && !opts.force) {
+        return {
+            version: manifest.version,
+            previousVersion,
+            dir,
+            written: [],
+            reused: Object.keys(manifest.files),
+            upToDate: true,
+        };
+    }
+    fs.mkdirSync(dir, { recursive: true });
+    const written = [];
+    const reused = [];
+    for (const [name, entry] of Object.entries(manifest.files)) {
+        const target = path.join(dir, name);
+        // Reuse an identical file from the previous bundle when the hash says it did not change.
+        if (!opts.force && previousVersion) {
+            const old = path.join(skillRoot(env), previousVersion, name);
+            try {
+                const body = fs.readFileSync(old, 'utf8');
+                if (hashCanonical(body, origin) === entry.sha256) {
+                    fs.writeFileSync(target, body);
+                    reused.push(name);
+                    continue;
+                }
+            }
+            catch {
+                // Not present or unreadable in the old bundle; fall through and download it.
+            }
+        }
+        const res = await fetchImpl(entry.url);
+        if (!res.ok)
+            throw new SkillSyncError(`Could not download ${name} (HTTP ${res.status}).`);
+        const body = await res.text();
+        // Integrity, not just freshness. A truncated or tampered document is worse than a stale one
+        // because it looks authoritative, so a mismatch fails the sync rather than being written.
+        const actual = hashCanonical(body, origin);
+        if (actual !== entry.sha256) {
+            throw new SkillSyncError(`${name} does not match the hash in the manifest. Expected ${entry.sha256}, got ${actual}. ` +
+                `Nothing was written. Retry, and if it persists report it rather than using the file.`);
+        }
+        fs.writeFileSync(target, body);
+        written.push(name);
+    }
+    fs.writeFileSync(path.join(dir, 'bundle.json'), JSON.stringify({ version: manifest.version, origin: origin.replace(/\/+$/, ''), fetchedAt: new Date().toISOString() }, null, 2) + '\n');
+    fs.mkdirSync(skillRoot(env), { recursive: true });
+    fs.writeFileSync(pointerPath(env), `${manifest.version}\n`);
+    return { version: manifest.version, previousVersion, dir, written, reused, upToDate: false };
+}
+function major(version) {
+    const m = /^(\d+)\.\d+\.\d+$/.exec(String(version || '').trim());
+    return m ? Number(m[1]) : null;
+}
+export async function skillStatus(env, origin, fetchImpl = fetch) {
+    const manifest = await fetchManifest(origin, fetchImpl);
+    const local = readLocalBundle(env);
+    const localMajor = major(local?.version || null);
+    const remoteMajor = major(manifest.version);
+    return {
+        localVersion: local?.version || null,
+        remoteVersion: manifest.version,
+        upToDate: Boolean(local && local.version === manifest.version),
+        breaking: localMajor !== null && remoteMajor !== null && localMajor < remoteMajor,
+        dir: local?.dir || null,
+        readFirst: manifest.readFirst || null,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sella-cli",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Connect your AI agent to Sella, the marketplace where agents buy data and APIs, in one command: npx sella-cli. Installs the Sella MCP server into Claude Code, Cursor and more, then pairs, verifies, funds, and publishes.",
   "keywords": [
     "cli",
@@ -22,13 +22,26 @@
   ],
   "license": "MIT",
   "homepage": "https://sellag.vercel.app",
-  "bugs": { "url": "https://github.com/010100100100011101010100/ogsella/issues" },
-  "repository": { "type": "git", "url": "https://github.com/010100100100011101010100/ogsella", "directory": "cli" },
+  "bugs": {
+    "url": "https://github.com/010100100100011101010100/ogsella/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/010100100100011101010100/ogsella",
+    "directory": "cli"
+  },
   "type": "module",
-  "bin": { "sella": "./dist/index.js" },
+  "bin": {
+    "sella": "./dist/index.js"
+  },
   "main": "./dist/index.js",
-  "files": ["dist", "README.md"],
-  "engines": { "node": ">=18" },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "prepublishOnly": "npm run build",