@mcp-com-ai/plugin-sdk 1.0.1-beta.260912

package/README.md

@@ -0,0 +1,48 @@
+# @hapi/plugin-sdk
+
+The contract every HAPI CLI plugin implements.
+
+This package is intentionally tiny and stable. It exports:
+
+- `HapiCliPlugin` — the plugin shape the core CLI loads
+- `CliCommand` / `CliContext` / `CliInvocation` — the runtime types
+- `defineCommand` / `definePlugin` — identity helpers for IntelliSense + validation
+- `parseArgs` — a small, dependency-free flag parser
+- `renderCommandHelp` — consistent help output
+- `HAPI_CLI_API_VERSION` — the current plugin-contract version
+
+## Writing a plugin
+
+```ts
+import { definePlugin, defineCommand, HAPI_CLI_API_VERSION } from '@mcp-com-ai/plugin-sdk';
+
+const connect = defineCommand({
+  name: 'connect',
+  description: 'Connect to an MCP server',
+  arguments: [{ name: 'server-url', description: 'Target MCP server URL', required: true }],
+  async run({ positionals }, ctx) {
+    const [url] = positionals;
+    ctx.stdout.write(`Connecting to ${url}\n`);
+  },
+});
+
+export default definePlugin({
+  name: '@mcp-com-ai/client',
+  version: '0.1.0',
+  compatibility: { cliApiVersion: HAPI_CLI_API_VERSION },
+  commands: [
+    {
+      name: 'client',
+      description: 'MCP client operations',
+      subcommands: [connect],
+    },
+  ],
+});
+```
+
+## Stability policy
+
+The SDK follows a simple rule: **additive changes keep the same
+`HAPI_CLI_API_VERSION`. Any breaking change bumps the major.** The CLI
+refuses to load plugins whose `compatibility.cliApiVersion` does not
+match the CLI's advertised version.

package/dist/helpers.d.ts

@@ -0,0 +1,32 @@
+import type { CliCommand, CliContext, CliInvocation, CliOption, HapiCliPlugin } from './types';
+/**
+ * `defineCommand` is a no-op helper that exists purely to give plugin
+ * authors good IntelliSense without forcing them to import the `CliCommand`
+ * type explicitly. Works at the top level of subcommand trees too.
+ */
+export declare function defineCommand(command: CliCommand): CliCommand;
+/**
+ * `definePlugin` validates a plugin shape at declaration time and returns it
+ * unchanged. Keep the runtime cost trivial.
+ */
+export declare function definePlugin(plugin: HapiCliPlugin): HapiCliPlugin;
+/**
+ * Minimal flag parser built on top of standard argv. Recognises:
+ *   - --flag
+ *   - --flag=value
+ *   - --flag value
+ *   - --no-flag (sets boolean false)
+ *   - -x value / -x=value (short alias)
+ *   - -- (marks end of flags; everything after goes to `rest`)
+ *
+ * Unknown flags are preserved in `options` as raw string values so commands
+ * can choose to forward them to child processes (e.g., wrangler, docker).
+ */
+export declare function parseArgs(argv: readonly string[], options?: readonly CliOption[], args?: {
+    allowUnknown?: boolean;
+}): CliInvocation;
+/**
+ * Emit a standard help block for a command. Plugins can call this from
+ * `run` to render consistent help text.
+ */
+export declare function renderCommandHelp(command: CliCommand, context: CliContext, crumbs?: string[]): void;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./types";
+export { defineCommand, definePlugin, parseArgs, renderCommandHelp, } from "./helpers";
+export { DEFAULT_DOCUMENT_SOURCE_POLICY, assertRemoteDocumentUrl, redactDocumentUrl, } from "./source-policy";
+export { isSupportedVersionRange, satisfiesVersionRange, } from "./version-compatibility";

package/dist/index.js

@@ -0,0 +1,16 @@
+// @bun
+var M="1.0.1-beta.260912";var T=Number(M.split(".")[0]);function P(e){return e}function F(e){if(!e.name)throw Error("HAPI plugin missing required `name`");if(!e.version)throw Error(`HAPI plugin '${e.name}' missing required \`version\``);if(!e.compatibility?.cliApiVersion)throw Error(`HAPI plugin '${e.name}' must declare compatibility.cliApiVersion (current: '${T}')`);if(!Array.isArray(e.commands))throw Error(`HAPI plugin '${e.name}' must declare a commands[] array`);let r=new Set;for(let s of e.serveProviders??[]){if(!s.id||!s.kind||!s.rootField||!s.description)throw Error(`HAPI plugin '${e.name}' has an invalid serve provider declaration`);if(typeof s.serve!=="function")throw Error(`HAPI plugin '${e.name}' serve provider '${s.id}' must declare serve()`);if(r.has(s.id))throw Error(`HAPI plugin '${e.name}' declares duplicate serve provider '${s.id}'`);r.add(s.id)}return e}function H(e,r=[],s={}){let c=s.allowUnknown??!0,n=[],t=[],f={};for(let i of r)if(i.env&&process.env[i.env]!==void 0)f[i.name]=E(process.env[i.env],i);else if(i.default!==void 0)f[i.name]=i.default;let u=new Map,j=new Map;for(let i of r)if(u.set(i.name,i),i.alias)j.set(i.alias,i);let h=0;while(h<e.length){let i=e[h];if(i==="--"){t.push(...e.slice(h+1));break}if(i.startsWith("--")){let d=i.slice(2),R=d.indexOf("="),x=R>=0?d.slice(0,R):d,S=R>=0?d.slice(R+1):void 0,U=x.startsWith("no-"),V=U?x.slice(3):x,L=u.get(V)??u.get(Z(V));if(!L){if(!c)throw Error(`Unknown option: --${x}`);if(S!==void 0)f[D(x)]=S,h++;else if(U)f[D(V)]=!1,h++;else{let A=e[h+1];if(A!==void 0&&!String(A).startsWith("-"))f[D(x)]=A,h+=2;else f[D(x)]=!0,h++}continue}if(L.type==="boolean"){f[L.name]=U?!1:S?O(S):!0,h++;continue}let m=S;if(m===void 0)m=e[h+1],h+=m!==void 0&&!String(m).startsWith("-")?2:1;else h++;if(L.type==="array"){let A=f[L.name]??[];f[L.name]=[...A,...String(m??"").split(",").map((_)=>_.trim()).filter(Boolean)]}else f[L.name]=E(m,L);continue}if(i.startsWith("-")&&i.length>1){let d=i.slice(1),R=d.indexOf("="),x=R>=0?d.slice(0,R):d,S=R>=0?d.slice(R+1):void 0,U=j.get(x);if(!U){if(!c)throw Error(`Unknown option: -${x}`);n.push(i),h++;continue}if(U.type==="boolean"){f[U.name]=S?O(S):!0,h++;continue}let V=S;if(V===void 0)V=e[h+1],h+=V!==void 0&&!String(V).startsWith("-")?2:1;else h++;f[U.name]=E(V,U);continue}n.push(i),h++}return{positionals:n,options:f,rest:t}}function E(e,r){if(e===void 0)return e;switch(r.type){case"number":{let s=Number(e);return Number.isFinite(s)?s:e}case"boolean":return O(e);case"array":return String(e).split(",").map((s)=>s.trim()).filter(Boolean);default:return String(e)}}function O(e){if(typeof e==="boolean")return e;let r=String(e).toLowerCase();return r==="1"||r==="true"||r==="yes"||r==="on"}function Z(e){return e.replace(/-([a-z0-9])/g,(r,s)=>s.toUpperCase())}function D(e){return Z(e)}function W(e,r,s=[]){let c=s.length?`${s.join(" ")} `:"",n=(t)=>r.stdout.write(t);if(n(`
+${c}${e.name} \u2014 ${e.description}
+`),e.arguments?.length){n(`
+Arguments:
+`);for(let t of e.arguments){let f=t.variadic?`${t.name}...`:t.name,u=t.required?`<${f}>`:`[${f}]`;n(`  ${u.padEnd(24)} ${t.description}
+`)}}if(e.options?.length){n(`
+Options:
+`);for(let t of e.options){let f=t.alias?`-${t.alias}, --${t.name}`:`    --${t.name}`,u=t.default!==void 0?`${t.description} (default: ${JSON.stringify(t.default)})`:t.description;n(`  ${f.padEnd(28)} ${u}
+`)}}if(e.subcommands?.length){n(`
+Subcommands:
+`);for(let t of e.subcommands){if(t.hidden)continue;n(`  ${t.name.padEnd(14)} ${t.description}
+`)}}if(e.longHelp)n(`
+${e.longHelp}
+`);n(`
+`)}var Y=Object.freeze({maxBytes:5242880,timeoutMs:1e4,maxRedirects:5});function B(e){if(e.protocol!=="http:"&&e.protocol!=="https:")throw Error(`Remote documents cannot resolve ${e.protocol} sources`)}function b(e){try{let r=e instanceof URL?new URL(e.href):new URL(e);if(r.username="",r.password="",r.search)r.search="?redacted";return r.href}catch{return String(e)}}var G=/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z.-]+)?$/,$=/^(<=|>=|<|>|=)?(\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z.-]+)?)$/;function J(e,r){let s=C(e);if(!s||!y(r))return!1;if(r.startsWith("^")){let n=C(r.slice(1));return n!==void 0&&z(s,n)>=0&&z(s,K(n))<0}let c=r.trim().split(/\s+/).filter(Boolean);return c.length>0&&c.every((n)=>{let t=n.match($);if(!t)return!1;let f=t[2];if(!f)return!1;let u=C(f);if(!u)return!1;let j=z(s,u);switch(t[1]??"="){case"=":return j===0;case">":return j>0;case">=":return j>=0;case"<":return j<0;case"<=":return j<=0;default:return!1}})}function y(e){if(e.startsWith("^"))return C(e.slice(1))!==void 0;let r=e.trim().split(/\s+/).filter(Boolean);return r.length>0&&r.every((s)=>{let n=s.match($)?.[2];return n!==void 0&&C(n)!==void 0})}function C(e){let r=e.match(G);if(!r)return;return{major:Number(r[1]),minor:Number(r[2]),patch:Number(r[3]),prerelease:r[4]?.split(".")??[]}}function K(e){if(e.major>0)return{major:e.major+1,minor:0,patch:0,prerelease:["0"]};if(e.minor>0)return{major:0,minor:e.minor+1,patch:0,prerelease:["0"]};return{major:0,minor:0,patch:e.patch+1,prerelease:["0"]}}function z(e,r){for(let c of["major","minor","patch"])if(e[c]!==r[c])return e[c]<r[c]?-1:1;if(e.prerelease.length===0||r.prerelease.length===0){if(e.prerelease.length===r.prerelease.length)return 0;return e.prerelease.length===0?1:-1}let s=Math.max(e.prerelease.length,r.prerelease.length);for(let c=0;c<s;c++){let n=e.prerelease[c],t=r.prerelease[c];if(n===void 0)return-1;if(t===void 0)return 1;if(n===t)continue;let f=/^\d+$/.test(n),u=/^\d+$/.test(t);if(f&&u)return Number(n)<Number(t)?-1:1;if(f!==u)return f?-1:1;return n<t?-1:1}return 0}export{J as satisfiesVersionRange,W as renderCommandHelp,b as redactDocumentUrl,H as parseArgs,y as isSupportedVersionRange,F as definePlugin,P as defineCommand,B as assertRemoteDocumentUrl,T as HAPI_CLI_API_VERSION,Y as DEFAULT_DOCUMENT_SOURCE_POLICY};

package/dist/source-policy.d.ts

@@ -0,0 +1,8 @@
+/** Shared conservative defaults used by document-owning serve providers. */
+export declare const DEFAULT_DOCUMENT_SOURCE_POLICY: Readonly<{
+    maxBytes: number;
+    timeoutMs: 10000;
+    maxRedirects: 5;
+}>;
+export declare function assertRemoteDocumentUrl(url: URL): void;
+export declare function redactDocumentUrl(value: URL | string): string;

package/dist/types.d.ts

@@ -0,0 +1,153 @@
+/**
+ * The plugin contract for the HAPI CLI.
+ *
+ * Everything a plugin needs to declare itself to the core belongs here.
+ * Keep this surface small and boring — stability matters more than ergonomics.
+ */
+/**
+ * Version of the plugin API that the CLI advertises.
+ * Plugins declare the version they target; the loader refuses to load mismatches.
+ */
+export declare const HAPI_CLI_API_VERSION: number;
+export type HapiCliApiVersion = typeof HAPI_CLI_API_VERSION;
+/**
+ * Write-able streams injected into commands so plugins don't need to touch
+ * `process.stdout` directly. Mostly convenience — tests can substitute streams.
+ */
+export interface CliWritableStream {
+    write(chunk: string): void;
+}
+export interface CliReadableStream {
+    read?(): unknown;
+}
+export interface CliContext {
+    cwd: string;
+    env: Record<string, string | undefined>;
+    stdout: CliWritableStream;
+    stderr: CliWritableStream;
+    stdin: CliReadableStream;
+    rawArgv: readonly string[];
+    /**
+     * HAPI home directory. Resolved from $HAPI_HOME, falling back to $HOME/.hapi.
+     * Plugins should read/write their state under this directory.
+     */
+    hapiHome: string;
+    /**
+     * Absolute path to the root of the monorepo or install, for tools that
+     * need to resolve bundled assets.
+     */
+    installRoot?: string;
+    /**
+     * Opaque service registry. Plugins can use it to share cross-plugin
+     * services (e.g., a license service, a telemetry reporter) without
+     * creating direct dependencies.
+     */
+    services: Map<string, unknown>;
+}
+/**
+ * Flags/options recognised by a command. Parsing is intentionally simple —
+ * commands can opt out and parse rawArgs themselves if they need more.
+ */
+export interface CliOption {
+    name: string;
+    alias?: string;
+    description: string;
+    type?: "string" | "boolean" | "number" | "array";
+    default?: unknown;
+    required?: boolean;
+    env?: string;
+    choices?: readonly string[];
+}
+/**
+ * A runnable command. Subcommands are first-class: a command that has
+ * subcommands does not need a `run`; if it has both, `run` handles the
+ * case where no subcommand was supplied.
+ */
+export interface CliCommand {
+    name: string;
+    description: string;
+    aliases?: readonly string[];
+    options?: readonly CliOption[];
+    arguments?: readonly CliArgument[];
+    subcommands?: readonly CliCommand[];
+    run?: (args: CliInvocation, context: CliContext) => Promise<number | void> | number | void;
+    /** Optional long-form help appended below the autogenerated help block. */
+    longHelp?: string;
+    /** Marks a command as hidden from help output. */
+    hidden?: boolean;
+}
+export interface CliArgument {
+    name: string;
+    description: string;
+    required?: boolean;
+    variadic?: boolean;
+}
+/**
+ * What a command's `run` receives. Positional args are `positionals`; any
+ * unknown tokens are surfaced in `rest`.
+ */
+export interface CliInvocation {
+    positionals: string[];
+    options: Record<string, unknown>;
+    rest: string[];
+}
+/** A parsed source passed from the CLI to a document-specific serve provider. */
+export interface DocumentSourceEnvelope {
+    /** The value typed by the user, before path or URL resolution. */
+    identifier: string;
+    /** Canonical absolute file URL or final HTTP(S) retrieval URL. */
+    canonicalUri: string;
+    /** URI used to resolve relative source descriptions. */
+    baseUri: string;
+    /** Original UTF-8 document text. */
+    raw: string;
+    /** Parsed JSON/YAML root value. */
+    document: unknown;
+    /** Whether the entry document was retrieved over HTTP(S). */
+    remote: boolean;
+}
+export interface ServeProviderRequest {
+    source?: DocumentSourceEnvelope;
+    invocation: CliInvocation;
+}
+/**
+ * Optional contribution used by the generic `hapi serve` dispatcher.
+ * Document semantics remain inside the plugin that owns the provider.
+ */
+export interface ServeProvider {
+    id: string;
+    kind: string;
+    rootField: string;
+    description: string;
+    options?: readonly CliOption[];
+    /** Permit legacy identifiers that do not resolve to a document, e.g. an OpenAPI project name. */
+    legacyFallback?: boolean;
+    serve: (request: ServeProviderRequest, context: CliContext) => Promise<number | void> | number | void;
+}
+export interface HapiCliPlugin {
+    name: string;
+    version: string;
+    displayName?: string;
+    description?: string;
+    /** Declared plugin-contract version. Must match HAPI_CLI_API_VERSION. */
+    compatibility: {
+        cliApiVersion: HapiCliApiVersion | string;
+        /**
+         * Present when the plugin consumes @mcp-com-ai/core. The version is read
+         * from the same resolved core package that the plugin imports at runtime.
+         */
+        core?: {
+            version: string;
+            range: string;
+        };
+    };
+    commands: readonly CliCommand[];
+    /** Document kinds this plugin can serve through the top-level dispatcher. */
+    serveProviders?: readonly ServeProvider[];
+    /**
+     * Optional lifecycle hook called once at CLI boot after all plugins load.
+     * Useful for plugins that need to register cross-plugin services
+     * (telemetry, license) without attaching them to commands.
+     */
+    onLoad?: (context: CliContext) => Promise<void> | void;
+}

package/dist/version-compatibility.d.ts

@@ -0,0 +1,2 @@
+export declare function satisfiesVersionRange(version: string, range: string): boolean;
+export declare function isSupportedVersionRange(range: string): boolean;

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@mcp-com-ai/plugin-sdk",
+  "version": "1.0.1-beta.260912",
+  "description": "The shared plugin contract for the HAPI CLI. Consumed by the core CLI, first-party plugins, and third-party extensions.",
+  "license": "LRL-CL",
+  "type": "module",
+  "module": "./dist/index.js",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "hapi-build-source": "./src/index.ts",
+      "bun": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "typecheck": "bunx tsc --noEmit",
+    "build": "bun ../../scripts/build-package.ts ."
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "engines": {
+  "bun": ">=1.3.0"
+},
+"publishConfig": {
+"access": "public"
+},
+"keywords": ["hapi", "hapi-plugin", "mcp", "cli"]
+}