@springbrand/cli 0.1.0

package/dist/lib/verify.js

@@ -0,0 +1,169 @@
+/** 复刻自 tiny-fish CLI 编译产物：verify.d.ts + verify.impl.js */
+import { BASE_URL, CLI_AGENT_IDENTITY, CLI_VERSION } from './constants.js';
+const VERIFY_TIMEOUT_MS = 5_000;
+// `fetch` collapses every network fault to "fetch failed" and hides the cause on `e.cause`.
+function networkCode(e) {
+    const cause = e.cause;
+    switch (cause?.code) {
+        case 'ECONNREFUSED':
+            return 'connection refused';
+        case 'ENOTFOUND':
+            return 'host not found';
+        case 'ETIMEDOUT':
+            return 'connection timed out';
+        case 'CERT_HAS_EXPIRED':
+        case 'UNABLE_TO_VERIFY_LEAF_SIGNATURE':
+        case 'DEPTH_ZERO_SELF_SIGNED_CERT':
+            return 'TLS verification failed';
+        default:
+            return e instanceof Error && e.name === 'TimeoutError'
+                ? 'request timed out'
+                : 'could not reach the endpoint';
+    }
+}
+/**
+ * The Gateway's authored prose per error code. Its stable codes say more than a status does:
+ * 401 alone cannot tell "revoked" from "wrong environment", and both 502 and 503 mean the
+ * platform could not answer rather than that the key is bad.
+ */
+const CODE_PROSE = {
+    AUTH_MCP_KEY_INVALID: 'the API key is invalid, revoked, or expired',
+    AUTH_MCP_KEY_ENVIRONMENT_MISMATCH: 'the API key was issued for a different environment',
+    AUTH_MCP_ACCOUNT_DISABLED: 'the SpringBrand account is disabled',
+    AUTH_MCP_SCOPE_DENIED: 'the API key is missing the mcp:access scope',
+    REQUEST_FORBIDDEN: 'SpringBrand refused the key on this endpoint',
+    REQUEST_RATE_LIMITED: 'rate limited',
+    AUTH_MCP_VERIFICATION_UNAVAILABLE: 'SpringBrand key verification is temporarily unavailable',
+    AUTH_MCP_VERIFICATION_INVALID_RESPONSE: 'SpringBrand returned an unexpected verification response',
+};
+function statusProse(status) {
+    if (status === 401)
+        return 'the API key is invalid or expired';
+    if (status === 403)
+        return 'the API key is not allowed to do this';
+    if (status === 429)
+        return 'rate limited';
+    return status >= 500 ? 'SpringBrand returned a server error' : `the endpoint returned HTTP ${status}`;
+}
+/** Only 401 and 403 blame the credential; everything else is worth retrying. */
+function failureKind(status) {
+    return status === 401 || status === 403 ? 'credential_rejected' : 'retryable';
+}
+/** The `{code, errMsg, requestId}` contract; a non-conforming body is simply no code. */
+async function readErrorCode(response) {
+    const body = await response.json().catch(() => undefined);
+    const code = body?.code;
+    return typeof code === 'string' && code in CODE_PROSE ? code : undefined;
+}
+const IDENTITY_HEADERS = {
+    accountId: 'x-springbrand-mcp-account-id',
+    keyId: 'x-springbrand-mcp-key-id',
+    environment: 'x-springbrand-mcp-environment',
+};
+/** Present on every accepted key request; proves the credential works, not that a host loaded us. */
+function readIdentity(response) {
+    const accountId = response.headers.get(IDENTITY_HEADERS.accountId);
+    const keyId = response.headers.get(IDENTITY_HEADERS.keyId);
+    const environment = response.headers.get(IDENTITY_HEADERS.environment);
+    if (!accountId || !keyId || !environment)
+        return undefined;
+    return { accountId, keyId, environment };
+}
+/** Bounded, so a `Retry-After` of a day cannot be printed as advice. */
+const MAX_RETRY_AFTER_SECONDS = 3600;
+function readRetryAfter(response) {
+    const raw = Number(response.headers.get('retry-after'));
+    if (!Number.isInteger(raw) || raw <= 0)
+        return undefined;
+    return Math.min(raw, MAX_RETRY_AFTER_SECONDS);
+}
+/**
+ * Cheapest authenticated round-trip the gateway offers: `/mcp` is the only supported
+ * endpoint, and `initialize` touches no business state.
+ */
+async function probeAuthenticated(apiKey, apiBaseUrl) {
+    // Callers omit the base for a default-endpoint install; the SDK used to fill it in.
+    return fetch(`${apiBaseUrl ?? BASE_URL}/mcp`, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+            'Content-Type': 'application/json',
+            Accept: 'application/json, text/event-stream',
+        },
+        body: JSON.stringify({
+            jsonrpc: '2.0',
+            id: 1,
+            method: 'initialize',
+            params: {
+                protocolVersion: '2025-06-18',
+                capabilities: {},
+                clientInfo: { name: CLI_AGENT_IDENTITY, version: CLI_VERSION },
+            },
+        }),
+        signal: AbortSignal.timeout(VERIFY_TIMEOUT_MS),
+    });
+}
+/** Reachability check. Verify failure is a warning, never install failure. */
+export async function verifyMcpHealth(mcpUrl) {
+    try {
+        const response = await fetch(mcpUrl, {
+            method: 'GET',
+            // Redirect (captive portal, typo'd --url) is not healthy.
+            redirect: 'error',
+            signal: AbortSignal.timeout(VERIFY_TIMEOUT_MS),
+        });
+        // MCP rejects bare GET with 4xx — still proves endpoint routed.
+        if (response.status >= 500) {
+            return {
+                depth: 'health',
+                ok: false,
+                reason: `endpoint returned HTTP ${response.status}`,
+                code: `the endpoint returned HTTP ${response.status}`,
+            };
+        }
+        return { depth: 'health', ok: true };
+    }
+    catch (e) {
+        return {
+            depth: 'health',
+            ok: false,
+            reason: e instanceof Error ? e.message : 'network error reaching MCP endpoint',
+            code: networkCode(e),
+        };
+    }
+}
+/** Authenticated check — where the CLI holds the key (Cursor, OpenClaw, Hermes). */
+export async function verifyMcpAuth(apiKey, apiBaseUrl) {
+    let response;
+    try {
+        // Bound it: a warning-only check must never hang an install.
+        response = await probeAuthenticated(apiKey, apiBaseUrl);
+    }
+    catch (e) {
+        // No answer at all says nothing about the key, so it is never blamed for one.
+        return {
+            depth: 'health+auth',
+            ok: false,
+            kind: 'retryable',
+            reason: e instanceof Error ? e.message : String(e),
+            code: networkCode(e),
+        };
+    }
+    if (response.ok) {
+        const identity = readIdentity(response);
+        return { depth: 'health+auth', ok: true, ...(identity ? { identity } : {}) };
+    }
+    const errorCode = await readErrorCode(response);
+    const retryAfter = response.status === 429 ? readRetryAfter(response) : undefined;
+    return {
+        depth: 'health+auth',
+        ok: false,
+        kind: failureKind(response.status),
+        status: response.status,
+        reason: `the endpoint returned HTTP ${response.status}`,
+        code: errorCode ? CODE_PROSE[errorCode] : statusProse(response.status),
+        ...(errorCode ? { errorCode } : {}),
+        ...(retryAfter === undefined ? {} : { retryAfter }),
+    };
+}
+//# sourceMappingURL=verify.js.map

package/dist/lib/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../../src/lib/verify.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAE1D,OAAO,EAAE,QAAQ,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC3E,MAAM,iBAAiB,GAAG,KAAK,CAAC;AAChC,4FAA4F;AAC5F,SAAS,WAAW,CAAC,CAAU;IAC3B,MAAM,KAAK,GAAI,CAAmC,CAAC,KAAK,CAAC;IACzD,QAAQ,KAAK,EAAE,IAAI,EAAE,CAAC;QAClB,KAAK,cAAc;YACf,OAAO,oBAAoB,CAAC;QAChC,KAAK,WAAW;YACZ,OAAO,gBAAgB,CAAC;QAC5B,KAAK,WAAW;YACZ,OAAO,sBAAsB,CAAC;QAClC,KAAK,kBAAkB,CAAC;QACxB,KAAK,iCAAiC,CAAC;QACvC,KAAK,6BAA6B;YAC9B,OAAO,yBAAyB,CAAC;QACrC;YACI,OAAO,CAAC,YAAY,KAAK,IAAI,CAAC,CAAC,IAAI,KAAK,cAAc;gBAClD,CAAC,CAAC,mBAAmB;gBACrB,CAAC,CAAC,8BAA8B,CAAC;IAC7C,CAAC;AACL,CAAC;AACD;;;;GAIG;AACH,MAAM,UAAU,GAA2B;IACvC,oBAAoB,EAAE,6CAA6C;IACnE,iCAAiC,EAAE,oDAAoD;IACvF,yBAAyB,EAAE,qCAAqC;IAChE,qBAAqB,EAAE,6CAA6C;IACpE,iBAAiB,EAAE,8CAA8C;IACjE,oBAAoB,EAAE,cAAc;IACpC,iCAAiC,EAAE,yDAAyD;IAC5F,sCAAsC,EAAE,0DAA0D;CACrG,CAAC;AACF,SAAS,WAAW,CAAC,MAAc;IAC/B,IAAI,MAAM,KAAK,GAAG;QACd,OAAO,mCAAmC,CAAC;IAC/C,IAAI,MAAM,KAAK,GAAG;QACd,OAAO,uCAAuC,CAAC;IACnD,IAAI,MAAM,KAAK,GAAG;QACd,OAAO,cAAc,CAAC;IAC1B,OAAO,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,qCAAqC,CAAC,CAAC,CAAC,8BAA8B,MAAM,EAAE,CAAC;AAC1G,CAAC;AACD,gFAAgF;AAChF,SAAS,WAAW,CAAC,MAAc;IAC/B,OAAO,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,WAAW,CAAC;AAClF,CAAC;AACD,yFAAyF;AACzF,KAAK,UAAU,aAAa,CAAC,QAAkB;IAC3C,MAAM,IAAI,GAAY,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IACnE,MAAM,IAAI,GAAI,IAAuC,EAAE,IAAI,CAAC;IAC5D,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,IAAI,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7E,CAAC;AACD,MAAM,gBAAgB,GAAG;IACrB,SAAS,EAAE,8BAA8B;IACzC,KAAK,EAAE,0BAA0B;IACjC,WAAW,EAAE,+BAA+B;CACtC,CAAC;AACX,qGAAqG;AACrG,SAAS,YAAY,CAAC,QAAkB;IACpC,MAAM,SAAS,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,SAAS,CAAC,CAAC;IACnE,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAC3D,MAAM,WAAW,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,WAAW,CAAC,CAAC;IACvE,IAAI,CAAC,SAAS,IAAI,CAAC,KAAK,IAAI,CAAC,WAAW;QACpC,OAAO,SAAS,CAAC;IACrB,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC;AAC7C,CAAC;AACD,wEAAwE;AACxE,MAAM,uBAAuB,GAAG,IAAI,CAAC;AACrC,SAAS,cAAc,CAAC,QAAkB;IACtC,MAAM,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC;IACxD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;QAClC,OAAO,SAAS,CAAC;IACrB,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,uBAAuB,CAAC,CAAC;AAClD,CAAC;AACD;;;GAGG;AACH,KAAK,UAAU,kBAAkB,CAAC,MAAc,EAAE,UAA8B;IAC5E,oFAAoF;IACpF,OAAO,KAAK,CAAC,GAAG,UAAU,IAAI,QAAQ,MAAM,EAAE;QAC1C,MAAM,EAAE,MAAM;QACd,OAAO,EAAE;YACL,aAAa,EAAE,UAAU,MAAM,EAAE;YACjC,cAAc,EAAE,kBAAkB;YAClC,MAAM,EAAE,qCAAqC;SAChD;QACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;YACjB,OAAO,EAAE,KAAK;YACd,EAAE,EAAE,CAAC;YACL,MAAM,EAAE,YAAY;YACpB,MAAM,EAAE;gBACJ,eAAe,EAAE,YAAY;gBAC7B,YAAY,EAAE,EAAE;gBAChB,UAAU,EAAE,EAAE,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,WAAW,EAAE;aACjE;SACJ,CAAC;QACF,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,iBAAiB,CAAC;KACjD,CAAC,CAAC;AACP,CAAC;AACD,8EAA8E;AAC9E,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,MAAc;IAChD,IAAI,CAAC;QACD,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,MAAM,EAAE;YACjC,MAAM,EAAE,KAAK;YACb,0DAA0D;YAC1D,QAAQ,EAAE,OAAO;YACjB,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,iBAAiB,CAAC;SACjD,CAAC,CAAC;QACH,gEAAgE;QAChE,IAAI,QAAQ,CAAC,MAAM,IAAI,GAAG,EAAE,CAAC;YACzB,OAAO;gBACH,KAAK,EAAE,QAAQ;gBACf,EAAE,EAAE,KAAK;gBACT,MAAM,EAAE,0BAA0B,QAAQ,CAAC,MAAM,EAAE;gBACnD,IAAI,EAAE,8BAA8B,QAAQ,CAAC,MAAM,EAAE;aACxD,CAAC;QACN,CAAC;QACD,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IACzC,CAAC;IACD,OAAO,CAAC,EAAE,CAAC;QACP,OAAO;YACH,KAAK,EAAE,QAAQ;YACf,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,qCAAqC;YAC9E,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC;SACvB,CAAC;IACN,CAAC;AACL,CAAC;AACD,oFAAoF;AACpF,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,MAAc,EAAE,UAAmB;IACnE,IAAI,QAAkB,CAAC;IACvB,IAAI,CAAC;QACD,6DAA6D;QAC7D,QAAQ,GAAG,MAAM,kBAAkB,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,CAAC,EAAE,CAAC;QACP,8EAA8E;QAC9E,OAAO;YACH,KAAK,EAAE,aAAa;YACpB,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,WAAW;YACjB,MAAM,EAAE,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;YAClD,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC;SACvB,CAAC;IACN,CAAC;IACD,IAAI,QAAQ,CAAC,EAAE,EAAE,CAAC;QACd,MAAM,QAAQ,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;QACxC,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;IACjF,CAAC;IACD,MAAM,SAAS,GAAG,MAAM,aAAa,CAAC,QAAQ,CAAC,CAAC;IAChD,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAClF,OAAO;QACH,KAAK,EAAE,aAAa;QACpB,EAAE,EAAE,KAAK;QACT,IAAI,EAAE,WAAW,CAAC,QAAQ,CAAC,MAAM,CAAC;QAClC,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,MAAM,EAAE,8BAA8B,QAAQ,CAAC,MAAM,EAAE;QACvD,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,SAAS,CAAE,CAAC,CAAC,CAAC,WAAW,CAAC,QAAQ,CAAC,MAAM,CAAC;QACvE,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnC,GAAG,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC;KACtD,CAAC;AACN,CAAC"}

package/dist/program.d.ts

@@ -0,0 +1,8 @@
+/** 复刻自 tiny-fish CLI 编译产物：program.d.ts + program.impl.js */
+import { Command } from 'commander';
+/** Split from index.ts so tests can drive the real program instead of hand-assembling one. */
+export declare function buildProgram(argv?: string[]): Promise<{
+    program: Command;
+    uninstallNotice: () => NodeJS.Process;
+}>;
+//# sourceMappingURL=program.d.ts.map

package/dist/program.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"program.d.ts","sourceRoot":"","sources":["../src/program.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAE5D,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA+BpC,8FAA8F;AAC9F,wBAAsB,YAAY,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE;;;GAqBjD"}

package/dist/program.js

@@ -0,0 +1,54 @@
+/** 复刻自 tiny-fish CLI 编译产物：program.d.ts + program.impl.js */
+import { Command } from 'commander';
+import { CLI_VERSION } from './lib/constants.js';
+import { installNoticeEmit } from './lib/notice.js';
+const GROUPS = {
+    auth: async (p) => (await import('./commands/auth.js')).registerAuth(p),
+    connect: async (p) => (await import('./commands/connect.js')).registerConnect(p),
+    doctor: async (p) => (await import('./commands/doctor.js')).registerDoctor(p),
+    upgrade: async (p) => (await import('./commands/upgrade.js')).registerUpgrade(p),
+    'check-version': async (p) => (await import('./commands/check-version.js')).registerCheckVersion(p),
+    // `config-claude` is deliberately unregistered: it points Claude Code at `sp search`
+    // and `sp fetch`, which do not exist yet. commands/config-claude.ts and lib/claude-config.ts
+    // are kept so it can be re-registered once those commands land. See README TODO.
+};
+/** Commander answers these before routing, so no command module is needed. */
+const VERSION_FLAGS = ['-V', '--version'];
+// Unknown names need the full list to suggest against.
+/** First bare token is the command. Assumes no global option takes a value. */
+function groupsFor(argv = process.argv) {
+    for (const arg of argv.slice(2)) {
+        if (arg === '--')
+            break;
+        if (!arg.startsWith('-')) {
+            return Object.hasOwn(GROUPS, arg) ? [arg] : Object.keys(GROUPS);
+        }
+        if (VERSION_FLAGS.includes(arg))
+            return [];
+    }
+    return Object.keys(GROUPS);
+}
+/** Split from index.ts so tests can drive the real program instead of hand-assembling one. */
+export async function buildProgram(argv) {
+    const program = new Command();
+    program
+        .name('sp')
+        .description('SpringBrand CLI — connect your agents to the SpringBrand Gateway.')
+        .version(CLI_VERSION, VERSION_FLAGS.join(', '), 'Show version')
+        .helpOption('-h, --help', 'Show help')
+        .addHelpCommand(false)
+        .enablePositionalOptions()
+        .option('--debug', 'Print HTTP requests and responses to stderr (or set SPRINGBRAND_DEBUG=1)')
+        .hook('preAction', (cmd) => {
+        if (cmd.opts().debug) {
+            process.env['SPRINGBRAND_DEBUG'] = '1';
+        }
+    });
+    // Order is user-visible: help lists commands as registered.
+    for (const name of groupsFor(argv ?? process.argv)) {
+        await GROUPS[name](program);
+    }
+    const uninstallNotice = installNoticeEmit(program);
+    return { program, uninstallNotice };
+}
+//# sourceMappingURL=program.js.map

package/dist/program.js.map

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

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@springbrand/cli",
+  "version": "0.1.0",
+  "description": "SpringBrand CLI — connect MCP hosts to the SpringBrand Gateway",
+  "type": "module",
+  "bin": {
+    "sp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "skill",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "dev": "tsc --watch",
+    "test": "npm run build && vitest run",
+    "test:unit": "vitest run test/mcp-json-config.test.ts test/branding.test.ts",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "mcp",
+    "gateway",
+    "cli",
+    "springbrand"
+  ],
+  "author": "SpringBrand",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "cross-spawn": "^7.0.6",
+    "open": "^10.1.0",
+    "tldts": "^6.1.86",
+    "which": "^2.0.2",
+    "yaml": "^2.9.1",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/cross-spawn": "^6.0.6",
+    "@types/node": "^22.10.2",
+    "@types/which": "^3.0.4",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/skill/springbrand-action-api/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: springbrand-action-api
+description: Use SpringBrand Action APIs for available API services and their operations. Use this guidance for API discovery, current contracts, confirmed execution, and saved results.
+---
+
+# SpringBrand Action API
+
+Use the unified SpringBrand MCP for SpringBrand-managed API services. The CLI
+has already configured and authenticated the MCP connection. This Skill does
+not manage third-party connections or install a service.
+
+## Discover and inspect
+
+Call `search_tools` once with one concise English query that states the
+intended result, service, important input, and output. Search results are
+bounded; an incomplete result is not proof of absence. Select an Action API
+operation, copy its opaque Tool ID unchanged, and call `get_tool_schemas` for
+its current input and output contract.
+
+Do not parse a Tool ID to infer a supplier, model, version, or domain. Do not
+execute a result whose described effect belongs to Platform or Connector; use
+an explicit state-preserving Domain transition instead.
+
+## Confirm and execute
+
+Before a write, explain what will happen, the arguments, known fee or credit
+charge, reported risk, and any output limitation. Ask for missing business
+values rather than using placeholders. Execute once with schema-valid
+arguments and a stable idempotency key.
+
+Only `succeeded` means complete. If an execution ID is returned, copy it
+exactly and use `get_execution` to read its status or saved result. Running or
+queued remains in progress. A failed or cancelled result is reported with its
+actual safe reason. `outcome_unknown` means the request may have taken effect:
+never retry or re-execute automatically; verify the external effect using the
+same idempotency identity.
+
+## Reusing state
+
+An exact execution ID takes precedence over rediscovery. An exact Tool ID with
+its current contract takes precedence over another search. A Tool ID without a
+current contract requires `get_tool_schemas`; never invent a revision or
+reconstruct an identifier.
+
+## Boundaries
+
+Action API owns discovery, contract lookup, confirmation, execution, and saved
+result reads for SpringBrand-managed API services. It does not use
+`manage_connections`; connection repair belongs to the Connector Skill.

package/skill/springbrand-action-api/references/action-aliases.md

@@ -0,0 +1,156 @@
+# Action discovery alias map
+
+Use this map when a request names an API service, supplier, platform/product,
+model, object, or operation through an abbreviation, alternative spelling, or
+non-English name. It converts that wording into one catalogue-facing English
+form for the unified `search_tools` query; it does not choose or authorize an
+Action.
+
+Do not invent a supplier, model version, platform, operation, or modality when
+an alias is ambiguous.
+
+## Inventory provenance and maintenance
+
+This snapshot was audited on 2026-09-05 against the then-current Action
+inventory, which contained 52 entries across the ten Supplier ID families
+listed below. It is a terminology aid, not a current availability guarantee.
+
+The mappings below were curated from public catalogue text and common,
+unambiguous names; never claim that the service returned them as alias
+metadata. Never copy an ID from this historical snapshot into contract lookup
+or execution: only a current opaque Tool ID returned by unified discovery is
+usable.
+
+This is a temporary Agent-side discovery aid. Current unified discovery is
+bounded rather than a complete inventory, so update the map only from an
+authoritative catalogue audit outside a user workflow. A later server-side
+discovery improvement should replace the need for this maintained map.
+
+## Inventory coverage
+
+| Supplier ID family | Entries | Public catalogue families reviewed |
+| --- | ---: | --- |
+| `supplier.frank.apify` | 9 | Facebook Ad Library; Reddit scraper and monitor; Google Keyword Volume, Maps Reviews, and Trends; Instagram Profile; TikTok Ads and Data |
+| `supplier.frank.apollo-io` | 2 | Organization Enrichment; People Search |
+| `supplier.frank.elevenlabs` | 1 | Text to Speech |
+| `supplier.frank.exa` | 2 | Web Content Extraction; Web Search |
+| `supplier.frank.firecrawl` | 3 | Structured Data Extraction; Web Scraping; Web Search and Scrape |
+| `supplier.frank.kie-ai-image` | 5 | Seedream 5 Lite image-to-image and text-to-image; Nano Banana 2; GPT Image 2 image-to-image and text-to-image |
+| `supplier.frank.kie-ai-video` | 3 | Seedance 2.0 Fast, Mini, and standard video |
+| `supplier.frank.people-data-labs` | 2 | Company and Person Enrichment |
+| `supplier.frank.serper` | 5 | Google Image, Maps, News, Places, and Shopping Search |
+| `supplier.frank.tikhub` | 20 | Instagram (4); Reddit (2); TikTok (4); X (3); Xiaohongshu (4); YouTube (3) |
+
+## Canonicalization rules
+
+- Match aliases case-insensitively after ordinary Unicode normalization. For short
+  abbreviations such as `X`, `IG`, `TT`, `YT`, `PDL`, `TTS`, `T2I`, and `I2V`,
+  require a whole token and capability-relevant context.
+- Prefer the longest, most specific alias when forms overlap. Preserve explicit
+  model variants such as `Fast` and `Mini`, and preserve every platform,
+  supplier, operation, object, and modality constraint the user actually gave.
+- Preserve canonical phrases such as `Text to Image` and `Image to Video`
+  intact when extracting keywords; `to` defines the modality direction.
+- Emit one canonical English form in the search query. Do not stuff aliases
+  into the query and do not fan out multiple searches.
+- An alias supplies only the concept in its row. A platform alias does not
+  invent an operation or object, and a model-family alias does not invent a
+  version or input modality.
+- Treat the canonicalized concept as a hard compatibility constraint when the
+  user stated it explicitly. Include a supplier in the query only when the
+  user explicitly requires that supplier.
+
+## Service and supplier aliases
+
+Every current entry uses a `supplier.frank.*` Supplier ID. `Frank` alone is
+non-discriminating across the present inventory, so omit it from the search
+query unless the user explicitly makes it a constraint.
+
+| Canonical form | Curated aliases | Current inventory family |
+| --- | --- | --- |
+| `Apify` | — | `supplier.frank.apify` |
+| `Apollo` | `Apollo.io`, `Apollo IO` | `supplier.frank.apollo-io` |
+| `ElevenLabs` | `Eleven Labs`, `11Labs` | `supplier.frank.elevenlabs` |
+| `Exa` | `Exa.ai` | `supplier.frank.exa` |
+| `Firecrawl` | `Fire Crawl` | `supplier.frank.firecrawl` |
+| `Kie.ai` | `Kie AI`, `KIE` | `supplier.frank.kie-ai-image`, `supplier.frank.kie-ai-video` |
+| `People Data Labs` | `PDL`, `PeopleDataLabs`, `People DataLabs` | `supplier.frank.people-data-labs` |
+| `Serper` | `Serper.dev` | `supplier.frank.serper` |
+| `TikHub` | `Tik Hub` | `supplier.frank.tikhub` |
+
+## Platform and product aliases
+
+| Canonical form | Curated aliases | Current inventory scope |
+| --- | --- | --- |
+| `Facebook Ad Library` | `Facebook Ads Library`, `FB Ad Library`, `Meta Ad Library`, `Meta Ads Library`, `脸书广告库` | `action.apify.scrape_facebook_ad_library` |
+| `Reddit` | `红迪` | `action.apify.scrape_reddit__practical-tools-apify`, `action.apify.monitor_reddit_mentions`, `action.tikhub.reddit-*` |
+| `Google Keyword Volume` | `Google Search Volume`, `keyword search volume`, `关键词搜索量` | `action.apify.keyword_volume` |
+| `Google Maps` | `Google Map`, `GMaps`, `谷歌地图` | `action.apify.scrape_google_maps_reviews`, `action.serper.maps` |
+| `Google Trends` | `GTrends`, `谷歌趋势` | `action.apify.scrape_google_trends` |
+| `Instagram` | `IG`, `Insta` | `action.apify.scrape_profiles`, `action.tikhub.instagram-*` |
+| `TikTok Ads Library` | `TikTok Ads`, `TikTok广告库` | `action.apify.scrape_tiktok_ads_library` |
+| `TikTok` | `Tik Tok`, `TT`, `抖音国际版`, `国际版抖音` | `action.apify.tiktok_api`, `action.tikhub.tiktok-*` |
+| `Douyin` | `抖音`, `抖音短视频` | `catalogue-summary-only` |
+| `X` | `Twitter`, `推特`, `X.com`, `X/Twitter` | `action.tikhub.twitter-*` |
+| `Xiaohongshu` | `xhs`, `小红书`, `RedNote`, `Red Note`, `little red book`, `RED` | `action.tikhub.xhs-*` |
+| `YouTube` | `YT`, `You Tube`, `油管` | `action.tikhub.youtube-*` |
+| `Google Image` | `Google Images`, `谷歌图片` | `action.serper.images` |
+| `Google News` | `谷歌新闻` | `action.serper.news` |
+| `Google Places` | `Google Place`, `谷歌地点` | `action.serper.places` |
+| `Google Shopping` | `谷歌购物` | `action.serper.shopping` |
+| `Web` | `website`, `web page`, `网页`, `网站` | `action.exa.*`, `action.firecrawl.*` |
+
+`Douyin` appears in the TikHub catalogue summary, but the audited 52-entry
+inventory has no dedicated Douyin Action. Preserve `Douyin` as the platform
+constraint and, if current discovery finds no compatible entry, report that
+bounded result honestly. Never silently rewrite `Douyin` to `TikTok`.
+Likewise, treat bare `X` as the social platform only when the surrounding
+request refers to posts, profiles, social search, or `X.com`.
+
+## Model and vendor aliases
+
+| Canonical form | Curated aliases | Current inventory scope |
+| --- | --- | --- |
+| `ByteDance` | `Bytedance`, `字节跳动`, `字节` | `action.kie-ai-image.seedream-*`, `action.kie-ai-video.bytedance-*` |
+| `Seedream` | `即梦`, `即梦AI` | `action.kie-ai-image.seedream-5-lite-*` |
+| `Seedream 5 Lite` | `Seedream5 Lite` | `action.kie-ai-image.seedream-5-lite-*` |
+| `Nano Banana 2` | `NanoBanana2`, `Nano Banana` | `action.kie-ai-image.google-nanobanana2` |
+| `OpenAI` | `Open AI` | `action.kie-ai-image.gpt-gpt-image-2-*` |
+| `GPT Image 2` | `GPT-Image-2`, `GPT Image2` | `action.kie-ai-image.gpt-gpt-image-2-*` |
+| `Seedance 2.0` | `Seedance 2`, `Seedance2` | `action.kie-ai-video.bytedance-seedance-2*` |
+
+`Nano Banana` currently resolves to `Nano Banana 2` because it is the only
+Nano Banana family in this inventory snapshot. Re-audit that shorthand as
+soon as another version appears. Bare `Seedream` is a family form; `Seedream
+5 Lite` is the exact current model. Retain every explicit version, `Fast`, or
+`Mini` modifier instead of silently selecting one.
+
+## Object, modality, and operation aliases
+
+| Canonical form | Curated aliases | Current inventory meaning |
+| --- | --- | --- |
+| `Search` | `find`, `look up`, `lookup`, `query`, `搜索`, `查找`, `检索` | Locate existing catalogue data. |
+| `Details` | `detail`, `info`, `information`, `详情`, `详细信息` | Fetch one exact post, note, or video. |
+| `User Profile` | `profile`, `account profile`, `user info`, `账号资料`, `用户资料`, `主页` | Fetch a public account profile. |
+| `User Posts` | `account posts`, `author posts`, `用户帖子`, `账号内容` | List content published by one user. |
+| `Comments` | `comment`, `replies`, `responses`, `评论`, `回复` | Fetch replies on one content item. |
+| `Reviews` | `review`, `ratings`, `评价`, `评分` | Fetch Google Maps reviews. |
+| `Monitor` | `track`, `watch`, `monitoring`, `监控`, `追踪` | Monitor Reddit brand mentions. |
+| `Scrape` | `scraper`, `crawl`, `抓取`, `爬取` | Retrieve public web or social data. |
+| `Extract` | `extraction`, `抽取`, `提取` | Extract web content or structured fields. |
+| `Enrichment` | `enrich`, `data enrichment`, `补全`, `数据补充` | Enrich a person, company, or organization. |
+| `Post` | `posts`, `帖子`, `动态` | A social post; `tweet` and `推文` mean `X Post` only in X/Twitter context. |
+| `Note` | `notes`, `笔记` | A Xiaohongshu content item. |
+| `Video` | `videos`, `短视频` | A TikTok or YouTube video, or generated video. |
+| `Image` | `images`, `picture`, `photo`, `图片`, `图像` | An existing or generated image. |
+| `Text to Speech` | `TTS`, `text2speech`, `txt2speech`, `文本转语音`, `语音合成` | ElevenLabs speech generation. |
+| `Text to Image` | `T2I`, `text2image`, `txt2img`, `文生图`, `文字生成图片` | Generate an image from text. |
+| `Image to Image` | `I2I`, `image2image`, `img2img`, `图生图`, `图片编辑` | Edit or transform an existing image. |
+| `Text to Video` | `T2V`, `text2video`, `txt2vid`, `文生视频`, `文字生成视频` | Generate video with text input. |
+| `Image to Video` | `I2V`, `image2video`, `img2vid`, `图生视频`, `图片生成视频` | Generate video with image input. |
+
+Operation and modality mappings are compatibility constraints, not synonyms
+for one another. `Search` cannot satisfy `Details`; `Comments` cannot satisfy
+`User Posts`; `Text to Image` cannot satisfy `Image to Image`; and `Text to
+Video` cannot satisfy `Image to Video` when the user explicitly requires the
+input modality.

package/skill/springbrand-action-api/references/action-discovery.md

@@ -0,0 +1,95 @@
+# Action API discovery through the unified Meta Tools
+
+Read this reference only when the Action API Skill needs discovery. It records
+Agent behavior, not the Gateway wire contract. Runtime tool schemas and results
+remain authoritative.
+
+## Build one search
+
+Call `search_tools` with one concise English query. Translate a non-English
+request yourself and preserve every explicit constraint that distinguishes the
+operation: required supplier, platform or product, operation, object or
+modality, and output type. Keep topic content, dates, formatting preferences,
+and other execution arguments in task state unless they help identify the
+operation.
+
+Use [action-aliases.md](action-aliases.md) only to canonicalize an unambiguous
+concept. Do not invent a supplier, model version, platform, operation, or
+modality. Do not send synonyms as multiple searches.
+
+Examples of useful queries:
+
+- `Xiaohongshu note search`
+- `TikHub Xiaohongshu note search` only when the user explicitly requires
+  TikHub
+- `text to image`
+- `Seedance 2.0 image to video` when both model and modality were explicit
+
+SpringBrand host names, courtesy language, and generic phrases such as "use
+an API" do not distinguish an Action and should not dominate the query.
+
+## Interpret the bounded result
+
+Discovery returns one bounded list. It is not globally ranked and is not a
+complete inventory. Preserve returned order while applying the user's hard
+compatibility constraints:
+
+1. supplier, only when explicitly required;
+2. platform or product;
+3. operation, such as search, details, comments, or profile;
+4. object or modality, such as note, video, text to image, or image to video;
+5. required output type.
+
+Recommend the first returned Action API operation that satisfies every
+applicable constraint. This is compatibility filtering, not reranking: do not
+invent scores, merge another list, or treat a score as task-success
+probability.
+
+Unified discovery can return Platform and Connector operations too. Ignore
+those results here. Their presence does not authorize cross-domain execution.
+
+## Missing, empty, incomplete, and failed results
+
+Keep these outcomes distinct:
+
+- **Compatible candidate found** — preserve its opaque Tool ID exactly and
+  inspect its current contract with `get_tool_schemas`.
+- **Complete empty or incompatible result** — report no fit for this query, or
+  narrow/revise it once when the user's explicit constraints support a more
+  precise query.
+- **Incomplete result** — it cannot establish no-match. Narrow or revise the
+  English query; there is no search pagination contract to invent.
+- **Provider or tool failure** — report the actual transport, authentication,
+  permission, schema, or upstream error. An error is not a no-match.
+
+Do not fan out over query variants. Do not use an inventory crawl as a hidden
+fallback. If safe refinement lacks enough identifying signal, ask the user one
+focused question instead of guessing.
+
+## Contract inspection
+
+Search summaries are not executable contracts. Send the selected opaque Tool
+ID unchanged to `get_tool_schemas` and use the returned current contract to
+check:
+
+- the operation description and access state;
+- exact input and output schemas;
+- risk and known costs;
+- revision information;
+- attachment and produced-material requirements.
+
+Never construct, edit, decode, or classify the Tool ID. A contract error is a
+lookup failure, not proof that the Action does not exist. Do not fall through
+to another candidate silently.
+
+## Execution association and reuse
+
+Use the runtime `execute_tools` schema exactly. One logical run gets one stable
+idempotency key, retained with the exact Tool ID and arguments before the call.
+Do not invent observation fields, discovery IDs, expected revisions, or
+classification metadata that the runtime tool schema does not declare.
+
+When execution returns an exact execution ID, retain it with task state. A
+later status or result read uses `get_execution` with that same ID. It never
+searches again, invokes again, or charges again. Only a new user-approved run
+gets a new logical invocation and key.

package/skill/springbrand-connector/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: springbrand-connector
+description: Use SpringBrand Connector for Gmail, GitHub, Slack, and other connected third-party services, including account connection management and external reads or writes.
+---
+
+# SpringBrand Connector
+
+Use the unified SpringBrand MCP for third-party services. The CLI has already
+configured and authenticated the MCP connection. Provider credentials are
+owned by the Gateway and must never be requested, copied, logged, or placed in
+an argument, URL, prompt, or result.
+
+## Discover and inspect
+
+Call `search_tools` once with a concise English query naming the service and
+operation. Preserve the user's requested account and effect. Select a
+Connector operation, copy its opaque Tool ID unchanged, and inspect its current
+contract with `get_tool_schemas`. Ignore Platform and Action API candidates;
+use an explicit state-preserving transition when the task belongs elsewhere.
+
+## Connections
+
+Use `manage_connections` only when the current Connector contract requires an
+account or the user asks about connections. Use exactly one operation at a
+time: list, start, status, repair, or disconnect. Preserve the exact
+connection or authorization-attempt identifier returned by the Gateway. Show
+an authorization link unchanged when one is returned, but never handle the
+Provider credential itself.
+
+An API-key-authenticated Gateway session may have Connector limitations. Report
+a dedicated capability error or warning when the Gateway says Connector API
+key support is unavailable; do not turn that condition into a generic
+authorization failure or invent an OAuth session.
+
+## Execute and read results
+
+Build arguments from the current schema and ask for missing service values.
+Before a write, explain the target account, effect, known risk, and approval
+requirement. Execute once with a stable idempotency key. Only `succeeded`
+confirms completion. Use `get_execution` only with an exact returned execution
+ID. An unknown write result is never automatically retried; verify the
+external effect first.
+
+## Boundaries
+
+Connector owns third-party operations and their connection lifecycle. It does
+not acquire Plugins, publish Creations, or execute Action APIs. Keep one
+executor active at a time and preserve state across an explicit Domain
+transition.