@ryuhq/sdk 0.1.14 → 0.2.2

package/src/cli.ts

@@ -4,7 +4,8 @@
  *
  * Usage:
  *   bunx ryu pack <dir>
- *   bunx ryu publish <dir>
+ *   bunx ryu github-publish <repository-or-package-url>
+ *   bunx ryu publish <dir>  (legacy migration escape hatch)
  *   bunx ryu agent-plugin <dir>
  *
  * Commands:
@@ -12,9 +13,10 @@
  *                   Plugin bundle at <dir>/dist/plugin.bundle.json, plus the
  *                   Agent Plugins interop pair in <dir> itself.
  *                   Exits 0 on success; exits 1 with the failing field on error.
- *   publish <dir>   Validate the manifest.json and POST it to the Ryu Marketplace
- *                   publish endpoint with the author's auth token. The item is
- *                   stored as `pending` until a moderator approves it.
+ *   github-publish <url>
+ *                   Submit a seller-owned GitHub repository/package URL to the
+ *                   GitHub-backed marketplace bridge.
+ *   publish <dir>   Deprecated server-artifact publishing; disabled by default.
  *   agent-plugin <dir>
  *                   Emit only the Agent Plugins v1 interop pair (plugin.json and,
  *                   when servers exist, mcp.json) derived from the manifest.json.
@@ -25,10 +27,12 @@ import {
 	existsSync,
 	mkdirSync,
 	readFileSync,
+	realpathSync,
 	rmSync,
 	writeFileSync,
+	writeSync,
 } from "node:fs";
-import { join, resolve } from "node:path";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import {
 	AGENT_PLUGIN_MANIFEST_FILE,
 	AGENT_PLUGIN_MCP_FILE,
@@ -56,7 +60,9 @@ function printUsage(): void {
 			"",
 			"Usage:",
 			"  bunx ryu pack <dir>      Validate and bundle a manifest.json Plugin",
-			"  bunx ryu publish <dir>   Validate and publish a manifest.json Plugin to the Ryu Marketplace",
+			"  bunx ryu github-publish <url>",
+			"                           Submit a GitHub repository/package URL to the Marketplace",
+			"  bunx ryu publish <dir>   Deprecated server-artifact publishing (migration only)",
 			"  bunx ryu dev <entry>     Run a Runnable locally with an interactive chat loop",
 			"  bunx ryu agent-plugin <dir>",
 			"                           Emit the Agent Plugins v1 interop pair (plugin.json + mcp.json)",
@@ -66,7 +72,7 @@ function printUsage(): void {
 }
 
 function exitError(message: string): never {
-	process.stderr.write(`error: ${message}\n`);
+	writeSync(process.stderr.fd, `error: ${message}\n`);
 	process.exit(1);
 }
 
@@ -91,17 +97,21 @@ const MANIFEST_FILE_NAMES = [
 // `manifest.json` — and then fail validation for missing `id`. The `$schema`
 // discriminator separates them (see `isAgentPluginManifest`).
 function resolveNativeManifestPath(dir: string): string | undefined {
-	return MANIFEST_FILE_NAMES.map((name) => join(dir, name)).find((candidate) => {
-		if (!existsSync(candidate)) {
-			return false;
-		}
-		try {
-			return !isAgentPluginManifest(JSON.parse(readFileSync(candidate, "utf8")));
-		} catch {
-			// Unparseable: let the caller surface the JSON error against this path.
-			return true;
+	return MANIFEST_FILE_NAMES.map((name) => join(dir, name)).find(
+		(candidate) => {
+			if (!existsSync(candidate)) {
+				return false;
+			}
+			try {
+				return !isAgentPluginManifest(
+					JSON.parse(readFileSync(candidate, "utf8"))
+				);
+			} catch {
+				// Unparseable: let the caller surface the JSON error against this path.
+				return true;
+			}
 		}
-	});
+	);
 }
 
 // Read + parse + validate the manifest in `dir`. Exits with the failing
@@ -140,6 +150,28 @@ function loadManifest(dir: string): LoadedManifest {
 const CODE_FILE_DIRS = ["hooks", "adapters"];
 const CODE_FILE_PATH = /^(hooks|adapters)\/[A-Za-z0-9_][A-Za-z0-9._-]*\.m?js$/;
 
+function containedPackageFile(dir: string, rel: string, label: string): string {
+	let realRoot: string;
+	let realTarget: string;
+	try {
+		realRoot = realpathSync(dir);
+		realTarget = realpathSync(join(dir, rel));
+	} catch (error) {
+		exitError(`${label}: could not resolve '${rel}': ${String(error)}`);
+	}
+	const fromRoot = relative(realRoot, realTarget);
+	if (
+		fromRoot === ".." ||
+		fromRoot.startsWith(`..${sep}`) ||
+		isAbsolute(fromRoot)
+	) {
+		exitError(
+			`${label}: '${rel}' resolves outside the plugin package (${realTarget})`
+		);
+	}
+	return realTarget;
+}
+
 /**
  * Read one `code_file` and return its contents, or exit with a clear error.
  *
@@ -153,7 +185,7 @@ function readCodeFile(dir: string, rel: string, label: string): string {
 			`${label}: code_file '${rel}' must be exactly '<${CODE_FILE_DIRS.join("|")}>/<name>.js' with no traversal`
 		);
 	}
-	const path = join(dir, rel);
+	const path = containedPackageFile(dir, rel, label);
 	let body: string;
 	try {
 		body = readFileSync(path, "utf8");
@@ -267,7 +299,7 @@ function inlineOutputStyleFiles(
 		}
 		let body: string;
 		try {
-			body = readFileSync(join(dir, rel), "utf8");
+			body = readFileSync(containedPackageFile(dir, rel, label), "utf8");
 		} catch (err) {
 			exitError(`${label}: could not read file '${rel}': ${String(err)}`);
 		}
@@ -316,12 +348,12 @@ function resolveUiEntry(manifest: LoadedManifest): string | null {
 	return null;
 }
 
-// Resolve a companion's `ui_format` discriminator. `"html"` (Path B) means the
-// `ui_entry` file is ALREADY a self-contained HTML document (a
-// vite-plugin-singlefile build for a heavy app like the whiteboard) and must be
-// shipped VERBATIM as `ui_code` — NOT run through `Bun.build`, which would try to
-// bundle an HTML file as an ESM entry and fail. Anything else (absent / `"js"`) is
-// the default: `ui_entry` is an ESM module `Bun.build` bundles into `ui_code`.
+// Resolve a UI entry's format. `"html"` means the `ui_entry` file is ALREADY a
+// self-contained HTML document (a vite-plugin-singlefile build for a heavy
+// companion, or a hand-authored widget) and must be shipped VERBATIM as
+// `ui_code` — NOT run through `Bun.build`, which would try to bundle an HTML
+// file as an ESM entry and fail. Anything else (absent / `"js"`) is the default:
+// `ui_entry` is an ESM module `Bun.build` bundles into `ui_code`.
 function resolveUiFormat(manifest: LoadedManifest): "html" | "js" {
 	for (const runnable of manifest.runnables) {
 		if (runnable.kind !== "companion") {
@@ -333,6 +365,15 @@ function resolveUiFormat(manifest: LoadedManifest): "html" | "js" {
 			return "html";
 		}
 	}
+	for (const widget of manifest.contributes?.widgets ?? []) {
+		const entry = widget.ui_entry;
+		if (
+			typeof entry === "string" &&
+			entry.trim().toLowerCase().endsWith(".html")
+		) {
+			return "html";
+		}
+	}
 	return "js";
 }
 
@@ -572,8 +613,16 @@ async function commandPublish(rawDir: string): Promise<void> {
 		...(manifest.description ? { description: manifest.description } : {}),
 		...(manifest.tagline ? { tagline: manifest.tagline } : {}),
 		...(developer ? { developer } : {}),
+		...(manifest.author ? { author: manifest.author } : {}),
+		...(manifest.repository ? { repository: manifest.repository } : {}),
+		...(manifest.external ? { external: true } : {}),
 		...(manifest.category ? { category: manifest.category } : {}),
+		...(manifest.license ? { license: manifest.license } : {}),
+		...(manifest.keywords?.length ? { keywords: manifest.keywords } : {}),
 		...(manifest.iconUrl ? { iconUrl: manifest.iconUrl } : {}),
+		...(manifest.icon ? { icon: manifest.icon } : {}),
+		...(manifest.iconDither ? { iconDither: manifest.iconDither } : {}),
+		...(manifest.banner ? { banner: manifest.banner } : {}),
 		...(manifest.screenshots?.length
 			? { screenshots: manifest.screenshots }
 			: {}),
@@ -648,6 +697,58 @@ async function commandPublish(rawDir: string): Promise<void> {
 	);
 }
 
+async function commandGithubPublish(repositoryUrl: string): Promise<void> {
+	const input = repositoryUrl.trim();
+	if (!input) {
+		exitError(
+			"github-publish requires a GitHub repository or package URL, for example https://github.com/acme/my-app"
+		);
+	}
+	const token = authToken();
+	const url = `${publishBaseUrl()}/api/marketplace/github/publish`;
+	const proof = process.env.RYU_GITHUB_INSTALLATION_PROOF?.trim();
+	const body = {
+		url: input,
+		...(proof ? { installationProof: proof } : {}),
+	};
+	let response: Response;
+	try {
+		response = await fetch(url, {
+			method: "POST",
+			headers: {
+				authorization: `Bearer ${token}`,
+				"content-type": "application/json",
+			},
+			body: JSON.stringify(body),
+		});
+	} catch (error) {
+		exitError(`could not reach ${url}: ${String(error)}`);
+	}
+	const text = await response.text();
+	if (!response.ok) {
+		try {
+			const error = JSON.parse(text) as {
+				code?: string;
+				installationUrl?: string;
+				error?: string;
+			};
+			if (error.installationUrl) {
+				exitError(
+					`${error.error ?? "GitHub App installation required"}. Open ${error.installationUrl}, then set RYU_GITHUB_INSTALLATION_PROOF to the callback proof and retry.`
+				);
+			}
+			exitError(
+				`github-publish failed (${response.status}): ${error.error ?? text}`
+			);
+		} catch {
+			exitError(`github-publish failed (${response.status}): ${text}`);
+		}
+	}
+	process.stdout.write(
+		`GitHub-backed listing submitted for moderation:\n${text}\n`
+	);
+}
+
 // ── main ──────────────────────────────────────────────────────────────────────
 
 const [, , command, ...args] = process.argv;
@@ -670,9 +771,24 @@ if (command === "pack") {
 	if (!dir) {
 		exitError("publish requires a directory argument: bunx ryu publish <dir>");
 	}
+	if (process.env.RYU_ENABLE_LEGACY_MARKETPLACE_WRITES !== "true") {
+		exitError(
+			"ryu publish is deprecated because marketplace package contents now live in GitHub Releases; use bunx ryu github-publish <repository-or-package-url>"
+		);
+	}
 	commandPublish(dir).catch((err: unknown) => {
 		exitError(String(err));
 	});
+} else if (command === "github-publish") {
+	const repositoryUrl = args[0];
+	if (!repositoryUrl) {
+		exitError(
+			"github-publish requires a GitHub repository or package URL, for example https://github.com/acme/my-app"
+		);
+	}
+	commandGithubPublish(repositoryUrl).catch((err: unknown) => {
+		exitError(String(err));
+	});
 } else if (command === "agent-plugin") {
 	const dir = args[0];
 	if (!dir) {

package/src/contracts-lockstep.test.ts

@@ -9,7 +9,7 @@
  * Schema, and the generated types stay describing the same manifest:
  *
  * 1. a known-good repo manifest (apps-store/mail/manifest.json — the first
- *    fully manifest-driven app) parses with the zod `PluginManifestSchema`;
+ *    fully manifest-driven app) parses without losing any top-level wire field;
  * 2. every key the schema marks required exists in the schema, the generated
  *    TS, and the fixture;
  * 3. every top-level key the fixture uses is a key the wire model knows.
@@ -42,12 +42,26 @@ const schema = JSON.parse(readFileSync(SCHEMA_PATH, "utf8")) as {
 	properties: Record<string, unknown>;
 };
 const generatedSource = readFileSync(GENERATED_PATH, "utf8");
+const CORE_FIELDS_PREVIOUSLY_STRIPPED = [
+	"permission_levels",
+	"sidecars",
+	"stability",
+	"surfaces",
+] as const;
 
 describe("contracts lockstep (zod ↔ blessed JSON Schema ↔ generated TS)", () => {
-	test("the known-good mail manifest.json parses with the zod authoring schema", () => {
+	test("the known-good mail manifest survives the zod pack path without field loss", () => {
 		const parsed = PluginManifestSchema.parse(fixture);
 		expect(parsed.id).toBe("@ryu/mail");
 		expect(parsed.runnables.length).toBeGreaterThan(0);
+		for (const key of Object.keys(fixture)) {
+			expect(Object.hasOwn(parsed, key), key).toBe(true);
+		}
+		for (const key of CORE_FIELDS_PREVIOUSLY_STRIPPED) {
+			expect(schema.properties).toHaveProperty(key);
+			expect(fixture).toHaveProperty(key);
+			expect(parsed[key]).toEqual(fixture[key]);
+		}
 	});
 
 	test("blessed schema describes PluginManifest with the required identity keys", () => {

package/src/exports-lockstep.test.ts

@@ -0,0 +1,93 @@
+/**
+ * Package exports ↔ tsup entries lockstep guard.
+ *
+ * The SDK's public surface is split across `package.json` `exports` subpaths
+ * (`@ryuhq/sdk/model`, `@ryuhq/sdk/mcp/server`, …) and `tsup.config.ts`
+ * entrypoints that compile each one. They must stay a bijection: a subpath
+ * with no entry never builds, and an entry with no subpath is unreachable.
+ * This is the cheap structural guard that keeps the two from drifting again
+ * (a past drift left docs importing `@ryuhq/sdk/model` / `@ryuhq/sdk/mcp/server`
+ * that resolved to nothing).
+ *
+ * Deterministic, filesystem-only, no network.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import tsupConfig from "../tsup.config.ts";
+
+const PKG_PATH = join(import.meta.dir, "../package.json");
+const pkg = JSON.parse(readFileSync(PKG_PATH, "utf8")) as {
+	exports: Record<
+		string,
+		{ types?: string; import?: string; require?: string }
+	>;
+};
+
+// tsup's `defineConfig` type is the `Options | Options[] | fn` union, which the
+// spread doesn't narrow; the entry map is the one shape this package uses.
+const entryKeys = Object.keys(
+	(tsupConfig as { entry?: Record<string, string> }).entry ?? {}
+);
+const exportKeys = Object.keys(pkg.exports);
+
+describe("package exports ↔ tsup entries lockstep", () => {
+	test("every tsup entry has a matching exports subpath", () => {
+		// `.` in the exports map corresponds to the `index` entry.
+		const expected = entryKeys.map((key) =>
+			key === "index" ? "." : `./${key}`
+		);
+		for (const key of expected) {
+			expect(exportKeys).toContain(key);
+		}
+	});
+
+	test("every exports subpath has a matching tsup entry", () => {
+		const subpaths = exportKeys
+			.filter((key) => key !== ".")
+			.map((key) => key.replace(/^\.\//, ""));
+		for (const key of subpaths) {
+			expect(entryKeys).toContain(key);
+		}
+		expect(entryKeys).toContain("index");
+	});
+
+	test("every subpath the docs/examples import resolves in the exports map", () => {
+		// Each of these is referenced by real consumers (fumadocs cookbooks,
+		// examples/, the desktop host, create-ryu-app) and must never 404.
+		const documented = [
+			"action",
+			"manifest",
+			"agent",
+			"model",
+			"mcp",
+			"mcp/server",
+			"mcp/client",
+			"plugin",
+			"runnable",
+			"builder",
+		];
+		for (const sub of documented) {
+			expect(
+				pkg.exports[`./${sub}`],
+				`@ryuhq/sdk/${sub} must be exported`
+			).toBeTruthy();
+		}
+	});
+
+	test("each subpath points at its own dist files (no collisions)", () => {
+		const distFiles = new Set<string>();
+		for (const entry of Object.values(pkg.exports)) {
+			for (const kind of ["types", "import", "require"] as const) {
+				const path = entry?.[kind];
+				if (path) {
+					expect(distFiles.has(path), `dist file collision: ${path}`).toBe(
+						false
+					);
+					distFiles.add(path);
+				}
+			}
+		}
+	});
+});