@thenavidm/slipway 0.1.0

package/dist/tool.js

@@ -0,0 +1,151 @@
+/**
+ * The one definition both surfaces read.
+ *
+ * A tool is described once: its name, what it is for, the shape of its input,
+ * how risky it is and what it does. The MCP server and the CLI are both
+ * generated from that object, so a tool added today is a command today, and
+ * neither surface can describe it differently from the other.
+ */
+import { isBackground, MAX_WAIT_SECONDS, waitSecondsFor } from "./jobs.js";
+import { phrase } from "./util.js";
+import { advertised, CONTROL_NAMES, emptyInput, inputJsonSchema, isSchema, withControls, } from "./schema.js";
+const NAME = /^[a-z][a-z0-9_]{0,63}$/;
+const TAG = /^[a-z0-9][a-z0-9-]*$/;
+/** Define a tool. Throws at load time on a definition that cannot work, not on the first call. */
+export function defineTool(definition) {
+    const where = `Tool '${definition.name}'`;
+    if (!NAME.test(definition.name ?? "")) {
+        throw new Error(`${where}: names are snake_case, start with a letter and are at most 64 characters.`);
+    }
+    if (!definition.title?.trim())
+        throw new Error(`${where}: title is required.`);
+    if (!definition.description?.trim())
+        throw new Error(`${where}: description is required.`);
+    if (!["read", "write", "destructive"].includes(definition.risk)) {
+        throw new Error(`${where}: risk must be read, write or destructive.`);
+    }
+    if (definition.input !== undefined && !isSchema(definition.input)) {
+        throw new Error(`${where}: input must be a Zod object or jsonSchema({...}).`);
+    }
+    if (definition.output !== undefined && !isSchema(definition.output)) {
+        throw new Error(`${where}: output must be a Zod schema or jsonSchema({...}).`);
+    }
+    for (const tag of definition.tags ?? []) {
+        if (!TAG.test(tag))
+            throw new Error(`${where}: tag '${tag}' must be lowercase words joined by dashes.`);
+    }
+    if (typeof definition.handler !== "function")
+        throw new Error(`${where}: handler is required.`);
+    const job = definition.job;
+    if (job) {
+        if (definition.name.length > 57)
+            throw new Error(`${where}: a job tool's name is at most 57 characters, so its status tool fits in 64.`);
+        if (!isBackground(job)) {
+            const ok = (typeof job.id === "string" && job.id.length > 0) || typeof job.id === "function";
+            if (!ok || typeof job.status !== "function" || typeof job.done !== "function") {
+                throw new Error(`${where}: job needs id, status and done for a job the service runs, or { background: true }.`);
+            }
+        }
+        if (job.waitSeconds !== undefined && !(job.waitSeconds >= 0 && job.waitSeconds <= MAX_WAIT_SECONDS)) {
+            throw new Error(`${where}: job.waitSeconds must be 0-${MAX_WAIT_SECONDS}. Clients stop waiting on a call after about a minute.`);
+        }
+        if (definition.paginate)
+            throw new Error(`${where}: a job tool cannot also page.`);
+        if (definition.cache || definition.sync)
+            throw new Error(`${where}: a job tool cannot be cached or synced.`);
+    }
+    if (definition.cache) {
+        if (definition.risk !== "read")
+            throw new Error(`${where}: only reads can be cached. A write must reach the service every time.`);
+        if (!(typeof definition.cache.ttlSeconds === "number" && definition.cache.ttlSeconds > 0))
+            throw new Error(`${where}: cache.ttlSeconds must be a positive number.`);
+    }
+    let sync;
+    if (definition.sync) {
+        if (definition.risk !== "read")
+            throw new Error(`${where}: only reads can be synced.`);
+        const items = definition.sync.items ?? definition.paginate?.items;
+        if (!definition.sync.id || !items)
+            throw new Error(`${where}: sync needs id, and items unless the tool pages.`);
+        sync = { id: definition.sync.id, items };
+    }
+    const input = advertised((definition.input ?? emptyInput()));
+    const own = Object.keys(inputJsonSchema(input).properties ?? {});
+    for (const name of CONTROL_NAMES) {
+        if (own.includes(name))
+            throw new Error(`${where}: '${name}' is Slipway's own argument. Rename the input property.`);
+    }
+    const requireConfirm = definition.requireConfirm ?? definition.risk === "destructive";
+    const schema = withControls(input, {
+        confirm: requireConfirm,
+        ...(job ? { wait: { defaultSeconds: waitSecondsFor(job), maxSeconds: MAX_WAIT_SECONDS } } : {}),
+    });
+    const jsonSchema = inputJsonSchema(schema);
+    const properties = Object.keys(jsonSchema.properties ?? {});
+    for (const name of definition.positional ?? []) {
+        if (!properties.includes(name))
+            throw new Error(`${where}: positional '${name}' is not an input property.`);
+    }
+    if (definition.paginate && !properties.includes(definition.paginate.cursorArg)) {
+        throw new Error(`${where}: paginate.cursorArg '${definition.paginate.cursorArg}' is not an input property.`);
+    }
+    return Object.freeze({
+        kind: "slipway.tool",
+        name: definition.name,
+        command: definition.name.replace(/_/g, "-"),
+        title: definition.title.trim(),
+        description: definition.description.trim(),
+        risk: definition.risk,
+        idempotent: definition.idempotent ?? definition.risk === "read",
+        openWorld: definition.openWorld ?? true,
+        requireConfirm,
+        tags: Object.freeze([...(definition.tags ?? [])]),
+        examples: Object.freeze([...(definition.examples ?? [])]),
+        positional: Object.freeze([...(definition.positional ?? [])]),
+        timeoutMs: definition.timeoutMs,
+        maxResultChars: definition.maxResultChars,
+        icons: definition.icons,
+        meta: definition.meta,
+        paginate: definition.paginate,
+        ...(job ? { job } : {}),
+        ...(definition.cache ? { cache: { ttlSeconds: definition.cache.ttlSeconds } } : {}),
+        ...(sync ? { sync } : {}),
+        input,
+        schema,
+        output: definition.output ? advertised(definition.output) : undefined,
+        summary: definition.summary,
+        preview: definition.preview,
+        render: definition.render,
+        handler: definition.handler,
+        jsonSchema,
+    });
+}
+/**
+ * Bind `defineTool` to an app's context type once, so every handler in the
+ * repo gets `ctx.client` typed without repeating the generic:
+ *
+ *     export const { defineTool } = toolkit<Context>();
+ */
+export function toolkit() {
+    return {
+        defineTool: (definition) => defineTool(definition),
+    };
+}
+export function isTool(value) {
+    return value?.kind === "slipway.tool";
+}
+/**
+ * One line saying what a call is about to do, for refusals, approval forms and
+ * the audit log. The tool's own `summary`, or its title as a phrase: "delete a
+ * note". A summary that throws falls back too, because it runs before the
+ * arguments have been anywhere near the handler.
+ */
+export function summarize(tool, args) {
+    const fallback = phrase(tool.title);
+    try {
+        return tool.summary?.(args)?.trim() || fallback;
+    }
+    catch {
+        return fallback;
+    }
+}

package/dist/util.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Small helpers more than one module needs.
+ */
+/** JSON with object keys sorted at every depth, so equal values always serialize the same. */
+export declare function stableJson(value: unknown): string;
+export declare function sha256(text: string): string;
+/** "2.1.286" as numbers, ignoring anything after the first non-numeric part. */
+export declare function versionParts(version: string | undefined): number[];
+/** Whether `version` is at least `minimum`. An unreadable version is never at least anything. */
+export declare function versionAtLeast(version: string | undefined, minimum: readonly number[]): boolean;
+/** A title or summary as it reads mid-sentence: "Delete a course" becomes "delete a course", "GitHub issue" keeps its capitals. */
+export declare function phrase(text: string): string;

package/dist/util.js

@@ -0,0 +1,35 @@
+/**
+ * Small helpers more than one module needs.
+ */
+import { createHash } from "node:crypto";
+/** JSON with object keys sorted at every depth, so equal values always serialize the same. */
+export function stableJson(value) {
+    return JSON.stringify(value, (_key, inner) => inner && typeof inner === "object" && !Array.isArray(inner)
+        ? Object.fromEntries(Object.entries(inner).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
+        : inner) ?? "null";
+}
+export function sha256(text) {
+    return createHash("sha256").update(text).digest("hex");
+}
+/** "2.1.286" as numbers, ignoring anything after the first non-numeric part. */
+export function versionParts(version) {
+    const match = /^v?(\d+(?:\.\d+)*)/.exec(version?.trim() ?? "");
+    return match ? match[1].split(".").map(Number) : [];
+}
+/** Whether `version` is at least `minimum`. An unreadable version is never at least anything. */
+export function versionAtLeast(version, minimum) {
+    const parts = versionParts(version);
+    if (parts.length === 0)
+        return false;
+    for (let i = 0; i < minimum.length; i++) {
+        const have = parts[i] ?? 0;
+        if (have !== minimum[i])
+            return have > minimum[i];
+    }
+    return true;
+}
+/** A title or summary as it reads mid-sentence: "Delete a course" becomes "delete a course", "GitHub issue" keeps its capitals. */
+export function phrase(text) {
+    const trimmed = text.trim().replace(/[.!?]+$/, "");
+    return /^[A-Z][a-z]/.test(trimmed) && !/^[A-Z][a-z]+[A-Z]/.test(trimmed) ? trimmed.charAt(0).toLowerCase() + trimmed.slice(1) : trimmed;
+}

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@thenavidm/slipway",
+  "version": "0.1.0",
+  "description": "Slipway, the TypeScript framework for MCP servers and agent-native CLIs. One tool definition ships an MCP server and a CLI, with write safety, typed results and release checks built in.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "author": "Navid Moazzez (https://navid.me)",
+  "homepage": "https://github.com/thenavidm/slipway#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thenavidm/slipway.git"
+  },
+  "bugs": {
+    "url": "https://github.com/thenavidm/slipway/issues"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "mcp framework",
+    "cli",
+    "cli framework",
+    "agent-native cli",
+    "ai agents",
+    "claude code",
+    "codex",
+    "typescript",
+    "tool calling",
+    "mcp sdk",
+    "standard schema",
+    "zod",
+    "openapi",
+    "llm tools",
+    "claude desktop",
+    "cursor"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "slipway": "dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "SKILL.md",
+    "LICENSE",
+    "NOTICE",
+    "CHANGELOG.md",
+    "SECURITY.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "^2.3.0",
+    "zod": "^4.2.0"
+  },
+  "peerDependencies": {
+    "ajv": "^8.17.1"
+  },
+  "peerDependenciesMeta": {
+    "ajv": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "^2.3.0",
+    "@types/node": "^22.10.0",
+    "ajv": "^8.17.1",
+    "typescript": "^7.0.2",
+    "vite": "^8.3.2",
+    "vitest": "^5.0.3"
+  }
+}